From 38562b03e3f866cfe2b76fbd77ef8e7589a761b0 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 27 Feb 2024 11:02:39 -0800 Subject: [PATCH 01/25] Moving the previous API documentation to the RKA section for the latest and 2.8 versions. Adjusted the titles and some wording, as well as updated the redirect for the latest versions. Signed-off-by: Sunil Singh --- .../api-tokens.md | 90 ++++++++++++++++++ .../previous-rancher-api-versions.md | 93 +++++++++++++++++++ docusaurus.config.js | 4 +- sidebars.js | 21 ++--- .../api-tokens.md | 90 ++++++++++++++++++ .../previous-rancher-api-versions.md | 93 +++++++++++++++++++ versioned_sidebars/version-2.8-sidebars.json | 21 ++--- 7 files changed, 386 insertions(+), 26 deletions(-) create mode 100644 docs/api/previous-rancher-api-versions/api-tokens.md create mode 100644 docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md create mode 100644 versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md create mode 100644 versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md diff --git a/docs/api/previous-rancher-api-versions/api-tokens.md b/docs/api/previous-rancher-api-versions/api-tokens.md new file mode 100644 index 00000000000..f1253bc0b20 --- /dev/null +++ b/docs/api/previous-rancher-api-versions/api-tokens.md @@ -0,0 +1,90 @@ +--- +title: Using API Tokens in Past Rancher Versions +--- + + + + + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. + +You can deactivate API tokens by deleting them or by deactivating the user account. + +### Deleting tokens +To delete a token, + +1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. + +1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` + +1. Click **Delete**. + +Here is the complete list of tokens that are generated with `ttl=0`: + +| Token | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubeconfig-*` | Kubeconfig token | +| `kubectl-shell-*` | Access to `kubectl` shell in the browser | +| `agent-*` | Token for agent deployment | +| `compose-token-*` | Token for compose | +| `helm-token-*` | Token for Helm chart deployment | +| `telemetry-*` | Telemetry token | +| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | + + +### Setting TTL on Kubeconfig Tokens + +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means tokens never expire. + +:::note + +This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). + +::: + +### Disable Tokens in Generated Kubeconfigs + +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. + +2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). + +### Token Hashing + +Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. + +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). + +This feature will affect all tokens which include, but are not limited to, the following: + +- Kubeconfig tokens +- Bearer tokens API keys/calls +- Tokens used by internal operations + +### Token Settings +These global settings affect Rancher token behavior. + +| Setting | Description | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | +| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | +| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | + +#### auth-user-session-ttl-minutes +Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. + +#### kubeconfig-default-token-TTL-minutes +Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). +**Introduced in version 2.6.6**. + +#### kubeconfig-token-ttl-minutes +Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when [`kubeconfig-generate-token`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). +**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).** + +#### auth-token-max-ttl-minutes +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. +**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** + +#### kubeconfig-generate-token +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md new file mode 100644 index 00000000000..0dab8dfb6fd --- /dev/null +++ b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -0,0 +1,93 @@ +--- +title: Previous API Guide +--- + + + + + +## How to use the API + +The previous Rancher API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: + + + + +1. Click on your user avatar in the upper right corner. +1. Click **Account & API Keys**. +1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +Go to the URL endpoint at `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +## Authentication + +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). + +## Making requests + +The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). + +- Every type has a Schema which describes: + - The URL to get to the collection of this type of resources + - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. + - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). + - Every field that filtering is allowed on + - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. + + +- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. + +- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. + +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. + +- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. + +- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. + +- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. + +- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). + +## Filtering + +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. + +## Sorting + +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. + +## Pagination + +API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. + +## Capturing Rancher API Calls + +You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: + +1. In the Rancher UI, go to **Cluster Management** and click **Create.** +1. Click one of the cluster types. This example uses Digital Ocean. +1. Fill out the form with a cluster name and node template, but don't click **Create**. +1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** +1. In the developer tools, click the **Network** tab. +1. On the **Network** tab, make sure **Fetch/XHR** is selected. +1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. +1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** +1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. + +### Enable View in API + +You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: + +1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. +2. Under the **Advanced Features** section, click **Enable "View in API"** + +Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. diff --git a/docusaurus.config.js b/docusaurus.config.js index 215a647d839..98e9570b7a7 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1682,7 +1682,7 @@ module.exports = { from: '/v2.8/pages-for-subheaders/about-rke1-templates' }, { - to: '/v2.8/reference-guides/about-the-api', + to: '/v2.8/api/previous-rancher-api-versions', from: '/v2.8/pages-for-subheaders/about-the-api' }, { @@ -2030,7 +2030,7 @@ module.exports = { from: '/pages-for-subheaders/about-rke1-templates' }, { - to: '/reference-guides/about-the-api', + to: '/api/previous-rancher-api-versions', from: '/pages-for-subheaders/about-the-api' }, { diff --git a/sidebars.js b/sidebars.js index e80a933e2bc..8fb2bbca81e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1034,17 +1034,6 @@ const sidebars = { "reference-guides/cli-with-rancher/kubectl-utility", ] }, - { - type: 'category', - label: 'About the API', - link: { - type: 'doc', - id: "reference-guides/about-the-api/about-the-api", - }, - items: [ - "reference-guides/about-the-api/api-tokens", - ] - }, "reference-guides/rancher-cluster-tools", "reference-guides/rancher-project-tools", @@ -1363,7 +1352,15 @@ const sidebars = { "api/workflows/projects" ] }, - "api/api-reference" + "api/api-reference", + { + "type": "category", + "label": "Previous API Versions", + "items": [ + "api/previous-rancher-api-versions/previous-rancher-api-versions", + "api/previous-rancher-api-versions/api-tokens", + ] + }, ] }, "contribute-to-rancher", diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md new file mode 100644 index 00000000000..f1253bc0b20 --- /dev/null +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md @@ -0,0 +1,90 @@ +--- +title: Using API Tokens in Past Rancher Versions +--- + + + + + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. + +You can deactivate API tokens by deleting them or by deactivating the user account. + +### Deleting tokens +To delete a token, + +1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. + +1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` + +1. Click **Delete**. + +Here is the complete list of tokens that are generated with `ttl=0`: + +| Token | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubeconfig-*` | Kubeconfig token | +| `kubectl-shell-*` | Access to `kubectl` shell in the browser | +| `agent-*` | Token for agent deployment | +| `compose-token-*` | Token for compose | +| `helm-token-*` | Token for Helm chart deployment | +| `telemetry-*` | Telemetry token | +| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | + + +### Setting TTL on Kubeconfig Tokens + +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means tokens never expire. + +:::note + +This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). + +::: + +### Disable Tokens in Generated Kubeconfigs + +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. + +2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). + +### Token Hashing + +Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. + +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). + +This feature will affect all tokens which include, but are not limited to, the following: + +- Kubeconfig tokens +- Bearer tokens API keys/calls +- Tokens used by internal operations + +### Token Settings +These global settings affect Rancher token behavior. + +| Setting | Description | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | +| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | +| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | + +#### auth-user-session-ttl-minutes +Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. + +#### kubeconfig-default-token-TTL-minutes +Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). +**Introduced in version 2.6.6**. + +#### kubeconfig-token-ttl-minutes +Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when [`kubeconfig-generate-token`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). +**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).** + +#### auth-token-max-ttl-minutes +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. +**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** + +#### kubeconfig-generate-token +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md new file mode 100644 index 00000000000..0dab8dfb6fd --- /dev/null +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -0,0 +1,93 @@ +--- +title: Previous API Guide +--- + + + + + +## How to use the API + +The previous Rancher API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: + + + + +1. Click on your user avatar in the upper right corner. +1. Click **Account & API Keys**. +1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +Go to the URL endpoint at `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +## Authentication + +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). + +## Making requests + +The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). + +- Every type has a Schema which describes: + - The URL to get to the collection of this type of resources + - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. + - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). + - Every field that filtering is allowed on + - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. + + +- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. + +- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. + +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. + +- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. + +- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. + +- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. + +- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). + +## Filtering + +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. + +## Sorting + +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. + +## Pagination + +API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. + +## Capturing Rancher API Calls + +You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: + +1. In the Rancher UI, go to **Cluster Management** and click **Create.** +1. Click one of the cluster types. This example uses Digital Ocean. +1. Fill out the form with a cluster name and node template, but don't click **Create**. +1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** +1. In the developer tools, click the **Network** tab. +1. On the **Network** tab, make sure **Fetch/XHR** is selected. +1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. +1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** +1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. + +### Enable View in API + +You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: + +1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. +2. Under the **Advanced Features** section, click **Enable "View in API"** + +Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index c1823a88108..9224ae972cf 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -997,17 +997,6 @@ "reference-guides/cli-with-rancher/kubectl-utility" ] }, - { - "type": "category", - "label": "About the API", - "link": { - "type": "doc", - "id": "reference-guides/about-the-api/about-the-api" - }, - "items": [ - "reference-guides/about-the-api/api-tokens" - ] - }, "reference-guides/rancher-cluster-tools", "reference-guides/rancher-project-tools", "reference-guides/system-tools", @@ -1323,7 +1312,15 @@ "api/workflows/projects" ] }, - "api/api-reference" + "api/api-reference", + { + "type": "category", + "label": "Previous API Versions", + "items": [ + "api/previous-rancher-api-versions/previous-rancher-api-versions", + "api/previous-rancher-api-versions/api-tokens" + ] + } ] }, "contribute-to-rancher" From b2c17b1c4aa45f7609bebe8847aa06c6c8fd2375 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 27 Feb 2024 13:40:46 -0800 Subject: [PATCH 02/25] Updating the markdown links to point to the correct location after moving pages. Signed-off-by: Sunil Singh --- docs/api/previous-rancher-api-versions/api-tokens.md | 4 ++-- .../previous-rancher-api-versions.md | 2 +- .../api/previous-rancher-api-versions/api-tokens.md | 4 ++-- .../previous-rancher-api-versions.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/previous-rancher-api-versions/api-tokens.md b/docs/api/previous-rancher-api-versions/api-tokens.md index f1253bc0b20..18ba2501385 100644 --- a/docs/api/previous-rancher-api-versions/api-tokens.md +++ b/docs/api/previous-rancher-api-versions/api-tokens.md @@ -44,7 +44,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ### Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. 2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). @@ -87,4 +87,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt **Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** #### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md index 0dab8dfb6fd..aed82517653 100644 --- a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md index f1253bc0b20..18ba2501385 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md @@ -44,7 +44,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ### Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. 2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). @@ -87,4 +87,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt **Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** #### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md index 0dab8dfb6fd..aed82517653 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). From 1201f3bca285c227915e3fe8eacbe1dfa5103374 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Wed, 28 Feb 2024 13:44:43 -0800 Subject: [PATCH 03/25] Removing the old API files from the latest/2.8 versions and updating the redirect to current URL, also updating some verbiage after review. Signed-off-by: Sunil Singh --- .../api-tokens.md | 2 + .../previous-rancher-api-versions.md | 4 +- .../about-the-api/about-the-api.md | 93 ------------------- .../about-the-api/api-tokens.md | 90 ------------------ docusaurus.config.js | 4 + .../api-tokens.md | 2 + .../previous-rancher-api-versions.md | 4 +- .../about-the-api/about-the-api.md | 92 ------------------ .../about-the-api/api-tokens.md | 82 ---------------- 9 files changed, 12 insertions(+), 361 deletions(-) delete mode 100644 docs/reference-guides/about-the-api/about-the-api.md delete mode 100644 docs/reference-guides/about-the-api/api-tokens.md delete mode 100644 versioned_docs/version-2.8/reference-guides/about-the-api/about-the-api.md delete mode 100644 versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md diff --git a/docs/api/previous-rancher-api-versions/api-tokens.md b/docs/api/previous-rancher-api-versions/api-tokens.md index 18ba2501385..4ffed1b254b 100644 --- a/docs/api/previous-rancher-api-versions/api-tokens.md +++ b/docs/api/previous-rancher-api-versions/api-tokens.md @@ -6,6 +6,8 @@ title: Using API Tokens in Past Rancher Versions +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In previous Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). + By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. You can deactivate API tokens by deleting them or by deactivating the user account. diff --git a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md index aed82517653..7227c062168 100644 --- a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -6,9 +6,9 @@ title: Previous API Guide -## How to use the API +## How to Use the API -The previous Rancher API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/docs/reference-guides/about-the-api/about-the-api.md b/docs/reference-guides/about-the-api/about-the-api.md deleted file mode 100644 index 21f3c03bdc1..00000000000 --- a/docs/reference-guides/about-the-api/about-the-api.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: API ---- - - - - - -## How to use the API - -The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: - - - - -1. Click on your user avatar in the upper right corner. -1. Click **Account & API Keys**. -1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. - - - - -Go to the URL endpoint at `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. - - - - -## Authentication - -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). - -## Making requests - -The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). - -- Every type has a Schema which describes: - - The URL to get to the collection of this type of resources - - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. - - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). - - Every field that filtering is allowed on - - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. - - -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. - -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. - -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. - -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. - -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - -- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). - -## Filtering - -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. - -## Sorting - -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. - -## Pagination - -API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. - -## Capturing Rancher API Calls - -You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: - -1. In the Rancher UI, go to **Cluster Management** and click **Create.** -1. Click one of the cluster types. This example uses Digital Ocean. -1. Fill out the form with a cluster name and node template, but don't click **Create**. -1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** -1. In the developer tools, click the **Network** tab. -1. On the **Network** tab, make sure **Fetch/XHR** is selected. -1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. -1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** -1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. - -### Enable View in API - -You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: - -1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. -2. Under the **Advanced Features** section, click **Enable "View in API"** - -Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. diff --git a/docs/reference-guides/about-the-api/api-tokens.md b/docs/reference-guides/about-the-api/api-tokens.md deleted file mode 100644 index c6f738d1836..00000000000 --- a/docs/reference-guides/about-the-api/api-tokens.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: API Tokens ---- - - - - - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. - -You can deactivate API tokens by deleting them or by deactivating the user account. - -### Deleting tokens -To delete a token, - -1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. - -1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` - -1. Click **Delete**. - -Here is the complete list of tokens that are generated with `ttl=0`: - -| Token | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `kubeconfig-*` | Kubeconfig token | -| `kubectl-shell-*` | Access to `kubectl` shell in the browser | -| `agent-*` | Token for agent deployment | -| `compose-token-*` | Token for compose | -| `helm-token-*` | Token for Helm chart deployment | -| `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | - - -### Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means tokens never expire. - -:::note - -This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). - -::: - -### Disable Tokens in Generated Kubeconfigs - -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. - -2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). - -### Token Hashing - -Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature will affect all tokens which include, but are not limited to, the following: - -- Kubeconfig tokens -- Bearer tokens API keys/calls -- Tokens used by internal operations - -### Token Settings -These global settings affect Rancher token behavior. - -| Setting | Description | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | -| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | -| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | - -#### auth-user-session-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. - -#### kubeconfig-default-token-TTL-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). -**Introduced in version 2.6.6**. - -#### kubeconfig-token-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when [`kubeconfig-generate-token`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). -**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).** - -#### auth-token-max-ttl-minutes -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. -**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** - -#### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/docusaurus.config.js b/docusaurus.config.js index 98e9570b7a7..05c7d62428e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1685,6 +1685,10 @@ module.exports = { to: '/v2.8/api/previous-rancher-api-versions', from: '/v2.8/pages-for-subheaders/about-the-api' }, + { + to: '/v2.8/api/previous-rancher-api-versions', + from: '/v2.8/reference-guides/about-the-api' + }, { to: '/v2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters', from: '/v2.8/pages-for-subheaders/access-clusters' diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md index 18ba2501385..4ffed1b254b 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md @@ -6,6 +6,8 @@ title: Using API Tokens in Past Rancher Versions +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In previous Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). + By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. You can deactivate API tokens by deleting them or by deactivating the user account. diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md index aed82517653..7227c062168 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -6,9 +6,9 @@ title: Previous API Guide -## How to use the API +## How to Use the API -The previous Rancher API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/versioned_docs/version-2.8/reference-guides/about-the-api/about-the-api.md b/versioned_docs/version-2.8/reference-guides/about-the-api/about-the-api.md deleted file mode 100644 index 40068f7cfe5..00000000000 --- a/versioned_docs/version-2.8/reference-guides/about-the-api/about-the-api.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: API ---- - - - - - -## How to use the API - -The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: - - - - -1. Click on your user avatar in the upper right corner. -1. Click **Account & API Keys**. -1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. - - - - -Go to the URL endpoint at `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. - - - - -## Authentication - -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). - -## Making requests - -The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). - -- Every type has a Schema which describes: - - The URL to get to the collection of this type of resources - - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. - - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). - - Every field that filtering is allowed on - - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. - - -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. - -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. - -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. - -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. - -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - -- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). - -## Filtering - -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. - -## Sorting - -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. - -## Pagination - -API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. - -## Capturing Rancher API Calls - -You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: - -1. In the Rancher UI, go to **Cluster Management** and click **Create.** -1. Click one of the cluster types. This example uses Digital Ocean. -1. Fill out the form with a cluster name and node template, but don't click **Create**. -1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** -1. In the developer tools, click the **Network** tab. -1. On the **Network** tab, make sure **Fetch/XHR** is selected. -1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. -1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** -1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. - -### Enable View in API -You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: - -1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. -2. Under the **Advanced Features** section, click **Enable "View in API"** - -Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. diff --git a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md deleted file mode 100644 index d19fdd47b68..00000000000 --- a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: API Tokens ---- - - - - - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. - -You can deactivate API tokens by deleting them or by deactivating the user account. - -### Deleting tokens -To delete a token, - -1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. - -1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` - -1. Click **Delete**. - -Here is the complete list of tokens that are generated with `ttl=0`: - -| Token | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `kubectl-shell-*` | Access to `kubectl` shell in the browser | -| `agent-*` | Token for agent deployment | -| `compose-token-*` | Token for compose | -| `helm-token-*` | Token for Helm chart deployment | -| `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | - - -### Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 43200, which is 30 days. - -:::note - -This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). - -::: - -### Disable Tokens in Generated Kubeconfigs - -Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. - -### Token Hashing - -Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature will affect all tokens which include, but are not limited to, the following: - -- Kubeconfig tokens -- Bearer tokens API keys/calls -- Tokens used by internal operations - -### Token Settings -These global settings affect Rancher token behavior. - -| Setting | Description | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | -| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | - -#### auth-user-session-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. - -#### kubeconfig-default-token-TTL-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). -**Introduced in version 2.6.6**. - -#### auth-token-max-ttl-minutes -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. -**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** - -#### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). From ce0e9fb1b4ef83f696dbd4385cf5e0939b4fb50d Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Wed, 28 Feb 2024 13:55:49 -0800 Subject: [PATCH 04/25] Update with link to v2.7 API ref page. Signed-off-by: Sunil Singh --- .../previous-rancher-api-versions.md | 2 +- .../previous-rancher-api-versions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md index 7227c062168..a82f9d5f2ea 100644 --- a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -8,7 +8,7 @@ title: Previous API Guide ## How to Use the API -The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a [web browser](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md index 7227c062168..a82f9d5f2ea 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md @@ -8,7 +8,7 @@ title: Previous API Guide ## How to Use the API -The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a [web browser](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: From eafbafc1c5009967f0c5812071f57fb08bc40d30 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Wed, 28 Feb 2024 14:48:54 -0800 Subject: [PATCH 05/25] Updating links after checker flagged items and adjusting some wording. Signed-off-by: Sunil Singh --- docs/api/previous-rancher-api-versions/api-tokens.md | 2 +- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- .../new-user-guides/manage-clusters/nodes-and-node-pools.md | 2 +- docs/reference-guides/cli-with-rancher/kubectl-utility.md | 4 ++-- docs/reference-guides/user-settings/api-keys.md | 2 +- .../api/previous-rancher-api-versions/api-tokens.md | 2 +- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- .../new-user-guides/manage-clusters/nodes-and-node-pools.md | 2 +- .../reference-guides/cli-with-rancher/kubectl-utility.md | 4 ++-- .../version-2.8/reference-guides/user-settings/api-keys.md | 2 +- 12 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/api/previous-rancher-api-versions/api-tokens.md b/docs/api/previous-rancher-api-versions/api-tokens.md index 4ffed1b254b..c61dba41671 100644 --- a/docs/api/previous-rancher-api-versions/api-tokens.md +++ b/docs/api/previous-rancher-api-versions/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens in Past Rancher Versions -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In previous Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In past Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md index f10a4fd7ec1..33a69728948 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../reference-guides/about-the-api/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/previous-rancher-api-versions/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index 8db87b8b982..f3ce0e13027 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../reference-guides/about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md index fbbe7813b4e..461e56b0381 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -76,7 +76,7 @@ To manage individual nodes, browse to the cluster that you want to manage and th ## Viewing a Node in the Rancher API -Select this option to view the node's [API endpoints](../../../reference-guides/about-the-api/about-the-api.md). +Select this option to view the node's [API endpoints](../../../api/quickstart.md). ## Deleting a Node diff --git a/docs/reference-guides/cli-with-rancher/kubectl-utility.md b/docs/reference-guides/cli-with-rancher/kubectl-utility.md index fefa1a66b1b..80172c65f3a 100644 --- a/docs/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/docs/reference-guides/cli-with-rancher/kubectl-utility.md @@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully. _Requirements_ -If admins have [kubeconfig token generation turned off](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +If admins have [kubeconfig token generation turned off](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: `Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/previous-rancher-api-versions/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file diff --git a/docs/reference-guides/user-settings/api-keys.md b/docs/reference-guides/user-settings/api-keys.md index d5ff1d1fb24..5a3c97216bf 100644 --- a/docs/reference-guides/user-settings/api-keys.md +++ b/docs/reference-guides/user-settings/api-keys.md @@ -21,7 +21,7 @@ API Keys are composed of four components: :::note -Users may opt to enable [token hashing](../about-the-api/api-tokens.md). +Users may opt to enable [token hashing](../../api/previous-rancher-api-versions/api-tokens.md). ::: diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md index 4ffed1b254b..c61dba41671 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens in Past Rancher Versions -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In previous Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In past Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md index f10a4fd7ec1..33a69728948 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../reference-guides/about-the-api/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/previous-rancher-api-versions/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index 8db87b8b982..f3ce0e13027 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../reference-guides/about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md index fbbe7813b4e..461e56b0381 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -76,7 +76,7 @@ To manage individual nodes, browse to the cluster that you want to manage and th ## Viewing a Node in the Rancher API -Select this option to view the node's [API endpoints](../../../reference-guides/about-the-api/about-the-api.md). +Select this option to view the node's [API endpoints](../../../api/quickstart.md). ## Deleting a Node diff --git a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md index fefa1a66b1b..80172c65f3a 100644 --- a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md @@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully. _Requirements_ -If admins have [kubeconfig token generation turned off](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +If admins have [kubeconfig token generation turned off](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: `Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/previous-rancher-api-versions/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file diff --git a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md index d5ff1d1fb24..5a3c97216bf 100644 --- a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md +++ b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md @@ -21,7 +21,7 @@ API Keys are composed of four components: :::note -Users may opt to enable [token hashing](../about-the-api/api-tokens.md). +Users may opt to enable [token hashing](../../api/previous-rancher-api-versions/api-tokens.md). ::: From f23888fcadc86094c84b752e3edc4135ee0bac11 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 29 Mar 2024 13:18:52 -0700 Subject: [PATCH 06/25] Adding back in About the API section to fix merge conflict. Signed-off-by: Sunil Singh --- .../api-tokens.md | 2 +- .../previous-rancher-api-versions.md | 2 +- .../about-the-api/api-tokens.md | 85 +++++++++++++++++++ .../api-tokens.md | 4 +- .../previous-rancher-api-versions.md | 2 +- .../about-the-api/api-tokens.md | 85 +++++++++++++++++++ 6 files changed, 175 insertions(+), 5 deletions(-) rename docs/api/{previous-rancher-api-versions => }/api-tokens.md (97%) rename docs/api/{previous-rancher-api-versions => }/previous-rancher-api-versions.md (95%) create mode 100644 docs/reference-guides/about-the-api/api-tokens.md rename versioned_docs/version-2.8/api/{previous-rancher-api-versions => }/api-tokens.md (96%) rename versioned_docs/version-2.8/api/{previous-rancher-api-versions => }/previous-rancher-api-versions.md (95%) create mode 100644 versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md diff --git a/docs/api/previous-rancher-api-versions/api-tokens.md b/docs/api/api-tokens.md similarity index 97% rename from docs/api/previous-rancher-api-versions/api-tokens.md rename to docs/api/api-tokens.md index c61dba41671..f4b7b40a532 100644 --- a/docs/api/previous-rancher-api-versions/api-tokens.md +++ b/docs/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens in Past Rancher Versions -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In past Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](../previous-rancher-api-versions#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/docs/api/previous-rancher-api-versions.md similarity index 95% rename from docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md rename to docs/api/previous-rancher-api-versions.md index a82f9d5f2ea..77236ea1ae9 100644 --- a/docs/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/docs/api/previous-rancher-api-versions.md @@ -8,7 +8,7 @@ title: Previous API Guide ## How to Use the API -The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a [web browser](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/docs/reference-guides/about-the-api/api-tokens.md b/docs/reference-guides/about-the-api/api-tokens.md new file mode 100644 index 00000000000..0568de9e149 --- /dev/null +++ b/docs/reference-guides/about-the-api/api-tokens.md @@ -0,0 +1,85 @@ +--- +title: API Tokens +--- + + + + + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. + +You can deactivate API tokens by deleting them or by deactivating the user account. + +## Deleting Tokens + +To delete a token: + +1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. + +1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` + +1. Click **Delete**. + +The following is a complete list of tokens generated with `ttl=0`: + +| Token | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubectl-shell-*` | Access to `kubectl` shell in the browser | +| `agent-*` | Token for agent deployment | +| `compose-token-*` | Token for compose | +| `helm-token-*` | Token for Helm chart deployment | +| `telemetry-*` | Telemetry token | +| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | + +## Setting TTL on Kubeconfig Tokens + +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. + +:::note + +This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). + +::: + +## Disable Tokens in Generated Kubeconfigs + +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. + +## Token Hashing + +Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. + +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). + +This feature affects all tokens which include, but are not limited to, the following: + +- Kubeconfig tokens +- Bearer tokens API keys/calls +- Tokens used by internal operations + +## Token Settings + +These global settings affect Rancher token behavior. + +| Setting | Description | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | + +### auth-user-session-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. + +### kubeconfig-default-token-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. + +### auth-token-max-ttl-minutes + +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md similarity index 96% rename from versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md rename to versioned_docs/version-2.8/api/api-tokens.md index c61dba41671..d7b8abc3a4a 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -1,12 +1,12 @@ --- -title: Using API Tokens in Past Rancher Versions +title: Using API Tokens --- -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. In past Rancher versions `v2.7.x` and below you can access token resources through the previously used [web interface](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](../previous-rancher-api-versions#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/previous-rancher-api-versions.md similarity index 95% rename from versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md rename to versioned_docs/version-2.8/api/previous-rancher-api-versions.md index a82f9d5f2ea..77236ea1ae9 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions/previous-rancher-api-versions.md +++ b/versioned_docs/version-2.8/api/previous-rancher-api-versions.md @@ -8,7 +8,7 @@ title: Previous API Guide ## How to Use the API -The past Rancher versions `v2.7.x` and below have their own API user interfaces accessible from a [web browser](https://ranchermanager.docs.rancher.com/v2.7/reference-guides/about-the-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md new file mode 100644 index 00000000000..0568de9e149 --- /dev/null +++ b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md @@ -0,0 +1,85 @@ +--- +title: API Tokens +--- + + + + + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. + +You can deactivate API tokens by deleting them or by deactivating the user account. + +## Deleting Tokens + +To delete a token: + +1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. + +1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` + +1. Click **Delete**. + +The following is a complete list of tokens generated with `ttl=0`: + +| Token | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubectl-shell-*` | Access to `kubectl` shell in the browser | +| `agent-*` | Token for agent deployment | +| `compose-token-*` | Token for compose | +| `helm-token-*` | Token for Helm chart deployment | +| `telemetry-*` | Telemetry token | +| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | + +## Setting TTL on Kubeconfig Tokens + +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. + +:::note + +This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). + +::: + +## Disable Tokens in Generated Kubeconfigs + +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. + +## Token Hashing + +Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. + +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). + +This feature affects all tokens which include, but are not limited to, the following: + +- Kubeconfig tokens +- Bearer tokens API keys/calls +- Tokens used by internal operations + +## Token Settings + +These global settings affect Rancher token behavior. + +| Setting | Description | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | + +### auth-user-session-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. + +### kubeconfig-default-token-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. + +### auth-token-max-ttl-minutes + +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). From de1b9f3a0877db58efa34b83c66abd885432b648 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 29 Mar 2024 13:24:12 -0700 Subject: [PATCH 07/25] Syncing page with 2.8 version to fix merge conflict. Signed-off-by: Sunil Singh --- .../version-2.8/reference-guides/about-the-api/api-tokens.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md index 0568de9e149..266271f7279 100644 --- a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md +++ b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md @@ -64,8 +64,8 @@ These global settings affect Rancher token behavior. | Setting | Description | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | | [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | ### auth-user-session-ttl-minutes From 0f6dec11ac7536905911a8359d7c5a37a1ab3820 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 29 Mar 2024 14:26:45 -0700 Subject: [PATCH 08/25] This commit consists of removing the old API section completely and updating the API sidebards for Latest/2.8. Subsequent commits will focus on content adjustment as needed. Signed-off-by: Sunil Singh --- .../about-the-api/api-tokens.md | 85 ------------------- sidebars.js | 10 +-- .../about-the-api/api-tokens.md | 85 ------------------- versioned_sidebars/version-2.8-sidebars.json | 10 +-- 4 files changed, 4 insertions(+), 186 deletions(-) delete mode 100644 docs/reference-guides/about-the-api/api-tokens.md delete mode 100644 versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md diff --git a/docs/reference-guides/about-the-api/api-tokens.md b/docs/reference-guides/about-the-api/api-tokens.md deleted file mode 100644 index 0568de9e149..00000000000 --- a/docs/reference-guides/about-the-api/api-tokens.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: API Tokens ---- - - - - - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. - -You can deactivate API tokens by deleting them or by deactivating the user account. - -## Deleting Tokens - -To delete a token: - -1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. - -1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` - -1. Click **Delete**. - -The following is a complete list of tokens generated with `ttl=0`: - -| Token | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `kubectl-shell-*` | Access to `kubectl` shell in the browser | -| `agent-*` | Token for agent deployment | -| `compose-token-*` | Token for compose | -| `helm-token-*` | Token for Helm chart deployment | -| `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | - -## Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. - -:::note - -This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). - -::: - -## Disable Tokens in Generated Kubeconfigs - -Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. - -## Token Hashing - -Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature affects all tokens which include, but are not limited to, the following: - -- Kubeconfig tokens -- Bearer tokens API keys/calls -- Tokens used by internal operations - -## Token Settings - -These global settings affect Rancher token behavior. - -| Setting | Description | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | -| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | - -### auth-user-session-ttl-minutes - -Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. - -### kubeconfig-default-token-ttl-minutes - -Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. - -### auth-token-max-ttl-minutes - -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. - -### kubeconfig-generate-token - -When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/sidebars.js b/sidebars.js index a7cf29f8353..69343b28990 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1353,14 +1353,8 @@ const sidebars = { ] }, "api/api-reference", - { - "type": "category", - "label": "Previous API Versions", - "items": [ - "api/previous-rancher-api-versions/previous-rancher-api-versions", - "api/previous-rancher-api-versions/api-tokens", - ] - }, + "api/api-tokens", + "api/previous-rancher-api-versions", ] }, "contribute-to-rancher", diff --git a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md deleted file mode 100644 index 266271f7279..00000000000 --- a/versioned_docs/version-2.8/reference-guides/about-the-api/api-tokens.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: API Tokens ---- - - - - - -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. - -You can deactivate API tokens by deleting them or by deactivating the user account. - -## Deleting Tokens - -To delete a token: - -1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. - -1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` - -1. Click **Delete**. - -The following is a complete list of tokens generated with `ttl=0`: - -| Token | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `kubectl-shell-*` | Access to `kubectl` shell in the browser | -| `agent-*` | Token for agent deployment | -| `compose-token-*` | Token for compose | -| `helm-token-*` | Token for Helm chart deployment | -| `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | - -## Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. - -:::note - -This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). - -::: - -## Disable Tokens in Generated Kubeconfigs - -Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. - -## Token Hashing - -Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature affects all tokens which include, but are not limited to, the following: - -- Kubeconfig tokens -- Bearer tokens API keys/calls -- Tokens used by internal operations - -## Token Settings - -These global settings affect Rancher token behavior. - -| Setting | Description | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | -| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | - -### auth-user-session-ttl-minutes - -Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. - -### kubeconfig-default-token-ttl-minutes - -Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. - -### auth-token-max-ttl-minutes - -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. - -### kubeconfig-generate-token - -When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index adba2f701cd..c342ab9eae4 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -1313,14 +1313,8 @@ ] }, "api/api-reference", - { - "type": "category", - "label": "Previous API Versions", - "items": [ - "api/previous-rancher-api-versions/previous-rancher-api-versions", - "api/previous-rancher-api-versions/api-tokens" - ] - } + "api/api-tokens", + "api/previous-rancher-api-versions" ] }, "contribute-to-rancher" From d7e29d7c194545d01fa89aee6f1ea5a4938cf842 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 29 Mar 2024 16:00:06 -0700 Subject: [PATCH 09/25] This commit aims to fix the broken markdown links to pass the checker and updates the sidebar structure/titles of pages to add clarification. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 10 +++++----- docs/api/quickstart.md | 2 +- ...rancher-api-versions.md => v3-rancher-api-guide.md} | 4 ++-- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- .../cli-with-rancher/kubectl-utility.md | 4 ++-- docs/reference-guides/user-settings/api-keys.md | 2 +- sidebars.js | 2 +- versioned_docs/version-2.8/api/api-tokens.md | 8 ++++---- versioned_docs/version-2.8/api/quickstart.md | 2 +- ...rancher-api-versions.md => v3-rancher-api-guide.md} | 4 ++-- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- .../cli-with-rancher/kubectl-utility.md | 4 ++-- .../reference-guides/user-settings/api-keys.md | 2 +- versioned_sidebars/version-2.8-sidebars.json | 4 ++-- 16 files changed, 28 insertions(+), 28 deletions(-) rename docs/api/{previous-rancher-api-versions.md => v3-rancher-api-guide.md} (93%) rename versioned_docs/version-2.8/api/{previous-rancher-api-versions.md => v3-rancher-api-guide.md} (93%) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index f4b7b40a532..49c1ffdc2fb 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -1,12 +1,12 @@ --- -title: Using API Tokens in Past Rancher Versions +title: Using API Tokens --- -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](../previous-rancher-api-versions#enable-view-in-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. @@ -46,7 +46,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ### Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. 2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). @@ -54,7 +54,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). This feature will affect all tokens which include, but are not limited to, the following: @@ -89,4 +89,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt **Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** #### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/docs/api/quickstart.md b/docs/api/quickstart.md index 9ec6a5b4611..3077a51188a 100644 --- a/docs/api/quickstart.md +++ b/docs/api/quickstart.md @@ -1,5 +1,5 @@ --- -title: API Quick Start Guide +title: RK-API Quick Start Guide --- diff --git a/docs/api/previous-rancher-api-versions.md b/docs/api/v3-rancher-api-guide.md similarity index 93% rename from docs/api/previous-rancher-api-versions.md rename to docs/api/v3-rancher-api-guide.md index 77236ea1ae9..c55b7b0faa5 100644 --- a/docs/api/previous-rancher-api-versions.md +++ b/docs/api/v3-rancher-api-guide.md @@ -1,5 +1,5 @@ --- -title: Previous API Guide +title: Previous v3 Rancher API Guide --- @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). diff --git a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md index 33a69728948..0fc4db611e1 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/previous-rancher-api-versions/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index f3ce0e13027..e7813dc740a 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/docs/reference-guides/cli-with-rancher/kubectl-utility.md b/docs/reference-guides/cli-with-rancher/kubectl-utility.md index 80172c65f3a..39989372e92 100644 --- a/docs/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/docs/reference-guides/cli-with-rancher/kubectl-utility.md @@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully. _Requirements_ -If admins have [kubeconfig token generation turned off](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +If admins have [kubeconfig token generation turned off](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: `Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/previous-rancher-api-versions/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file diff --git a/docs/reference-guides/user-settings/api-keys.md b/docs/reference-guides/user-settings/api-keys.md index 5a3c97216bf..356439ad59f 100644 --- a/docs/reference-guides/user-settings/api-keys.md +++ b/docs/reference-guides/user-settings/api-keys.md @@ -21,7 +21,7 @@ API Keys are composed of four components: :::note -Users may opt to enable [token hashing](../../api/previous-rancher-api-versions/api-tokens.md). +Users may opt to enable [token hashing](../../api/api-tokens.md). ::: diff --git a/sidebars.js b/sidebars.js index 69343b28990..54ec7429574 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1354,7 +1354,7 @@ const sidebars = { }, "api/api-reference", "api/api-tokens", - "api/previous-rancher-api-versions", + "api/v3-rancher-api-guide", ] }, "contribute-to-rancher", diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index d7b8abc3a4a..49c1ffdc2fb 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](../api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](../previous-rancher-api-versions#enable-view-in-api). +Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. @@ -46,7 +46,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ### Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. 2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). @@ -54,7 +54,7 @@ This setting is used by all kubeconfig tokens except those created by the CLI to Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). This feature will affect all tokens which include, but are not limited to, the following: @@ -89,4 +89,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt **Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** #### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/quickstart.md b/versioned_docs/version-2.8/api/quickstart.md index 9ec6a5b4611..3077a51188a 100644 --- a/versioned_docs/version-2.8/api/quickstart.md +++ b/versioned_docs/version-2.8/api/quickstart.md @@ -1,5 +1,5 @@ --- -title: API Quick Start Guide +title: RK-API Quick Start Guide --- diff --git a/versioned_docs/version-2.8/api/previous-rancher-api-versions.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md similarity index 93% rename from versioned_docs/version-2.8/api/previous-rancher-api-versions.md rename to versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 77236ea1ae9..c55b7b0faa5 100644 --- a/versioned_docs/version-2.8/api/previous-rancher-api-versions.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -1,5 +1,5 @@ --- -title: Previous API Guide +title: Previous v3 Rancher API Guide --- @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md index 33a69728948..0fc4db611e1 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/previous-rancher-api-versions/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index f3ce0e13027..e7813dc740a 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md index 80172c65f3a..49fe73d5d12 100644 --- a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md @@ -22,7 +22,7 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully. _Requirements_ -If admins have [kubeconfig token generation turned off](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +If admins have [kubeconfig token generation turned off](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: `Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/previous-rancher-api-versions/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/previous-rancher-api-versions/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. diff --git a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md index 5a3c97216bf..356439ad59f 100644 --- a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md +++ b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md @@ -21,7 +21,7 @@ API Keys are composed of four components: :::note -Users may opt to enable [token hashing](../../api/previous-rancher-api-versions/api-tokens.md). +Users may opt to enable [token hashing](../../api/api-tokens.md). ::: diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index c342ab9eae4..0f348f242b4 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -1305,6 +1305,7 @@ "label": "Rancher Kubernetes API", "items": [ "api/quickstart", + "api/v3-rancher-api-guide", { "type": "category", "label": "Example Workflows", @@ -1312,9 +1313,8 @@ "api/workflows/projects" ] }, - "api/api-reference", "api/api-tokens", - "api/previous-rancher-api-versions" + "api/api-reference" ] }, "contribute-to-rancher" From 1b6f3ee909ce353dbd59037407a02273f5c15f62 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Mon, 1 Apr 2024 08:57:42 -0700 Subject: [PATCH 10/25] Updating markdown link error tied to pages-for-subheaders. Signed-off-by: Sunil Singh --- .../gke-cluster-configuration/gke-cluster-configuration.md | 2 +- .../resources/helm-version-requirements.md | 2 +- .../gke-cluster-configuration/gke-cluster-configuration.md | 2 +- .../set-up-cloud-providers/amazon.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md index f3ba98c2cf0..78564d636ab 100644 --- a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md +++ b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -199,7 +199,7 @@ _Mutable: yes_ The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) -> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/pages-for-subheaders/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [logging feature as of v2.5](../../../../explanations/integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. +> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [logging feature as of v2.5](../../../../explanations/integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. > Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. diff --git a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md index 2b1204b6115..21fd44abe15 100644 --- a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md +++ b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md @@ -8,7 +8,7 @@ title: Helm Version Requirements This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster. -> The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 Migration Docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section](../../../../version-2.0-2.4/pages-for-subheaders/helm2.md) provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. +> The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 Migration Docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section](/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm2.md) provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. - Helm v3.2.x or higher is required to install or upgrade Rancher v2.5. - Helm v2.16.0 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the [release notes](https://github.com/rancher/rke/releases) for the version of RKE that you are using. diff --git a/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md index dea8738c63c..5cd3a9c52b9 100644 --- a/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md +++ b/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -204,7 +204,7 @@ The node operating system image. For more information for the node image options :::note -The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/pages-for-subheaders/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature](../../../../integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. +The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature](../../../../integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. ::: diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md index 3483b28f07d..e561cbc80ca 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md @@ -299,7 +299,7 @@ rancher_kubernetes_engine_config: useInstanceMetadataHostname: true ``` -You must not enable `useInstanceMetadataHostname` when setting custom values for `hostname-override` for custom clusters. When you create a [custom cluster](../../../../pages-for-subheaders/use-existing-nodes.md), add [`--node-name`](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) to the `docker run` node registration command to set `hostname-override` — for example, `"$(hostname -f)"`. This can be done manually or by using **Show Advanced Options** in the Rancher UI to add **Node Name**. +You must not enable `useInstanceMetadataHostname` when setting custom values for `hostname-override` for custom clusters. When you create a [custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes), add [`--node-name`](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) to the `docker run` node registration command to set `hostname-override` — for example, `"$(hostname -f)"`. This can be done manually or by using **Show Advanced Options** in the Rancher UI to add **Node Name**. 2. Select the cloud provider. From 6a7782a6a6d77af1fef4a44250d5e6c00366ca4c Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Mon, 1 Apr 2024 14:59:10 -0700 Subject: [PATCH 11/25] Fixing merge conflict. Signed-off-by: Sunil Singh --- .../gke-cluster-configuration/gke-cluster-configuration.md | 2 +- .../gke-cluster-configuration/gke-cluster-configuration.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md index 78564d636ab..f6614c5a300 100644 --- a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md +++ b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -199,7 +199,7 @@ _Mutable: yes_ The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) -> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [logging feature as of v2.5](../../../../explanations/integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. +> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [logging feature as of v2.5](../../../../explanations/integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. > Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. diff --git a/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md index 5cd3a9c52b9..9d7a2abb0d6 100644 --- a/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md +++ b/versioned_docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -204,7 +204,7 @@ The node operating system image. For more information for the node image options :::note -The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](../../../../../version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature](../../../../integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. +The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature](../../../../integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. ::: From 10baedc1dc46b8495d15bdc67a1b7dcb20412c73 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 10:38:18 -0700 Subject: [PATCH 12/25] Updating the redirects to point to new v3-rancher-api-guide.md page. Signed-off-by: Sunil Singh --- docusaurus.config.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 7b0959d0a8b..70055b8ff37 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1690,11 +1690,11 @@ module.exports = { from: '/v2.8/pages-for-subheaders/about-rke1-templates' }, { - to: '/v2.8/api/previous-rancher-api-versions', + to: '/v2.8/api/v3-rancher-api-guide', from: '/v2.8/pages-for-subheaders/about-the-api' }, { - to: '/v2.8/api/previous-rancher-api-versions', + to: '/v2.8/api/v3-rancher-api-guide', from: '/v2.8/reference-guides/about-the-api' }, { @@ -2042,7 +2042,7 @@ module.exports = { from: '/pages-for-subheaders/about-rke1-templates' }, { - to: '/api/previous-rancher-api-versions', + to: '/api/v3-rancher-api-guide', from: '/pages-for-subheaders/about-the-api' }, { From b48217361566354393dafb09e848bed218b29f8a Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 11:14:03 -0700 Subject: [PATCH 13/25] Updating some wording and aligning the sidebars for latest and v2.8. Signed-off-by: Sunil Singh --- docs/api/v3-rancher-api-guide.md | 2 +- versioned_docs/version-2.8/api/v3-rancher-api-guide.md | 2 +- versioned_sidebars/version-2.8-sidebars.json | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index c55b7b0faa5..2a5417b35e1 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -8,7 +8,7 @@ title: Previous v3 Rancher API Guide ## How to Use the API -The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index c55b7b0faa5..2a5417b35e1 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -8,7 +8,7 @@ title: Previous v3 Rancher API Guide ## How to Use the API -The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index 0f348f242b4..9ccfa0a271f 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -1305,7 +1305,6 @@ "label": "Rancher Kubernetes API", "items": [ "api/quickstart", - "api/v3-rancher-api-guide", { "type": "category", "label": "Example Workflows", @@ -1313,8 +1312,9 @@ "api/workflows/projects" ] }, + "api/api-reference", "api/api-tokens", - "api/api-reference" + "api/v3-rancher-api-guide" ] }, "contribute-to-rancher" From 3ef0b1db0162e37fe63362cfcec0f79397acc619 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 12:27:58 -0700 Subject: [PATCH 14/25] Adding redirects for new pages from old URL's and grouping more logically in the config file. Signed-off-by: Sunil Singh --- docusaurus.config.js | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 70055b8ff37..35720dbe5b7 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1693,10 +1693,6 @@ module.exports = { to: '/v2.8/api/v3-rancher-api-guide', from: '/v2.8/pages-for-subheaders/about-the-api' }, - { - to: '/v2.8/api/v3-rancher-api-guide', - from: '/v2.8/reference-guides/about-the-api' - }, { to: '/v2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters', from: '/v2.8/pages-for-subheaders/access-clusters' @@ -3436,7 +3432,25 @@ module.exports = { { to: '/v2.7/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale', from: '/v2.7/reference-guides/best-practices/rancher-server/tips-for-scaling-rancher' + }, + // Redirects for restructure from PR #1147 (start) + { + to: '/v2.8/api/v3-rancher-api-guide', + from: '/v2.8/reference-guides/about-the-api' + }, + { + to: '/v2.8/api/api-tokens', + from: '/v2.8/reference-guides/about-the-api/api-tokens' + }, + { + to: '/api/v3-rancher-api-guide', + from: '/reference-guides/about-the-api' + }, + { + to: '/api/api-tokens', + from: '/reference-guides/about-the-api/api-tokens' } + // Redirects for restructure from PR #1147 (end) ], }, ], From 9beef5c1fa3d815c3fbab20e6f3f49dc4e6769cf Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 14:11:05 -0700 Subject: [PATCH 15/25] Syncing with PR 1184 and editing the canonical links to correct URL. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 61 +++++++++--------- docs/api/v3-rancher-api-guide.md | 2 +- versioned_docs/version-2.8/api/api-tokens.md | 63 +++++++++---------- .../version-2.8/api/v3-rancher-api-guide.md | 2 +- 4 files changed, 59 insertions(+), 69 deletions(-) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index 49c1ffdc2fb..f5c00c5da06 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -3,7 +3,7 @@ title: Using API Tokens --- - + Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). @@ -12,8 +12,9 @@ By default, some cluster-level API tokens are generated with infinite time-to-li You can deactivate API tokens by deleting them or by deactivating the user account. -### Deleting tokens -To delete a token, +## Deleting Tokens + +To delete a token: 1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. @@ -21,22 +22,20 @@ To delete a token, 1. Click **Delete**. -Here is the complete list of tokens that are generated with `ttl=0`: +The following is a complete list of tokens generated with `ttl=0`: | Token | Description | | ----------------- | -------------------------------------------------------------------------------------- | -| `kubeconfig-*` | Kubeconfig token | | `kubectl-shell-*` | Access to `kubectl` shell in the browser | | `agent-*` | Token for agent deployment | | `compose-token-*` | Token for compose | | `helm-token-*` | Token for Helm chart deployment | | `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | +| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | +## Setting TTL on Kubeconfig Tokens -### Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means tokens never expire. +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. :::note @@ -44,49 +43,45 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ::: -### Disable Tokens in Generated Kubeconfigs +## Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. -2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). +## Token Hashing -### Token Hashing +Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). -To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature will affect all tokens which include, but are not limited to, the following: +This feature affects all tokens which include, but are not limited to, the following: - Kubeconfig tokens - Bearer tokens API keys/calls - Tokens used by internal operations -### Token Settings +## Token Settings + These global settings affect Rancher token behavior. | Setting | Description | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | -| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | | [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | | [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | -#### auth-user-session-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. +### auth-user-session-ttl-minutes -#### kubeconfig-default-token-TTL-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). -**Introduced in version 2.6.6**. +Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. -#### kubeconfig-token-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when [`kubeconfig-generate-token`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). -**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).** +### kubeconfig-default-token-ttl-minutes -#### auth-token-max-ttl-minutes -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. -**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** +Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. -#### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +### auth-token-max-ttl-minutes + +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 2a5417b35e1..200a8179920 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -3,7 +3,7 @@ title: Previous v3 Rancher API Guide --- - + ## How to Use the API diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index 49c1ffdc2fb..fa33f0b9b8e 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -3,7 +3,7 @@ title: Using API Tokens --- - + Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). @@ -12,8 +12,9 @@ By default, some cluster-level API tokens are generated with infinite time-to-li You can deactivate API tokens by deleting them or by deactivating the user account. -### Deleting tokens -To delete a token, +## Deleting Tokens + +To delete a token: 1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. @@ -21,22 +22,20 @@ To delete a token, 1. Click **Delete**. -Here is the complete list of tokens that are generated with `ttl=0`: +The following is a complete list of tokens generated with `ttl=0`: | Token | Description | | ----------------- | -------------------------------------------------------------------------------------- | -| `kubeconfig-*` | Kubeconfig token | | `kubectl-shell-*` | Access to `kubectl` shell in the browser | | `agent-*` | Token for agent deployment | | `compose-token-*` | Token for compose | | `helm-token-*` | Token for Helm chart deployment | | `telemetry-*` | Telemetry token | -| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) | +| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | +## Setting TTL on Kubeconfig Tokens -### Setting TTL on Kubeconfig Tokens - -Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is 0, which means tokens never expire. +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. :::note @@ -44,49 +43,45 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ::: -### Disable Tokens in Generated Kubeconfigs +## Disable Tokens in Generated Kubeconfigs -1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. -2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). +## Token Hashing -### Token Hashing +Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. +To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). -To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). - -This feature will affect all tokens which include, but are not limited to, the following: +This feature affects all tokens which include, but are not limited to, the following: - Kubeconfig tokens - Bearer tokens API keys/calls - Tokens used by internal operations -### Token Settings +## Token Settings + These global settings affect Rancher token behavior. | Setting | Description | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | -| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). **Introduced in version 2.6.6.** | -| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | TTL used for tokens generated via the CLI. **Deprecated since version 2.6.6, and will be removed in 2.8.0.** This setting will be removed, and `kubeconfig-default-token-TTL-minutes` will be used for all kubeconfig tokens. | -| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | | [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | -#### auth-user-session-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a user auth session token expires. When expired, the user will be required to log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. +### auth-user-session-ttl-minutes -#### kubeconfig-default-token-TTL-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token expires. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to a token generated in a requested kubeconfig file. Except those [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). -**Introduced in version 2.6.6**. +Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. -#### kubeconfig-token-ttl-minutes -Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when [`kubeconfig-generate-token`](#kubeconfig-generate-token) is false. When the token is expired, the API will reject the token. This setting can not be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). -**Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes).** +### kubeconfig-default-token-ttl-minutes -#### auth-token-max-ttl-minutes -Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher will set the token TTL to the value of `auth-token-max-ttl-minutes`. Auth tokens are tokens created for authenticating API requests. -**Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.** +Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. -#### kubeconfig-generate-token -When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then will retrieve and cache a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +### auth-token-max-ttl-minutes + +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 2a5417b35e1..200a8179920 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -3,7 +3,7 @@ title: Previous v3 Rancher API Guide --- - + ## How to Use the API From 67d22738f11fc33069f64cfa37b8e6a49e72d8cf Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 14:14:36 -0700 Subject: [PATCH 16/25] Removing backticks after review. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 2 +- versioned_docs/version-2.8/api/api-tokens.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index f5c00c5da06..09b3d1d5a00 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index fa33f0b9b8e..8e164ea7564 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher `v2.8.0` introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. From e9eefeb03fc00fab3b2ef85bf5b8a9d570e2d04a Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 2 Apr 2024 14:28:09 -0700 Subject: [PATCH 17/25] Resyncing new links in API tokens page. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 6 +++--- versioned_docs/version-2.8/api/api-tokens.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index 09b3d1d5a00..7d9e632a1b3 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -45,13 +45,13 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ## Disable Tokens in Generated Kubeconfigs -Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. ## Token Hashing Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). This feature affects all tokens which include, but are not limited to, the following: @@ -84,4 +84,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt ### kubeconfig-generate-token -When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index 8e164ea7564..9e9b9a9d0cd 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -45,13 +45,13 @@ This setting is used by all kubeconfig tokens except those created by the CLI to ## Disable Tokens in Generated Kubeconfigs -Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. ## Token Hashing Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. -To enable token hashing, refer to [this section](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). This feature affects all tokens which include, but are not limited to, the following: @@ -84,4 +84,4 @@ Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempt ### kubeconfig-generate-token -When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). From 62733510ecad46942b3c59eb13c7d637a2e59898 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 7 May 2024 11:24:53 -0700 Subject: [PATCH 18/25] Adjusting links and information after reviews and adjusting syntax to be in line with SUSE style guide. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 6 ++---- docs/api/v3-rancher-api-guide.md | 4 ++-- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- docs/reference-guides/cli-with-rancher/kubectl-utility.md | 2 +- versioned_docs/version-2.8/api/api-tokens.md | 2 +- versioned_docs/version-2.8/api/v3-rancher-api-guide.md | 4 ++-- .../installation-references/feature-flags.md | 2 +- .../access-clusters/authorized-cluster-endpoint.md | 2 +- .../reference-guides/cli-with-rancher/kubectl-utility.md | 2 +- 10 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index 7d9e632a1b3..b71c53bcdcd 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform, and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. @@ -49,9 +49,7 @@ Set the `kubeconfig-generate-token` setting to `false`. This setting instructs R ## Token Hashing -Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. This feature affects all tokens which include, but are not limited to, the following: diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 200a8179920..ffadd8138fd 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). @@ -47,7 +47,7 @@ The API is generally RESTful but has several features to make the definition of - In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. diff --git a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md index ecc870fb48a..de153cd50e1 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index e7813dc740a..588f33fb030 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/docs/reference-guides/cli-with-rancher/kubectl-utility.md b/docs/reference-guides/cli-with-rancher/kubectl-utility.md index 39989372e92..b3f49191ede 100644 --- a/docs/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/docs/reference-guides/cli-with-rancher/kubectl-utility.md @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. \ No newline at end of file +When you first run kubectl, for example, `kubectl get pods`, you are prompted to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, you must log in with the Rancher server again to run the `kubectl get pods` command. diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index 9e9b9a9d0cd..9114b037d56 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl` or the [web interface](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform, and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 200a8179920..edb5e58b71d 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -27,7 +27,7 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). @@ -47,7 +47,7 @@ The API is generally RESTful but has several features to make the definition of - In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md index ecc870fb48a..de153cd50e1 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -26,7 +26,7 @@ The following is a list of feature flags available in Rancher. If you've upgrade - `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. - `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. - `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. - `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index e7813dc740a..588f33fb030 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -23,7 +23,7 @@ You will need a separate kubeconfig file for each cluster that you have access t After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. -If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires [rancher cli](./authorized-cluster-endpoint.md) to be present in your PATH. +If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH. ### Two Authentication Methods for RKE Clusters diff --git a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md index 49fe73d5d12..b3f49191ede 100644 --- a/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/versioned_docs/version-2.8/reference-guides/cli-with-rancher/kubectl-utility.md @@ -33,4 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n 4. OpenLDAP 5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. +When you first run kubectl, for example, `kubectl get pods`, you are prompted to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, you must log in with the Rancher server again to run the `kubectl get pods` command. From 21764c96eb06e4965da8298def8340a95e8a8fad Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Tue, 7 May 2024 12:03:21 -0700 Subject: [PATCH 19/25] Fixing spacing. Signed-off-by: Sunil Singh --- docs/api/v3-rancher-api-guide.md | 8 ++++---- versioned_docs/version-2.8/api/v3-rancher-api-guide.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index ffadd8138fd..5333b5fb186 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -45,9 +45,9 @@ The API is generally RESTful but has several features to make the definition of - So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. @@ -59,11 +59,11 @@ The API is generally RESTful but has several features to make the definition of ## Filtering -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. ## Sorting -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. ## Pagination diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index edb5e58b71d..730a5b29e72 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -45,9 +45,9 @@ The API is generally RESTful but has several features to make the definition of - So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. - Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. @@ -59,11 +59,11 @@ The API is generally RESTful but has several features to make the definition of ## Filtering -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. ## Sorting -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. ## Pagination From d32bc64e77f21e46fffe22e025457d659f181f15 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Thu, 9 May 2024 12:12:04 -0700 Subject: [PATCH 20/25] Squashing vale commits Signed-off-by: Sunil Singh --- .github/workflows/vale.yml | 5 + docs/api/api-tokens.md | 4 +- docs/api/quickstart.md | 4 +- docs/api/v3-rancher-api-guide.md | 36 +- .../installation-references/feature-flags.md | 20 +- .../configure-azure-ad.md | 3 + .../authorized-cluster-endpoint.md | 6 +- .../manage-clusters/nodes-and-node-pools.md | 33 +- .../user-settings/api-keys.md | 6 +- .../version-2.6.json | 130 +++---- .../version-2.6/faq/deprecated-features.md | 37 ++ .../version-2.6/faq/general-faq.md | 66 ++-- .../air-gapped-upgrades.md | 32 +- ...install-upgrade-on-a-kubernetes-cluster.md | 356 ++++++++++++++++++ .../rancher-on-aks.md | 8 +- .../rancher-on-amazon-eks.md | 6 +- .../rancher-on-gke.md | 4 +- .../upgrades.md | 4 +- .../installation-and-upgrade.md | 94 +++++ .../installation-references/feature-flags.md | 2 +- .../helm-chart-options.md | 10 +- .../installation-references.md | 5 + .../install-docker.md | 12 +- .../installation-requirements.md | 215 +++++++++++ .../port-requirements.md | 10 +- .../air-gapped-helm-cli-install.md | 31 ++ .../infrastructure-private-registry.md | 2 +- .../publish-images.md | 4 +- .../other-installation-methods.md | 19 + .../rancher-behind-an-http-proxy.md | 13 + .../set-up-infrastructure.md | 2 +- .../certificate-troubleshooting.md | 2 + .../rancher-on-a-single-node-with-docker.md | 209 ++++++++++ .../roll-back-docker-installed-rancher.md | 4 +- .../upgrade-docker-installed-rancher.md | 2 +- .../resources/add-tls-secrets.md | 2 +- .../resources/choose-a-rancher-version.md | 2 +- .../resources/helm-version-requirements.md | 2 +- .../resources/local-system-charts.md | 2 +- .../resources/resources.md | 25 ++ .../upgrade-and-roll-back-kubernetes.md | 4 +- ...de-kubernetes-without-upgrading-rancher.md | 2 +- .../version-2.6/getting-started/overview.md | 20 +- .../deploy-rancher-manager/aws-marketplace.md | 6 +- .../deploy-rancher-manager/aws.md | 4 +- .../deploy-rancher-manager/azure.md | 4 +- .../deploy-rancher-manager.md | 20 + .../deploy-rancher-manager/digitalocean.md | 4 +- .../deploy-rancher-manager/equinix-metal.md | 6 +- .../deploy-rancher-manager/gcp.md | 4 +- .../deploy-rancher-manager/helm-cli.md | 3 +- .../deploy-rancher-manager/hetzner-cloud.md | 4 +- .../deploy-rancher-manager/linode.md | 79 ++++ .../deploy-rancher-manager/outscale-qs.md | 4 +- .../deploy-rancher-manager/vagrant.md | 4 +- .../deploy-workloads/deploy-workloads.md | 8 + .../quick-start-guides/quick-start-guides.md | 17 + .../cis-scan-guides/cis-scan-guides.md | 17 + .../enable-experimental-features.md | 125 ++++++ .../istio-setup-guide/istio-setup-guide.md | 34 ++ .../monitoring-alerting-guides.md | 15 + .../prometheus-federator-guides.md | 12 + .../advanced-configuration.md | 19 + .../advanced-configuration/prometheusrules.md | 2 +- .../monitoring-v2-configuration-guides.md | 55 +++ .../about-provisioning-drivers.md | 51 +++ .../about-rke1-templates.md | 130 +++++++ .../authentication-config.md | 145 +++++++ ...on-permissions-and-global-configuration.md | 57 +++ ...re-microsoft-ad-federation-service-saml.md | 39 ++ .../configure-ms-adfs-for-rancher.md | 4 + .../configure-rancher-for-ms-adfs.md | 4 + .../configure-openldap/configure-openldap.md | 56 +++ .../openldap-config-reference.md | 2 +- .../about-group-permissions.md | 8 +- .../configure-shibboleth-saml.md | 104 +++++ .../manage-role-based-access-control-rbac.md | 29 ++ .../infrastructure-setup.md | 12 + .../kubernetes-cluster-setup.md | 11 + ...checklist-for-production-ready-clusters.md | 52 +++ .../kubernetes-clusters-in-rancher-setup.md | 80 ++++ .../set-up-cloud-providers.md | 47 +++ ...usters-from-hosted-kubernetes-providers.md | 33 ++ .../use-windows-clusters.md | 290 ++++++++++++++ .../access-clusters/access-clusters.md | 35 ++ .../create-kubernetes-persistent-storage.md | 78 ++++ .../install-cluster-autoscaler.md | 28 ++ .../manage-clusters/manage-clusters.md | 36 ++ .../provisioning-storage-examples.md | 15 + .../new-user-guides/new-user-guides.md | 13 + .../cis-scans/cis-scans.md | 110 ++++++ .../aws-cloud-marketplace.md | 36 ++ .../cloud-marketplace/cloud-marketplace.md | 11 + .../fleet-gitops-at-scale.md | 67 ++++ .../configuration-options.md | 43 +++ .../integrations-in-rancher/istio/istio.md | 148 ++++++++ .../custom-resource-configuration.md | 12 + .../logging/logging.md | 140 +++++++ .../monitoring-and-alerting.md | 100 +++++ .../about-the-api/about-the-api.md | 84 +++++ .../about-the-api/api-tokens.md | 4 + .../backup-restore-configuration.md | 12 + .../best-practices/best-practices.md | 21 ++ .../rancher-managed-clusters.md | 23 ++ .../rancher-server/rancher-server.md | 21 ++ ...and-best-practices-for-rancher-at-scale.md | 117 ++++++ .../cli-with-rancher/cli-with-rancher.md | 9 + .../cli-with-rancher/kubectl-utility.md | 4 + .../cli-with-rancher/rancher-cli.md | 4 + .../cluster-configuration.md | 32 ++ .../downstream-cluster-configuration.md | 9 + .../machine-configuration.md | 9 + .../node-template-configuration.md | 9 + .../gke-cluster-configuration.md | 324 ++++++++++++++++ .../rancher-server-configuration.md | 16 + .../use-existing-nodes/use-existing-nodes.md | 141 +++++++ .../monitoring-v2-configuration.md | 15 + .../reference-guides/pipelines/pipelines.md | 278 ++++++++++++++ .../prometheus-federator.md | 108 ++++++ .../rancher-manager-architecture.md | 21 ++ .../kubernetes-security-best-practices.md | 4 + .../rancher-security/rancher-security.md | 87 +++++ .../rancher-v2.6-hardening-guides.md | 50 +++ .../security-advisories-and-cves.md | 8 + .../selinux-rpm/selinux-rpm.md | 20 + .../single-node-rancher-in-docker.md | 9 + .../user-settings/user-settings.md | 19 + .../_cluster-capabilities-table.md | 20 +- .../kubernetes-components.md | 21 ++ .../about-provisioning-drivers.md | 2 +- .../configure-azure-ad.md | 4 + .../configure-azure-ad.md | 3 + .../configure-azure-ad.md | 3 + .../configure-azure-ad.md | 3 + versioned_docs/version-2.8/api/api-tokens.md | 4 +- versioned_docs/version-2.8/api/quickstart.md | 4 +- .../version-2.8/api/v3-rancher-api-guide.md | 36 +- .../installation-references/feature-flags.md | 20 +- .../configure-azure-ad.md | 3 + .../authorized-cluster-endpoint.md | 6 +- .../manage-clusters/nodes-and-node-pools.md | 33 +- .../user-settings/api-keys.md | 6 +- 142 files changed, 5241 insertions(+), 312 deletions(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/deprecated-features.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-and-upgrade.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/installation-references.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/resources.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/linode.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/quick-start-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/new-user-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cis-scans/cis-scans.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/fleet-gitops-at-scale.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/configuration-options/configuration-options.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/istio.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/logging.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/about-the-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/backup-restore-configuration/backup-restore-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/best-practices.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/rancher-server.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/cli-with-rancher.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/cluster-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/pipelines/pipelines.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/prometheus-federator/prometheus-federator.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-security.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rancher-v2.6-hardening-guides.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/user-settings/user-settings.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-2.6/troubleshooting/kubernetes-components/kubernetes-components.md diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index a695beac412..bdd2a453b3c 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -13,10 +13,12 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + continue-on-error: true with: fetch-depth: 0 # OR "2" -> To retrieve the preceding commit. submodules: true - name: Get all changed markdown files + continue-on-error: true id: changed-markdown-files uses: tj-actions/changed-files@v42 with: @@ -29,11 +31,13 @@ jobs: env: ALL_CHANGED_FILES: ${{ 0 }} - name: No files changed? + continue-on-error: true if: steps.changed-markdown-files.outputs.any_changed == 'false' run: | echo "No files changed" echo "ALL_CHANGED_FILES=$ALL_CHANGED_FILES" >> $GITHUB_ENV - name: List all changed files markdown files + continue-on-error: true if: steps.changed-markdown-files.outputs.any_changed == 'true' env: ALL_CHANGED_FILES: ${{ steps.changed-markdown-files.outputs.all_changed_files }} @@ -45,6 +49,7 @@ jobs: echo ${ALL_CHANGED_FILES} echo "ALL_CHANGED_FILES=$ALL_CHANGED_FILES" >> $GITHUB_ENV - uses: errata-ai/vale-action@v2.1.0 + continue-on-error: true if: steps.changed-markdown-files.outputs.any_changed == 'true' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index b71c53bcdcd..6552eca4156 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform, and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. @@ -49,7 +49,7 @@ Set the `kubeconfig-generate-token` setting to `false`. This setting instructs R ## Token Hashing -You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. +You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups before enabling and/or evaluating in a test environment first. This feature affects all tokens which include, but are not limited to, the following: diff --git a/docs/api/quickstart.md b/docs/api/quickstart.md index 3077a51188a..2b215857a39 100644 --- a/docs/api/quickstart.md +++ b/docs/api/quickstart.md @@ -6,7 +6,7 @@ title: RK-API Quick Start Guide -You can access Rancher's resources through the Kubernetes API. This guide will help you get started on using this API as a Rancher user. +You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user. 1. In the upper left corner, click **☰ > Global Settings**. 2. Find and copy the address in the `server-url` field. @@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. ::: -4. The following commands will convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: +4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: ```bash export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 5333b5fb186..3976657a7db 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -8,14 +8,14 @@ title: Previous v3 Rancher API Guide ## How to Use the API -The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it: -1. Click on your user avatar in the upper right corner. -1. Click **Account & API Keys**. -1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. +1. Click your user avatar in the upper right corner. +1. Click **Account & API Keys**. +1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. @@ -29,11 +29,11 @@ Go to the URL endpoint at `https:///v3`, where `` is API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). +By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). ## Making requests -The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). +The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md). - Every type has a Schema which describes: - The URL to get to the collection of this type of resources @@ -43,31 +43,31 @@ The API is generally RESTful but has several features to make the definition of - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. +- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +- In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. - Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. +- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Certain actions require input or produce output, see the individual documentation for each type or the schemas for specific information. -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. +- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. +- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). ## Filtering -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. ## Sorting -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. ## Pagination -API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. +API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. ## Capturing Rancher API Calls @@ -76,18 +76,18 @@ You can use browser developer tools to capture how the Rancher API is called. Fo 1. In the Rancher UI, go to **Cluster Management** and click **Create.** 1. Click one of the cluster types. This example uses Digital Ocean. 1. Fill out the form with a cluster name and node template, but don't click **Create**. -1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** +1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.** 1. In the developer tools, click the **Network** tab. 1. On the **Network** tab, make sure **Fetch/XHR** is selected. 1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. 1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** -1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. +1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials. ### Enable View in API You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: -1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. +1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu. 2. Under the **Advanced Features** section, click **Enable "View in API"** -Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. +Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI. diff --git a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md index de153cd50e1..70c35e18d34 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -18,16 +18,16 @@ Some feature flags require a restart of the Rancher container. Features that req The following is a list of feature flags available in Rancher. If you've upgraded from a previous Rancher version, you may see additional flags in the Rancher UI, such as `proxy` or `dashboard` (both [discontinued](/versioned_docs/version-2.5/reference-guides/installation-references/feature-flags.md)): -- `continuous-delivery`: Allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. -- `fleet`: The Rancher provisioning framework in v2.6 and later requires Fleet. The flag will be automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. -- `harvester`: Manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. -- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. -- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. -- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. -- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. -- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. -- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. +- `continuous-delivery`: allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. +- `fleet`: the Rancher provisioning framework in v2.6 and later requires Fleet. The flag is automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. +- `harvester`: manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. +- `istio-virtual-service-ui`: enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. +- `legacy`: enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features scheduled to be available in newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. +- `multi-cluster-management`: allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. +- `rke1-custom-node-cleanup`: enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. +- `rke2`: enables provisioning RKE2 clusters. This flag is enabled by default. +- `token-hashing`: enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `unsupported-storage-drivers`: enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md index d9950de322d..817a490ecda 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -225,6 +225,9 @@ To complete configuration, enter information about your AD instance in the Ranch **Result:** Azure Active Directory authentication is configured. +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). ### Migrating from Azure AD Graph API to Microsoft Graph API diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index 588f33fb030..9d88e779b12 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -19,9 +19,9 @@ The kubeconfig file and its contents are specific to each cluster. It can be dow 1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row. 1. Select **Download KubeConfig** from the submenu. -You will need a separate kubeconfig file for each cluster that you have access to in Rancher. +You need a separate kubeconfig file for each cluster that you have access to in Rancher. -After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. +After you download the kubeconfig file, you are able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH. @@ -36,7 +36,7 @@ For RKE clusters, the kubeconfig file allows you to be authenticated in two ways This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher. -To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) +To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters. diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md index 461e56b0381..b8c2133a475 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -100,7 +100,7 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster. -1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH will be downloaded. +1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH is then downloaded. 1. Extract the ZIP file to any location. 1. Open Terminal. Change your location to the extracted ZIP file. 1. Enter the following command: @@ -111,13 +111,13 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch ## Cordoning a Node -_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. +_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. ## Draining a Node _Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption. -- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod. +- For pods with a replica set, the pod is replaced by a new pod that is scheduled to a new node. Additionally, if the pod is part of a service, then clients are automatically redirected to the new pod. - For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it. @@ -127,20 +127,21 @@ However, you can override the conditions draining when you initiate the drain. Y ### Aggressive and Safe Draining Options -When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled. +When you configure the upgrade strategy for the cluster, you can enable node draining. If node draining is enabled, you are able to configure how pods are deleted and rescheduled. - **Aggressive Mode** In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. - Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods. + Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir is deleted once the pod is removed from the node. Choosing aggressive mode deletes these pods. - **Safe Mode** - If a node has standalone pods or ephemeral data it will be cordoned but not drained. + If a node has stand-alone pods or ephemeral data it is cordoned but not drained. + ### Grace Period -The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used. +The timeout given to each pod for cleaning things up so they have a chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to an external storage. If negative, the default value specified in the pod is used. ### Timeout @@ -156,17 +157,17 @@ The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was n If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node. -If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to `cordoned`. +If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which then stops the drain process and changes the node's state to `cordoned`. -Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node. +Once drain successfully completes, the node is in a state of `drained`. You can then power off or delete the node. **Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/). ## Labeling a Node to be Ignored by Rancher -Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. +Certain solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. -Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI. +Since the node never finishes registering, it is always shown as unhealthy in the Rancher UI. In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing. @@ -181,16 +182,16 @@ There is an [open issue](https://github.com/rancher/rancher/issues/24172) in whi ### Labeling Nodes to be Ignored with kubectl -To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label: +To add a node that is ignored by Rancher, use `kubectl` to create a node that has the following label: ``` cattle.rancher.io/node-status: ignore ``` -**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`. +**Result**: If you add the node to a cluster, Rancher skips syncing with this node. The node can still be part of the cluster and can be listed with `kubectl`. -If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI. +If the label is added before the node is added to the cluster, the node is not shown in the Rancher UI. -If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI. +If the label is added after the node is added to a Rancher cluster, the node is not removed from the UI. -If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`. +If you delete the node from the Rancher server using the Rancher UI or API, the node is not removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`. diff --git a/docs/reference-guides/user-settings/api-keys.md b/docs/reference-guides/user-settings/api-keys.md index 356439ad59f..634a7396d33 100644 --- a/docs/reference-guides/user-settings/api-keys.md +++ b/docs/reference-guides/user-settings/api-keys.md @@ -35,9 +35,9 @@ Users may opt to enable [token hashing](../../api/api-tokens.md). The API key won't be valid after expiration. Shorter expiration periods are more secure. - Expiration period will be bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period. + Expiration period is bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, the API key is created with max-ttl as the expiration period. - A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information. + A scope limits the API key so that it only works against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you are able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information. 4. Click **Create**. @@ -49,7 +49,7 @@ Users may opt to enable [token hashing](../../api/api-tokens.md). ## What's Next? -- Enter your API key information into the application that will send requests to the Rancher API. +- Enter your API key information into the application that sends requests to the Rancher API. - Learn more about the Rancher endpoints and parameters by selecting **View in API** for an object in the Rancher UI. - API keys are used for API calls and [Rancher CLI](../cli-with-rancher/cli-with-rancher.md). diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6.json b/i18n/zh/docusaurus-plugin-content-docs/version-2.6.json index 9fc315cd1c8..3facd1724fa 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6.json +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6.json @@ -11,11 +11,11 @@ "message": "快速入门指南", "description": "The label for category Quick Start Guides in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Deploy Rancher": { + "sidebar.tutorialSidebar.category.Deploying Rancher Server": { "message": "部署 Rancher", "description": "The label for category Deploy Rancher in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Deploy Workloads": { + "sidebar.tutorialSidebar.category.Deploying Workloads": { "message": "部署工作负载", "description": "The label for category Deploy Workloads in sidebar tutorialSidebar" }, @@ -64,28 +64,28 @@ "description": "The label for category New User Guides in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Authentication, Permissions, and Global Configuration": { - "message": "身份验证、权限和全局配置", + "message": "认证、权限和全局配置", "description": "The label for category Authentication, Permissions, and Global Configuration in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Authentication Config": { - "message": "身份验证配置", - "description": "The label for category Authentication Config in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Configuring Authentication": { + "message": "配置认证", + "description": "The label for category Configuring Authentication in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Configure OpenLDAP": { + "sidebar.tutorialSidebar.category.Configuring OpenLDAP": { "message": "配置 OpenLDAP", - "description": "The label for category Configure OpenLDAP in sidebar tutorialSidebar" + "description": "The label for category Configuring OpenLDAP in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Configure Microsoft AD Federation Service (SAML)": { + "sidebar.tutorialSidebar.category.Configuring Microsoft AD Federation Service (SAML)": { "message": "配置 Microsoft AD FS (SAML)", - "description": "The label for category Configure Microsoft AD Federation Service (SAML) in sidebar tutorialSidebar" + "description": "The label for category Configuring Microsoft AD Federation Service (SAML) in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Configure Shibboleth (SAML)": { + "sidebar.tutorialSidebar.category.Configuring Shibboleth (SAML)": { "message": "配置 Shibboleth (SAML)", - "description": "The label for category Configure Shibboleth (SAML) in sidebar tutorialSidebar" + "description": "The label for category Configuring Shibboleth (SAML) in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Manage Role-Based Access Control (RBAC)": { + "sidebar.tutorialSidebar.category.Managing Role-Based Access Control (RBAC)": { "message": "管理 RBAC", - "description": "The label for category Manage Role-Based Access Control (RBAC) in sidebar tutorialSidebar" + "description": "The label for category Managing Role-Based Access Control (RBAC) in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.About Provisioning Drivers": { "message": "关于 Provisioning 驱动", @@ -95,9 +95,9 @@ "message": "关于 RKE1 模板", "description": "The label for category About RKE1 Templates in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Manage Clusters": { - "message": "管理集群", - "description": "The label for category Manage Clusters in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Cluster Administration": { + "message": "集群管理", + "description": "The label for category Cluster Administration in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Access Clusters": { "message": "访问集群", @@ -115,49 +115,53 @@ "message": "配置存储示例", "description": "The label for category Provisioning Storage Examples in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Kubernetes Cluster Setup": { - "message": "Kubernetes 集群设置", - "description": "The label for category Kubernetes Cluster Setup in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Setting up a Kubernetes Cluster for Rancher Server": { + "message": "为 Rancher 设置 Kubernetes 集群", + "description": "The label for category Setting up a Kubernetes Cluster for Rancher Server in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Infrastructure Setup": { "message": "基础设施设置", "description": "The label for category Infrastructure Setup in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Kubernetes Clusters in Rancher Setup": { - "message": "Rancher 设置中的 Kubernetes 集群", + "message": "Rancher 中的 Kubernetes 集群设置", "description": "The label for category Kubernetes Clusters in Rancher Setup in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Checklist for Production-Ready Clusters": { "message": "生产就绪集群检查清单", "description": "The label for category Checklist for Production-Ready Clusters in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Set Up Clusters from Hosted Kubernetes Providers": { + "sidebar.tutorialSidebar.category.Setting up Clusters from Hosted Kubernetes Providers": { "message": "通过托管 Kubernetes 提供商设置集群", - "description": "The label for category Set Up Clusters from Hosted Kubernetes Providers in sidebar tutorialSidebar" + "description": "The label for category Setting up Clusters from Hosted Kubernetes Providers in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Launching Kubernetes on Windows Clusters": { + "message": "在 Windows 集群上启动 Kubernetes", + "description": "The label for category Launching Kubernetes on Windows Clusters in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Use Windows Clusters": { "message": "使用 Windows 集群", "description": "The label for category Use Windows Clusters in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Set Up Cloud Providers": { + "sidebar.tutorialSidebar.category.Setting up Cloud Providers": { "message": "设置 Cloud Provider", - "description": "The label for category Set Up Cloud Providers in sidebar tutorialSidebar" + "description": "The label for category Setting up Cloud Providers in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Launch Kubernetes with Rancher": { + "sidebar.tutorialSidebar.category.Launching Kubernetes with Rancher": { "message": "使用 Rancher 启动 Kubernetes", - "description": "The label for category Launch Kubernetes with Rancher in sidebar tutorialSidebar" + "description": "The label for category Launching Kubernetes with Rancher in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Use New Nodes in an Infra Provider": { + "sidebar.tutorialSidebar.category.Launching New Nodes in an Infra Provider": { "message": "在基础设施提供商中使用新节点", - "description": "The label for category Use New Nodes in an Infra Provider in sidebar tutorialSidebar" + "description": "The label for category Launching New Nodes in an Infra Provider in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.vSphere": { - "message": "vSphere", - "description": "The label for category vSphere in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Creating a vSphere Cluster": { + "message": "创建 vSphere 集群", + "description": "The label for category Creating a vSphere Cluster in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Nutanix": { - "message": "Nutanix", - "description": "The label for category Nutanix in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Creating a Nutanix AOS Cluster": { + "message": "创建 Nutanix AOS 集群", + "description": "The label for category Creating a Nutanix AOS Cluster in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Kubernetes Resources Setup": { "message": "Kubernetes 资源设置", @@ -175,13 +179,13 @@ "message": "负载均衡和 Ingress Controller", "description": "The label for category Load Balancer and Ingress Controller in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Helm Charts in Rancher": { - "message": "Rancher 中的 Helm Chart", - "description": "The label for category Helm Charts in Rancher in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Helm Charts and Apps": { + "message": "Helm Charts 和 Apps", + "description": "The label for category Helm Charts and Apps in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Deploy Apps Across Clusters": { + "sidebar.tutorialSidebar.category.Deploying Apps Across Clusters": { "message": "跨集群部署应用", - "description": "The label for category Deploy Apps Across Clusters in sidebar tutorialSidebar" + "description": "The label for category Deploying Apps Across Clusters in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Backup, Restore, and Disaster Recovery": { "message": "备份、还原和灾难恢复", @@ -191,13 +195,13 @@ "message": "高级用户指南", "description": "The label for category Advanced User Guides in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Manage Projects": { - "message": "管理项目", - "description": "The label for category Manage Projects in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Project Administration": { + "message": "项目管理", + "description": "The label for category Project Administration in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Manage Project Resource Quotas": { - "message": "管理项目资源配额", - "description": "The label for category Manage Project Resource Quotas in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Project Resource Quotas": { + "message": "项目资源配额", + "description": "The label for category Project Resource Quotas in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Monitoring/Alerting Guides": { "message": "Monitoring/Alerting 指南", @@ -207,33 +211,33 @@ "message": "Prometheus Federator 指南", "description": "The label for category Prometheus Federator Guides in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Monitoring V2 Configuration Guides": { - "message": "Monitoring V2 配置指南", - "description": "The label for category Monitoring V2 Configuration Guides in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Monitoring Configuration Guides": { + "message": "Monitoring 配置指南", + "description": "The label for category Monitoring Configuration Guides in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Advanced Configuration": { "message": "高级配置", "description": "The label for category Advanced Configuration in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Istio Setup Guide": { + "sidebar.tutorialSidebar.category.Istio Setup Guides": { "message": "Istio 设置指南", - "description": "The label for category Istio Setup Guide in sidebar tutorialSidebar" + "description": "The label for category Istio Setup Guides in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.CIS Scan Guides": { "message": "CIS 扫描指南", "description": "The label for category CIS Scan Guides in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Enable Experimental Features": { + "sidebar.tutorialSidebar.category.Enabling Experimental Features": { "message": "启用实验功能", - "description": "The label for category Enable Experimental Features in sidebar tutorialSidebar" + "description": "The label for category Enabling Experimental Features in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Reference Guides": { "message": "参考指南", "description": "The label for category Reference Guides in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Best Practices": { + "sidebar.tutorialSidebar.category.Best Practice Guides": { "message": "最佳实践", - "description": "The label for category Best Practices in sidebar tutorialSidebar" + "description": "The label for category Best Practice Guides in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Rancher Server": { "message": "Rancher Server", @@ -255,9 +259,9 @@ "message": "Rancher Server 配置", "description": "The label for category Rancher Server Configuration in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.GKE Cluster Configuration": { + "sidebar.tutorialSidebar.category.GKE Cluster Configuration Reference": { "message": "GKE 集群配置", - "description": "The label for category GKE Cluster Configuration in sidebar tutorialSidebar" + "description": "The label for category GKE Cluster Configuration Reference in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Use Existing Nodes": { "message": "使用现有节点", @@ -283,9 +287,9 @@ "message": "备份和恢复配置", "description": "The label for category Backup & Restore Configuration in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Monitoring V2 Configuration": { - "message": "Monitoring V2 配置", - "description": "The label for category Monitoring V2 Configuration in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Monitoring Configuration Reference": { + "message": "Monitoring 配置", + "description": "The label for category Monitoring Configuration Reference in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Prometheus Federator": { "message": "Prometheus Federator", @@ -307,9 +311,9 @@ "message": "流水线", "description": "The label for category Pipelines in sidebar tutorialSidebar" }, - "sidebar.tutorialSidebar.category.Rancher Security": { - "message": "Rancher 安全", - "description": "The label for category Rancher Security in sidebar tutorialSidebar" + "sidebar.tutorialSidebar.category.Rancher Security Guides": { + "message": "Rancher 安全指南", + "description": "The label for category Rancher Security Guides in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.Rancher v2.6 Hardening Guides": { "message": "Rancher 2.6 强化指南", diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/deprecated-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/deprecated-features.md new file mode 100644 index 00000000000..935c36166a8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/deprecated-features.md @@ -0,0 +1,37 @@ +--- +title: Rancher 中已弃用的功能 +--- + + + + + +### Rancher 的弃用策略是什么？ + +我们已经在支持的[服务条款](https://rancher.com/support-maintenance-terms)中发布了官方的弃用策略。 + +### 在哪里可以了解 Rancher 中已弃用哪些功能？ + +Rancher 将在 GitHub 上发布的 Rancher 的[发版说明](https://github.com/rancher/rancher/releases)中发布已弃用的功能。有关已弃用的功能，请参阅以下的补丁版本： + +| 补丁版本 | 发布日期 | +| ----------------------------------------------------------------- | ------------------- | +| [2.6.14](https://github.com/rancher/rancher/releases/tag/v2.6.14) | 2024 年 2 月 8 日 | +| [2.6.13](https://github.com/rancher/rancher/releases/tag/v2.6.13) | 2023 年 5 月 31 日 | +| [2.6.12](https://github.com/rancher/rancher/releases/tag/v2.6.12) | 2023 年 4 月 27 日 | +| [2.6.11](https://github.com/rancher/rancher/releases/tag/v2.6.11) | 2023 年 3 月 8 日 | +| [2.6.10](https://github.com/rancher/rancher/releases/tag/v2.6.10) | 2023 年 1 月 24 日 | +| [2.6.9](https://github.com/rancher/rancher/releases/tag/v2.6.9) | 2022 年 10 月 18 日 | +| [2.6.8](https://github.com/rancher/rancher/releases/tag/v2.6.8) | 2022 年 8 月 29 日 | +| [2.6.7](https://github.com/rancher/rancher/releases/tag/v2.6.7) | 2022 年 8 月 18 日 | +| [2.6.6](https://github.com/rancher/rancher/releases/tag/v2.6.6) | 2022 年 6 月 30 日 | +| [2.6.5](https://github.com/rancher/rancher/releases/tag/v2.6.5) | 2022 年 5 月 12 日 | +| [2.6.4](https://github.com/rancher/rancher/releases/tag/v2.6.4) | 2022 年 3 月 31 日 | +| [2.6.3](https://github.com/rancher/rancher/releases/tag/v2.6.3) | 2021 年 12 月 21 日 | +| [2.6.2](https://github.com/rancher/rancher/releases/tag/v2.6.2) | 2021 年 10 月 19 日 | +| [2.6.1](https://github.com/rancher/rancher/releases/tag/v2.6.1) | 2021 年 10 月 11 日 | +| [2.6.0](https://github.com/rancher/rancher/releases/tag/v2.6.0) | 2021 年 8 月 31 日 | + +### 当一个功能被标记为弃用我可以得到什么样的预期？ + +当功能被标记为“已弃用”时，它依然可用并得到支持，允许按照常规的流程进行升级。一旦升级完成，用户/管理员应开始计划在升级到标记为已移除的版本之前放弃使用已弃用的功能。对于新的部署，建议不要使用已弃用的功能。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/general-faq.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/general-faq.md index 8022655b815..416fee676c5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/general-faq.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/faq/general-faq.md @@ -2,68 +2,50 @@ title: 一般常见问题解答 --- -本文包含了用户常见的 Rancher 2.x 问题。 + + + + +此常见问题解答是一项正在进行的工作，旨在回答有关 Rancher v2.x 最常见的问题。 有关常见技术问题，请参阅[常见技术问题解答](technical-items.md)。 -
+## Rancher v2.x 是否支持 Docker Swarm 和 Mesos 作为环境类型? -**Rancher 2.x 支持 Docker Swarm 和 Mesos 作为环境类型吗？** +在 Rancher v2.x 中创建新环境时，Swarm 和 Mesos 不再是可选择的选项。但是，Swarm 和 Mesos 将继续作为你可以部署的目录应用程序提供。这是一个艰难的决定，但最终归结为采用。例如，在 15,000 多个集群中，只有大约 200 个在运行 Swarm。 -如果你在 Rancher 2.x 中创建环境，Swarm 和 Mesos 将不再是可选的标准选项。但是，Swarm 和 Mesos 还能继续作为可以部署的商店应用程序。这是一个艰难的决定，但这是大势所趋。比如说，15,000 多个集群可能只有大约 200 个在运行 Swarm。 +## 可以使用 Rancher v2.x 管理 Azure Kubernetes 服务吗? -
+是的。请参阅我们的[集群管理](../how-to-guides/new-user-guides/manage-clusters/manage-clusters.md)指南，了解 AKS 上可用的 Rancher 功能，以及[有关 AKS 的文档](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md)。 -**是否可以使用 Rancher 2.x 管理 Azure Kubernetes 服务？** +## Rancher 是否支持 Windows? -是的。 +是的。Rancher 支持 Windows Server 1809 containers。有关如何使用 Windows worker 节点设置集群的详细信息，请参阅[为 Windows 配置自定义集群](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)部分。 -
+## Rancher 是否支持 Istio? -**Rancher 是否支持 Windows？** +是的。Rancher 支持 [Istio](../integrations-in-rancher/istio/istio.md). -从 Rancher 2.3.0 开始，我们支持 Windows Server 1809 容器。有关如何使用 Windows Worker 节点设置集群的详细信息，请参阅[为 Windows 配置自定义集群](../pages-for-subheaders/use-windows-clusters.md)。 +## Rancher v2.x 会支持 Hashicorp 的 Vault 来存储 secrets 吗? -
+Secrets 管理已在我们的 roadmap 上，但我们尚未将其分配给特定版本。 -**Rancher 是否支持 Istio？** - -从 Rancher 2.3.0 开始，我们支持 [Istio.](../pages-for-subheaders/istio.md) - -此外，Istio 是在我们的微型 PaaS “Rio” 中实现的，它可以运行在 Rancher 2.x 以及任何符合 CNCF 的 Kubernetes 集群上。详情请参阅[这里](https://rio.io/)。 - -
- -**Rancher 2.x 是否支持使用 Hashicorp 的 Vault 来存储密文？** - -密文管理已在我们的 roadmap 上，但我们尚未将该功能分配给特定版本。 - -
- -**Rancher 2.x 是否也支持 RKT 容器？** +## Rancher v2.x 是否也支持 RKT containers? 目前，我们只支持 Docker。 -
+## Rancher v2.x 是否支持 Calico、Contiv、Contrail、Flannel、Weave net 等嵌入式和注册的 Kubernetes？ -**Rancher 2.x 是否支持将 Calico、Contiv、Contrail、Flannel、Weave net 等网络插件用于嵌入和已注册的 Kubernetes？** +Rancher 开箱即用，为 Kubernetes 集群提供了以下 CNI 网络提供商：Canal、Flannel、Calico 和 Weave。请务必参考 [Rancher 支持矩阵](https://rancher.com/support-maintenance-terms/)了解官方支持的内容。 -Rancher 开箱即用地为 Kubernetes 集群提供了几个 CNI 网络插件，分别是 Canal、Flannel、Calico 和 Weave。有关官方支持的详细信息，请参阅 [Rancher 支持矩阵](https://rancher.com/support-maintenance-terms/)。 +## 你是否计划为现有设置支持 Traefik? -
+我们目前不打算提供嵌入式 Traefik 支持，但我们仍在探索负载均衡方法。 -**Rancher 是否计划支持 Traefik？** +## 我可以将 OpenShift Kubernetes 集群导入 v2.x 吗? -目前，我们不打算提供嵌入式 Traefik 支持，但我们仍在探索负载均衡方案。 +我们的目标是运行任何 Kubernetes 集群。因此，Rancher v2.x 应该可以与 OpenShift 配合使用，但我们还没有测试过。 -
+## Longhorn 是否与 Rancher 集成? -**我可以将 OpenShift Kubernetes 集群导入 2.x 吗？** - -我们的目标是运行任何上游 Kubernetes 集群。因此，Rancher 2.x 应该可以与 OpenShift 一起使用，但我们尚未对此进行测试。 - -
- -**Rancher 会集成 Longhorn 吗？** - -是的。Longhorn 已集成到 Rancher 2.5+ 中。 +是的。 Longhorn 与 Rancher v2.5 及更高版本集成。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md index dee4c863bcf..8e5c0eca63f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md @@ -1,5 +1,5 @@ --- -title: 在离线环境中渲染 Helm 模板 +title: 在离线环境中升级 --- :::note @@ -35,6 +35,26 @@ helm template rancher ./rancher-.tgz --output-dir . \ --set useBundledSystemChart=true # Use the packaged Rancher system charts ``` +#### 解决 UPGRADE FAILED 错误 + +如果你遇到错误消息 `Error: UPGRADE FAILED: "rancher" has no deployed releases`，Rancher 可能是通过 `helm template` 命令安装的。要成功升级 Rancher，请改用以下命令： + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +执行 Helm 命令后，需要应用渲染后的模板： + +``` +kubectl -n cattle-system apply -R -f ./rancher +``` ### 选项 B：使用 Kubernetes 密文从文件中获取证书 ```plain @@ -62,16 +82,6 @@ helm template rancher ./rancher-.tgz --output-dir . \ --set useBundledSystemChart=true # Use the packaged Rancher system charts ``` -### 应用已渲染的模板 - -将渲染的 manifest 目录复制到可以访问 Rancher Server 集群的系统中，并应用渲染的模板。 - -使用 `kubectl` 来应用渲染的 manifest。 - -```plain -kubectl -n cattle-system apply -R -f ./rancher -``` - ## 验证升级 登录 Rancher 以确认升级成功。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md new file mode 100644 index 00000000000..e4660004425 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -0,0 +1,356 @@ +--- +title: 在 Kubernetes 集群上安装/升级 Rancher +description: 了解如何在开发和生产环境中安装 Rancher。了解单节点和高可用安装 +--- + +在本节中，你将学习如何使用 Helm CLI 在 Kubernetes 集群上部署 Rancher。 + + +## 先决条件 + +- [Kubernetes 集群](#kubernetes-集群) +- [Ingress Controller](#ingress-controller) +- [CLI 工具](#cli-工具) + +### Kubernetes 集群 + +设置 Rancher Server 的本地 Kubernetes 集群。 + +Rancher 可以安装在任何 Kubernetes 集群上。这个集群可以使用上游 Kubernetes，也可以使用 Rancher 的 Kubernetes 发行版之一，也可以是来自 Amazon EKS 等提供商的托管 Kubernetes 集群。 + +你可参考以下教程，以获得设置 Kubernetes 集群的帮助： + +- **RKE**：[安装 RKE Kubernetes 集群的教程](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md)；[为高可用 RKE 集群设置基础设施的教程](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md)。 +- **K3s**：[安装 K3s Kubernetes 集群的教程](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md)；[设置高可用 K3s 集群的基础设施的教程](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md)。 +- **RKE2:** ：[安装 RKE2 Kubernetes 集群的教程](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md)；[设置高可用 RKE2 集群的基础设施的教程](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md)。 +- **Amazon EKS**：[在 Amazon EKS 上安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server](rancher-on-amazon-eks.md)。 +- **AKS**：[使用 Azure Kubernetes 服务安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server](rancher-on-aks.md)。 +- **GKE**：有关如何使用 GKE 安装 Rancher，包括如何安装 Ingress Controller 以便可以访问 Rancher Server，请参阅[此页面](rancher-on-gke.md)。GKE 创建 Kubernetes 集群时有两种运行模式，分别是 Autopilot 和 Standard 模式。Autopilot 模式的集群配置对编辑 kube-system 命名空间有限制。但是，Rancher 在安装时需要在 kube-system 命名空间中创建资源。因此，你将无法在以 Autopilot 模式创建的 GKE 集群上安装 Rancher。 + + +### Ingress Controller + +Rancher UI 和 API 通过 Ingress 公开。换言之，安装 Rancher 的 Kubernetes 集群必须包含一个 Ingress Controller。 + +对于 RKE、RKE2 和 K3s，你不需要手动安装 Ingress Controller，因为它是默认安装的。 + +对于默认不包含 Ingress Controller 的发行版（例如 EKS、GKE 或 AKS 等托管 Kubernetes 集群），你必须先部署 Ingress Controller。请注意，Rancher Helm Chart 默认情况下不会在 Ingress 上设置 `ingressClassName`。因此，你必须将 Ingress Controller 配置为在没有 `ingressClassName` 的情况下也可以监视 Ingress。 + +上面的 **Amazon EKS**、**AKS** 和 **GKE** 教程中包含了示例。 + +### CLI 工具 + +设置 Kubernetes 集群需要以下 CLI 工具。请确保这些工具已安装并在你的 `$PATH` 中可用。 + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes 命令行工具。 +- [Helm](https://docs.helm.sh/using_helm/#installing-helm) - Kubernetes 的包管理器。请参见 [Helm 版本要求](../resources/helm-version-requirements.md)选择 Helm 版本来安装 Rancher。请为你的具体平台参见 [Helm 项目提供的说明](https://helm.sh/docs/intro/install/)。 + +## 安装 Rancher Helm Chart + +Rancher 是使用 Kubernetes 的 [Helm](https://helm.sh/) 包管理器安装的。Helm Chart 为 Kubernetes YAML 清单文件提供了模板语法。通过 Helm，用户可以创建可配置的 deployment，而不仅仅只能使用静态文件。 + +如果系统无法直接访问互联网，请参见[离线环境：Kubernetes 安装](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)。 + +如果要指定安装的 Rancher 版本，请参见[选择 Rancher 版本](../resources/choose-a-rancher-version.md)。 + +如果要指定用于安装 Rancher 的 Helm 版本，请参见[Helm 版本要求](../resources/helm-version-requirements.md)。 + +:::note + +本安装指南假定你使用的是 Helm 3。 + +::: + +要设置 Rancher： + +1. [添加 Helm Chart 仓库](#1-添加-helm-chart-仓库) +2. [为 Rancher 创建命名空间](#2-为-rancher-创建命名空间) +3. [选择 SSL 配置](#3-选择-ssl-配置) +4. [安装 cert-manager](#4-安装-cert-manager)（除非你自带证书，否则 TLS 将在负载均衡器上终止） +5. [使用 Helm 和你选择的证书选项安装 Rancher](#5-根据你选择的证书选项通过-helm-安装-rancher) +6. [验证 Rancher Server 是否部署成功](#6-验证-rancher-server-是否部署成功) +7. [保存选项](#7-保存选项) + +### 1. 添加 Helm Chart 仓库 + +执行 `helm repo add` 命令，以添加包含安装 Rancher 的 Chart 的 Helm Chart 仓库。有关如何选择仓库，以及哪个仓库最适合你的用例，请参见[选择 Rancher 版本](../getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md)。 + +- Latest：建议用于试用最新功能 + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` +- Stable：建议用于生产环境 + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` +- Alpha：即将发布的实验性预览。 + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + 注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。 + +### 2. 为 Rancher 创建命名空间 + +你需要定义一个 Kubernetes 命名空间，用于安装由 Chart 创建的资源。这个命名空间的名称为 `cattle-system`： + +``` +kubectl create namespace cattle-system +``` + +### 3. 选择 SSL 配置 + +Rancher Management Server 默认需要 SSL/TLS 配置来保证访问的安全性。 + +:::note + +如果你想在外部终止 SSL/TLS，请参见[外部负载均衡器的 TLS 终止](../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#外部-tls-终止)。 + +::: + +你可以从以下三种证书来源中选择一种，用于在 Rancher Server 中终止 TLS： + +- **Rancher 生成的 TLS 证书**：要求你在集群中安装 `cert-manager`。Rancher 使用 `cert-manager` 签发并维护证书。Rancher 会生成自己的 CA 证书，并使用该 CA 签署证书。然后 `cert-manager`负责管理该证书。 +- **Let's Encrypt**：Let's Encrypt 选项也需要使用 `cert-manager`。但是，在这种情况下，cert-manager 与 Let's Encrypt 的特殊颁发者相结合，该颁发者执行获取 Let's Encrypt 颁发的证书所需的所有操作（包括请求和验证）。此配置使用 HTTP 验证（`HTTP-01`），因此负载均衡器必须具有可以从互联网访问的公共 DNS 记录。 +- **你已有的证书**：使用已有的 CA 颁发的公有或私有证书。Rancher 将使用该证书来保护 WebSocket 和 HTTPS 流量。在这种情况下，你必须上传名称分别为 `tls.crt` 和 `tls.key`的 PEM 格式的证书以及相关的密钥。如果你使用私有 CA，则还必须上传该 CA 证书。这是由于你的节点可能不信任此私有 CA。Rancher 将获取该 CA 证书，并从中生成一个校验和，各种 Rancher 组件将使用该校验和来验证其与 Rancher 的连接。 + + +| 配置 | Helm Chart 选项 | 是否需要 cert-manager | +| ------------------------------ | ----------------------- | ------------------------------------- | +| Rancher 生成的证书（默认） | `ingress.tls.source=rancher` | [是](#4-安装-cert-manager) | +| Let’s Encrypt | `ingress.tls.source=letsEncrypt` | [是](#4-安装-cert-manager) | +| 你已有的证书 | `ingress.tls.source=secret` | 否 | + +### 4. 安装 cert-manager + +:::note + +v2.6.4 兼容 cert-manager 版本 1.6.2 和 1.7.1。推荐使用 v1.7.x，因为 v 1.6.x 将在 2022 年 3 月 30 日结束生命周期。 + +::: + +> 如果你使用自己的证书文件（`ingress.tls.source=secret`）或使用[外部负载均衡器的 TLS 终止](../installation-references/helm-chart-options.md#外部-tls-终止)，你可以跳过此步骤。 + +仅在使用 Rancher 生成的证书（`ingress.tls.source=rancher`）或 Let's Encrypt 颁发的证书（`ingress.tls.source=letsEncrypt`）时，才需要安装 cert-manager。 + +
+ 单击展开 + +:::note 重要提示： + +由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.11.0 的 cert-manager 版本，请参见[升级文档](../resources/upgrade-cert-manager.md)。 + +::: + +这些说明来自 [cert-manager 官方文档](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm)。 + +:::note + +要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 [cert-manager 文档](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration)。 + +::: + +``` +# 如果你手动安装了CRD，而不是在 Helm 安装命令中添加了 `--set installCRDs=true` 选项，你应该在升级 Helm Chart 之前升级 CRD 资源。 +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml + +# 添加 Jetstack Helm 仓库 +helm repo add jetstack https://charts.jetstack.io + +# 更新本地 Helm Chart 仓库缓存 +helm repo update + +# 安装 cert-manager Helm Chart +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set installCRDs=true \ + --version v1.11.0 +``` + +安装完 cert-manager 后，你可以通过检查 cert-manager 命名空间中正在运行的 Pod 来验证它是否已正确部署： + +``` +kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +
+ +### 5. 根据你选择的证书选项，通过 Helm 安装 Rancher + +不同的证书配置需要使用不同的 Rancher 安装命令。 + +但是，无论证书如何配置，Rancher 在 `cattle-system` 命名空间中的安装名称应该总是 `rancher`。 + +:::tip 测试和开发： + +这个安装 Rancher 的最终命令需要一个将流量转发到 Rancher 的域名。如果你使用 Helm CLI 设置概念证明，则可以在传入 `hostname` 选项时使用伪域名。伪域名的一个例子是 `.sslip.io`，这会把 Rancher 暴露在它运行的 IP 上。生产安装中要求填写真实的域名。 + +::: + + + + +默认情况是使用 Rancher 生成 CA，并使用 `cert-manager` 颁发用于访问 Rancher Server 接口的证书。 + +由于 `rancher` 是 `ingress.tls.source` 的默认选项，因此在执行 `helm install` 命令时，我们不需要指定 `ingress.tls.source`。 + +- 将 `hostname` 设置为解析到你的负载均衡器的 DNS 名称。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 如果你需要安装指定的 Rancher 版本，使用 `--version` 标志，例如 `--version 2.3.6`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin +``` + +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +等待 Rancher 运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + + +此选项使用 `cert-manager` 来自动请求和续订 [Let's Encrypt](https://letsencrypt.org/) 证书。Let's Encrypt 是免费的，而且是受信的 CA，因此可以为你提供有效的证书。 + +:::note + +由于 HTTP-01 质询只能在端口 80 上完成，因此你需要打开端口 80。 + +::: + +在以下命令中， + +- 将 `hostname` 设置为公有 DNS 记录。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 将 `ingress.tls.source` 设置为 `letsEncrypt`。 +- 将 `letsEncrypt.email` 设置为可通讯的电子邮件地址，用于发送通知（例如证书到期的通知）。 +- 将 `letsEncrypt.ingress.class` 设为你的 Ingress Controller（例如 `traefik`，`nginx`，`haproxy`） + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=letsEncrypt \ + --set letsEncrypt.email=me@example.org \ + --set letsEncrypt.ingress.class=nginx +``` + +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +等待 Rancher 运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + +在此选项中，你使用你自己的证书来创建 Kubernetes 密文，以供 Rancher 使用。 + +运行这个命令时，`hostname` 选项必须与服务器证书中的 `Common Name` 或 `Subject Alternative Names` 条目匹配，否则 Ingress controller 将无法正确配置。 + +虽然技术上仅需要 `Subject Alternative Names` 中有一个条目，但是拥有一个匹配的 `Common Name` 可以最大程度地提高与旧版浏览器/应用的兼容性。 + +:::note + +如果你想检查证书是否正确，请查看[如何在服务器证书中检查 Common Name 和 Subject Alternative Names](../../../faq/technical-items.md#如何在服务器证书中检查-common-name-和-subject-alternative-names)。 + +::: + +- 设置 `hostname`。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 将 `ingress.tls.source` 设置为 `secret`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret +``` +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +如果你使用的是私有 CA 证书，请在命令中增加 `--set privateCA=true`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret \ + --set privateCA=true +``` + +**添加 TLS 密文（千万不要遗漏此步骤）**：现在 Rancher 已经完成部署，你还需要参考[添加 TLS 密文](../resources/add-tls-secrets.md)发布证书文件，以便 Rancher 和 Ingress Controller 可以使用它们。 + + + + +Rancher Chart 有许多选项，用于为你的具体环境自定义安装。以下是一些常见的高级方案： + +- [HTTP 代理](../installation-references/helm-chart-options.md#http-代理) +- [私有容器镜像仓库](../installation-references/helm-chart-options.md#私有仓库和离线安装) +- [外部负载均衡器上的 TLS 终止](../installation-references/helm-chart-options.md#外部-tls-终止) + +如需获取完整的选项列表，请参见 [Chart 选项](../installation-references/helm-chart-options.md)。 + + +### 6. 验证 Rancher Server 是否部署成功 + +添加密文后，检查 Rancher 是否已成功运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +如果你看到 `error: deployment "rancher" exceeded its progress deadline` 这个错误，可运行以下命令来检查 deployment 的状态： + +``` +kubectl -n cattle-system get deploy rancher +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +rancher 3 3 3 3 3m +``` + +`DESIRED` 和 `AVAILABLE`的个数应该相同。 + +### 7. 保存选项 + +请保存你使用的 `--set` 选项。使用 Helm 升级 Rancher 到新版本时，你将需要使用相同的选项。 + +### 安装完成 + +安装已完成。现在 Rancher Server 应该已经可以正常运行了。 + +使用浏览器打开把流量转发到你的负载均衡器的 DNS 域名。然后，你就会看到一个漂亮的登录页面了。 + +如果遇到任何问题，请参见[故障排除](troubleshooting.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md index 848cbfcb86b..72da789c5e0 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md @@ -6,7 +6,7 @@ title: 在 Azure Kubernetes Service 上安装 Rancher 本指南使用命令行工具来配置一个带有 Ingress 的 AKS 集群。如果你更喜欢使用 Azure 门户来配置集群，请参见[官方文档](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)。 -如果你已有一个 AKS Kubernetes 集群，请直接跳到[安装 Ingress](#5-安装-ingress) 的步骤，然后按照[此页](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。 +如果你已有一个 AKS Kubernetes 集群，请直接跳到[安装 Ingress](#5-安装-ingress) 的步骤，然后按照[此页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。 ## 先决条件 @@ -19,7 +19,7 @@ title: 在 Azure Kubernetes Service 上安装 Rancher - [Microsoft Azure 账号](https://azure.microsoft.com/en-us/free/)：用于创建部署 Rancher 和 Kubernetes 的资源。 - [Microsoft Azure 订阅](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal)：如果你没有的话，请访问此链接查看如何创建 Microsoft Azure 订阅。 - [Micsoroft Azure 租户](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant)：访问此链接并参考教程以创建 Microsoft Azure 租户。 -- 你的订阅有足够的配额，至少有 2 个 vCPU。有关 Rancher Server 资源要求的详情，请参见[此节](../../../pages-for-subheaders/installation-requirements.md#rke-和托管-kubernetes)。 +- 你的订阅有足够的配额，至少有 2 个 vCPU。有关 Rancher Server 资源要求的详情，请参见[此节](../installation-requirements/installation-requirements.md)。 - 在 Azure 中用 Helm 安装 Rancher 时，请使用 L7 负载均衡器来避免网络问题。详情请参见 [Azure 负载均衡器限制](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations)。 ## 1. 准备你的工作站 @@ -133,7 +133,7 @@ ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229 ## 8. 安装 Rancher Helm Chart -按照[本页](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 +按照[本页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 安装 Rancher 时，使用上一步获取的 DNS 名称作为 Rancher Server 的 URL。它可以作为 Helm 选项传递进来。例如，如果 DNS 名称是 `rancher.my.org`，你需要使用 `--set hostname=rancher.my.org` 选项来运行 Helm 安装命令。 @@ -145,4 +145,4 @@ ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229 --set ingress.ingressClassName=nginx ``` -请参阅[Helm 安装命令](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 +请参阅[Helm 安装命令](install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md index ec39f0fe0e7..df81cad3bdf 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md @@ -4,7 +4,7 @@ title: 在 Amazon EKS 上安装 Rancher 本文介绍了如何在 Amazon EKS 集群上安装 Rancher。你也可以[通过 AWS Marketplace 安装 Rancher](../../quick-start-guides/deploy-rancher-manager/aws-marketplace.md)。 -如果你已经有一个 EKS Kubernetes 集群，请直接跳转到[安装 Ingress](#5-安装-ingress)这个步骤。然后按照[此处](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 +如果你已经有一个 EKS Kubernetes 集群，请直接跳转到[安装 Ingress](#5-安装-ingress)这个步骤。然后按照[此处](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 ## 为 Rancher Server 创建 EKS 集群 @@ -138,7 +138,7 @@ ingress-nginx-controller LoadBalancer 10.100.90.18 a904a952c73bf4f668a17c4 ### 8. 安装 Rancher Helm Chart -按照[本页](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 +按照[本页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 安装 Rancher 时，使用上一步获取的 DNS 名称作为 Rancher Server 的 URL。它可以作为 Helm 选项传递进来。例如，如果 DNS 名称是 `rancher.my.org`，你需要使用 `--set hostname=rancher.my.org` 选项来运行 Helm 安装命令。 @@ -150,4 +150,4 @@ ingress-nginx-controller LoadBalancer 10.100.90.18 a904a952c73bf4f668a17c4 --set ingress.ingressClassName=nginx ``` -请参阅[Helm 安装命令](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 +请参阅[Helm 安装命令](install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md index 4cc50d1f7cd..88d0b04f512 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md @@ -4,13 +4,13 @@ title: 在 GKE 集群上安装 Rancher 在本节中，你将学习如何使用 GKE 安装 Rancher。 -如果你已经有一个 GKE Kubernetes 集群，请直接跳转到[安装 Ingress](#7-安装-ingress)这个步骤。然后按照[此处](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 +如果你已经有一个 GKE Kubernetes 集群，请直接跳转到[安装 Ingress](#7-安装-ingress)这个步骤。然后按照[此处](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 ## 先决条件 - 你需要有一个 Google 账号。 - 你需要有一个 Google Cloud Billing 账号。你可使用 Google Cloud Console 来管理你的 Cloud Billing 账号。有关 Cloud Console 的详情，请参见 [ Console 通用指南](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599)。 -- 你需要至少一个在用的 IP 地址和至少 2 个 CPU 的云配额。有关 Rancher Server 的硬件要求，请参见[本节](../../../pages-for-subheaders/installation-requirements.md#rke-和托管-kubernetes)。 +- 你需要至少一个在用的 IP 地址和至少 2 个 CPU 的云配额。有关 Rancher Server 的硬件要求，请参见[本节](../installation-requirements/installation-requirements.md)。 ## 1. 启用 Kubernetes Engine API diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md index 22ac50184c5..1c573cc0f8d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md @@ -32,7 +32,7 @@ kubeconfig 也可以通过 `--kubeconfig` 标签（详情请参见 https://helm. ### 离线安装：推送镜像到私有镜像仓库 -[仅适用于离线安装](../../../pages-for-subheaders/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像。使用你需要针对 Rancher 版本升级的镜像，按照步骤[推送镜像到私有镜像仓库](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)。 +[仅适用于离线安装](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像。使用你需要针对 Rancher 版本升级的镜像，按照步骤[推送镜像到私有镜像仓库](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)。 ### 使用 cert-manager 0.8.0 之前的版本升级 @@ -59,7 +59,7 @@ kubeconfig 也可以通过 `--kubeconfig` 标签（详情请参见 https://helm. 1. 获取你用来安装 Rancher 的仓库名称。 - 关于仓库及其区别，请参见 [Helm Chart Repositories](../resources/choose-a-rancher-version.md#helm-chart-仓库)。 + 关于仓库及其区别，请参见 [Helm Chart 仓库](../resources/choose-a-rancher-version.md#helm-chart-仓库)。 - Latest：建议用于试用最新功能 ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-and-upgrade.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-and-upgrade.md new file mode 100644 index 00000000000..d7615c6019c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-and-upgrade.md @@ -0,0 +1,94 @@ +--- +title: 安装/升级 Rancher +description: 了解如何在开发和生产环境中安装 Rancher。了解单节点和高可用安装 +--- + +本节介绍了 Rancher 各种安装方式以及每个安装方式的优点。 + +## 名词解释 + +本章节涉及以下名词： + +- **Rancher Server**：用于管理和配置 Kubernetes 集群。你可以通过 Rancher Server 的 UI 与下游 Kubernetes 集群进行交互。Rancher Management Server 可以安装到任意 Kubernetes 集群上，包括托管的集群，如 Amazon EKS 集群。 +- **RKE（Rancher Kubernetes Engine）**：是经过认证的 Kubernetes 发行版，也是用于创建和管理 Kubernetes 集群的 CLI 工具和库。 +- **K3s（轻量级 Kubernetes）**：也是经过认证的 Kubernetes 发行版。它比 RKE 更新，更易用且更轻量，其所有组件都在一个小于 100 MB 的二进制文件中。 +- **RKE2**：一个完全合规的 Kubernetes 发行版，专注于安全和合规性。 + +`restrictedAdmin` Helm Chart 选项在 **Rancher Server** 可用。如果该选项设置为 true，初始的 Rancher 用户访问本地 Kubernetes 集群会受到限制，以避免权限升级。详情请参见 [restricted-admin 角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#受限管理员)。 + +## 安装方式概述 + +Rancher 可以安装在以下主要架构上： + +### 使用 Helm CLI 安装的高可用 Kubernetes + +我们建议使用 Kubernetes 包管理器 Helm 在专用的 Kubernetes 集群上安装 Rancher。在 RKE 集群中，需要使用三个节点才能实现高可用集群。在 K3s 集群中，只需要两个节点即可。 + +### 通过 AWS Marketplace 在 EKS 上安装 Rancher + +你可以[通过 AWS Marketplace](../quick-start-guides/deploy-rancher-manager/aws-marketplace.md) 将 Rancher 安装到 Amazon Elastic Kubernetes Service (EKS) 上。部署的 EKS 集群已生产就绪，并遵循 AWS 最佳实践。 + +### 单节点 Kubernetes 安装 + +Rancher 可以安装在单节点 Kubernetes 集群上。但是，在单节点安装的情况下，Rancher Server 没有高可用性。而高可用性对在生产环境中运行 Rancher 非常重要。 + +但是，如果你想要短期内使用单节点节省资源，同时又保留高可用性迁移路径，那么单节点 Kubernetes 安装也是合适的。你也可以之后向集群中添加节点，获得高可用的 Rancher Server。 + +### Docker 安装 + +如果你的目的是测试或演示，你可以使用 Docker 把 Rancher 安装到单个节点中。本地 Kubernetes 集群是安装到单个 Docker 容器中的，而 Rancher 是安装到本地集群中的。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +### 其他方式 + +如果你需要在离线环境中或使用 HTTP 代理安装 Rancher，请参见以下独立的说明文档： + +| 网络访问方式 | 基于 Kubernetes 安装（推荐） | 基于 Docker 安装 | +| ---------------------------------- | ------------------------------ | ---------- | +| 可直接访问互联网 | [文档](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) | [文档](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) | +| 使用 HTTP 代理 | [文档](other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md) | [文档](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)及[配置](../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) | +| 离线环境 | [文档](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | [文档](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | + +我们建议在 Kubernetes 集群上安装 Rancher，因为在多节点集群中，Rancher Server 可以实现高可用。高可用配置可以提升 Rancher 访问其管理的下游 Kubernetes 集群的稳定性。 + +因此，我们建议在生产级别的架构中，设置一个高可用的 Kubernetes 集群，然后在这个集群上安装 Rancher。安装 Rancher 后，你可以使用 Rancher 部署和管理 Kubernetes 集群。 + +如果你的目的是测试或演示，你可以将 Rancher 安装到单个 Docker 容器中。Docker 安装可以让你实现开箱即用，以使用 Rancher 设置 Kubernetes 集群。Docker 安装主要是用于探索 Rancher Server 的功能，只适用于开发和测试。 + +[在 Kubernetes 上安装 Rancher 的说明](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)介绍了如何首先使用 K3s 或 RKE 创建和管理 Kubernetes 集群，然后再将 Rancher 安装到该集群上。 + +如果 Kubernetes 集群中的节点正在运行且满足[节点要求](installation-requirements/installation-requirements.md)，你可以使用 Helm 将 Rancher 部署到 Kubernetes 上。Helm 使用 Rancher 的 Helm Chart 在 Kubernetes 集群的每个节点上安装 Rancher 的副本。我们建议使用负载均衡器将流量定向到集群中的每个 Rancher 副本上。 + +如需进一步了解 Rancher 架构，请参见[架构概述](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)，[生产级别架构推荐](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)或[最佳实践指南](../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md)。 + +## 先决条件 + +安装 Rancher 之前，请确保你的节点满足所有[安装要求](installation-requirements/installation-requirements.md)。 + +## 架构建议 + +为了达到最佳性能和安全性，我们建议你为 Rancher Management Server 使用单独的专用 Kubernetes 集群。不建议在此集群上运行用户工作负载。部署 Rancher 后，你可以[创建或导入集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)来运行你的工作负载。 + +详情请参见[架构推荐](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)。 + +### 在 Kubernetes 上安装 Rancher 的更多选项 + +参见 [Helm Chart 选项](installation-references/helm-chart-options.md)以了解在 Kubernetes 集群上安装 Rancher 的其他配置，包括： + +- [开启 API 审计日志来记录所有事务](installation-references/helm-chart-options.md#api-审计日志) +- [负载均衡器上的 TLS 终止](installation-references/helm-chart-options.md#外部-tls-终止) +- [自定义 Ingress](installation-references/helm-chart-options.md#自定义-ingress) + +在 Rancher 的安装指南中，我们推荐使用 K3s 或 RKE 来配置 Kubernetes 集群，然后再在这个集群中安装 Rancher。K3s 和 RKE 均提供许多配置选项，用于为你的具体环境自定义 Kubernetes 集群。有关选项和功能的完整列表，请参见： + +- [RKE 配置选项](https://rancher.com/docs/rke/latest/en/config-options/) +- [K3s 配置选项](https://rancher.com/docs/k3s/latest/en/installation/install-options/) + +### 在 Docker 上安装 Rancher 的更多选项 + +参见 [Docker 安装选项](rancher-on-a-single-node-with-docker.md)了解其他配置，包括： + +- [开启 API 审计日志来记录所有事务](../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志) +- [外部负载均衡器](../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md) +- [持久化数据存储](../reference-guides/single-node-rancher-in-docker/advanced-options.md#持久化数据) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/feature-flags.md index 8b2d0874d38..84ff4ce16a5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -4,7 +4,7 @@ title: 功能开关 使用功能开关（Feature Flag），你可以试用可选或实验性的功能并启用正在逐步淘汰的旧版功能。 -要了解功能的值以及如何启用它们，请参阅[启用实验性功能](../../../pages-for-subheaders/enable-experimental-features.md)。 +要了解功能的值以及如何启用它们，请参阅[启用实验性功能](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 :::note diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md index e30a94c6d8b..1d8ee6a2926 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md @@ -7,7 +7,7 @@ keywords: [rancher v2.0-v2.4 Helm Chart, rancher v2.0-v2.4 helm 选项, rancher 如需选择 Helm Chart 版本，请参见[本页](../../../getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md)。 -了解开启实验性功能的详情，请参见[本页](../../../pages-for-subheaders/enable-experimental-features.md)。 +了解开启实验性功能的详情，请参见[本页](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 ## 常用选项 @@ -78,13 +78,13 @@ kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ 启用 [API 审计日志](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md)。 -你可以像收集其他容器日志一样收集此日志。在 Rancher Server 集群上为 `System` 项目启用 [Logging](../../../pages-for-subheaders/logging.md)。 +你可以像收集其他容器日志一样收集此日志。在 Rancher Server 集群上为 `System` 项目启用 [Logging](../../../integrations-in-rancher/logging/logging.md)。 ```plain --set auditLog.level=1 ``` -默认情况下，启用审计日志会在 Rancher pod 中创建一个 Sidecar 容器。这个容器（`rancher-audit-log`）会把日志流传输到 `stdout`。你可以像收集其他容器日志一样收集此日志。如果你使用 Sidecar 作为审计日志的目标时， `hostPath`，`maxAge`，`maxBackups` 和 `maxSize` 选项不会生效。建议使用你的操作系统或 Docker Daemon 的日志轮换功能来控制磁盘空间的使用。请为 Rancher Server 集群或 System 项目启用 [Logging](../../../pages-for-subheaders/logging.md)。 +默认情况下，启用审计日志会在 Rancher pod 中创建一个 Sidecar 容器。这个容器（`rancher-audit-log`）会把日志流传输到 `stdout`。你可以像收集其他容器日志一样收集此日志。如果你使用 Sidecar 作为审计日志的目标时， `hostPath`，`maxAge`，`maxBackups` 和 `maxSize` 选项不会生效。建议使用你的操作系统或 Docker Daemon 的日志轮换功能来控制磁盘空间的使用。请为 Rancher Server 集群或 System 项目启用 [Logging](../../../integrations-in-rancher/logging/logging.md)。 将 `auditLog.destination` 的值设为 `hostPath`，可以将日志转发到与主机系统共享的卷，而不是传输到 Sidecar 容器。如果目标设置为 `hostPath`，你可能需要调整其他 auditLog 参数以进行日志轮换。 @@ -156,7 +156,7 @@ Rancher 的一些功能（Helm Chart）需要使用互联网才能使用。你 不包括敏感数据时，可以使用 `proxy` 或 `extraEnv` Chart 选项。使用 `extraEnv` 时将忽略 `noProxy` Helm 选项。因此，`NO_PROXY` 环境变量也必须设置为 `extraEnv`。 -以下是使用 `extraEnv` Chart 选项设置代理的示例： +以下是使用 `proxy` Chart 选项设置代理的示例： ```plain --set proxy="http:///" @@ -199,7 +199,7 @@ kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca- ### 私有仓库和离线安装 -有关使用私有仓库安装 Rancher 的详情，请参见[离线安装](../../../pages-for-subheaders/air-gapped-helm-cli-install.md)。 +有关使用私有仓库安装 Rancher 的详情，请参见[离线安装](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 ## 外部 TLS 终止 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/installation-references.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/installation-references.md new file mode 100644 index 00000000000..c2d9035c3cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-references/installation-references.md @@ -0,0 +1,5 @@ +--- +title: 安装参考 +--- + +有关其他安装资源，请参阅以下参考指南：[Rancher Helm Chart 选项](helm-chart-options.md)、[TLS 设置](tls-settings.md)和[功能开关](feature-flags.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/install-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/install-docker.md index 5514a3af62a..04149ca1bb1 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/install-docker.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/install-docker.md @@ -2,19 +2,19 @@ title: 安装 Docker --- -在使用 Helm 或 Docker 在 RKE 集群节点上安装 Rancher Server 前，你需要先安装 Docker。RKE2 和 K3s 集群不要求使用 Docker。 +在使用 Helm 在 RKE 集群节点上或使用 Docker 安装 Rancher Server 前，你需要在节点中先安装 Docker。RKE2 和 K3s 集群不要求使用 Docker。 Docker 有几个安装方法。一种方法是参见 [Docker 官方文档](https://docs.docker.com/install/)以了解如何在 Linux 上安装 Docker。不同 Linux 发行版的安装步骤可能有所不同。 -另一种方式是使用 Rancher 的 Docker 安装脚本，该脚本可用于较新的 Docker 版本。 +另一种方式是使用 Rancher 的 Docker 安装脚本，该脚本可用于较新的 Docker 版本。 Rancher 为每个 Kubernetes 支持的上游 Docker 版本提供了安装脚本。 -例如，你可执行以下命令，在 Ubuntu 上安装 Docker 20.10： +例如，此命令可用于在 SUSE Linux Enterprise 或 Ubuntu 等主要 Linux 发行版上安装 Docker ： -``` -curl https://releases.rancher.com/install-docker/20.10.sh | sh +```bash +curl https://releases.rancher.com/install-docker/.sh | sh ``` -Rancher 提供 Kubernetes 支持的所有上游 Docker 版本的安装脚本。如需了解我们是否提供某个 Docker 版本的安装脚本，请参见包含了 Rancher 所有的 Docker 安装脚本的 [GitHub 仓库](https://github.com/rancher/install-docker)。 +请参阅 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix)，使用匹配你的操作系统和 Rancher 版本并且经过验证的 Docker 版本。 尽管支持矩阵列出了经过验证的 Docker 版本直至补丁版本，但只有发行版的主要版本和次要版本与 Docker 安装脚本相关。 请注意，必须应用以下 sysctl 设置： diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md new file mode 100644 index 00000000000..c18ac730e3c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md @@ -0,0 +1,215 @@ +--- +title: 安装要求 +description: 如果 Rancher 配置在 Docker 或 Kubernetes 中运行时，了解运行 Rancher Server 的每个节点的节点要求 +--- + +本文描述了对需要安装 Rancher Server 的节点的软件、硬件和网络要求。Rancher Server 可以安装在单个节点或高可用的 Kubernetes 集群上。 + +:::note 重要提示： + +如果你需要在 Kubernetes 集群上安装 Rancher，该节点的要求与用于运行应用和服务的[下游集群的节点要求](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)不同。 + +::: + +Rancher UI 在基于 Firefox 或 Chromium 的浏览器（Chrome、Edge、Opera、Brave）中效果最佳。 + +查看我们的[最佳实践](../../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md)页面，获取在生产环境中运行 Rancher Server 的建议。 + +## Kubernetes 与 Rancher 的兼容性 + +Rancher 需要安装在支持的 Kubernetes 版本上。请查阅 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-6-10/)，确保你的 Kubernetes 版本受支持。 + +## 操作系统和容器运行时要求 + +所有支持的操作系统都使用 64-bit x86 架构。Rancher 兼容当前所有的主流 Linux 发行版。 + +[Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-6-10/)列出了每个 Rancher 版本测试过的操作系统和 Docker 版本。 + +运行 RKE 集群的节点需要安装 Docker。RKE2 或 K3s 集群不需要它。 + +请安装 `ntp`（Network Time Protocol），以防止在客户端和服务器之间由于时间不同步造成的证书验证错误。 + +某些 Linux 发行版的默认防火墙规则可能会阻止 Kubernetes 集群内的通信。从 Kubernetes v1.19 开始，你必须关闭 firewalld，因为它与 Kubernetes 网络插件冲突。 + +如果你不太想这样做的话，你可以查看[相关问题](https://github.com/rancher/rancher/issues/28840)中的建议。某些用户已能成功[使用 ACCEPT 策略 为 Pod CIDR 创建一个独立的 firewalld 区域](https://github.com/rancher/rancher/issues/28840#issuecomment-787404822)。 + +如果你需要在 ARM64 上使用 Rancher，请参见[在 ARM64（实验功能）上运行 Rancher](../../../how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md)。 + +### RKE2 要求 + +对于容器运行时，RKE2 附带了自己的 containerd。RKE2 安装不需要 Docker。 + +如需了解 RKE2 通过了哪些操作系统版本的测试，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions)。 + + +### K3s 要求 + +对于容器运行时，K3s 默认附带了自己的 containerd。你也可以将 K3s 配置为使用已安装的 Docker 运行时。有关在 Docker 中使用 K3s 的更多信息，请参阅 [K3s 文档](https://docs.k3s.io/advanced#using-docker-as-the-container-runtime)。 + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-6-10/)。如需指定 K3s 版本，在运行 K3s 安装脚本时，使用 `INSTALL_K3S_VERSION` 环境变量。 + +如果你使用 **Raspbian Buster** 在 K3s 集群上安装 Rancher，请按照[这些步骤](https://rancher.com/docs/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster)切换到旧版 iptables。 + +如果你使用 Alpine Linux 的 K3s 集群上安装 Rancher，请按照[这些步骤](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup)进行其他设置。 + +### RKE 要求 + +RKE 需要 Docker 容器运行时。支持的 Docker 版本请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) + +有关详细信息，请参阅[安装 Docker](install-docker.md)。 + +## 硬件要求 + +本节描述安装 Rancher Server 的节点的 CPU、内存和磁盘要求。硬件要求根据你的 Rancher 部署规模而定。 + +### 实际考虑 + +Rancher 的硬件占用空间取决于许多因素，包括： + + - 托管的基础设施规模 (例如： 节点数量，集群数量)。 + - 所需访问控制规则的复杂性（例如：RoleBinding 对象计数）。 + - 工作负载数量 (例如： Kubernetes 部署，Fleet 部署)。 + - 使用模式 (例如：主动使用的功能集合，使用频率，并发用户数量). + +由于存在许多可能随时间变化的影响因素，因此此处列出的要求为适合大多数用例的起点。 然而，你的用例可能有不同的要求。 若你需要对于特定场景的咨询，请[联系 Rancher]((https://rancher.com/contact/)) 以获得进一步指导。 + + +特别指出，本页面中的要求基于以下假设的环境提出，包括： + - 每种类型的 Kubernetes 资源数量小于 60,000 个。 + - 每个节点最多 120 个 Pod。 + - 上游（本地）集群中最多 200 个 CRD。 + - 下游集群中最多 100 个 CRD。 + - 最多 50 个 Fleet 部署。 + +更多的数量也是能够达到的，但需要更高的硬件要求。 如果你有超过 20,000 个相同类型的资源，通过 Rancher UI 加载整个列表的时间可能需要几秒钟。 + +:::note Evolution: + +Rancher 的代码库不断发展，用例不断变化，Rancher 积累的经验也在不断增长。 + +随着指导方针的准确性不断的提高并且变得更加具体，硬件要求也会发生变化。 + +如果你发现你的 Rancher 部署不再符合列出的建议，请[联系 Rancher](https://rancher.com/contact/) 进行重新评估。 + +::: + +### RKE2 Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +| --------------- | -------- | --------- | ----- | ---- | +| 小 | 150 | 1500 | 4 | 16 GB | +| 中 | 300 | 3000 | 8 | 32 GB | +| 大 (*) | 500 | 5000 | 16 | 64 GB | +| 更大 (†) | (†) | (†) | (†) | (†) | + +(*)： 大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +(†)： 通过特别的硬件建议和调整能够实现更大的部署规模。 你可以[联系 Rancher](https://rancher.com/contact/) 进行定制评估。 + +有关 RKE2 一般要求的更多详细信息，请参见 [RKE2 文档](https://docs.rke2.io/install/requirements)。 + +### K3s Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | 外部数据库(*) | +| --------------- | ---------- | ------------ | -------| ---------| ------------------------- | +| Small | 150 | 1500 | 4 | 16 GB | 2 vCPUs, 8 GB + 1000 IOPS | +| Medium | 300 | 3000 | 8 | 32 GB | 4 vCPUs, 16 GB + 2000 IOPS | +| Large (†) | 500 | 5000 | 16 | 64 GB | 8 vCPUs, 32 GB + 4000 IOPS | + +(*)：外部数据库是指将 K3s 集群数据存储在[专用的外部主机](https://docs.k3s.io/datastore)上。 这是可选的。 具体要求取决于使用的外部数据库。 + +(†)：大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +有关 K3s 一般要求的更多详细信息，请参见 [K3s 文档](https://docs.k3s.io/installation/requirements)。 + +### 托管 Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +这些要求适用于托管 Kubernetes 集群，例如 Amazon Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS) 或 Google Kubernetes Engine (GKE)。 它们不适用于 Rancher SaaS 解决方案，例如 [Rancher Prime Hosted](https://www.rancher.com/products/rancher)。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +|-----------------------------|----------------------------|-------------------------|-------|-------| +| 小 | 150 | 1500 | 4 | 16 GB | +| 中 | 300 | 3000 | 8 | 32 GB | +| 大 (*) | 500 | 5000 | 16 | 64 GB | + +(*)：大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + + +### RKE + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +|-----------------------------|----------------------------|-------------------------|-------|-------| +| 小 | 150 | 1500 | 4 | 16 GB | +| 中 | 300 | 3000 | 8 | 32 GB | +| 大 (*) | 500 | 5000 | 16 | 64 GB | + +(*)： 大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +有关 RKE 一般要求的更多详细信息，请参见 [RKE 文档](https://rke.docs.rancher.com/os)。 + +### Docker + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，在 Docker 中安装 Rancher 仅适用于开发或测试目的。不建议在生产环境中使用。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +|-----------------------------|----------------------------|-------------------------|-------|------| +| 小 | 5 | 50 | 1 | 4 GB | +| 中 | 15 | 200 | 2 | 8 GB | + +## Ingress + +安装 Rancher 的 Kubernetes 集群中的每个节点都应该运行一个 Ingress。 + +Ingress 需要部署为 DaemonSet 以确保负载均衡器能成功把流量转发到各个节点。 + +如果是 RKE，RKE2 和 K3s 安装，你不需要手动安装 Ingress，因为它是默认安装的。 + +对于托管的 Kubernetes 集群（EKS、GKE、AKS），你需要设置 Ingress。 + +- **Amazon EKS**：[在 Amazon EKS 上安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md)。 +- **AKS**：[使用 Azure Kubernetes 服务安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md)。 +- **GKE**：[使用 GKE 安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md)。 + +## 磁盘 + +etcd 在集群中的性能决定了 Rancher 的性能。因此，为了获得最佳速度，我们建议使用 SSD 磁盘来支持 Rancher 管理的 Kubernetes 集群。在云提供商上，你还需使用能获得最大 IOPS 的最小大小。在较大的集群中，请考虑使用专用存储设备存储 etcd 数据和 wal 目录。 + +## 网络要求 + +本节描述了安装 Rancher Server 的节点的网络要求。 + +:::caution + +如果包含 Rancher 的服务器带有 `X-Frame-Options=DENY` 标头，在升级旧版 UI 之后，Rancher UI 中的某些页面可能无法渲染。这是因为某些旧版页面在新 UI 中是以 iFrames 模式嵌入的。 + +::: + +### 节点 IP 地址 + +无论你是在单个节点还是高可用集群上安装 Rancher，每个节点都应配置一个静态 IP。如果使用 DHCP，则每个节点都应该有一个 DHCP 预留，以确保节点分配到相同的 IP 地址。 + +### 端口要求 + +为了确保能正常运行，Rancher 需要在 Rancher 节点和下游 Kubernetes 集群节点上开放一些端口。不同集群类型的 Rancher 和下游集群的所有必要端口，请参见[端口要求](port-requirements.md)。 + +## Dockershim 支持 + +有关 Dockershim 支持的详情，请参见[此页面](dockershim.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md index 3646b0b255a..06eb5baf78b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -179,9 +179,9 @@ RKE2 server 需要开放端口 6443 和 9345 才能供集群中的其他节点 下游 Kubernetes 集群用于运行你的应用和服务。本节介绍了哪些端口需要在下游集群的节点上打开，以便 Rancher 能够与它们进行通信。 -不同的下游集群的启动方式有不同的端口要求。下面的每个标签都列出了不同[集群类型](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md)所需打开的端口。 +不同的下游集群的启动方式有不同的端口要求。下面的每个标签都列出了不同[集群类型](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)所需打开的端口。 -下图描述了为每个[集群类型](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md)打开的端口。 +下图描述了为每个[集群类型](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)打开的端口。
Rancher 管理面板的端口要求
@@ -198,7 +198,7 @@ RKE2 server 需要开放端口 6443 和 9345 才能供集群中的其他节点
单击展开 -下表描述了节点在[云提供商](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md)中创建的情况下，[Rancher 启动 Kubernetes](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) 的端口要求。 +下表描述了节点在[云提供商](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)中创建的情况下，[Rancher 启动 Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的端口要求。 :::note @@ -215,7 +215,7 @@ RKE2 server 需要开放端口 6443 和 9345 才能供集群中的其他节点
单击展开 -下表描述了使用[自定义节点](../../../pages-for-subheaders/use-existing-nodes.md)的情况下，[Rancher 启动 Kubernetes](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) 的端口要求。 +下表描述了使用[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)的情况下，[Rancher 启动 Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的端口要求。 @@ -226,7 +226,7 @@ RKE2 server 需要开放端口 6443 和 9345 才能供集群中的其他节点
单击展开 -下表描述了[托管集群](../../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md)的端口要求。 +下表描述了[托管集群](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)的端口要求。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md new file mode 100644 index 00000000000..4e36f893125 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md @@ -0,0 +1,31 @@ +--- +title: 离线 Helm CLI 安装 +--- + +本文介绍如何使用 Helm CLI 在离线环境中安装 Rancher Server。离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +Rancher 安装在 RKE Kubernetes 集群、K3s Kubernetes 集群，或单个 Docker 容器上对应的安装步骤会有所不同。 + +如需了解各个安装方式的更多信息，请参见[本页](../../installation-and-upgrade.md)。 + +在安装指导中，我们为不同的安装选项提供对应的 _选项卡_ 。 + +:::note 重要提示： + +如果你按照 Docker 安装指南安装 Rancher，你将没有把 Docker 安装转换为 Kubernetes 安装的升级途径。 + +::: + +## 安装概要 + +1. [设置基础设施和私有镜像仓库](infrastructure-private-registry.md) +2. [收集镜像到私有镜像仓库](publish-images.md) +3. [设置 Kubernetes 集群（如果你使用 Docker 安装，请跳过此步骤）](install-kubernetes.md) +4. [安装 Rancher](install-rancher-ha.md) + +## 升级 + +如需在离线环境中使用 Helm CLI 升级 Rancher，请按照[升级步骤](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md)进行操作。 + +### 后续操作 +[准备节点](infrastructure-private-registry.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md index 10215349175..a57420fa657 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md @@ -6,7 +6,7 @@ title: '1. 设置基础设施和私有镜像仓库' 离线环境是 Rancher Server 离线安装或安装在防火墙后面的环境。 -Rancher 安装在 K3s Kubernetes 集群、RKE Kubernetes 集群还是单个 Docker 容器上对应的基础设施设置会有所不同。如需了解各个安装方式的更多信息，请参见[本页](../../../../pages-for-subheaders/installation-and-upgrade.md)。 +Rancher 安装在 K3s Kubernetes 集群、RKE Kubernetes 集群还是单个 Docker 容器上对应的基础设施设置会有所不同。如需了解各个安装方式的更多信息，请参见[本页](../../installation-and-upgrade.md)。 Rancher 可以安装在任何 Kubernetes 集群上。为了阅读方便，我们在下文中仍提供了 RKE 和 K3s Kubernetes 基础设施教程。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md index e229fd7b360..58b3c2eb720 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -4,11 +4,11 @@ title: '2. 收集镜像并发布到私有仓库' 本文介绍如何配置私有镜像仓库，以便在安装 Rancher 时，Rancher 可以从此私有镜像仓库中拉取所需的镜像。 -默认情况下，所有用于[配置 Kubernetes 集群](../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md)或启动 Rancher 中的工具（如监控，流水线，告警等）的镜像都是从 Docker Hub 中拉取的。在 Rancher 的离线安装中，你需要一个私有仓库，该仓库位于你的 Rancher Server 中某个可访问的位置。然后，你可加载该存有所有镜像的镜像仓库。 +默认情况下，所有用于[配置 Kubernetes 集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)或启动 Rancher 中的工具（如监控，流水线，告警等）的镜像都是从 Docker Hub 中拉取的。在 Rancher 的离线安装中，你需要一个私有仓库，该仓库位于你的 Rancher Server 中某个可访问的位置。然后，你可加载该存有所有镜像的镜像仓库。 使用 Docker 安装 Rancher，和把 Rancher 安装到 Kubernetes 集群，其对应的推送镜像到私有镜像仓库步骤是一样的。 -你使用 Rancher 配置的下游集群是否有运行 Windows 的节点，决定了本文涉及的步骤。我们提供的推送镜像到私有镜像仓库步骤，是基于假设 Rancher 仅配置运行 Linux 节点的下游 Kubernetes 集群的。但是，如果你计划[在下游 Kubernetes 集群中使用 Windows 节点](../../../../pages-for-subheaders/use-windows-clusters.md)，我们有单独的文档来介绍如何为需要的镜像提供支持。 +你使用 Rancher 配置的下游集群是否有运行 Windows 的节点，决定了本文涉及的步骤。我们提供的推送镜像到私有镜像仓库步骤，是基于假设 Rancher 仅配置运行 Linux 节点的下游 Kubernetes 集群的。但是，如果你计划[在下游 Kubernetes 集群中使用 Windows 节点](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)，我们有单独的文档来介绍如何为需要的镜像提供支持。 :::note 先决条件： diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md new file mode 100644 index 00000000000..24d8ac7d47c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md @@ -0,0 +1,19 @@ +--- +title: 其他安装方式 +--- + +### 离线安装 + +按照[以下步骤](air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)在离线环境中安装 Rancher Server。 + +离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +### Docker 安装 + +[单节点 Docker 安装](rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)适用于想要测试 Rancher 的用户。你无需使用 Helm 在 Kubernetes 集群上运行 Rancher，你可以使用 `docker run` 命令，把 Rancher Server 组件安装到单个节点上。 + +Docker 安装仅用于开发和测试环境。 + +由于只有一个节点和一个 Docker 容器，因此，如果该节点发生故障，由于其他节点上没有可用的 etcd 数据副本，你将丢失 Rancher Server 的所有数据。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md new file mode 100644 index 00000000000..1701dba329e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md @@ -0,0 +1,13 @@ +--- +title: 使用 HTTP 代理安装 Rancher +--- + +很多企业本地运行的服务器或虚拟机不能直接访问互联网，但是出于安全考虑，他们必须通过 HTTP(S) 代理连接到外部服务。本教程将分步介绍如何在这样的环境中进行高可用的 Rancher 安装。 + +另外，用户也可以在没有任何互联网访问的情况下离线设置 Rancher。详情请参见 [Rancher 官方文档](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 + +## 安装概要 + +1. [配置基础设施](set-up-infrastructure.md) +2. [配置 Kubernetes 集群](install-kubernetes.md) +3. [安装 Rancher](install-rancher.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md index 58414b8ed1d..f60e31b2c3e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md @@ -22,7 +22,7 @@ title: '1. 配置基础设施' 这些主机将通过 HTTP 代理连接到互联网。 -请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../../../pages-for-subheaders/installation-requirements.md)的常规要求。 +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../installation-requirements/installation-requirements.md)的常规要求。 如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)的教程。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 6e1ac8ee365..34ee707431b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -2,6 +2,8 @@ title: 证书故障排除 --- + + ### 如何确定我的证书格式是否为 PEM？ 你可以通过以下特征识别 PEM 格式： diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md new file mode 100644 index 00000000000..c2a63b86a5e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -0,0 +1,209 @@ +--- +title: 使用 Docker 将 Rancher 安装到单个节点中 +description: 在开发和测试环境中，你可以使用 Docker 安装。在单个 Linux 主机上安装 Docker，然后使用一个 Docker 容器部署 Rancher。 +--- + + + +Rancher 可以通过运行单个 Docker 容器进行安装。 + +在这种安装方案中，你需要将 Docker 安装到单个 Linux 主机，然后使用单个 Docker 容器将 Rancher 部署到主机中。 + +:::note 想要使用外部负载均衡器？ + +请参阅[使用外部负载均衡器的 Docker 安装](../../../../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md)。 + +::: + +Rancher 的 Docker 安装仅推荐用于开发和测试环境中。Rancher 版本决定了能否将 Rancher 迁移到高可用集群。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +## Rancher 特权访问 + +当 Rancher Server 部署在 Docker 容器中时，容器内会安装一个本地 Kubernetes 集群供 Rancher 使用。为 Rancher 的很多功能都是以 deployment 的方式运行的，而在容器内运行容器是需要特权模式的，因此你需要在安装 Rancher 时添加 `--privileged` 选项。 + +## 操作系统，Docker，硬件和网络要求 + +请确保你的节点满足常规的[安装要求](../../installation-requirements/installation-requirements.md)。 + +## 1. 配置 Linux 主机 + +按照[要求](../../installation-requirements/installation-requirements.md)配置一个 Linux 主机，用于运行 Rancher Server。 + +## 2. 选择一个 SSL 选项并安装 Rancher + +出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。 + +:::tip 你是否需要： + +- 使用代理。参见 [HTTP 代理配置](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md)。 +- 配置自定义 CA 根证书以访问服务。参见[自定义 CA 根证书](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#自定义-ca-证书)。 +- 完成离线安装。参见 [离线：Docker 安装](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 +- 记录所有 Rancher API 的事务。参加 [API 审计](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志)。 + +::: + +选择以下的选项之一： + +- [选项 A：使用 Rancher 生成的默认自签名证书](#选项-a使用-rancher-生成的默认自签名证书) +- [选项 B：使用你自己的证书 - 自签名](#选项-b使用你自己的证书---自签名) +- [选项 C：使用你自己的证书 - 可信 CA 签名的证书](#选项-c使用你自己的证书---可信-ca-签名的证书) +- [选项 D：Let's Encrypt 证书](#选项-dlets-encrypt-证书) +- [选项 E：Localhost 隧道，不使用证书](#选项-elocalhost-隧道不使用证书) + +### 选项 A：使用 Rancher 生成的默认自签名证书 + +如果你在不考虑身份验证的开发或测试环境中安装 Rancher，可以使用 Rancher 生成的自签名证书安装 Rancher。这种安装方式避免了自己生成证书的麻烦。 + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest +``` + +### 选项 B：使用你自己的证书 - 自签名 +在你团队访问 Rancher Server 的开发或测试环境中，创建一个用于你的安装的自签名证书，以便团队验证他们对实例的连接。 + +:::note 先决条件： + +使用 [OpenSSL](https://www.openssl.org/) 或其他方法创建自签名证书。 + +- 证书文件的格式必须是 PEM。 +- 在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)。 + +::: + +创建证书后，运行以下 Docker 命令以安装 Rancher。使用 `-v` 标志并提供证书的路径，以将证书挂载到容器中。 + +| 占位符 | 描述 | +| ------------------- | --------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | CA 证书的路径。 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher:latest +``` + +### 选项 C：使用你自己的证书 - 可信 CA 签名的证书 + +在公开暴露应用的生产环境中，请使用由可信 CA 签名的证书，以避免用户收到证书安全警告。 + +不建议将 Docker 安装用于生产环境。这些说明仅适用于测试和开发。 + +:::note 先决条件： + +- 证书文件的格式必须是 PEM。 +- 在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)。 + +::: + +获取证书后，运行以下 Docker 命令。 + +- 使用 `-v` 标志并提供证书的路径，以将证书挂载到容器中。因为你的证书是由可信的 CA 签名的，因此你不需要安装额外的 CA 证书文件。 +- 使用 `--no-cacerts` 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。 + +| 占位符 | 描述 | +| ------------------- | ----------------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +### 选项 D：Let's Encrypt 证书 + +:::caution + +Let's Encrypt 对新证书请求有频率限制。因此，请限制创建或销毁容器的频率。详情请参见 [Let's Encrypt 官方文档 - 频率限制](https://letsencrypt.org/docs/rate-limits/)。 + +::: + +你也可以在生产环境中使用 [Let's Encrypt](https://letsencrypt.org/) 证书。Let's Encrypt 使用 HTTP-01 质询来验证你对域名的控制权。如果要确认你对该域名有控制权，你可将用于访问 Rancher 的主机名（例如 `rancher.mydomain.com`）指向运行的主机的 IP。你可通过在 DNS 中创建 A 记录，以将主机名绑定到 IP 地址。 + +不建议将 Docker 安装用于生产环境。这些说明仅适用于测试和开发。 + +:::note 先决条件： + +- Let's Encrypt 是联网服务。因此，在内网和离线环境中不能使用。 +- 在 DNS 中创建一条记录，将 Linux 主机 IP 地址绑定到要用于访问 Rancher 的主机名（例如，`rancher.mydomain.com`）。 +- 在 Linux 主机上打开 `TCP/80` 端口。Let's Encrypt 的 HTTP-01 质询可以来自任何源 IP 地址，因此端口 `TCP/80` 必须开放开所有 IP 地址。 + +::: + +满足先决条件后，你可以运行以下命令使用 Let's Encrypt 证书安装 Rancher。 + +| 占位符 | 描述 | +| ----------------- | ------------------- | +| `` | 你的域名地址 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --acme-domain +``` + +### 选项 E：Localhost 隧道，不使用证书 + +如果你在开发或测试环境中安装 Rancher，且环境中有运行的 localhost 隧道解决方案（如 [ngrok](https://ngrok.com/)），不要生成证书。此安装选项不需要证书。 + +- 使用 `--no-cacerts` 作为参数，以禁用 Rancher 生成的默认 CA 证书。 + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +## 高级选项 + +使用 Docker 将 Rancher 安装到单个节点时，有如下几个可开启的高级选项： + +- 自定义 CA 证书 +- API 审计日志 +- TLS 设置 +- 离线环境 +- 持久化数据 +- 在同一个节点中运行 `rancher/rancher` 和 `rancher/rancher-agent` + +详情请参见[本页](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md)。 + +## 故障排除 + +如需了解常见问题及故障排除提示，请参见[本页](certificate-troubleshooting.md)。 + +## 后续操作 + +- **推荐**：检查单节点[备份](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md)和[恢复](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md)。你可能暂时没有需要备份的数据，但是我们建议你在常规使用 Rancher 后创建备份。 +- 创建 Kubernetes 集群：[配置 Kubernetes 集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 32fbf2f4254..762ec2bd1a5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -2,6 +2,8 @@ title: 回滚 Docker 安装的 Rancher --- + + 如果 Rancher 升级没有成功完成，你需要回滚到你在 [Docker 升级](upgrade-docker-installed-rancher.md)之前使用的 Rancher 设置。回滚可以恢复： - 先前版本的 Rancher。 @@ -78,7 +80,7 @@ docker pull rancher/rancher: --privileged \ rancher/rancher: ``` - 特权访问是[必须](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + 特权访问是[必须](rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 :::danger diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index 68d23b34c33..7dbef6d2cab 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -13,7 +13,7 @@ title: 升级 Docker 安装的 Rancher ## 先决条件 - 在 Rancher 文档中**检查[已知升级问题](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#已知升级问题)**，了解升级 Rancher 时最需要注意的问题。你可以在 [GitHub](https://github.com/rancher/rancher/releases) 发布说明以及 [Rancher 论坛](https://forums.rancher.com/c/announcements/12)中找到每个 Rancher 版本的已知问题。不支持升级或升级到 [rancher-alpha 仓库](../../resources/choose-a-rancher-version.md#helm-chart-仓库)中的任何 Chart。 -- **[仅适用于离线安装](../../../../pages-for-subheaders/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像**。按照指南为你想要升级的目标 Rancher 版本[推送镜像到私有镜像仓库](../air-gapped-helm-cli-install/publish-images.md)。 +- **[仅适用于离线安装](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像**。按照指南为你想要升级的目标 Rancher 版本[推送镜像到私有镜像仓库](../air-gapped-helm-cli-install/publish-images.md)。 ## 占位符 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/add-tls-secrets.md index dc58f216be0..87f320d0dca 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/add-tls-secrets.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -42,4 +42,4 @@ Rancher 启动时会检索配置的 `tls-ca` 密文。如果 Rancher 在运行 ## 更新私有 CA 证书 -按照[步骤](update-rancher-certificate.md)更新 [Rancher 高可用 Kubernetes 安装](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md)中的 Ingress，或从默认自签名证书切换到自定义证书。 \ No newline at end of file +按照[步骤](update-rancher-certificate.md)更新 [Rancher 高可用 Kubernetes 安装](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中的 Ingress，或从默认自签名证书切换到自定义证书。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md index b168ecdcb05..7ddfcef2d8e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md @@ -11,7 +11,7 @@ title: 选择 Rancher 版本 -如果 Rancher Server 是[安装在 Kubernetes 集群上](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md)的，Rancher Server 的安装，升级和回滚中，都是使用 Kubernetes 集群上的 Helm Chart 来安装 Rancher 的。因此，在准备安装或升级 Rancher 高可用时，必须添加包含用于安装 Rancher 的 Chart 的 Helm Chart 仓库。 +如果 Rancher Server 是[安装在 Kubernetes 集群上](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)的，Rancher Server 的安装，升级和回滚中，都是使用 Kubernetes 集群上的 Helm Chart 来安装 Rancher 的。因此，在准备安装或升级 Rancher 高可用时，必须添加包含用于安装 Rancher 的 Chart 的 Helm Chart 仓库。 请参见 [Helm 版本要求](helm-version-requirements.md)选择 Helm 版本来安装 Rancher。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md index 273711a4de0..a5e0a779fc7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/helm-version-requirements.md @@ -4,7 +4,7 @@ title: Helm 版本要求 本文介绍 Helm 的要求。Helm 是用于把 Rancher 安装在高可用 Kubernetes 集群上的工具。 -> 我们已针对 Helm 3 更新了安装指南。如果你使用 Helm 2 进行安装，请参见 [Helm 2 迁移到 Helm 3 文档](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/)。[本文](/versioned_docs/version-2.0-2.4/pages-for-subheaders/helm2.md)提供了较早的使用 Helm 2 的 Rancher 高可用安装指南的副本。如果你如果无法升级到 Helm 3，可以使用这个说明安装。 +> 我们已针对 Helm 3 更新了安装指南。如果你使用 Helm 2 进行安装，请参见 [Helm 2 迁移到 Helm 3 文档](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/)。[本文](/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm2.md)提供了较早的使用 Helm 2 的 Rancher 高可用安装指南的副本。如果你如果无法升级到 Helm 3，可以使用这个说明安装。 - 如需安装或升级 Rancher 2.5，请使用 Helm 3.2.x 或更高版本。 - Kubernetes 1.16 要求 Helm 2.16.0 或更高版本。如果使用的是默认 Kubernetes 版本，请参见[发行说明](https://github.com/rancher/rke/releases)获取所使用的 RKE 版本。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/local-system-charts.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/local-system-charts.md index 4048c5b2566..17c965ad095 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/local-system-charts.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -10,4 +10,4 @@ title: 离线安装中设置本地 System Charts `system-charts` 的一个本地副本已经打包到 `rancher/rancher` 容器中。为了在离线安装中使用这些功能，你需要使用额外的环境变量 `CATTLE_SYSTEM_CATALOG=bundled` 来运行 Rancher 安装命令，该环境变量告诉 Rancher 使用 Chart 的本地副本，而不是尝试从 GitHub 获取 Chart。 -带有 `system-charts` 的 Rancher 安装命令示例包含在 Docker 和 Helm 的[离线安装说明](../../../pages-for-subheaders/air-gapped-helm-cli-install.md)中。 +带有 `system-charts` 的 Rancher 安装命令示例包含在 Docker 和 Helm 的[离线安装说明](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/resources.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/resources.md new file mode 100644 index 00000000000..2862aba2cd2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/resources/resources.md @@ -0,0 +1,25 @@ +--- +title: 资源 +--- + +### Docker 安装 + +[单节点 Docker 安装](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)适用于想要测试 Rancher 的用户。你无需使用 Helm 在 Kubernetes 集群上运行 Rancher，你可以使用 `docker run` 命令，把 Rancher Server 组件安装到单个节点上。 + +由于只有一个节点和一个 Docker 容器，因此，如果该节点发生故障，由于其他节点上没有可用的 etcd 数据副本，你将丢失 Rancher Server 的所有数据。 + +### 离线安装 + +按照[以下步骤](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)在离线环境中安装 Rancher Server。 + +离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +### 高级选项 + +安装 Rancher 时，有如下几个可开启的高级选项：每个安装指南中都提供了对应的选项。了解选项详情： + +- [自定义 CA 证书](custom-ca-root-certificates.md) +- [API 审计日志](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) +- [TLS 设置](../installation-references/tls-settings.md) +- [etcd 配置](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md) +- [离线安装 Local System Chart](local-system-charts.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md index 98de6aef74e..0e4467c0fbd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md @@ -32,9 +32,9 @@ RKE v1.1.0 改变了集群升级的方式。 :::note 先决条件： -- 以下选项适用于 [Rancher 启动的 Kubernetes 集群](../../pages-for-subheaders/launch-kubernetes-with-rancher.md)和[注册的 K3s Kubernetes 集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#已注册-k3s-集群的附加功能)。 +- 以下选项适用于 [Rancher 启动的 Kubernetes 集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)和[注册的 K3s Kubernetes 集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#已注册-k3s-集群的附加功能)。 - 以下选项也适用于导入且已注册的 RKE2 集群。如果你从外部云平台导入集群但不注册，你将无法在 Rancher 中升级 Kubernetes 版本。 -- 在升级 Kubernetes 之前，先[备份你的集群](../../pages-for-subheaders/backup-restore-and-disaster-recovery.md)。 +- 在升级 Kubernetes 之前，先[备份你的集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md)。 ::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md index 5778609354b..1945c1422f0 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md @@ -10,7 +10,7 @@ Kubernetes API 可以在次要版本之间更改。因此，我们不支持引 ::: -Rancher 的 Kubernetes 元数据包含 Rancher 用于配置 [RKE 集群](../../pages-for-subheaders/launch-kubernetes-with-rancher.md)的 Kubernetes 版本信息。Rancher 会定期同步数据并为 **系统镜像**、**服务选项**和**插件模板**创建自定义资源定义 (CRD)。因此，当新的 Kubernetes 版本与 Rancher Server 版本兼容时，Kubernetes 元数据可以使 Rancher 使用新版本来配置集群。元数据概述了 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) 用于部署各种 Kubernetes 版本的信息。 +Rancher 的 Kubernetes 元数据包含 Rancher 用于配置 [RKE 集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的 Kubernetes 版本信息。Rancher 会定期同步数据并为 **系统镜像**、**服务选项**和**插件模板**创建自定义资源定义 (CRD)。因此，当新的 Kubernetes 版本与 Rancher Server 版本兼容时，Kubernetes 元数据可以使 Rancher 使用新版本来配置集群。元数据概述了 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) 用于部署各种 Kubernetes 版本的信息。 下表描述了受周期性数据同步影响的 CRD。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/overview.md index 4e0414b2630..000d0733dcc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/overview.md @@ -30,21 +30,21 @@ Rancher API Server 是基于嵌入式 Kubernetes API Server 和 etcd 数据库 ### 授权和基于角色的权限控制（RBAC） -- **用户管理**：Rancher API Server 除了管理本地用户，还[管理用户用来访问外部服务所需的认证信息](../pages-for-subheaders/authentication-config.md)，如登录 Active Directory 和 GitHub 所需的账号密码。 -- **授权**：Rancher API Server 可以管理[访问控制策略](../pages-for-subheaders/manage-role-based-access-control-rbac.md)和[安全策略](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md)。 +- **用户管理**：Rancher API Server 除了管理本地用户，还[管理用户用来访问外部服务所需的认证信息](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)，如登录 Active Directory 和 GitHub 所需的账号密码。 +- **授权**：Rancher API Server 可以管理[访问控制策略](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)和[安全策略](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md)。 ### 使用 Kubernetes 的功能 -- **配置 Kubernetes 集群**：Rancher API Server 可以在已有节点上[配置 Kubernetes](../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md)，或进行 [Kubernetes 版本升级](installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 -- **管理应用商店**：Rancher 支持使用 [Helm Chart 应用商店](../pages-for-subheaders/helm-charts-in-rancher.md)实现轻松重复部署应用。 -- **管理项目**：项目由集群中多个命名空间和访问控制策略组成，是 Rancher 中的一个概念，Kubernetes 中并没有这个概念。你可以使用项目实现以组为单位，管理多个命名空间，并进行 Kubernetes 相关操作。Rancher UI 提供用于[项目管理](../pages-for-subheaders/manage-projects.md)和[项目内应用管理](../pages-for-subheaders/kubernetes-resources-setup.md)的功能。 -- **Fleet 持续交付**：在 Rancher 中，你可以使用 [Fleet 持续交付](../pages-for-subheaders/fleet-gitops-at-scale.md)将应用程序从 Git 仓库部署到目标下游 Kubernetes 集群，无需任何手动操作。 -- **Istio**：[Rancher 与 Istio 集成](../pages-for-subheaders/istio.md)，使得管理员或集群所有者可以将 Istio 交给开发者，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署，金丝雀部署，和 A/B 测试进行流量管理。 +- **配置 Kubernetes 集群**：Rancher API Server 可以在已有节点上[配置 Kubernetes](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)，或进行 [Kubernetes 版本升级](installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 +- **管理应用商店**：Rancher 支持使用 [Helm Chart 应用商店](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md)实现轻松重复部署应用。 +- **管理项目**：项目由集群中多个命名空间和访问控制策略组成，是 Rancher 中的一个概念，Kubernetes 中并没有这个概念。你可以使用项目实现以组为单位，管理多个命名空间，并进行 Kubernetes 相关操作。Rancher UI 提供用于[项目管理](../how-to-guides/advanced-user-guides/manage-projects/manage-projects.md)和[项目内应用管理](../how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md)的功能。 +- **Fleet 持续交付**：在 Rancher 中，你可以使用 [Fleet 持续交付](../integrations-in-rancher/fleet-gitops-at-scale/fleet-gitops-at-scale.md)将应用程序从 Git 仓库部署到目标下游 Kubernetes 集群，无需任何手动操作。 +- **Istio**：[Rancher 与 Istio 集成](../integrations-in-rancher/istio/istio.md)，使得管理员或集群所有者可以将 Istio 交给开发者，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署，金丝雀部署，和 A/B 测试进行流量管理。 ### 配置云基础设施 - **同步节点信息**：Rancher API Server 可以同步所有集群中全部[节点](../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md)的信息。 -- **配置云基础设施**：如果你为 Rancher 配置了云提供商，Rancher 可以在云端动态配置[新节点](../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md)和[持久化存储](../pages-for-subheaders/create-kubernetes-persistent-storage.md)。 +- **配置云基础设施**：如果你为 Rancher 配置了云提供商，Rancher 可以在云端动态配置[新节点](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)和[持久化存储](../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md)。 ### 查看集群信息 @@ -54,9 +54,9 @@ Rancher API Server 是基于嵌入式 Kubernetes API Server 和 etcd 数据库 ## 使用 Rancher 编辑下游集群 -对于已有集群而言，可提供的选项和设置取决于你配置集群的方法。例如，只有[通过 RKE 启动](../pages-for-subheaders/launch-kubernetes-with-rancher.md)的集群才有可编辑的**集群选项**。 +对于已有集群而言，可提供的选项和设置取决于你配置集群的方法。例如，只有[通过 RKE 启动](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的集群才有可编辑的**集群选项**。 -使用 Rancher 创建集群后，集群管理员可以管理集群成员，开启 Pod 安全策略，管理节点池，以及进行[其他操作](../pages-for-subheaders/cluster-configuration.md)。 +使用 Rancher 创建集群后，集群管理员可以管理集群成员，开启 Pod 安全策略，管理节点池，以及进行[其他操作](../reference-guides/cluster-configuration/cluster-configuration.md)。 下表总结了每一种类型的集群和对应的可编辑的选项和设置： diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md index 2fc1ce0bd33..1d06135d7f4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md @@ -1,6 +1,6 @@ --- -title: Rancher AWS Marketplace 快速入门 -description: 使用 Amazon EKS 部署 Rancher Server。 +title: Rancher Prime AWS Marketplace 快速入门 +description: 使用 Amazon Marketplace 列表部署 Rancher Server。 --- -Amazon Elastic Kubernetes Service (EKS) 可以快速[将 Rancher 部署到 Amazon Web Services (AWS)](https://documentation.suse.com/trd/kubernetes/single-html/gs_rancher_aws-marketplace/)。详情请参见我们的 [Amazon Marketplace 列表](https://aws.amazon.com/marketplace/pp/prodview-go7ent7goo5ae)。观看 [demo](https://youtu.be/9dznJ7Ons0M)，了解 AWS Marketplace SUSE Rancher 设置的演练。 +你可以快速将 Rancher Prime 部署到 Amazon Elastic Kubernetes Service (EKS)。详情请参见[说明](https://suse-enceladus.github.io/marketplace-docs/rancher-prime/aws/?repository=rancher-payg-billing-adapter-llc-prd)以及我们的 [Amazon Marketplace 列表](https://aws.amazon.com/marketplace/pp/prodview-go7ent7goo5ae)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws.md index cb47333ce32..34590ac8931 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/aws.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher AWS 指南，以快速部署带有单节点 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -86,7 +86,7 @@ AWS 模块只创建一个 EC2 密钥对、一个 EC2 安全组和一个 EC2 实 ## 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/azure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/azure.md index 33a8d411ba0..2775340b7a5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/azure.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/azure.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher Azure 指南，以快速部署带有单节 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -72,7 +72,7 @@ description: 阅读此分步 Rancher Azure 指南，以快速部署带有单节 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md new file mode 100644 index 00000000000..5eebb87e4e8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md @@ -0,0 +1,20 @@ +--- +title: 部署 Rancher Server +--- + +你可使用以下指南之一，在你选择的提供商中部署和配置 Rancher 和 Kubernetes 集群。 + +- [AWS](aws.md)（使用 Terraform） +- [AWS Marketplace](aws-marketplace.md)（使用 Amazon EKS） +- [Azure](azure.md)（使用 Terraform） +- [DigitalOcean](digitalocean.md)（使用 Terraform） +- [GCP](gcp.md)（使用 Terraform） +- [Hetzner Cloud](hetzner-cloud.md)（使用 Terraform） +- [Linode](linode.md) (使用 Terraform) +- [Vagrant](vagrant.md) +- [Equinix Metal](equinix-metal.md) +- [Outscale](outscale-qs.md)（使用 Terraform） + +如有需要，你可以查看以下指南以了解分步步骤。如果你需要在其他提供商中或本地运行 Rancher，或者你只是想看看它是多么容易上手，你可阅读以下指南： + +- [手动安装](helm-cli.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md index e87f17c26d0..8e0280f9fa6 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher DigitalOcean 指南，以快速部署带有 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -65,7 +65,7 @@ description: 阅读此分步 Rancher DigitalOcean 指南，以快速部署带有 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md index c7316352cc2..bca4519d296 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md @@ -11,7 +11,7 @@ title: Rancher Equinix Metal 快速入门 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。不建议将 Docker 安装用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。不建议将 Docker 安装用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -38,7 +38,7 @@ title: Rancher Equinix Metal 快速入门 - 如果使用 CLI 或 API 配置新的 Equinix Metal Server，你需要提供项目 ID、计划、metro 和操作系统。 - 当使用云主机的虚拟机时，你需要允许 80 和 443 端口的入站 TCP 通信。有关端口配置的信息，请参见你的云主机的文档。 - 如需了解所有端口要求，请参见 [Docker 安装](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)。 -- 根据我们的[要求](../../../pages-for-subheaders/installation-requirements.md)配置主机。 +- 根据我们的[要求](../../installation-and-upgrade/installation-requirements/installation-requirements.md)配置主机。 ::: ### 2. 安装 Rancher @@ -103,4 +103,4 @@ title: Rancher Equinix Metal 快速入门 #### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md index 5c113fc447c..74af3068f04 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher GCP 指南，以快速部署带有单节点 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -68,7 +68,7 @@ description: 阅读此分步 Rancher GCP 指南，以快速部署带有单节点 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md index a6bba0c9d1a..75e7d074fd3 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md @@ -10,8 +10,7 @@ title: Helm CLI 快速入门 你的 Linux 主机可以位于任何地方。例如，它可以是 Amazon EC2 实例、Digital Ocean Droplet 或 Azure 虚拟机。其他 Rancher 文档也经常称它们为“节点”。部署 Linux 主机的一种方法是设置一个 Amazon EC2 实例，如[本教程](../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)中所示。 -完整的安装要求在[这里](../../../pages-for-subheaders/installation-requirements.md)。 - +完整的安装要求在[这里](../../installation-and-upgrade/installation-requirements/installation-requirements.md)。 ## 在 Linux 上安装 K3s diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md index 585353441b2..16ebb833b2a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher Hetzner Cloud 指南，以快速部署带 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -67,7 +67,7 @@ description: 阅读此分步 Rancher Hetzner Cloud 指南，以快速部署带 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/linode.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/linode.md new file mode 100644 index 00000000000..9b6a00f6f7e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/linode.md @@ -0,0 +1,79 @@ +--- +title: Rancher Linode 快速入门指南 +description: 阅读此分步 Rancher Linode 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 Linode 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Linode 会产生费用。 + +::: + +- [Linode 账号](https://linode.com): 用于运行服务器和集群。 +- [Linode 访问密钥](https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/): 用于权限认证的 Linode 访问密钥。 +- [Terraform](https://www.terraform.io/downloads.html): 用于在 Linode 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/linode` 命令，进入包含 Terraform 文件的 Linode 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `linode_token` - 上面提到的 Linode 访问密钥。 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [Linode Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/linode) 了解更多信息。 + 建议包括： + - `linode_region` - 创建服务器以及集群的目标 Linode 区域。 + - 默认: `eu-central` + - 完整的区域列表, 请参照[官方的可用区域页面](https://www.linode.com/global-infrastructure/availability/). + - `prefix` - 所有创建资源的前缀 + - `linode_type` - 所有的 Linode 资源使用的类型/计划 + - 默认: `g6-standard-2` + - 完整的计划列表, 请参照[官方的计划类型页面](https://www.linode.com/docs/products/compute/compute-instances/plans/). + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/linode` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 Linode 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/linode` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md index 46b42901db9..76d320a862e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md @@ -7,7 +7,7 @@ description: 阅读此分步 Rancher Outscale 指南，以快速部署带有单 :::note -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -67,7 +67,7 @@ description: 阅读此分步 Rancher Outscale 指南，以快速部署带有单 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md index 5bc3da3fba9..57d37fbf1a7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md @@ -6,7 +6,7 @@ title: Vagrant 快速入门 :::caution -本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../../pages-for-subheaders/installation-and-upgrade.md)。 +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 ::: @@ -42,7 +42,7 @@ title: Vagrant 快速入门 ### 后续操作 -使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../../../pages-for-subheaders/deploy-rancher-workloads.md)。 +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 ## 销毁环境 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md new file mode 100644 index 00000000000..80c8505d35e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md @@ -0,0 +1,8 @@ +--- +title: 部署工作负载 +--- + +这些指南指导你完成一个应用的部署，包括如何将应用暴露在集群之外使用。 + +- [部署带有 Ingress 的工作负载](workload-ingress.md) +- [部署带有 NodePort 的工作负载](nodeports.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/quick-start-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/quick-start-guides.md new file mode 100644 index 00000000000..e3e750dc9b4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/getting-started/quick-start-guides/quick-start-guides.md @@ -0,0 +1,17 @@ +--- +title: Rancher 部署快速入门指南 +--- + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +你可以阅读本章节，以快速开始部署和测试 Rancher 2.x。本章节包含 Rancher 的简单设置和一些常见用例的说明。未来，我们会在本章节中添加更多内容。 + +我们提供以下快速入门指南： + +- [部署 Rancher Server](deploy-rancher-manager/deploy-rancher-manager.md)：使用最方便的方式运行 Rancher。 + +- [部署工作负载](deploy-workloads/deploy-workloads.md)：部署一个简单的[工作负载](https://kubernetes.io/docs/concepts/workloads/)并公暴露工作负载，以从集群外部访问工作负载。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md new file mode 100644 index 00000000000..ff6b6200e19 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md @@ -0,0 +1,17 @@ +--- +title: CIS 扫描指南 +--- + + + + + +- [安装 Rancher CIS Benchmark](install-rancher-cis-benchmark.md) +- [卸载 Rancher CIS Benchmark](uninstall-rancher-cis-benchmark.md) +- [运行扫描](run-a-scan.md) +- [定时运行扫描](run-a-scan-periodically-on-a-schedule.md) +- [跳过测试](skip-tests.md) +- [查看报告](view-reports.md) +- [为 Rancher CIS Benchmark 启用告警](enable-alerting-for-rancher-cis-benchmark.md) +- [为定时扫描配置告警](configure-alerts-for-periodic-scan-on-a-schedule.md) +- [为集群扫描创建自定义 Benchmark 版本](create-a-custom-benchmark-version-to-run.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md new file mode 100644 index 00000000000..97218077f07 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md @@ -0,0 +1,125 @@ +--- +title: 启用实验功能 +--- + + + + + +Rancher 包含一些默认关闭的实验功能。在某些情况下，例如当你认为使用[不支持的存储类型](unsupported-storage-drivers.md)的好处大于使用未经测试的功能的风险时，你可能想要启用实验功能。为了让你能够试用这些默认关闭的功能，我们引入了功能开关（feature flag）。 + +实验功能可以通过以下三种方式启用： + +- [使用 CLI](#启动-rancher-时启用功能)：在使用 CLI 安装 Rancher 时，使用功能开关默认启用某个功能。 +- [使用 Rancher UI](#使用-rancher-ui-启用功能)：在**设置**页面启用功能。 +- [使用 Rancher API](#使用-rancher-api-启用功能)：安装 Rancher 后启用功能。 + +每个功能均有以下两个值： + +- 默认值：可以通过在命令行使用标志或环境变量进行配置。 +- 设置值：可以通过 Rancher API 或 UI 进行配置。 + +如果没有设置值，Rancher 会使用默认值。 + +设置值是通过 API 设置的，而默认值是通过命令行设置。因此，如果你使用 API 或 UI 启用或禁用某个功能，命令行中设置的值将被覆盖。 + +如果你安装 Rancher 后使用 Rancher API 将功能开关设置为 true，然后在使用命令升级 Rancher 时将功能开关设置为 false，在这种情况下，虽然默认值会是 false，但是该功能依然会被启用，因为它是通过 API 设置的。如果你随后使用 Rancher API 删除设置值（true）并将它设置为 NULL，则默认值（false）将生效。有关详细信息，请参阅[功能开关页面](../../../getting-started/installation-and-upgrade/installation-references/feature-flags.md)。 + +## 启动 Rancher 时启用功能 + +安装 Rancher 时，使用功能开关启用你所需的功能。通过单节点容器安装 Rancher，和在 Kubernetes 集群上安装 Rancher 对应的命令有所不同。 + +### Kubernetes 安装的情况下启用功能 + +:::note + +通过 Rancher API 设置的值会覆盖命令行传入的值。 + +::: + +使用 Helm Chart 安装 Rancher 时，使用 `--set` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +:::note + +如果你安装的是 alpha 版本，Helm 要求你在命令中添加 `--devel` 选项。 + +::: + +### 离线安装的情况下渲染 Helm Chart + +如果你是在离线环境安装 Rancher 的，在使用 Helm 安装 Rancher 之前，你需要添加一个 Helm Chart 仓库并渲染一个 Helm 模板。详情请参见[离线安装文档](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)。 + +以下是在渲染 Helm 模板时传入功能开关名称的命令示例。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能。 + +Helm 命令如下： + +``` +helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # 设置在 Rancher 中使用的私有镜像仓库 + --set useBundledSystemChart=true # 使用打包的 Rancher System Chart + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +### Docker 安装的情况下启用功能 + +如果 Rancher 是使用 Docker 安装的，请使用 `--features` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +``` +docker run -d -p 80:80 -p 443:443 \ + --restart=unless-stopped \ + rancher/rancher:rancher-latest \ + --features==true,=true +``` + +## 使用 Rancher UI 启用功能 + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 单击**功能开关**。 +1. 如需启用某个功能，找到该已禁用的功能，并点击**⋮ > 激活**。 + +**结果**：该功能已启用。 + +### 使用 Rancher UI 禁用功能 + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 单击**功能开关**。你将看到实验功能列表。 +1. 如需禁用某个功能，找到该已启用的功能，并点击**⋮ > 停用**。 + +**结果**：该功能已禁用。 + +## 使用 Rancher API 启用功能 + +1. 前往 `/v3/features`。 +1. 在 `data` 中，你会看到一个数组，该数组包含所有能通过功能开关启用的功能。功能的名称在 `id` 字段中。单击要启用的功能的名称。 +1. 在左上角的 **Operations** 下，点击 **Edit**。 +1. 在 **Value** 下拉菜单中，单击 **True**。 +1. 单击 **Show Request**。 +1. 单击 **Send Request**。 +1. 点击 **Close**。 + +**结果**：该功能已启用。 + +### 使用 Rancher API 禁用功能 + +1. 前往 `/v3/features`。 +1. 在 `data` 中，你会看到一个数组，该数组包含所有能通过功能开关启用的功能。功能的名称在 `id` 字段中。单击要启用的功能的名称。 +1. 在左上角的 **Operations** 下，点击 **Edit**。 +1. 在 **Value** 下拉菜单中，单击 **False**。 +1. 单击 **Show Request**。 +1. 单击 **Send Request**。 +1. 点击 **Close**。 + +**结果**：该功能已禁用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md new file mode 100644 index 00000000000..e6b3e08e753 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md @@ -0,0 +1,34 @@ +--- +title: 设置指南 +--- + + + + + +本文介绍如何启用 Istio 并在你的项目中使用它。 + +如果你使用 Istio 进行流量管理，则需要允许外部流量进入集群。在这种情况下，你将需要执行以下所有步骤。 + +## 先决条件 + +本指南假设你已经[安装 Rancher](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md)，且已经[配置了一个单独的 Kubernetes 集群](../../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)并要在该集群上安装 Istio。 + +集群中的节点必须满足 [CPU 和内存要求](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md)。 + +Istio 控制的工作负载和服务必须满足 [Istio 要求](https://istio.io/docs/setup/additional-setup/requirements/)。 + +## 安装 + +:::tip 快速设置提示: + +如果你不需要外部流量到达 Istio，而只想设置 Istio 以监控和跟踪集群内的流量，请跳过[设置 Istio Gateway](set-up-istio-gateway.md)和[设置 Istio 的流量管理组件](set-up-traffic-management.md)步骤。 + +::: + +1. [在集群中启用 Istio。](enable-istio-in-cluster.md) +2. [在命名空间中启用 Istio。](enable-istio-in-namespace.md) +3. [使用 Istio Sidecar 添加部署和服务。](use-istio-sidecar.md) +4. [设置 Istio Gateway。](set-up-istio-gateway.md) +5. [设置 Istio 的流量管理组件。](set-up-traffic-management.md) +6. [生成和查看流量。](generate-and-view-traffic.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md new file mode 100644 index 00000000000..a3b2d089c77 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md @@ -0,0 +1,15 @@ +--- +title: Monitoring/Alerting 指南 +--- + + + + + +- [启用 Monitoring](enable-monitoring.md) +- [卸载 Monitoring](uninstall-monitoring.md) +- [为工作负载设置 Monitoring](set-up-monitoring-for-workloads.md) +- [自定义 Grafana 仪表板](customize-grafana-dashboard.md) +- [持久化 Grafana 仪表板](create-persistent-grafana-dashboard.md) +- [调试高内存用量](debug-high-memory-usage.md) +- [迁移 Monitoring V1 到 V2](migrate-to-rancher-v2.5+-monitoring.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md new file mode 100644 index 00000000000..7bc98a902e4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md @@ -0,0 +1,12 @@ +--- +title: Prometheus Federator 指南 +--- + + + + + +- [启用 Prometheus Federator](enable-prometheus-federator.md) +- [卸载 Prometheus Federator](uninstall-prometheus-federator.md) +- [自定义 Grafana 仪表板](customize-grafana-dashboards.md) +- [为工作负载设置 Prometheus Federator](set-up-workloads.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md new file mode 100644 index 00000000000..f08162e1615 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md @@ -0,0 +1,19 @@ +--- +title: 高级配置 +--- + + + + + +### Alertmanager + +有关配置 Alertmanager 自定义资源的信息，请参阅[此页面。](alertmanager.md) + +### Prometheus + +有关配置 Prometheus 自定义资源的信息，请参阅[此页面。](prometheus.md) + +### PrometheusRules + +有关配置 PrometheusRules 自定义资源的信息，请参阅[此页面。](prometheusrules.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md index fc12de7e488..458011a703c 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md @@ -1,5 +1,5 @@ --- -title: 配置 PrometheusRule +title: PrometheusRule 配置 --- PrometheusRule 定义了一组 Prometheus 告警和/或记录规则。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md new file mode 100644 index 00000000000..3b53fe7214f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md @@ -0,0 +1,55 @@ +--- +title: 配置 +--- + + + + + +本文介绍在 Rancher UI 中配置 Monitoring V2 的一些最重要选项。 + +有关为 Prometheus 配置自定义抓取目标和规则的信息，请参阅 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 的上游文档。Prometheus Operator [设计文档](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/design.md)中解释了一些最重要的自定义资源。Prometheus Operator 文档还可以帮助你设置 RBAC、Thanos 或进行自定义配置。 + +## 设置资源限制和请求 + +安装 `rancher-monitoring` 时可以配置 Monitoring 应用的资源请求和限制。有关默认限制的更多信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#配置资源限制和请求)。 + +:::tip + +在空闲集群上，Monitoring 可能会占用很多 CPU 资源。要提高性能，请关闭 Prometheus Adapter。 + +::: + +## Prometheus 配置 + +通常不需要直接编辑 Prometheus 自定义资源。 + +相反，要让 Prometheus 抓取自定义指标，你只需创建一个新的 ServiceMonitor 或 PodMonitor 来将 Prometheus 配置为抓取其他指标。 + +### ServiceMonitor 和 PodMonitor 配置 + +有关详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md)。 + +### 高级 Prometheus 配置 + +有关直接编辑 Prometheus 自定义资源（对高级用例可能有帮助）的更多信息，请参阅[此页面](advanced-configuration/prometheus.md)。 + +## Alertmanager 配置 + +Alertmanager 自定义资源通常不需要直接编辑。在常见用例中，你可以通过更新路由和接收器来管理告警。 + +路由和接收器是 Alertmanager 自定义资源配置的一部分。在 Rancher UI 中，路由（Route）和接收器（Receiver）并不是真正的自定义资源，而是 Prometheus Operator 用来将你的配置与 Alertmanager 自定义资源同步的伪自定义资源。当路由和接收器更新时，Monitoring 应用将自动更新 Alertmanager 来反映这些更改。 + +对于一些高级用例，你可能需要直接配置 Alertmanager。有关详细信息，请参阅[此页面](advanced-configuration/alertmanager.md)。 + +### 接收器 + +接收器（Receiver）用于设置通知。有关如何配置接收器的详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/receivers.md)。 + +### 路由 + +路由（Route）在通知到达接收器之前过滤它们。每条路由都需要引用一个已经配置好的接收器。有关如何配置路由的详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/routes.md)。 + +### 高级配置 + +有关直接编辑 Alertmanager 自定义资源（对高级用例可能有帮助）的更多信息，请参阅[此页面](advanced-configuration/alertmanager.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md new file mode 100644 index 00000000000..391a6577ecd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md @@ -0,0 +1,51 @@ +--- +title: 配置驱动 +--- + + + + + +使用 Rancher 中的驱动，你可以管理可以使用哪些供应商来部署[托管的 Kubernetes 集群](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)或[云服务器节点](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)，以允许 Rancher 部署和管理 Kubernetes。 + +### Rancher 驱动 + +你可以启用或禁用 Rancher 中内置的驱动。如果相关驱动 Rancher 尚未实现，你可以添加自己的驱动。 + +Rancher 中有两种类型的驱动： + +* [集群驱动](#集群驱动) +* [主机驱动](#主机驱动) + +### 集群驱动 + +集群驱动用于配置[托管的 Kubernetes 集群](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)，例如 GKE、EKS、AKS 等。创建集群时可以显示的集群驱动，是由集群驱动的状态定义的。只有 `active` 集群驱动将显示为为托管 Kubernetes 集群创建集群的选项。默认情况下，Rancher 与几个现有的集群驱动打包在一起，但你也可以创建自定义集群驱动并添加到 Rancher。 + +默认情况下，Rancher 已激活多个托管 Kubernetes 云提供商，包括： + +* [Amazon EKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md) +* [Google GKE](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md) +* [Azure AKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md) + +还有几个托管的 Kubernetes 云提供商是默认禁用的，但也打包在 Rancher 中： + +* [Alibaba ACK](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.md) +* [Huawei CCE](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.md) +* [Tencent](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.md) + +### 主机驱动 + +主机驱动用于配置主机，Rancher 使用这些主机启动和管理 Kubernetes 集群。主机驱动与 [Docker Machine 驱动](https://docs.docker.com/machine/drivers/)相同。创建主机模板时可以显示的主机驱动，是由主机驱动的状态定义的。只有 `active` 主机驱动将显示为创建节点模板的选项。默认情况下，Rancher 与许多现有的 Docker Machine 驱动打包在一起，但你也可以创建自定义主机驱动并添加到 Rancher。 + +如果你不想向用户显示特定的主机驱动，则需要停用这些主机驱动。 + +Rancher 支持几家主要的云提供商，但默认情况下，这些主机驱动处于 active 状态并可供部署： + +* [Amazon EC2](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) +* [Azure](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md) +* [Digital Ocean](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md) +* [vSphere](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md) + +还有其他几个默认禁用的主机驱动，但打包在 Rancher 中： + +* [Harvester](../../../../integrations-in-rancher/harvester.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md new file mode 100644 index 00000000000..921ab1cc00a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md @@ -0,0 +1,130 @@ +--- +title: RKE 模板 +--- + + + + + +RKE 模板旨在让 DevOps 和安全团队标准化和简化 Kubernetes 集群创建的流程。 + +RKE 的全称是 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/)，它是 Rancher 用来配置 Kubernetes 集群的工具。 + +随着 Kubernetes 越来越受欢迎，管理更多小型集群逐渐成为趋势。如果你想要创建大量集群，对集群进行一致管理尤为重要。多集群管理面临着安全和附件配置执行的挑战，在将集群移交给最终用户之前，这些配置需要标准化。 + +RKE 模板有助于标准化这些配置。无论是使用 Rancher UI、Rancher API 还是自动化流程创建的集群，Rancher 都将保证从 RKE 集群模板创建的每个集群在生成方式上是一致的。 + +管理员可以控制最终用户能更改的集群选项。RKE 模板还可以与特定的用户和组共享，以便管理员可以为不同的用户集创建不同的 RKE 模板。 + +如果集群是使用 RKE 模板创建的，则不能让集群使用另一个 RKE 模板。你只能将集群更新为同一模板的新版本。 + +你可以[将现有集群的配置保存为 RKE 模板](apply-templates.md#将现有集群转换为使用-rke-模板)。这样，只有模板更新后才能更改集群的设置。新模板还可用于启动新集群。 + +RKE 模板的核心功能允许 DevOps 和安全团队： + +- 标准化集群配置并确保按照最佳实践创建 Rancher 配置的集群 +- 配置集群时，防止用户做出不明智的选择 +- 与不同的用户和组共享不同的模板 +- 将模板的所有权委托给受信任的用户进行更改 +- 控制哪些用户可以创建模板 +- 要求用户使用模板来创建集群 + +## 可配置的设置 + +RKE 模板可以在 Rancher UI 中创建或以 YAML 格式定义。当你使用 Rancher 从基础设施提供商配置自定义节点或一般节点时，它们可以指定为相同的参数： + +- 云提供商选项 +- Pod 安全选项 +- 网络提供商 +- Ingress Controller +- 网络安全配置 +- 网络插件 +- 私有镜像仓库 URL 和凭证 +- 附加组件 +- Kubernetes 选项，包括 kube-api、kube-controller、kubelet 和服务等 Kubernetes 组件的配置 + +RKE 模板的[附加组件](#附加组件)的功能特别强大，因为它允许多种自定义选项。 + +## RKE 模板的范围 + +Rancher 配置的集群支持 RKE 模板。模板可用于配置自定义集群或由基础设施提供商启动的集群。 + +RKE 模板用于定义 Kubernetes 和 Rancher 设置。节点模板负责配置节点。有关如何将 RKE 模板与硬件结合使用的参考，请参阅 [RKE 模板和硬件](infrastructure.md). + +可以从头开始创建 RKE 模板来预先定义集群配置。它们可以用于启动新集群，也可以从现有的 RKE 集群导出模板。 + +现有集群的设置可以[保存为 RKE 模板](apply-templates.md#converting-an-existing-cluster-to-use-an-rke-template)。这会创建一个新模板并将集群设置绑定到该模板。这样，集群只有在[模板更新](manage-rke1-templates.md#更新模板)的情况下才能[使用新版本的模板](manage-rke1-templates.md#升级集群以使用新的模板修订版)进行升级。新模板也可以用来创建新集群。 + + +## 示例场景 +如果一个组织同时拥有普通和高级 Rancher 用户，管理员可能希望为高级用户提供更多用于集群创建的选项，并限制普通用户的选项。 + +这些[示例场景](example-use-cases.md)描述组织如何使用模板来标准化集群创建。 + +示例场景包括： + +- **强制执行模板**：如果希望所有 Rancher 配置的新集群都具有某些设置，管理员可能想要[为每个用户强制执行一项或多项模板设置](example-use-cases.md#强制执行模板设置)。 +- **与不同的用户共享不同的模板**：管理员可以为[普通用户和高级用户提供不同的模板](example-use-cases.md#普通用户和高级用户模板)。这样，普通用户会有更多限制选项，而高级用户在创建集群时可以使用更多选项。 +- **更新模板设置**：如果组织的安全和 DevOps 团队决定将最佳实践嵌入到新集群所需的设置中，这些最佳实践可能会随着时间而改变。如果最佳实践发生变化，[可以将模板更新为新版本](example-use-cases.md#更新模板和集群)，这样，使用模板创建的集群可以[升级到模板的新版本](manage-rke1-templates.md#升级集群以使用新的模板修订版)。 +- **共享模板的所有权**：当模板所有者不再想要维护模板或想要共享模板的所有权时，此方案描述了如何[共享模板所有权](example-use-cases.md#允许其他用户控制和共享模板)。 + +## 模板管理 + +创建 RKE 模板时，可以在 Rancher UI 中的**集群管理**下的 **RKE 模板**中使用模板。创建模板后，你将成为模板所有者，这将授予你修改和共享模板的权限。你可以与特定用户或组共享 RKE 模板，也可以公开模板。 + +管理员可以开启模板强制执行，要求用户在创建集群时始终使用 RKE 模板。这使管理员可以保证 Rancher 总是创建指定配置的集群。 + +RKE 模板更新通过修订系统处理。如果要更改或更新模板，请创建模板的新版本。然后，可以将使用旧版本模板创建的集群升级到新模板修订版。 + +在 RKE 模板中，模板所有者可以限制设置的内容，也可以打开设置以供最终用户选择值。它们的差别体现在，创建模板时，Rancher UI 中的每个设置上的**允许用户覆盖**标示。 + +对于无法覆盖的设置，最终用户将无法直接编辑它们。为了让用户使用这些设置的不同选项，RKE 模板所有者需要创建 RKE 模板的新版本，这将允许用户升级和更改该选项。 + +本节中的文件解释了 RKE 模板管理的细节： + +- [获取创建模板的权限](creator-permissions.md) +- [创建和修改模板](manage-rke1-templates.md) +- [强制执行模板设置](enforce-templates.md#强制新集群使用-rke-模板) +- [覆盖模板设置](override-template-settings.md) +- [与集群创建者共享模板](access-or-share-templates.md#与特定用户或组共享模板) +- [共享模板的所有权](access-or-share-templates.md#共享模板所有权) + +你可以参见此[模板的示例 YAML 文件](../../../../reference-guides/rke1-template-example-yaml.md)作为参考。 + +## 应用模板 + +你可以使用你自己创建的模板来[创建集群](apply-templates.md#使用-rke-模板创建集群)，也可以使用[与你共享的模板](access-or-share-templates.md)来创建集群。 + +如果 RKE 模板所有者创建了模板的新版本，你可以[将你的集群升级到该版本](apply-templates.md#更新使用-rke-模板创建的集群)。 + +可以从头开始创建 RKE 模板来预先定义集群配置。它们可以用于启动新集群，也可以从现有的 RKE 集群导出模板。 + +你可以[将现有集群的配置保存为 RKE 模板](apply-templates.md#将现有集群转换为使用-rke-模板)。这样，只有模板更新后才能更改集群的设置。 + +## 标准化硬件 + +RKE 模板的目的是标准化 Kubernetes 和 Rancher 设置。如果你还想标准化你的基础设施，一个选择是将 RKE 模板与[其他工具](infrastructure.md)一起使用。 + +另一种选择是使用包含节点池配置选项，但不强制执行配置的[集群模板](../../manage-clusters/manage-cluster-templates.md)。 + +## YAML 定制 + +如果将 RKE 模板定义为 YAML 文件，则可以修改此[示例 RKE 模板 YAML](../../../../reference-guides/rke1-template-example-yaml.md)。RKE 模板中的 YAML 使用了 Rancher 在创建 RKE 集群时使用的相同自定义设置。但由于 YAML 要在 Rancher 配置的集群中使用，因此需要将 RKE 模板自定义项嵌套在 YAML 中的 `rancher_kubernetes_engine_config` 参数下。 + +RKE 文档也提供[注释的](https://rancher.com/docs/rke/latest/en/example-yamls/) `cluster.yml` 文件供你参考。 + +有关可用选项的更多信息，请参阅[集群配置](https://rancher.com/docs/rke/latest/en/config-options/)上的 RKE 文档。 + +### 附加组件 + +RKE 模板配置文件的附加组件部分的工作方式与[集群配置文件的附加组件部分](https://rancher.com/docs/rke/latest/en/config-options/add-ons/)相同。 + +用户定义的附加组件指令允许你调用和下拉 Kubernetes 清单或将它们直接内联。如果这些 YAML 清单包括在 RKE 模板中，Rancher 将在集群中部署这些 YAML 文件。 + +你可以使用附加组件执行以下操作： + +- 启动 Kubernetes 集群后，在集群上安装应用 +- 在使用 Kubernetes Daemonset 部署的节点上安装插件 +- 自动设置命名空间、ServiceAccount 或角色绑定 + +RKE 模板配置必须嵌套在 `rancher_kubernetes_engine_config` 参数中。要设置附加组件，在创建模板时单击**以 YAML 文件编辑**。然后使用 `addons` 指令添加清单，或使用 `addons_include` 指令设置哪些 YAML 文件可用于附加组件。有关自定义附加组件的更多信息，请参见[用户自定义附加组件文档](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md new file mode 100644 index 00000000000..ff9bbd0e942 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md @@ -0,0 +1,145 @@ +--- +title: 配置认证 +weight: 10 +--- + + + + + +Rancher 为 Kubernetes 添加的一个关键功能是集中式用户认证，这个特性允许用户使用一组凭证对任何 Kubernetes 集群进行身份认证。 + +这种集中式用户认证是通过 Rancher 的认证代理完成的，该代理与 Rancher 的其余部分一并安装，此代理对用户进行认证并通过一个 Service Acount 将请求转发到 Kubernetes 集群中。 + +:::warning + +用来启用外部认证的账户将被授予管理员权限。如果你使用一个测试账号或非管理员账号，该账号仍然会被授予管理员级别权限。请查看[外部认证配置和主体用户](#外部认证配置和用户主体)了解原因。 + +::: + +## 外部认证与本地认证 + +Rancher 认证代理可以与以下外部认证服务集成。 + +| 认证服务 | +| ---------------------------------------------------------------------------------------------------------------------- | +| [Microsoft Active Directory](configure-active-directory.md) | +| [GitHub](configure-github.md) | +| [Microsoft Azure AD](configure-azure-ad.md) | +| [FreeIPA](configure-freeipa.md) | +| [OpenLDAP](../configure-openldap/configure-openldap.md) | +| [Microsoft AD FS](../configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md) | +| [PingIdentity](configure-pingidentity.md) | +| [Keycloak (OIDC)](configure-keycloak-oidc.md) | +| [Keycloak (SAML)](configure-keycloak-saml.md) | +| [Okta](configure-okta-saml.md) | +| [Google OAuth](configure-google-oauth.md) | +| [Shibboleth](../configure-shibboleth-saml/configure-shibboleth-saml.md) | + +当然，Rancher 也提供[本地认证](create-local-users.md). + +在多数情况下，你应该使用外部认证服务而不是使用本地认证，因为外部认证服务可以集中式的对用户进行管理。但是在极少数情况下，例如外部认证服务不可用或正在维护时，你可能需要使用本地认证用户来管理 Rancher。 + +## 用户和组 + +Rancher 依赖用户和组来决定允许谁登录 Rancher 以及他们可以访问哪些资源。当使用外部认证时，外部认证系统会根据用户提供组的信息。这些用户和组被赋予了集群、项目、多集群应用以及全局 DNS 提供商和条目等资源的特定角色。当你对组进行授权时，在认证服务中所有属于这个组中的用户都有访问指定的资源的权限。有关角色和权限的更多信息，请查看 [RBAC](../manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +:::note + +本地认证不支持创建或管理组 + +::: + +更多信息，请查看[用户和组](manage-users-and-groups.md) + +## Rancher 授权范围 + +当你配置完 Rancher 使用外部认证服务后，你可以配置允许谁登录和使用 Rancher，包含如下的选项： + +| 访问级别 | 描述 | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| 允许任何有效用户 | 在认证服务中的*任何*用户都可以访问 Rancher。通常情况下不建议使用该设置！ | +| 允许集群和项目成员，以及授权的用户和组织 | 认证服务中属于**集群成员**或**项目成员**的用户或组成员都可以登录 Rancher。此外添加在**授权的用户和组织**列表中的用户和组成员也可以登录到 Rancher。 | +| 仅限于授权的用户可以访问 | 仅有在授权用户和组织列表中的用户和组成员可以登录到 Rancher。 | + +要在授权服务中为用户设置 Rancher 访问级别，请执行以下步骤： + +1. 在左上角，点击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，点击 **认证**. +1. 设置完外部认证详细信息后，使用 **站点访问** 选项配置用户权限范围，上面的表格说明了每个选项的访问级别。 +1. 可选：如果你选择 **允许任何有效用户** 以外的选项，你可以通过在出现的文本框中搜索用户，将用户添加到授权用户和组织的列表中。 +1. 点击 **保存**。 + +**结果:** Rancher 的访问配置被应用。 + +:::note SAML 认证警告: + +- SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。 +- 添加用户时，必须正确输入确切的用户 ID（即 UID 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- 用户组下拉列表仅显示你所属的用户组。你将无法添加你不是其成员的组。 + +::: + +## 外部认证配置和用户主体 + +配置外部认证需要： + +- 分配了管理员角色的本地用户，以下称为 _本地主体_。 +- 可以使用外部认证服务进行认证的外部用户，以下简称为 _外部主体_。 + +外部认证的配置也会影响 Rancher 中主体用户的管理方式，具体地说，当用户账户启用了外部认证时，将授予其管理员级别的权限。这是因为本地主体和外部主体共享相同的用户 ID 和访问权限。 + +以下说明演示了这些效果： + +1. 作为本地主体登录到 Rancher 并完成外部身份验证的配置。 + + ![Sign In](/img/sign-in.png) + +2. Rancher 将外部主体与本地主体相关联。这两个用户共享本地主体的用户 ID。 + + ![Principal ID Sharing](/img/principal-ID.png) + +3. 完成配置后，Rancher 将自动退出本地主体。 + + ![Sign Out Local Principal](/img/sign-out-local.png) + +4. 然后，Rancher 会自动将你登录外部主体。 + + ![Sign In External Principal](/img/sign-in-external.png) + +5. 因为外部主体和本地主体共享一个 ID，所以用户列中不会再单独显示一个另外的外部主体的对象。 + + ![Sign In External Principal](/img/users-page.png) + +6. 外部主体和本地主体共享相同的访问权限。 + +:::note 重新配置先前设置的认证 + +如果需要重新配置或禁用后重新启用先前设置过的认证，请确保尝试这样做的用户以外部用户身份登录到 Rancher，而不是使用本地管理员登录。 + +::: + +## 禁用认证 + +当你禁用认证时，Rancher 会删除所有与之关联的资源，例如： + +- 密文 +- 绑定的全局角色。 +- 绑定的集群角色。 +- 绑定的项目角色。 +- 与外部认证关联但从未以本地用户身份登录 Rancher 的外部用户。 + +由于此操作可能会导致许多资源丢失，因此你可能需要添加一些保护措施。若要确保禁用外部认证时不执行清理流程，需要为外部认证的配置添加特殊的注释。 + +例如，若要对 Azure AD 认证增加保护措施，你需要在 authconfig 对象上增加 `azuread` 注释： + +`kubectl annotate --overwrite authconfig azuread management.cattle.io/auth-provider-cleanup='user-locked'` + +禁用 Azure AD 认证后，Rancher 不会执行清理流程，直到你将该注解设置为 `unlocked`。 + +### 手动运行资源清理 + +Rancher 可能会在本地集群中保留之前禁用的外部认证配置的资源，即使你配置对接了另一种认证也是如此。例如，如果你对接了 A 认证，然后禁用它，并重新对接使用 B 认证，当你升级到新版本的 Rancher 时，你可以手动触发对认证 A 配置的资源清理。 + +要手动触发已禁用的认证配置的清理，请将 `unlocked` 值添加到对应认证配置的 `management.cattle.io/auth-provider-cleanup` 注解中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md new file mode 100644 index 00000000000..db6c9b60ca0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md @@ -0,0 +1,57 @@ +--- +title: 认证、权限和全局配置 +--- + + + + + +安装完成后，[系统管理员](manage-role-based-access-control-rbac/global-permissions.md)需要配置 Rancher 来配置认证、授权、安全性、默认设置、安全策略、驱动和全局 DNS 条目。 + +## 首次登录 + +首次登录 Rancher 后，Rancher 会提示你输入 **Rancher Server URL**。你需要将 URL 设置为 Rancher Server 的主要入口点。当负载均衡器位于 Rancher Server 集群前面时，URL 需要设置为负载均衡器地址。系统会自动尝试从运行 Rancher Server 的主机的 IP 地址或主机名推断 Rancher Server 的 URL，上述推断仅在你运行单节点 Rancher Server 时才正确。因此，在大多数情况下，你需要自己将 Rancher Server 的 URL 设置为正确的值。 + +:::danger + +Rancher Server 的 URL 在设置后不可再更新。因此，你需要谨慎设置该 URL。 + +::: + +## 认证 + +Rancher 为 Kubernetes 增加了一项关键特性是集中式的用户认证。此特性允许设置本地用户和/或连接到外部认证程序。通过连接到外部认证程序，你可以使用该程序提供的用户和组。 + +更多关于认证的工作原理以及如何配置对接各个认证程序，请参考[认证](authentication-config/authentication-config.md)。 + +## 授权 + +在 Rancher 中，每个人都是以 _用户_ 的身份进行鉴权，这是一个授予你访问 Rancher 的登录身份。用户登录 Rancher 后，他们的 _授权_ 或者他们在系统中的访问权限由用户的角色决定。Rancher 提供了内置的角色，允许你你轻松地配置用户对资源的权限，但是 Rancher 还提供了为每个 Kubernetes 资源自定义角色的功能。 + +更多关于授权的工作原理以及自定义角色的使用，请参考 [RBAC](manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +## Pod 安全策略 + +_Pod 安全策略_ (或 PSPs) 是控制 Pod 安全敏感方面规范的对象，例如 root 权限。如果一个 Pod 不满足 PSP 中指定的条件，Kubernetes 将不允许 Pod 启动，同时 Rancher 会显示一条错误信息。 + +更多关于如何创建和使用 PSPs 的内容，请参考 [Pod 安全策略](create-pod-security-policies.md)。 + +## Provisioning Drivers + +Rancher 中的驱动允许你管理哪些程序可以预置[托管的 Kubernetes 集群](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)或[云服务器节点](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)，允许 Rancher 部署和管理 Kubernetes。 + +更多信息请参考 [Provisioning Drivers](about-provisioning-drivers/about-provisioning-drivers.md)。 + +## 添加 Kubernetes 版本到 Rancher 中 + +使用此功能，你可以在最新版本的 Kubernetes 发布后立即升级，而不需要升级 Rancher。此功能允许你轻松升级 Kubernetes 的补丁版本（例如 `v1.15.X`），但不打算升级 Kubernetes 的次要版本（例如 `v1.X.0`），因为 Kubernetes 倾向于在次要版本之间弃用或添加 API。 + +Rancher 用于配置 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的信息现在存储于 Rancher Kubernetes 元数据中，更多关于元数据的配置以及如何更改用于配置 RKE 集群的 Kubernetes 版本的信息，请参考 [Rancher Kubernetes 元数据](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md)。 + +Rancher Kubernetes 元数据包含 Kubernetes 版本信息，Rancher 使用这些信息来配置 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 + +关于元数据的工作原理以及如何配置元数据，请参考 [Rancher Kubernetes 元数据](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md)。 + +## 启用实验性功能 + +Rancher 包含一些默认处于实验性和/或禁用的功能，功能开关允许你启用这些特性。更多信息请参考[功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md new file mode 100644 index 00000000000..3b96b5f62ff --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md @@ -0,0 +1,39 @@ +--- +title: 配置 Microsoft AD FS (SAML) +--- + + + + + +如果你的组织使用 Active Directory Federation Service (AD FS) 进行用户身份认证，你可以通过配置 Rancher 来允许用户使用 AD FS 凭证登录。 + +## 先决条件 + +已安装 Rancher。 + +- 获取你的 Rancher Server URL。配置 AD FS 时，请使用该 URL 替换 `` 占位符。 +- 你必须在 Rancher 安装时具有全局管理员账号。 + +你必须配置 [Microsoft AD FS 服务器](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services)。 + +- 获取你的 AD FS 服务器 IP/DNS 名称。配置 AD FS 时，请使用该 IP/DNS 名称替换 `` 占位符。 +- 你必须有在 AD FS 服务器上添加 [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) 的权限。 + +## 配置概要 + +要让 Rancher Server 使用 Microsoft AD FS，你需要在 Active Directory 服务器上配置 AD FS，并将 Rancher 配置为使用 AD FS 服务器。如果需要获取在 Rancher 中设置 Microsoft AD FS 身份认证的指南，请参见： + +- [1. 在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) +- [2. 在 Rancher 中配置 Microsoft AD FS](configure-rancher-for-ms-adfs.md) + +:::note SAML 身份提供商注意事项 + +- SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。 +- 添加用户时，必须正确输入确切的用户 ID（即 `UID` 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- 用户组下拉列表仅显示你所属的用户组。如果你不是某个组的成员，你将无法添加该组。 + +::: + +### [后续操作：在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md index 858be390e9c..da098496bfc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md @@ -2,6 +2,10 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher --- + + + + 在配置 Rancher 以支持 Active Directory Federation Service (AD FS) 之前，你必须在 AD FS 中将 Rancher 添加为 [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts)（信赖方信任）。 1. 以管理用户身份登录 AD 服务器。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md index b4a15d2bf4c..fa8c6910af3 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -2,6 +2,10 @@ title: 2. 在 Rancher 中配置 Microsoft AD FS --- + + + + 完成[在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) 后，将你的 Active Directory Federation Service (AD FS) 信息输入 Rancher，以便 AD FS 用户可以通过 Rancher 进行身份认证。 :::note 配置 ADFS 服务器的重要说明： diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md new file mode 100644 index 00000000000..7594371a296 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md @@ -0,0 +1,56 @@ +--- +title: 配置 OpenLDAP +--- + + + + + +如果你的组织使用 LDAP 进行认证，则可以配置 Rancher 与 OpenLDAP 服务器通信以对用户进行认证。这时 Rancher 管理员可以对外部用户系统中的用户和组进行集群和项目的访问控制，同时允许终端用户在登录 Rancher UI 时使用其 LDAP 凭据进行身份认证。 + +## 先决条件 + +必须为 Rancher 配置 LDAP 绑定账号（即 ServiceAccount），来搜索和检索应该具有访问权限的用户和组的 LDAP 条目。建议不要使用管理员账号或个人账号，而应在 OpenLDAP 中创建一个专用账号，该账号对配置的搜索库下的用户和组需要具有只读权限（参见下文）。 + +> **使用 TLS?** +> +> 如果 OpenLDAP 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +## 在 Rancher 中配置 OpenLDAP + +配置 OpenLDAP 服务器，组和用户的设置。有关填写每个字段的帮助，请参见[配置参考](openldap-config-reference.md) + +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **OpenLDAP**。填写**配置 OpenLDAP 服务器**表单。 +1. 点击**启用**。 + +### 测试认证 + +完成配置后，请测试与 OpenLDAP 服务器的连接。如果测试成功，则表明 OpenLDAP 认证已启用。 + +:::note + +于此步骤中输入的 OpenLDAP 用户凭证将映射到本地主体账号，并在 Rancher 中分配系统管理员权限。因此，你应该决定使用哪个 OpenLDAP 账号来执行此步骤。 + +::: + +1. 输入应映射到本地主体账号的 OpenLDAP 账号的**用户名**和**密码** 。 +2. 点击**启用 OpenLDAP 认证**来测试 OpenLDAP 的连接并完成设置。 + +**结果**： + +- OpenLDAP 认证配置成功。 +- 与输入凭证对应的 LDAP 用户被映射到本地主体（管理员）账号。 + +:::note + +如果 LDAP 服务中断，你仍然可以使用本地配置的 `admin` 账号和密码登录。 + +::: + +## 附录：故障排除 + +如果在测试与 OpenLDAP 服务器的连接时遇到问题，请首先仔细检查为 ServiceAccount 输入的凭证以及搜索库配置。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#how-can-i-enable-debug-logging)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md index 581a85efc2c..eb298c51f49 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -4,7 +4,7 @@ title: OpenLDAP 配置参考 有关配置 OpenLDAP 认证的更多详细信息，请参见[官方文档](https://www.openldap.org/doc/)。 -> 在开始之前，请熟悉[外部身份验证配置和主体用户](../../../../pages-for-subheaders/authentication-config.md#外部身份验证配置和用户主体)的概念。 +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 ## 背景：OpenLDAP 认证流程 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md index 69155120d28..4321f1e6765 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md @@ -2,14 +2,18 @@ title: Shibboleth 和 OpenLDAP 的组权限 --- + + + + 由于 Shibboleth 是 SAML 提供者，因此它不支持搜索用户组的功能。虽然 Shibboleth 集成可以验证用户凭证，但是如果没有其他配置，Shibboleth 不能在 Rancher 中给用户组分配权限。 -你可以通过配置 OpenLDAP 标识提供者来解决这个问题。如果让 Shibboleth 使用 OpenLDAP 后端，你将能够在 Rancher 中搜索组，并从 Rancher UI 将集群、项目或命名空间等资源分配给用户组。 +你可以通过配置 OpenLDAP 来解决这个问题。如果让 Shibboleth 使用 OpenLDAP 后端，你将能够在 Rancher 中搜索组，并从 Rancher UI 将集群、项目或命名空间等资源分配给用户组。 ### 名词解释 - **Shibboleth**：用于计算机网络和互联网的单点登录系统。它允许用户仅使用一种身份登录到各种系统。它验证用户凭证，但不单独处理组成员身份。 -- **SAML**：安全声明标记语言（Security Assertion Markup Language），用于在身份提供程序和服务提供商之间交换身份验证和授权数据的开放标准。 +- **SAML**：安全声明标记语言（Security Assertion Markup Language），用于在身份提供程序和服务提供商之间交换认证和授权数据的开放标准。 - **OpenLDAP**：轻型目录访问协议（LDAP）的免费开源实现。它用于管理组织的计算机和用户。OpenLDAP 对 Rancher 用户很有用，因为它支持组。只要组已存在于身份提供程序中，你就可以在 Rancher 中为组分配权限，从而让组访问资源（例如集群，项目或命名空间）。 - **IdP 或 IDP**：身份提供程序。OpenLDAP 是身份提供程序的一个例子。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md new file mode 100644 index 00000000000..285a5d3e6aa --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md @@ -0,0 +1,104 @@ +--- +title: 配置 Shibboleth (SAML) +--- + + + + + +如果你的组织使用 Shibboleth Identity Provider (IdP) 进行用户身份认证，你可以通过配置 Rancher 来允许用户使用 Shibboleth 凭证登录。 + +在此配置中，当 Rancher 用户登录时，他们将被重定向到 Shibboleth IdP 来输入凭证。认证结束后，他们将被重定向回 Rancher UI。 + +如果你将 OpenLDAP 配置为 Shibboleth 的后端，SAML 断言会返回到 Rancher，其中包括用于引用组的用户属性。然后，通过认证的用户将能够访问其所在的组有权访问的 Rancher 资源。 + +> 本节假定你已了解 Rancher、Shibboleth 和 OpenLDAP 是如何协同工作的。有关工作原理的详细说明，请参见[本页](about-group-permissions.md) + +# 在 Rancher 中设置 Shibboleth + +### Shibboleth 先决条件 + +> - 你必须配置了 Shibboleth IdP 服务器。 +> - 以下是 Rancher Service Provider 配置所需的 URL： +> 元数据 URL：`https:///v1-saml/shibboleth/saml/metadata` +> 断言使用者服务 (ACS) URL：`https:///v1-saml/shibboleth/saml/acs` +> - 从 IdP 服务器导出 `metadata.xml` 文件。详情请参见 [Shibboleth 文档](https://wiki.shibboleth.net/confluence/display/SP3/Home)。 + +### 在 Rancher 中配置 Shibboleth + +如果你的组织使用 Shibboleth 进行用户身份认证，你可以通过配置 Rancher 来允许你的用户使用 IdP 凭证登录。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Shibboleth**。 +1. 填写**配置 Shibboleth 账号**表单。Shibboleth IdP 允许你指定要使用的数据存储。你可以添加数据库或使用现有的 ldap 服务器。例如，如果你选择 Active Directory (AD) 服务器，下面的示例将描述如何将 AD 属性映射到 Rancher 中的字段： + + 1. **显示名称字段**：包含用户显示名称的 AD 属性（例如：`displayName`）。 + + 1. **用户名字段**：包含用户名/给定名称的 AD 属性（例如：`givenName`）。 + + 1. **UID 字段**：每个用户唯一的 AD 属性（例如：`sAMAccountName`、`distinguishedName`）。 + + 1. **用户组字段**: 创建用于管理组成员关系的条目（例如：`memberOf`）。 + + 1. **Rancher API 主机**：你的 Rancher Server 的 URL。 + + 1. **私钥**和**证书**：密钥/证书对，用于在 Rancher 和你的 IdP 之间创建一个安全外壳（SSH）。 + + 你可以使用 openssl 命令进行创建。例如： + + ``` + openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" + ``` + + 1. **IDP 元数据**：从 IdP 服务器导出的 `metadata.xml` 文件。 + +1. 完成**配置 Shibboleth 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Shibboleth IdP 的用户凭证，来验证你的 Rancher Shibboleth 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 Shibboleth。你的用户现在可以使用 Shibboleth 登录名登录 Rancher。 + +### SAML 提供商注意事项 + +SAML 协议不支持用户或用户组的搜索或查找。因此，如果你没有为 Shibboleth 配置 OpenLDAP，则请留意以下警告。 + +- 在 Rancher 中为用户或组分配权限时，不会对用户或组进行验证。 +- 添加用户时，必须正确输入准确的用户 ID（即 UID 字段）。在你输入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- 用户组下拉列表仅显示你所属的用户组。如果你不是某个组的成员，你将无法添加该组。 + +要在 Rancher 中分配权限时启用搜索组，你需要为 SAML 身份认证服务配置支持组的后端（例如 OpenLDAP）。 + +# 在 Rancher 中设置 OpenLDAP + +如果你将 OpenLDAP 配置为 Shibboleth 的后端，SAML 断言会返回到 Rancher，其中包括用于引用组的用户属性。然后，通过认证的用户将能够访问其所在的组有权访问的 Rancher 资源。 + +### OpenLDAP 先决条件 + +必须为 Rancher 配置 LDAP 绑定账号（即 ServiceAccount），来搜索和检索应该具有访问权限的用户和组的 LDAP 条目。建议不要使用管理员账号或个人账号，而应在 OpenLDAP 中创建一个专用账号，该账号对配置的搜索库下的用户和组需要具有只读权限（参见下文）。 + +> **使用 TLS？** +> +> 如果 OpenLDAP 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +### 在 Rancher 中配置 OpenLDAP + +配置 OpenLDAP 服务器，组和用户的设置。有关填写每个字段的帮助，请参见[配置参考](../configure-openldap/openldap-config-reference.md)。请注意，嵌套组成员资格不适用于 Shibboleth。 + +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 + +1. 使用初始的本地 `admin` 账号登录到 Rancher UI。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **OpenLDAP**。将显示**配置 OpenLDAP 服务器**表单。 + +## 故障排除 + +如果在测试与 OpenLDAP 服务器的连接时遇到问题，请首先仔细检查为 ServiceAccount 输入的凭证以及搜索库配置。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#how-can-i-enable-debug-logging)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md new file mode 100644 index 00000000000..0e8a5e89824 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md @@ -0,0 +1,29 @@ +--- +title: 管理 RBAC +--- + + + + + +Rancher 通过 _用户_ 进行授权管理。如[认证](../authentication-config/authentication-config.md)中所述，用户可以是本地用户，也可以是外部用户。 + +配置外部认证后，**用户**页面上显示的用户会发生变化。 + +- 如果你以本地用户身份登录，则仅显示本地用户。 + +- 如果你以外部用户身份登录，则会同时显示外部用户和本地用户。 + +## 用户和角色 + +一旦用户登录到 Rancher，他们的 _授权_，也就是他们在系统中的访问权限，将由 _全局权限_ 和 _集群和项目角色_ 决定。 + +- [全局权限](global-permissions.md): + + 定义用户在任何特定集群之外的授权。 + +- [集群和项目角色](cluster-and-project-roles.md): + + 定义用户在分配了角色的特定集群或项目中的授权。 + +全局权限以及集群和项目角色都是基于 [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) 实现的。因此，权限和角色的底层实现是由 Kubernetes 完成的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md new file mode 100644 index 00000000000..8ce435e8a2b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md @@ -0,0 +1,12 @@ +--- +title: Kubernetes 集群基础设施 +--- + + + + + +要为具有外部数据库的高可用 K3s Kubernetes 集群设置基础设施，请参见[本页面](ha-k3s-kubernetes-cluster.md)。 + + +要为高可用 RKE Kubernetes 集群设置基础设施，请参见[本页面](ha-rke1-kubernetes-cluster.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md new file mode 100644 index 00000000000..0d92541308a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md @@ -0,0 +1,11 @@ +--- +title: 为 Rancher 服务器设置 Kubernetes 集群 +--- + + + + + +本章节介绍如何安装 Kubernetes 集群，使得 Rancher Server 可以安装在该集群上。 + +Rancher 可以在任何 Kubernetes 集群上运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md new file mode 100644 index 00000000000..c5e91cf7108 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md @@ -0,0 +1,52 @@ +--- +title: 生产就绪集群检查清单 +--- + + + + + +本节将介绍创建生产就绪型 Kubernetes 集群的最佳实践。这个集群可用于运行你的应用和服务 + +有关集群的要求（包括对 OS/Docker、硬件和网络的要求），请参阅[节点要求](../node-requirements-for-rancher-managed-clusters.md)。 + +本文介绍了我们推荐用于所有生产集群的最佳实践的简短列表。 + +如需获取推荐的所有最佳实践的完整列表，请参阅[最佳实践](../../../../reference-guides/best-practices/best-practices.md)。 + +### 节点要求 + +* 确保你的节点满足所有[节点要求](../node-requirements-for-rancher-managed-clusters.md)，包括端口要求。 + +### 备份 etcd + +* 启用 etcd 快照。验证是否正在创建快照，并执行灾难恢复方案，从而验证快照是否有效。etcd 是存储集群状态的位置，丢失 etcd 数据意味着丢失集群。因此，请确保为集群配置 etcd 的定期快照，并确保快照也是存储在外部（节点外）的。 + +### 集群架构 + +* 节点应具有以下角色配置之一： + * `etcd` + * `controlplane` + * `etcd` 和 `controlplane` + * `worker`（不应在具有 `etcd` 或 `controlplane` 角色的节点上使用或添加 `worker` 角色） +* 至少拥有三个角色为 `etcd` 的节点，来确保失去一个节点时仍能存活。增加 etcd 节点数量能提高容错率，而将 etcd 分散到不同可用区甚至能获取更好的容错能力。 +* 为两个或更多节点分配 `controlplane` 角色，能实现主组件的高可用性。 +* 为两个或多个节点分配 `worker` 角色，以便在节点故障时重新安排工作负载。 + +有关每个角色的用途的更多信息，请参阅 [Kubernetes 中的节点角色](roles-for-nodes-in-kubernetes.md)。 + +有关每个 Kubernetes 角色的节点数的详细信息，请参阅[推荐架构](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)。 + +### Logging 和 Monitoring + +* 为 Kubernetes 组件（系统服务）配置告警/通知程序。 +* 为集群分析和事后剖析配置 Logging。 + +### 可靠性 + +* 在集群上执行负载测试，以验证硬件是否可以支持你的工作负载。 + +### 网络 + +* 最小化网络延迟。Rancher 建议尽量减少 etcd 节点之间的延迟。`heartbeat-interval` 的默认设置是 `500`，`election-timeout` 的默认设置是 `5000`。这些 [etcd 调优设置](https://coreos.com/etcd/docs/latest/tuning.html) 允许 etcd 在大多数网络（网络延迟特别高的情况下除外）中运行。 +* 集群节点应位于单个区域内。大多数云厂商在一个区域内提供多个可用区，这可以提高你集群的可用性。任何角色的节点都可以使用多个可用区。如果你使用 [Kubernetes Cloud Provider](../set-up-cloud-providers/set-up-cloud-providers.md) 资源，请查阅文档以了解限制（即区域存储限制）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md new file mode 100644 index 00000000000..dc09f593143 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md @@ -0,0 +1,80 @@ +--- +title: 在 Rancher 中设置 Kubernetes 集群 +description: 配置 Kubernetes 集群 +--- + + + + + +Rancher 允许你通过 Rancher UI 来创建集群，从而简化了集群的创建流程。Rancher 提供了多种启动集群的选项。你可以选择最适合你的用例的选项。 + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../../../reference-guides/kubernetes-concepts.md)。 + +有关 Rancher Server 配置集群的方式，以及使用什么工具来创建集群的详细信息，请参阅[产品架构](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)。 + + + +### 不同类型集群的管理功能 + +下表总结了每一种类型的集群和对应的可编辑的选项和设置： + +import ClusterCapabilitiesTable from '../../../shared-files/_cluster-capabilities-table.md'; + + + +## 在托管的 Kubernetes 提供商中设置集群 + +在这种情况下，Rancher 不会配置 Kubernetes，因为它是由 Google Kubernetes Engine (GKE)、Amazon Elastic Container Service for Kubernetes 或 Azure Kubernetes Service 等提供商安装的。 + +如果你使用 Kubernetes 提供商，例如 Google GKE，Rancher 将与对应的云 API 集成，允许你从 Rancher UI 为托管集群创建和管理 RBAC。 + +详情请参阅[托管 Kubernetes 集群](set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)。 + +## 使用 Rancher 启动 Kubernetes + +在你自己的节点上配置 Kubernetes 时，Rancher 使用 [Rancher Kubernetes Engine (RKE)](https://rancher.com/docs/rke/latest/en/) 作为库。RKE 是 Rancher 自己的轻量级 Kubernetes 安装程序。 + +在 RKE 集群中，Rancher 管理 Kubernetes 的部署。这些集群可以部署在任何裸机服务器、云提供商或虚拟化平台上。 + +这些节点可以通过 Rancher 的 UI 动态配置，该 UI 调用 [Docker Machine](https://docs.docker.com/machine/) 在各种云提供商上启动节点。 + +如果你已经有一个想要添加到 RKE 集群的节点，你可以通过在节点上运行 Rancher Agent 容器将节点添加到集群中。 + +有关详细信息，请参阅 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 + +### 在基础设施提供商中启动 Kubernetes 并配置节点 + +Rancher 可以在 Amazon EC2、DigitalOcean、Azure 或 vSphere 等基础设施提供商中动态配置节点，然后在节点上安装 Kubernetes。 + +使用 Rancher，你可以基于[节点模板](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此模板定义了要在云提供商中启动的节点的参数。 + +使用由基础设施提供商托管的节点的一个好处是，如果一个节点与集群失去连接，Rancher 可以自动替换它，从而维护集群配置。 + +Rancher UI 中状态为 Active 的[主机驱动](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#主机驱动)决定了可用于创建节点模板的云提供商。 + +如需更多信息，请参阅[基础设施提供商托管的节点](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)。 + +### 在现有自定义节点上启动 Kubernetes + +在设置这种类型的集群时，Rancher 会在现有的[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)上安装 Kubernetes，从而创建一个自定义集群。 + +你可以使用任何节点，在 Rancher 中创建一个集群。 + +这些节点包括本地裸机服务器、云托管虚拟机或本地虚拟机。 + +## 注册现有集群 + +集群注册功能取代了导入集群的功能。 + +注册 EKS 集群的优点更多。在大多数情况下，注册的 EKS 集群和在 Rancher 中创建的 EKS 集群在 Rancher UI 中的处理方式相同（除了删除）。 + +删除在 Rancher 中创建的 EKS 集群后，该集群将被销毁。删除在 Rancher 中注册的 EKS 集群时，它与 Rancher Server 会断开连接，但它仍然存在。你仍然可以像在 Rancher 中注册之前一样访问它。 + +详情请参见[本页面](register-existing-clusters.md)。 + +## 以编程方式创建集群 + +通过 Rancher 以编程方式部署 Kubernetes 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 + +你可以使用 Terraform 创建或导入 EKS、GKE、AKS 集群和 RKE 集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md new file mode 100644 index 00000000000..cbe157dda48 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md @@ -0,0 +1,47 @@ +--- +title: 设置 Cloud Provider +--- + + + + + +_cloud provider_ 是 Kubernetes 中的一个模块，它提供了一个用于管理节点、负载均衡器和网络路由的接口。 + +在 Rancher 中设置 cloud provider 时，如果你使用的云提供商支持自动化，Rancher Server 可以在启动 Kubernetes 定义时自动配置新节点、负载均衡器或持久存储设备。 + +如果你配置的节点云提供商集群不满足先决条件，集群将无法正确配置。 + +**Cloud Provider** 选项默认设置为 `None`。 + +可以启用的云提供商包括： + +* Amazon +* Azure +* GCE (Google Compute Engine) +* vSphere + +### 设置 Amazon 云提供商 + +有关启用 Amazon 云提供商的详细信息，请参阅[此页面](amazon.md)。 + +### 设置 Azure 云提供商 + +有关启用 Azure 云提供商的详细信息，请参阅[此页面](azure.md)。 + +### 设置 GCE 云提供商 + +有关启用 Google Compute Engine 云提供商的详细信息，请参阅[此页面](google-compute-engine.md)。 + +### 设置 vSphere 云提供商 + +有关启用 vSphere 云提供商的详细信息，请参阅[树内 vSphere 配置](configure-in-tree-vsphere.md) 和[树外 vSphere 配置](configure-out-of-tree-vsphere.md)。 + +### 设置自定义云提供商 + +任何 Kubernetes Cloud Provider 都可以通过`自定义`云提供商进行配置。 + +对于自定义云提供商选项，你可以参考 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/)，了解如何为你的云提供商编辑 yaml 文件。特定云提供商的详细配置说明如下： + +* [vSphere](https://rke.docs.rancher.com/config-options/cloud-providers/vsphere) +* [OpenStack](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/openstack/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md new file mode 100644 index 00000000000..fe8c161c436 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md @@ -0,0 +1,33 @@ +--- +title: 通过托管 Kubernetes 提供商设置集群 +--- + + + + + +在这种情况下，Rancher 不会配置 Kubernetes，因为它是由 Google Kubernetes Engine (GKE)、Amazon Elastic Container Service for Kubernetes 或 Azure Kubernetes Service 等提供商安装的。 + +如果你使用 Kubernetes 提供商，例如 Google GKE，Rancher 将与对应的云 API 集成，允许你从 Rancher UI 为托管集群创建和管理 RBAC。 + +在这个用例中，Rancher 使用提供商的 API 向托管提供商发送请求。然后，提供商会为你配置和托管集群。集群创建成功后，你可以像管理本地集群或云上集群一样，通过 Rancher UI 对集群进行管理。 + +Rancher 支持以下 Kubernetes 提供商： + +- [Google GKE (Google Kubernetes Engine)](https://cloud.google.com/kubernetes-engine/) +- [Amazon EKS (Amazon Elastic Container Service for Kubernetes)](https://aws.amazon.com/eks/) +- [Microsoft AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/services/kubernetes-service/) +- [Alibaba ACK (Alibaba Cloud Container Service for Kubernetes)](https://www.alibabacloud.com/product/kubernetes) +- [Tencent TKE (Tencent Kubernetes Engine)](https://intl.cloud.tencent.com/product/tke) +- [Huawei CCE (Huawei Cloud Container Engine)](https://www.huaweicloud.com/en-us/product/cce.html) + +## 托管 Kubernetes 提供商的身份验证 + +使用 Rancher 创建由提供商托管的集群时，你需要输入身份验证信息。Rancher 会使用验证信息来访问云厂商的 API。有关如何获取此信息的详情，请参阅： + +- [创建 GKE 集群](gke.md) +- [创建 EKS 集群](eks.md) +- [创建 AKS 集群](aks.md) +- [创建 ACK 集群](alibaba.md) +- [创建 TKE 集群](tencent.md) +- [创建 CCE 集群](huawei.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md new file mode 100644 index 00000000000..d49da5e8434 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md @@ -0,0 +1,290 @@ +--- +title: 在 Windows 集群上启动 Kubernetes +--- + + + + + +使用 Rancher 配置[自定义集群](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)时，Rancher 通过 RKE（Rancher Kubernetes Engine）在现有节点上安装 Kubernetes。 + +在使用 Rancher 配置的 Windows 集群中，集群必须同时包含 Linux 和 Windows 节点。Kubernetes controlplane 只能运行在 Linux 节点上，Windows 节点只能有 Worker 角色。Windows 节点只能用于部署工作负载。 + +Windows 集群的其他要求如下： + +- 只有在创建集群时启用了 Windows 支持的集群才能添加 Windows 节点。无法为现有集群启用 Windows 支持。 +- 需要 Kubernetes 1.15+。 +- 必须使用 Flannel 网络提供商。 +- Windows 节点必须有 50 GB 的磁盘空间。 + +有关完整的要求列表，请参阅[本节](#windows-集群的要求)。 + +有关支持 Windows 的 Kubernetes 功能摘要，请参阅[在 Windows 中使用 Kubernetes 支持的功能和限制](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations)的 Kubernetes 文档，或[在 Kubernetes 中调度 Windows 容器的指南](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/)。 + + +## Rancher 2.6 变更 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。 + +在 Rancher 2.6.5 中，RKE2 已经 GA。 + +### RKE2 Windows + +RKE2 配置功能还包括在 Windows 集群上安装 RKE2。RKE2 的 Windows 功能包括： + +- 由 containerd 提供支持的使用 RKE2 的 Windows 容器 +- 直接从 Rancher UI 配置 Windows RKE2 自定义集群 +- 用于 Windows RKE2 自定义集群的 Calico CNI +- 技术预览包含了 Windows Server 的 SAC 版本（2004 和 20H2） + +要使 Windows 支持 RKE2 自定义集群，请选择 Calico 作为 CNI。 + +:::note + +默认情况下，Rancher 允许 Windows 工作负载 pod 部署在 Windows 和 Linux Worker 节点上。在 RKE2 中创建混合集群时，你必须编辑 Chart 中的 `nodeSelector`，从而将 Pod 放置到兼容的 Windows 节点上。有关如何使用 `nodeSelector` 将 pod 分配给节点的更多信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector)。 + +::: + +**_Rancher v2.6.7 新功能_** + +- Kubernetes v1.24.1 及更高版本支持 Windows RKE2 中的 HostProcess 容器。有关详细信息，请参阅[上游文档](https://kubernetes.io/docs/tasks/configure-pod-container/create-hostprocess-pod/)。 + +## Windows 集群的要求 + +网络、操作系统和 Docker 的一般节点要求与 [Rancher 安装](../../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)的节点要求相同。 + +### 操作系统和 Docker 要求 + +我们对 Windows Server 和 Windows 容器的支持与 LTSC（长期服务渠道）和 SAC（半年渠道）的 Microsoft 官方生命周期相匹配。 + +有关 Windows Server 的支持生命周期的日期，请参阅 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/get-started/windows-server-release-info)。 + +### Kubernetes 版本 + +需要 Kubernetes v1.15+。 + +如果你在 Windows Server 20H2 Standard Core 上使用 Kubernetes v1.21，则必须在节点上安装补丁“2019-08 Servicing Stack Update for Windows Server”。 + +### 节点要求 + +集群中的主机至少需要： + +- 2 核 CPU +- 5 GB 内存 +- 50 GB 磁盘空间 + +Rancher 不会配置不满足要求的节点。 + +### 网络要求 + +在配置新集群之前，请确保你已经在接收入站网络流量的设备上安装了 Rancher。这是集群节点与 Rancher 通信所必需的。如果你尚未安装 Rancher，请在继续阅读本指南之前先参阅[安装文档](../../../../getting-started/installation-and-upgrade/installation-and-upgrade.md)进行安装。 + +Rancher 仅支持使用 Flannel 作为网络提供商的 Windows。 + +有两个网络选项: [**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) 和 [**VXLAN (Overlay)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)。默认选项是 **VXLAN (Overlay)** 模式。 + +对于 **Host Gateway (L2bridge)** 网络，最好为所有节点使用相同的第 2 层网络。否则，你需要为它们配置路由规则。有关详细信息，请参阅[配置云托管 VM 路由的文档](network-requirements-for-host-gateway.md#云托管虚拟机的路由配置)。如果你使用的是 Amazon EC2、Google GCE 或 Azure 虚拟机，你需要[禁用私有 IP 地址检查](network-requirements-for-host-gateway.md#禁用私有-ip-地址检查)。 + +对于 **VXLAN (Overlay)** 网络，你必须安装 [KB4489899](https://support.microsoft.com/en-us/help/4489899) 修补程序。大多数云托管的 VM 已经具有此修补程序。 + +如果你在为 AWS 虚拟私有云配置 DHCP 选项集，请注意，你只能在 `domain-name` 选项字段中指定一个域名。详情请参见 [DHCP 选项文档](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html)。 + +:::note + +一些 Linux 操作系统支持以空格分隔的多个域名。但是，其他 Linux 操作系统和 Windows 将该值视为单个域名，从而导致意外错误。如果你的 DHCP 选项集与具有多个操作系统实例的 VPC 相关联，请仅指定一个域名。 + +::: + +### 带有 ESXi 6.7u2 及更高版本的 vSphere 上的 Rancher + +如果你在带有 ESXi 6.7u2 或更高版本的 VMware vSphere 上使用 Rancher，并使用 Red Hat Enterprise Linux 8.3、CentOS 8.3 或 SUSE Enterprise Linux 15 SP2 或更高版本，你需要禁用 `vmxnet3` 虚拟网络适配器硬件卸载功能。否则，不同集群节点上的 pod 之间的所有网络连接会因为超时错误而失败。从 Windows pod 到在 Linux 节点上运行的关键服务（例如 CoreDNS）的所有连接也将失败。外部连接也可能失败。出现这个问题的原因是 Linux 发行版在 `vmxnet3` 中启用了硬件卸载功能，而且 `vmxnet3` 硬件卸载功能中存在一个会丢弃客户覆盖流量的数据包的 bug。要解决此问题，必须禁用 `vmxnet3` 硬件卸载功能。此设置不会在重启后继续生效，因此需要在每次启动时禁用。推荐的做法是在 `/etc/systemd/system/disable_hw_offloading.service` 中创建一个 systemd 单元文件，这会在启动时禁用 `vmxnet3` 硬件卸载功能。禁用 `vmxnet3` 硬件卸载功能的示例 systemd 单元文件如下所示。注意，`` 必须自定义为主机的 `vmxnet3` 网络接口，如 `ens192`： + +``` +[Unit] +Description=Disable vmxnet3 hardware offloading feature + +[Service] +Type=oneshot +ExecStart=ethtool -K tx-udp_tnl-segmentation off +ExecStart=ethtool -K tx-udp_tnl-csum-segmentation off +StandardOutput=journal + +[Install] +WantedBy=multi-user.target +``` +然后在 systemd 单元文件上设置适当的权限： +``` +chmod 0644 /etc/systemd/system/disable_hw_offloading.service +``` +最后，启用 systemd 服务： +``` +systemctl enable disable_hw_offloading.service +``` + +### 架构要求 + +Kubernetes 集群管理节点（`etcd` 和 `controlplane`）必须运行在 Linux 节点上。 + +部署工作负载的 `worker` 节点通常是 Windows 节点，但必须至少有一个 `worker` 节点运行在 Linux 上，才能按顺序运行 Rancher Cluster Agent、DNS、Metrics Server 和 Ingress 相关容器。 + +#### 推荐架构 + +我们推荐下表中列出的三节点架构，但你始终可以添加额外的 Linux 和 Windows worker 节点来扩展集群，从而实现冗余： + +| 节点 | 操作系统 | Kubernetes 集群角色 | 用途 | +| ------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| 节点 1 | Linux（推荐 Ubuntu Server 18.04） | Control plane, etcd, worker | 管理 Kubernetes 集群 | +| 节点 2 | Linux（推荐 Ubuntu Server 18.04） | Worker | 支持集群的 Rancher Cluster Agent、Metrics Server、DNS 和 Ingress | +| 节点 3 | Windows（Windows Server 核心版本 1809 或更高版本） | Worker | 运行 Windows 容器 | + +### 容器要求 + +Windows 要求容器的版本必须与部署容器的 Windows Server 的版本一致。因此，你必须在 Windows Server 核心版本 1809 或更高版本上构建容器。如果你已经使用早期的 Windows Server 核心版本构建了容器，则必须使用 Windows Server 核心版本 1809 或更高版本重新构建容器。 + +### 云提供商要求 + +如果你在集群中设置了 Kubernetes 云提供商，则需要进行一些额外的操作。如果你想使用云提供商的功能，例如为集群自动配置存储、负载均衡器或其他基础设施，你可能需要设置云提供商。有关如何配置满足条件的云提供商集群节点，请参阅[此页面](../set-up-cloud-providers/set-up-cloud-providers.md)。 + +如果你的云提供商是 GCE（Google Compute Engine），则必须执行以下操作： + +- 按照[步骤](../set-up-cloud-providers/google-compute-engine.md)在`cluster.yml` 中启用 GCE 云提供商。 +- 在 Rancher 中配置集群时，在 Rancher UI 中选择**自定义云提供商**作为云提供商。 + +## 教程：如何创建支持 Windows 的集群 + +本教程描述了如何使用[推荐架构](#推荐架构)中的三个节点创建由 Rancher 配置的集群。 + +在现有节点上使用 Rancher 配置集群时，你需要在每个节点上安装 [Rancher Agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) 来将节点添加到集群中。在 Rancher UI 中创建或编辑集群时，你会看到一个**自定义节点运行命令**，你可以在每台服务器上运行该命令，从而将服务器添加到集群中。 + +要设置支持 Windows 节点和容器的集群，你需要完成以下任务： + + +### 1. 配置主机 + +要在具有 Windows 支持的现有节点上配置集群，请准备好你的主机。 + +主机可以是： + +- 云托管的虚拟机 +- 虚拟化集群中的虚拟机 +- 裸金属服务器 + +你将配置三个节点： + +- 一个 Linux 节点，用于管理 Kubernetes controlplane 并存储你的 `etcd`。 +- 第二个 Linux 节点，它将作为 worker 节点。 +- Windows 节点，它将作为 worker 节点运行 Windows 容器。 + +| 节点 | 操作系统 | +| ------ | ------------------------------------------------------------ | +| 节点 1 | Linux（推荐 Ubuntu Server 18.04） | +| 节点 2 | Linux（推荐 Ubuntu Server 18.04） | +| 节点 3 | Windows（Windows Server 核心版本 1809 或更高版本） | + +如果你的节点托管在**云提供商**上，并且你需要自动化支持（例如负载均衡器或持久存储设备），你的节点还需要满足额外的配置要求。详情请参见[选择云提供商](../set-up-cloud-providers/set-up-cloud-providers.md)。 + +### 2. 在现有节点上创建集群 + +在现有节点上创建 Windows 集群的说明与一般[创建自定义集群的说明](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)非常相似，但有一些特定于 Windows 的要求。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击**自定义**。 +1. 在**集群名称**字段中输入集群的名称。 +1. 在 **Kubernetes 版本**下拉菜单中，选择 v1.19 或更高版本。 +1. 在**网络提供商**字段中，选择 **Flannel**。 +1. 在 **Windows 支持**中，单击**启用**。 +1. 可选：启用 Windows 支持后，你将能够选择 Flannel 后端模式。有两个网络选项：[**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) 和 [**VXLAN (Overlay)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)。默认选项是 **VXLAN (Overlay)** 模式。 +1. 点击**下一步**。 + +:::note 重要提示： + +对于 Host Gateway (L2bridge) 网络，最好为所有节点使用相同的第 2 层网络。否则，你需要为它们配置路由规则。有关详细信息，请参阅[配置云托管 VM 路由的文档](network-requirements-for-host-gateway.md#云托管虚拟机的路由配置)。如果你使用的是 Amazon EC2、Google GCE 或 Azure 虚拟机，你需要[禁用私有 IP 地址检查](network-requirements-for-host-gateway.md#禁用私有-ip-地址检查)。 + +::: + +### 3. 将节点添加到集群 + +本节介绍如何将 Linux 和 Worker 节点注册到集群。你将在每个节点上运行一个命令，该命令将安装 Rancher Agent 并允许 Rancher 管理每个节点。 + +#### 添加 Linux master 节点 + +在本节中，你需要在 Rancher UI 上填写表单以获取自定义命令，从而在 Linux master 节点上安装 Rancher Agent。然后，复制该命令并在 Linux master 节点上运行命令，从而在集群中注册该节点。 + +集群中的第一个节点应该是具有 **controlplane** 和 **etcd** 角色的 Linux 主机。至少必须为此节点启用这两个角色，并且必须先将此节点添加到集群中，然后才能添加 Windows 主机。 + +1. 在**节点操作系统**中，单击 **Linux**。 +1. 在**节点角色**中，至少选择 **etcd** 和 **controlplane**。推荐选择所有的三个角色。 +1. 可选：如果点击**显示高级选项**，你可以自定义 [Rancher Agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) 和[节点标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)的设置。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. SSH 到你的 Linux 主机，然后运行复制到剪贴板的命令。 +1. 完成配置 Linux 节点后，选择**完成**。 + +**结果:** + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +节点可能需要几分钟才能注册到集群中。 + +#### 添加 Linux Worker 节点 + +在本节中，我们通过运行命令将 Linux Worker 节点注册到集群中。 + +在初始配置集群之后，你的集群只有一个 Linux 主机。接下来，我们添加另一个 Linux `worker` 主机，用于支持集群的 _Rancher Cluster Agent_、_Metrics Server_、_DNS_ 和 _Ingress_。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到你创建的集群，然后单击 **⋮ > 编辑配置**。 +1. 向下滚动到**节点操作系统**。选择 **Linux**。 +1. 在**自定义节点运行命令**中，转到**节点选项**并选择 **Worker** 角色。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. 使用远程终端连接登录到你的 Linux 主机。粘贴剪贴板的命令并运行。 +1. 在 **Rancher**中，单击**保存**。 + +**结果**：**Worker** 角色已安装在你的 Linux 主机上，并且节点会向 Rancher 注册。节点可能需要几分钟才能注册到集群中。 + +:::note + +Linux Worker 节点上的污点 + +以下污点将添加集群中的 Linux Worker 节点中。将此污点添加到 Linux Worker 节点后，添加到 Windows 集群的任何工作负载都将自动调度到 Windows Worker 节点。如果想将工作负载专门调度到 Linux Worker 节点上，则需要为这些工作负载添加容忍度。 + +| 污点键 | 污点值 | 污点效果 | +| -------------- | ----------- | ------------ | +| `cattle.io/os` | `linux` | `NoSchedule` | + +::: + +#### 添加 Windows Worker 节点 + +在本节中，我们通过运行命令将 Windows Worker 节点注册到集群中。 + +你可以通过编辑集群并选择 **Windows** 选项，从而将 Windows 主机添加到集群中。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到你创建的集群，然后单击 **⋮ > 编辑配置**。 +1. 向下滚动到**节点操作系统**。选择 **Windows**。注意：你将看到 **worker** 角色是唯一可用的角色。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. 使用你喜欢的工具（例如 [Microsoft 远程桌面](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)登录到 Windows 主机。在 **Command Prompt (CMD)** 中运行复制到剪贴板的命令。 +1. 在 Rancher 中，单击**保存**。 +1. 可选：如果要向集群添加更多 Windows 节点，请重复这些操作。 + +**结果**：**Worker** 角色已安装在你的 Windows 主机上，并且节点会向 Rancher 注册。节点可能需要几分钟才能注册到集群中。你现在已拥有一个 Windows Kubernetes 集群。 + +### 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher Server 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 + +## Azure 中存储类的配置 + +如果你的节点使用 Azure VM，则可以使用 [Azure 文件](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv)作为集群的存储类（StorageClass）。详情请参见[此部分](azure-storageclass-configuration.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md new file mode 100644 index 00000000000..d89955f9b78 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md @@ -0,0 +1,35 @@ +--- +title: 集群访问 +--- + + + + + +本节介绍可以用来访问 Rancher 管理的集群的工具。 + +有关如何授予用户访问集群的权限的信息，请参阅[将用户添加到集群](add-users-to-clusters.md)。 + +有关 RBAC 的更多信息，请参阅[本节](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +有关如何设置身份验证系统的信息，请参阅[本节](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)。 + + +### Rancher UI + +Rancher 提供了一个直观的用户界面来让你与集群进行交互。UI 中所有可用的选项都使用 Rancher API。因此，UI 中的任何操作都可以在 Rancher CLI 或 Rancher API 中进行。 + +### kubectl + +你可以使用 Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) 来管理你的集群。使用 kubectl 有两种选择： + +- **Rancher kubectl shell**：通过启动 Rancher UI 中可用的 kubectl shell 与集群交互。此选项不需要你进行任何配置操作。有关详细信息，请参阅[使用 kubectl Shell 访问集群](use-kubectl-and-kubeconfig.md)。 +- **终端远程连接**：你也可以通过在本地桌面上安装 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) ，然后将集群的 kubeconfig 文件复制到本地 `~/.kube/config` 目录来与集群交互。有关更多信息，请参阅[使用 kubectl 和 kubeconfig 文件访问集群](use-kubectl-and-kubeconfig.md)。 + +### Rancher CLI + +你可以下载 Rancher 自己的命令行工具 [Rancher CLI](../../../../reference-guides/cli-with-rancher/cli-with-rancher.md) 来控制你的集群。这个 CLI 工具可以直接与不同的集群和项目进行交互，或者向它们传递 `kubectl` 命令。 + +### Rancher API + +最后，你可以通过 Rancher API 与集群进行交互。在使用 API 之前，你必须先获取 [API 密钥](../../../../reference-guides/user-settings/api-keys.md)。要查看 API 对象的不同资源字段和操作，请打开 API UI（API UI 可以通过单击 Rancher UI 对象的**在 API 中查看**访问）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md new file mode 100644 index 00000000000..6966a35fb4c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md @@ -0,0 +1,78 @@ +--- +title: Kubernetes 持久存储：卷和存储类 +description: "了解在 Kubernetes 中创建持久存储的两种方式：持久卷和存储类" +--- + + + + + +在部署需要保​​留数据的应用时，你需要创建持久存储。持久存储允许你在运行应用的 pod 之外存储应用数据。即使运行应用的 pod 发生故障，这种存储方式也能让你保留应用数据。 + +本文假设你已了解 Kubernetes 的持久卷、持久卷声明和存储类的概念。如需更多信息，请参阅[存储的工作原理](manage-persistent-storage/about-persistent-storage.md)。 + +### 先决条件 + +设置持久存储需要`管理卷`的[角色](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色参考)。 + +如果你要为云集群配置存储，则存储和集群主机必须使用相同的云提供商。 + +要使用 Rancher 配置新存储，则必须启用云提供商。有关启用云提供商的详细信息，请参阅[此页面](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。 + +如果要将现有的持久存储连接到集群，则不需要启用云提供商。 + +### 设置现有存储 + +设置现有存储的总体流程如下： + +1. 设置你的持久存储。可以是云存储或你自己的存储。 +2. 添加引用持久存储的持久卷 (PV)。 +3. 添加引用 PV 的持久卷声明 (PVC)。 +4. 将 PVC 挂载为工作负载中的卷。 + +有关详细信息和先决条件，请参阅[此页面](manage-persistent-storage/set-up-existing-storage.md)。 + +### 在 Rancher 中动态配置新存储 + +配置新存储的总体流程如下： + +1. 添加一个 StorageClass 并将它配置为使用你的存储提供商。StorageClass 可以引用云存储或你自己的存储。 +2. 添加引用存储类的持久卷声明 (PVC)。 +3. 将 PVC 挂载为工作负载的卷。 + +有关详细信息和先决条件，请参阅[此页面](manage-persistent-storage/dynamically-provision-new-storage.md)。 + +### Longhorn 存储 + +[Longhorn](https://longhorn.io/) 是一个轻量级、可靠、易用的 Kubernetes 分布式块存储系统。 + +Longhorn 是免费的开源软件。Longhorn 最初由 Rancher Labs 开发，现在正在作为云原生计算基金会的沙盒项目进行开发。它可以通过 Helm、kubectl 或 Rancher UI 安装在任何 Kubernetes 集群上。 + +如果你有块存储池，Longhorn 可以帮助你为 Kubernetes 集群提供持久存储，而无需依赖云提供商。有关 Longhorn 功能的更多信息，请参阅[文档](https://longhorn.io/docs/latest/what-is-longhorn/)。 + +Rancher v2.5 简化了在 Rancher 管理的集群上安装 Longhorn 的过程。详情请参见[本页面](../../../../integrations-in-rancher/longhorn.md)。 + +### 配置存储示例 + +我们提供了如何使用 [NFS](../provisioning-storage-examples/nfs-storage.md)、[vSphere](../provisioning-storage-examples/vsphere-storage.md) 和 [Amazon EBS](../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md) 来配置存储的示例。 + +### GlusterFS 卷 + +在将数据存储在 GlusterFS 卷上的集群中，你可能会遇到重启 `kubelet` 后 pod 无法挂载卷的问题。有关避免此情况发生的详细信息，请参阅[此页面](manage-persistent-storage/about-glusterfs-volumes.md)。 + +### iSCSI 卷 + +在将数据存储在 iSCSI 卷上的 [Rancher 启动的 Kubernetes 集群](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中，你可能会遇到 kubelet 无法自动连接 iSCSI 卷的问题。有关解决此问题的详细信息，请参阅[此页面](manage-persistent-storage/install-iscsi-volumes.md)。 + +### hostPath 卷 +在创建 hostPath 卷之前，你需要在集群配置中设置 [extra_bind](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds/)。这会将路径作为卷安装在你的 kubelet 中，可用于工作负载中的 hostPath 卷。 + +### 将 vSphere Cloud Provider 从树内迁移到树外 + +Kubernetes 正在逐渐不在树内维护云提供商。vSphere 有一个树外云提供商，可通过安装 vSphere 云提供商和云存储插件来使用。 + +有关如何从树内 vSphere 云提供商迁移到树外，以及如何在迁移后管理现有虚拟机，请参阅[此页面](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 + +### 相关链接 + +- [Kubernetes 文档：存储](https://kubernetes.io/docs/concepts/storage/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md new file mode 100644 index 00000000000..9d03258c515 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md @@ -0,0 +1,28 @@ +--- +title: Cluster Autoscaler +--- + + + + + +在本文中，你将学习如何使用 AWS EC2 Auto Scaling 组在 Rancher 自定义集群上安装和使用 [Kubernetes cluster-autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/)。 + +Cluster Autoscaler 是一个自动调整 Kubernetes 集群大小的工具。该工具在满足以下条件之一时能自动调整集群大小： + +* 集群中有 Pod 因资源不足而无法运行。 +* 集群中有一些节点长时间未得到充分利用，而且它们的 Pod 可以放到其他现有节点上。 + +为防止你的 pod 被驱逐，请在你的 pod 规范中设置 `priorityClassName: system-cluster-critical` 属性。 + +Cluster Autoscaler 运行在 Kubernetes master 节点上。它可以在 `kube-system` 命名空间中运行。Cluster Autoscaler 不会缩减运行非镜像 `kube-system` pod 的节点。 + +你可以在 worker 节点上运行 Cluster Autoscaler 的自定义 deployment，但需要小心以保证 Cluster Autoscaler 能正常运行。 + +## 云提供商 + +Cluster Autoscaler 为不同的云提供商提供支持。有关详细信息，请参见 [Cluster Autoscaler 支持的云提供商](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler#deployment)。 + +### 在 Amazon 上设置 Cluster Autoscaler + +有关在 Amazon 上运行 Cluster Autoscaler 的详细信息，请参阅[此页面](use-aws-ec2-auto-scaling-groups.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md new file mode 100644 index 00000000000..390935ef480 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md @@ -0,0 +1,36 @@ +--- +title: 集群管理 +--- + + + + + +在 Rancher 中配置集群后，你可以开始使用强大的 Kubernetes 功能在开发、测试或生产环境中部署和扩展容器化应用。 + +:::note + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../../../reference-guides/kubernetes-concepts.md)。 + +::: + +## 在 Rancher 中管理集群 + +将集群[配置到 Rancher](../kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) 之后，[集群所有者](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#集群角色)需要管理这些集群。管理集群的选项如下： + +import ClusterCapabilitiesTable from '../../../shared-files/_cluster-capabilities-table.md'; + + + +## 配置工具 + +Rancher 包含 Kubernetes 中未包含的各种工具来协助你进行 DevOps 操作。Rancher 可以与外部服务集成，让你的集群更高效地运行。工具分为以下几类： + +- 告警 +- Notifiers +- Logging +- Monitoring +- Istio 服务网格 +- OPA Gatekeeper + +你可以通过 **Apps & Marketplace**（Rancher v2.6.5 之前的版本）或 **Apps**（Rancher v2.6.5+）来安装工具。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md new file mode 100644 index 00000000000..3e093ff09e4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md @@ -0,0 +1,15 @@ +--- +title: 配置存储示例 +--- + + + + + +Rancher 通过各种卷插件来支持持久存储。但是，在使用这些插件将持久存储绑定到工作负载之前，无论是使用云解决方案还是你自己管理的本地解决方案，你都必须先配置存储本身。 + +为了你的方便，Rancher 提供了配置主流存储的参考文档： + +- [NFS](nfs-storage.md) +- [vSphere](vsphere-storage.md) +- [EBS](persistent-storage-in-amazon-ebs.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/new-user-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/new-user-guides.md new file mode 100644 index 00000000000..be21f2b1596 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/how-to-guides/new-user-guides/new-user-guides.md @@ -0,0 +1,13 @@ +--- +title: 新用户指南 +--- + + + + + +新用户指南，也称为 **教程**，描述了用户在完成一些具体操作时要遵循的实用步骤。这些文档被称为“以学习为导向”的文档，用户通过“实际操作”来学习。 + +新用户指南旨在指导初学者或 Rancher 的日常用户通过一系列步骤来学习如何做某件事。目标是让用户可以通过易于操作、有意义的、可重复的指示来学习如何完成任务。这些指南将帮助用户完成工作，然后立即获得承诺的结果。 + +普通的 Rancher 用户的技术水平高于“初学者”，但是新用户指南旨在同等的帮助新用户、初学者以及经验丰富的 Rancher 客户，这是通过结合使用高级和技术语言来介绍主题并指导用户完成每个 Rancher 用户都必须了解的一般任务来实现的。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cis-scans/cis-scans.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cis-scans/cis-scans.md new file mode 100644 index 00000000000..19fa1007c39 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cis-scans/cis-scans.md @@ -0,0 +1,110 @@ +--- +title: CIS 扫描 +--- + + + + + +Rancher 可以通过运行安全扫描来检查 Kubernetes 是否按照 CIS Kubernetes Benchmark 中定义的安全最佳实践进行部署。CIS 扫描可以运行在任何 Kubernetes 集群，包括托管的 Kubernetes，例如 EKS、AKS 和 GKE。 + +`rancher-cis-benchmark` 应用使用了 kube-bench, ，这是 Aqua Security 的开源工具，用于检查集群是否符合 CIS Kubernetes Benchmark。此外，为了生成集群级别的报告，此应用使用了 Sonobuoy 来聚合报告。 + +## 关于 CIS Benchmark + +CIS（Center for Internet Security）是一个 501(c\)(3) 非营利组织，成立于 2000 年 10 月，其使命是识别、开发、验证、促进和维持网络防御的最佳实践方案，并建立和指导社区，以在网络空间中营造信任的环境。该组织总部位于纽约东格林布什，其成员包括大公司、政府机构和学术机构。 + +CIS Benchmark 是目标系统安全配置的最佳实践。CIS Benchmark 是由安全专家、技术供应商、公开和私人社区成员，以及 CIS Benchmark 开发团队共同志愿开发的。 + +在 CIS 网站上[注册](https://learn.cisecurity.org/benchmarks)以查看官方 Benchmark 文档。 + +## 关于生成的报告 + +每次扫描都会生成一份报告，你可以在 Rancher UI 中查看该报告，并以 CSV 格式下载它。 + +默认情况下使用 CIS Benchmark v1.6。 + +Benchmark 版本包含在生成的报告中。 + +Benchmark 提供两种类型的建议，分别是自动（Automated）和手动（Manual）。Benchmark 中标记为 Manual 的建议不包含在生成的报告中。 + +一些测试会被标记为“不适用”。由于 Rancher 配置 RKE 集群的方式，这些测试不会在任何 CIS 扫描中运行。有关如何审核测试结果，以及为什么某些测试会被标记为不适用，请参阅 Rancher 的 Kubernetes 对应版本的[自测指南](../../reference-guides/rancher-security/rancher-security.md#CIS-Benchmark-和自我评估)。 + +该报告包含以下信息： + +| 报告中的列 | 描述 | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | CIS Benchmark 的 ID 号。 | +| `description` | CIS Benchmark 测试的描述。 | +| `remediation` | 为了通过测试需要修复的内容。 | +| `state` | 测试的状态，可以是通过、失败、跳过或不适用。 | +| `node_type` | 节点角色，角色决定了在节点上运行的测试。主测试在 controlplane 节点上运行，etcd 测试在 etcd 节点上运行，节点测试在 Worker 节点上运行。 | +| `audit` | 这是 `kube-bench` 为此测试运行的审计检查。 | +| `audit_config` | 适用于审计脚本的任何配置。 | +| `test_info` | `kube-bench` 报告的测试相关信息（如果存在）。 | +| `commands` | `kube-bench` 报告的测试相关的命令（如果存在）。 | +| `config_commands` | `kube-bench` 报告的测试相关的配置数据（如果存在）。 | +| `actual_value` | 测试的实际值。如果由 `kube-bench` 报告，则会显示。 | +| `expected_result` | 测试的预期值。如果由 `kube-bench` 报告，则会显示。 | + +请参阅[集群加固指南中的表格](../../reference-guides/rancher-security/rancher-security.md)，以了解 Kubernetes、Benchmark、Rancher 以及我们的集群强化指南的版本对应关系。另外，请参阅强化指南，以获取符合 CIS 的集群的配置文件以及修复失败测试的信息。 + +## 测试配置文件 + +以下是可用的配置文件： + +- Generic CIS 1.5 +- Generic CIS 1.6 +- RKE permissive 1.5 +- RKE hardened 1.5 +- RKE permissive 1.6 +- RKE hardened 1.6 +- RKE2 permissive 1.5 +- RKE2 hardened 1.5 +- RKE2 permissive 1.6 +- RKE2 hardened 1.6 +- AKS +- EKS +- GKE + +你还可以通过保存一组要跳过的测试来自定义配置文件。 + +所有配置文件都会有一组不适用的测试，CIS 扫描会跳过这些测试。RKE 集群管理 Kubernetes 的方式导致这些测试被认为不适用。 + +RKE 集群扫描配置文件有两种类型： + +- **Permissive**：此配置文件有一组要跳过的测试，跳过的原因是这些测试会在默认的 RKE Kubernetes 集群上失败。除了跳过的测试列表之外，配置文件也不会运行不适用的测试。 +- **Hardened**：此配置文件不会跳过任何测试（不适用的测试除外）。 + +EKS 和 GKE 集群扫描的配置文件基于这些集群类型特定的 CIS Benchmark 版本。 + +要通过 “Hardened” 配置文件，你需要遵从[强化指南](../../reference-guides/rancher-security/rancher-security.md#Rancher-加固指南)并使用强化指南中定义的 `cluster.yml` 来配置一个强化集群。 + +默认配置文件和支持的 CIS Benchmark 版本取决于扫描的集群类型： + +`rancher-cis-benchmark` 支持 CIS 1.6 Benchmark 版本。 + +- RKE Kubernetes 集群默认使用 RKE Permissive 1.6 配置文件。 +- EKS 和 GKE 有自己的 CIS Benchmark，由 `kube-bench` 发布。这些集群默认使用相应的测试配置文件。 +- RKE2 Kubernetes 集群默认使用 RKE2 Permissive 1.6 配置文件。 +- RKE、RKE2、EKS 和 GKE 以外的集群类型默认使用 Generic CIS 1.5 配置文件。 + +## 跳过和不适用的测试 + +有关要跳过和不适用的测试列表，请参阅[此页面](../../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)。 + +目前，只有用户定义的跳过测试会在生成报告中标记为跳过。 + +如果某个默认配置文件将某个测试定义为跳过，则该测试也会标记为不适用。 + +## RBAC + +有关权限的详细信息，请参阅[此页面](rbac-for-cis-scans.md)。 + +## 配置 + +有关为扫描、配置文件和 Benchmark 版本配置自定义资源的更多信息，请参阅[此页面](configuration-reference.md)。 + +## 操作指南 + +要了解如何运行 CIS 扫描，请参阅 [CIS 扫描指南](../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md new file mode 100644 index 00000000000..c7dd9264ee4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md @@ -0,0 +1,36 @@ +--- +title: AWS Marketplace 集成 +--- + + + + + +## 概述 + +Rancher 提供与 AWS Marketplace 的集成，允许用户购买 SUSE 的支持合同。当你开始支持更多集群时，这种集成使你可以轻松调整支持需求。 + +## 限制 + +- 你必须运行 Rancher v2.6.7 或更高版本。 +- Rancher 的部署必须启用额外的指标。 +- Rancher 必须安装在 EKS 集群上。 +- 你必须通过 AWS Marketplace 购买至少一项 Rancher 支持的权限。 +- 你可能需要额外的设置来支持代理/离线用例。有关更多信息，请参阅[先决条件](adapter-requirements.md)。 + +## 如何使用 + +1. 完成[先决条件](adapter-requirements.md)。 +2. [安装 CSP Adapter](install-adapter.md)。 + +## 常见问题 + +**我以后可以购买对更多节点的支持吗？** + +可以。只需转到你最初用于购买支持的 AWS Marketplace 条目并增加权限数量即可。 + +**我可以在同一个 AWS 账户中使用多个 Rancher 实例吗？** + +可以。但是，Rancher 安装的每个集群都需要遵守先决条件。 + +此外，一个给定的权限一次只能由一个 Rancher 管理服务器使用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md new file mode 100644 index 00000000000..715ba68dd71 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md @@ -0,0 +1,11 @@ +--- +title: 云市场集成 +--- + + + + + +Rancher 提供与云市场的集成，以便轻松购买对托管在某些云提供商上的安装支持。此外，此集成还提供了生成 Supportconfig Bundle 的功能，该 Bundle 可以给 rancher 提供支持。 + +从 Rancher v2.6.7 开始，此集成仅支持 AWS。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/fleet-gitops-at-scale.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/fleet-gitops-at-scale.md new file mode 100644 index 00000000000..1a58a9aefc6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/fleet-gitops-at-scale.md @@ -0,0 +1,67 @@ +--- +title: 使用 Feet 进行持续交付 +--- + + + + + +使用 Fleet 进行持续交付是大规模的 GitOps。Fleet 旨在管理多达一百万个集群。它也足够轻量级，对于[单个集群](https://fleet.rancher.io/installation#default-install)也很有效，但当你达到[大规模](https://fleet.rancher.io/installation#configuration-for-multi-cluster)时，它真的会大放异彩。大规模是指单个组织中的大量集群、大量部署或大量团队。 + +Fleet 是 Rancher 的一个独立项目，可以通过 Helm 安装在任何 Kubernetes 集群上。 + +## 架构 + +有关 Fleet 如何运作的信息，请参阅[此处](./fleet-gitops-at-scale/architecture)。 + +## 在 Rancher UI 中访问 Fleet + +Fleet 预安装在 Rancher 中，并由 Rancher UI 中的**持续交付**选项进行管理。有关持续交付和其他 Fleet 故障排除技巧的更多信息，请参阅[此处](https://fleet.rancher.io/troubleshooting)。 + +用户可以按照 **gitops** 实践，利用持续交付将应用程序部署到 git 仓库中的 Kubernetes 集群，而无需任何手动操作。 + +按照以下步骤在 Rancher UI 中访问持续交付： + +1. 单击 **☰ > 持续交付**。 + +1. 在菜单顶部选择命名空间 ，注意以下事项： + + - 默认情况下，选择 **fleet-default**，包括通过 Rancher 注册的所有下游集群。 + + - 你可以切换到 **fleet-local**，它仅包含 **local** 集群，或者你可以创建自己的工作空间，将集群分配和移动到其中。 + + - 然后，你可以通过单击左侧导航栏上的**集群**来管理集群。 + +1. 单击左侧导航栏上的 **Gitrepos**，将 gitrepo 部署到当前工作空间的集群中。 + +1. 选择 [git 仓库](https://fleet.rancher.io/gitrepo-add)和[目标集群/集群组](https://fleet.rancher.io/gitrepo-targets)。你也可以通过单击左侧导航栏中的**集群组**在 UI 中创建集群组。 + +1. 部署 gitrepo 后，你可以通过 Rancher UI 监控应用程序。 + +## Windows 支持 + +有关对具有 Windows 节点的集群的支持的详细信息，请参阅[此页面](./fleet-gitops-at-scale/windows-support)。 + +## GitHub 仓库 + +Fleet Helm charts 可在[此处](https://github.com/rancher/fleet/releases/tag/v0.3.10)获取。 + +## 在代理后使用 Fleet + +有关在代理后面使用 Fleet 的详细信息，请参阅[此页面](./fleet-gitops-at-scale/use-fleet-behind-a-proxy)。 + +## Helm Chart 依赖 + +为了成功部署具有依赖项的 Helm Chart，你必须运行一个手动命令（如下所示），因为用户需要满足依赖列表。如果不执行此操作，继续克隆你的仓库并运行 `helm install`，则会因依赖项丢失而导致安装失败。 + +git 仓库中的 Helm Chart 必须在 Chart 子目录中包含其依赖。 你必须手动运行 `helm dependencies update $chart` 或在本地运行 `helm dependencies build $chart`，然后将完整的 Chart 目录提交到 git 仓库。请注意，你需要使用适当的参数更新你的命令。 + +## 故障排除 + +- **已知问题**：Fleet gitrepos 的 clientSecretName 和 helmSecretName 密文不包含在 [backup-restore-operator](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md#1-install-the-rancher-backup-operator) 创建的备份或恢复中。一旦有永久的解决方案，我们将更新社区内容。 + +- **临时解决方法**：默认情况下，用户定义的密文不会在 Fleet 中备份。如果执行灾难恢复或将 Rancher 迁移到新集群，则有必要重新创建密文。要修改 ResourceSet 以包含要备份的额外资源，请参阅文档[此处](https://github.com/rancher/backup-restore-operator#user-flow)。 + +## 文档 + +Fleet 文档位于 https://fleet.rancher.io/ 。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/configuration-options/configuration-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/configuration-options/configuration-options.md new file mode 100644 index 00000000000..658b3785bdb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/configuration-options/configuration-options.md @@ -0,0 +1,43 @@ +--- +title: 配置选项 +--- + + + + + +### Egress 支持 + +默认情况下，Egress 网关是禁用的，但你可以在安装或升级时使用 values.yaml 或[覆盖文件](#覆盖文件)启用它。 + +### 启用自动 Sidecar 注入 + +默认情况下，自动 sidecar 注入是禁用的。要启用此功能，请在安装或升级时在 values.yaml 中设置 `sidecarInjectorWebhook.enableNamespacesByDefault=true`。这会自动将 Istio sidecar 注入到所有已部署的新命名空间。 + +### 覆盖文件 + +覆盖文件用于为 Istio 进行更广泛的配置。它允许你更改 [IstioOperator API](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) 中可用的任何值。你可以自定义默认安装以满足你的需求。 + +覆盖文件将在 Istio Chart 默认安装的基础上添加配置。换言之，你不需要为安装中已定义的组件进行重新定义。 + +有关覆盖文件的更多信息，请参阅 [Istio 文档](https://istio.io/latest/docs/setup/install/istioctl/#configure-component-settings) + +### 选择器和抓取配置 + +Monitoring 应用设置了 `prometheus.prometheusSpec.ignoreNamespaceSelectors=false`，即在默认情况下跨所有命名空间进行监控。这样，你可以查看部署在具有 `istio-injection=enabled` 标签的命名空间中的资源的流量、指标和图。 + +如果你想将 Prometheus 限制为特定的命名空间，请设置 `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`。完成此操作后，你需要添加其他配置来继续监控你的资源。 + +详情请参阅[本节](selectors-and-scrape-configurations.md)。 + +### 在具有 Pod 安全策略的情况下启用 Istio + +详情请参阅[本节](pod-security-policies.md)。 + +### 在 RKE2 集群上安装 Istio 的其他步骤 + +详情请参阅[本节](install-istio-on-rke2-cluster.md)。 + +### 项目网络隔离的其他步骤 + +详情请参阅[本节](project-network-isolation.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/istio.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/istio.md new file mode 100644 index 00000000000..3cc6c997303 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/istio/istio.md @@ -0,0 +1,148 @@ +--- +title: Istio +--- + + + + + +[Istio](https://istio.io/) 是一种开源工具，可以让 DevOps 团队更轻松地观察、控制、排查并保护复杂的微服务网络中的流量。 + +随着微服务网络的变化和增长，微服务网络之间的交互变得越来越难以管理和理解。在这种情况下，将服务网格作为单独的基础设施层是非常有用的。Istio 的服务网格可以让你在不直接更改微服务的情况下控制微服务之间的流量。 + +Rancher 与 Istio 集成，使得管理员或集群所有者可以将 Istio 交给开发者团队，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署，金丝雀部署，和 A/B 测试进行流量管理。 + +此核心服务网格支持但不限于以下功能： + +- **管理流量**：例如入口和出口路由、断路、镜像。 +- **安全**：具有用于验证和授权流量和用户的资源，包括 mTLS。 +- **可观察性**：观察日志、指标和分布式流量。 + +[设置 Istio](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) 后，你可以通过 Rancher UI、`kubectl` 或 ` Istioctl` 来使用 Istio 的 controlplane 功能。 + +Istio 需要由 `cluster-admin` 设置后才能在项目中使用。 + +## Rancher 2.5 的新功能 + +Istio 已简化了整体架构。结合 Pilot、Citadel、Galley 和 sidecar injector 创建了一个单独的组件 Istiod。Node Agent 功能也已合并到 istio-agent 中。 + +以前由 Istio 安装的插件（cert-manager、Grafana、Jaeger、Kiali、Prometheus、Zipkin）现在需要单独安装。Istio 支持安装来自 Istio 项目的集成，并保持与非 Istio 项目的兼容性。 + +你仍然可以通过安装 [Rancher Monitoring](../monitoring-and-alerting/monitoring-and-alerting.md) 或安装你自己的 Prometheus operator 来使用 Prometheus 集成。Rancher 的 Istio chart 还默认安装 Kiali，确保你可以开箱即用地全面了解微服务。 + +Istio 已经脱离了使用 Helm 安装的方式，现在通过 Istioctl 二进制文件或 Istio Operator 进行安装。为了使用最简单的方式与 Istio 交互，Rancher 的 Istio 会维护一个 Helm Chart，该 Chart 使用 Istioctl 二进制文件来管理你的 Istio 安装。 + +此 Helm Chart 将在 UI 的**应用 & 市场**中提供。有权访问 Rancher Chart 应用商店的用户需要先设置 Istio，然后才能在项目中使用它。 + +## Istio 附带的工具 + +我们的 [Istio](https://istio.io/) 安装程序将 istioctl 二进制命令包装在一个 Helm chart 中，其中包括一个覆盖文件的选项，用来支持复杂的自定义配置。 + +它还包括以下内容： + +### Kiali + +Kiali 是一个全面的可视化辅助工具，用于绘制整个服务网格中的流量图。它允许你查看它们的连接方式，包括它们之间的流量速率和延迟。 + +你可以检查服务网格的运行状况，或深入查看单个组件的传入和传出请求。 + +### Jaeger + +Jaeger 是用于跟踪分布式系统的工具。我们的 Istio 安装程序包括能快速启动的一体化 [Jaeger](https://www.jaegertracing.io/) 安装。 + +请注意，这不是符合 Jaeger 生产要求的部署。此部署使用在内存中的存储组件，而 Jaeger 推荐在生产环境中使用持久存储组件。有关你所需的部署策略的更多信息，请参阅 [Jaeger 文档](https://www.jaegertracing.io/docs/latest/operator/#production-strategy)。 + +## 先决条件 + +在启用 Istio 之前，建议你先确认你的 Rancher worker 节点是否有足够的 [CPU 和内存](cpu-and-memory-allocations.md)来运行 Istio 的所有组件。 + +如果要在 RKE2 集群上安装 Istio，则需要执行一些额外的步骤。有关详细信息，请参阅[本节](#在-rke2-集群上安装-istio-的其他步骤) + +## 设置指南 + +如需了解如何设置 Istio 并在项目中使用它，请参阅[设置指南](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md)。 + +## 卸载 Istio + +要从集群、命名空间或工作负载中删除 Istio 组件，请参阅[卸载 Istio](disable-istio.md)。 + +## 从之前的 Istio 版本进行迁移 + +对于低于 1.7.x 版本的 Istio，不存在升级路径。要通过 Apps & Marketplace（Rancher 版本在 v2.6.5 之前）或 App（Rancher 版本在 v2.6.5+）成功安装 Istio，你需要在废弃的 Rancher UI 全局视图中禁用现有的 Istio。 + + +如果你有大量额外的 Istio CRD（自定义资源定义），可能需要考虑手动迁移那些在两个版本的 Istio 中都受支持的 CRD。你可以通过运行 `kubectl get -n istio-system -o yaml` 命令来完成此操作，将输出的 yaml 保存下来，并在新版本中重新部署。 + +另一个方法是逐个手动卸载 Istio 资源，但保留在两个版本的 Istio 中都受支持且新版本不会安装的资源。这种方法更容易导致安装新版本时出现问题，但根据环境情况可能是一个不错的选择。 + +## 访问可视化 + +> 默认情况下，只有 cluster-admin 可以访问 Kiali。有关如何允许具有管理员、编辑或查看权限的角色访问它们的说明，请参阅[本节](rbac-for-istio.md)。 +在集群中设置 Istio 后，你可以在 Rancher UI 中使用 Grafana、Prometheus 和 Kiali。 + +要访问 Grafana 和 Prometheus 可视化： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击**监控**。 +4. 点击 **Grafana** 或任何其他仪表板。 + +要访问 Kiali 可视化： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要查看 Kiali 的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击 **Istio**。 +4. 单击 **Kiali**。从这里，你可以访问**流量图**或**流量指标**选项卡，从而可视化网络指标。 + +默认情况下，prometheus 会拾取所有命名空间，并将数据用于 Kiali 图。如果你想使用不同的配置进行 prometheus 数据抓取，请参阅[选择器/抓取配置](configuration-options/selectors-and-scrape-configurations.md)。 + +你的角色决定了你对可视化的访问。只有 `cluster-admin` 角色可以使用 Grafana 和 Prometheus。默认情况下，只有 `cluster-admin` 可以使用 Kiali UI，但是 `cluster-admin` 可以通过编辑 Istio values.yaml 来允许其他角色进行访问。 + +## 架构 + +Istio 安装了一个服务网格，它使用 [Envoy](https://www.envoyproxy.io) Sidecar 代理来拦截到每个工作负载的流量。这些 sidecar 拦截并管理服务之间的通信，从而实现精细化观察并控制集群内的流量。 + +只有注入了 Istio sidecar 的工作负载可以通过 Istio 进行跟踪和控制。 + +如果命名空间启用了 Istio，部署到命名空间的新工作负载会自动具有 Istio sidecar。你需要为之前的工作负载手动启用 Istio。 + +有关 Istio sidecar 的更多信息，请参阅 [Istio sidecare-injection 文档](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/)。有关 Istio 架构的更多信息，请参阅 [Istio 架构文档](https://istio.io/latest/docs/ops/deployment/architecture/)。 + +### 多个 Ingress + +默认情况下，每个 Rancher 配置的集群都有一个 NGINX Ingress Controller 来允许流量进入集群。Istio 还在 `istio-system` 命名空间中默认安装一个 Ingress Gateway。因此，你的集群将有两个 ingress。 + +![启用 Istio 的集群可以有两个 ingress，分别是默认的 Nginx ingress 和默认的 Istio controller](/img/istio-ingress.svg) + +可以通过[覆盖文件](configuration-options/configuration-options.md#覆盖文件)来启用其他 Istio Ingress Gateway。 + +### Egress 支持 + +默认情况下，Egress 网关是禁用的，但你可以在安装或升级时使用 values.yaml 或[覆盖文件](configuration-options/configuration-options.md#覆盖文件)启用它。 + +## 在 RKE2 集群上安装 Istio 的其他步骤 + +要在 RKE2 集群上安装 Istio，请按照[步骤](configuration-options/install-istio-on-rke2-cluster.md)进行操作。 + +## 在离线环境中升级 Istio + +现在，Istio Pod 安全策略默认启用。新值 `installer.releaseMirror.enabled` 已添加到 rancher-istio Chart 中，以启用和禁用支持离线升级的 Server。请注意，`installer.releaseMirror.enabled` 默认设置为 `false`。你可以在安装或升级时根据需要设置该值。按照以下步骤执行： + +1. 在 Rancher UI 中配置离线 Rancher 实例和离线自定义集群。 +2. 在集群中安装 Monitoring：**Cluster Explorer > Apps & Marketplace > Charts > Monitoring**。 +3. 将 Istio 所需的所有镜像拉入在离线环境中使用的私有镜像仓库。 +4. 在集群中安装 Istio：**Cluster Explorer > Apps & Marketplace > Charts > Istio**。 + +:::note + +你可以在新安装的 Istio 上启用 [Jaeger](https://www.jaegertracing.io/) 和 [Kiali](https://kiali.io/)。为确保 Jaeger 和 Kiali 正常工作，请在安装期间将 `values.yaml` 中的 `installer.releaseMirror.enabled` 设置为 `true`。 + +::: + +5. 升级 Istio。 + +:::caution + +如果你还没有执行操作，请设置 `installer.releaseMirror.enabled=true` 以升级 Istio。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md new file mode 100644 index 00000000000..d719b72fe1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md @@ -0,0 +1,12 @@ +--- +title: 自定义资源配置 +--- + + + + + +通过以下自定义资源配置 logging： + +- [Flow 和 ClusterFlow](flows-and-clusterflows.md) +- [Output 和 ClusterOutput](outputs-and-clusteroutputs.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/logging.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/logging.md new file mode 100644 index 00000000000..2d61b94fd17 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/logging/logging.md @@ -0,0 +1,140 @@ +--- +title: Rancher Logging 集成 +description: Rancher 集成了主流的日志服务。了解集成日志服务的要求和优势，并在你的集群上启用 Logging。 +--- + + + + + +现在，Rancher 的日志管理由 [Logging operator](https://kube-logging.github.io/docs/) 提供支持，它取代了以前的内部解决方案。 + +## 启用 Logging + +你可以转到**应用**页面并安装 Logging 应用程序，从而为 Rancher 管理的集群启用 Logging： + + + +1. 转到要安装 Logging 的集群，然后单击 **Apps**。 +2. 点击 **Logging** 应用。 +3. 滚动到 Helm Chart README 的底部，然后单击**安装**。 + + + + +1. 转到要安装 Logging 的集群，然后单击 **Apps & Marketplace**。 +2. 点击 **Logging** 应用。 +3. 滚动到 Helm Chart README 的底部，然后单击**安装**。 + + + +**结果**：Logging 应用已部署到 `cattle-logging-system` 命名空间中。 + +## 卸载 Logging + + + +1. 转到要安装 Logging 的集群，然后单击 **Apps**。 +2. 点击**已安装的应用**。 +3. 转到 `cattle-logging-system` 命名空间并选中 `rancher-logging` 和 `rancher-logging-crd` 框。 +4. 单击**删除**。 +5. 确认**删除**。 + + + + +1. 转到要安装 Logging 的集群，然后单击 **Apps & Marketplace**。 +2. 点击**已安装的应用**。 +3. 转到 `cattle-logging-system` 命名空间并选中 `rancher-logging` 和 `rancher-logging-crd` 框。 +4. 单击**删除**。 +5. 确认**删除**。 + + + + +**结果**：已卸载 `rancher-logging`。 + +## 架构 + +有关 Logging 应用程序工作原理的更多信息，请参阅[本节](logging-architecture.md)。 + +## RBAC + +Rancher Logging 有两个角色，分别是 `logging-admin` 和 `logging-view`。有关如何以及何时使用这些角色的更多信息，请参阅[此页面](rbac-for-logging.md)。 + +## 配置 Logging 自定义资源 + +要管理 `Flows`、`ClusterFlows`、`Outputs` 和 `ClusterOutputs`： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要配置 Logging 自定义资源的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击 **Logging**。 + +### Flows 和 ClusterFlows + +有关配置 `Flows` 和 `ClusterFlows` 的帮助，请参阅[此页面](custom-resource-configuration/flows-and-clusterflows.md)。 + +### Outputs 和 ClusterOutputs + +有关配置 `Outputs` 和 `ClusterOutputs` 的帮助，请参阅[此页面](custom-resource-configuration/outputs-and-clusteroutputs.md)。 + +## 配置 Logging Helm Chart + +有关在安装或升级 Logging 应用程序时可配置的选项，请参阅[此页面](logging-helm-chart-options.md)。 + +### Windows 支持 + +你可以从 Windows 节点[启用 Logging](logging-helm-chart-options.md#启用禁用-windows-节点-logging)。 + +### 使用自定义 Docker 根目录 + +有关使用自定义 Docker 根目录的详细信息，请参阅[本节](logging-helm-chart-options.md#使用自定义-docker-根目录)。 + +### 处理污点和容忍度 + +有关如何在 Logging 应用程序中使用污点和容忍度的信息，请参阅[此页面](taints-and-tolerations.md)。 + +### 在 SELinux 上使用 Logging V2 + +有关在启用了 SELinux 的节点上使用 Logging 应用程序的信息，请参阅[本节](logging-helm-chart-options.md#启用-logging-应用程序以使用-selinux)。 + +### 其他日志来源 + +默认情况下，Rancher 会收集所有类型集群的 controlplane 组件和节点组件的日志。在某些情况下，也会收集其他日志。有关详细信息，请参阅[本节](logging-helm-chart-options.md#其他日志来源)。 + +## 故障排除 + +### 日志缓冲区导致 Pod 过载 + +根据你的配置，默认缓冲区大小可能太大并导致 Pod 故障。减少负载的一种方法是降低记录器的刷新间隔。这可以防止日志溢出缓冲区。你还可以添加更多刷新线程来处理大量日志试图同时填充缓冲区的情况。 + +有关如何配置日志缓冲区来满足企业需求的更完整说明，请参阅[缓冲区](https://kube-logging.github.io/docs/configuration/plugins/outputs/buffer/)和 [Fluentd 配置](https://kube-logging.github.io/docs/logging-infrastructure/fluentd/)的官方 Logging Operator 文档。 + +### `cattle-logging` 命名空间正在重新创建 + +如果你的集群之前在旧版 Rancher UI 的全局视图中部署了 Logging，`cattle-logging` 命名空间可能会不断被重新创建。 + +要解决这个问题，你可以将所有 `clusterloggings.management.cattle.io` 和 `projectloggings.management.cattle.io` 自定义资源从管理集群中针对该集群的命名空间中删除。 +这些自定义资源会导致 Rancher 在下游集群中创建 `cattle-logging` 命名空间（如果不存在）。 + +集群命名空间与集群 ID 匹配，因此我们需要找到每个集群的集群 ID。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要获取 ID 的集群，然后单击 **Explore**。 +2. 从以下其中一个 URL 中复制 `` 的内容。`` 是集群命名空间名称。 + +```bash +# Cluster Management UI +https:///c// + +# Cluster Dashboard +https:///dashboard/c// +``` + +现在我们有了 `` 命名空间，我们可以删除导致 `cattle-logging` 不断重新创建的自定义资源。 +*警告*：请确保当前未使用 Logging （从旧版 Rancher UI 全局视图中安装的版本）。 + +```bash +kubectl delete crd clusterloggings.management.cattle.io -n +kubectl delete crd projectloggings.management.cattle.io -n +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md new file mode 100644 index 00000000000..12a26c0e478 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md @@ -0,0 +1,100 @@ +--- +title: 监控和告警 +description: Prometheus 允许你查看来自不同 Rancher 和 Kubernetes 对象的指标。了解监控范围以及如何启用集群监控 +--- + + + + + +你可以使用 `rancher-monitoring` 应用，将业界领先的开源监控和告警解决方案快速部署到你的集群中。 + +### 功能 + +Prometheus 支持查看 Rancher 和 Kubernetes 对象的指标。通过使用时间戳，Prometheus 能让你通过 Rancher UI 或 Grafana（与 Prometheus 一起部署的分析查看平台）以更容易阅读的图表和视觉形式来查询和查看这些指标。 + +通过查看 Prometheus 从集群的 controlplane、节点和 deployment 中抓取的数据，你可以随时了解集群中发生的所有事件。然后，你可以使用这些分析来更好地运行你的环境，例如在系统紧急情况发生之前阻止它们、制定维护策略，或恢复崩溃的服务器。 + +Rancher v2.5 的 `rancher-monitoring` operator 由 [Prometheus](https://prometheus.io/)，[Grafana](https://grafana.com/grafana/)，[Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)，[Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 和 [Prometheus adapter](https://github.com/DirectXMan12/k8s-prometheus-adapter) 组成。 + +Monitoring 应用： + +- 监控集群节点、Kubernetes 组件和软件部署的状态和进程。 +- 根据 Prometheus 收集的指标定义告警。 +- 创建自定义 Grafana 仪表板。 +- 使用 Prometheus Alertmanager 通过电子邮件、Slack、PagerDuty 等配置告警通知。 +- 根据 Prometheus 收集的指标，将预先计算的、经常需要的，或计算成本高的表达式定义为新的时间序列。 +- 通过 Prometheus Adapter，将从 Prometheus 收集的指标公开给 Kubernetes Custom Metrics API，以便在 HPA 中使用。 + +## Monitoring 工作原理 + +有关监控组件如何协同工作的说明，请参阅 [Monitoring 工作原理](how-monitoring-works.md)。 + +## 默认组件和部署 + +### 内置仪表板 + +默认情况下，监控应用将 Grafana 仪表板（由 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) 项目策划）部署到集群上。 + +它还部署一个 Alertmanager UI 和一个 Prometheus UI。有关这些工具的更多信息，请参见[内置仪表板](built-in-dashboards.md)。 + +### 默认指标 Exporter + +默认情况下，Rancher Monitoring 会部署 Exporter（例如 [node-exporter](https://github.com/prometheus/node_exporter) 和 [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)）。 + +这些默认 Exporter 会自动从 Kubernetes 集群的所有组件（包括工作负载）中抓取 CPU 和内存的指标。 + +### 默认告警 + +Monitoring 应用会默认部署一些告警。要查看默认告警，请转到 [Alertmanager UI](built-in-dashboards.md#alertmanager-ui) 并单击**展开所有组**。 + +### Rancher UI 中公开的组件 + +有关 Rancher UI 中公开的监控组件列表，以及编辑它们的常见用例，请参阅[本节](how-monitoring-works.md#rancher-ui-中公开的组件)。 + +## RBAC + +有关配置 monitoring 访问权限的信息，请参阅[此页面](rbac-for-monitoring.md)。 + + +## 指南 + +- [启用 monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md) +- [卸载 monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md) +- [Monitoring 工作负载](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md) +- [自定义 Grafana 仪表板](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md) +- [持久化 Grafana 仪表板](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md) +- [调试高内存使用率](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) +- [迁移 Monitoring V1 到 V2](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.md) + +## 配置 + +### 在 Rancher 中配置 Monitoring 资源 + +此处的配置参考假设你已经熟悉 monitoring 组件的协同工作方式。如需更多信息，请参阅 [monitoring 的工作原理](how-monitoring-works.md)。 + +- [ServiceMonitor 和 PodMonitor](../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) +- [接收器](../../reference-guides/monitoring-v2-configuration/receivers.md) +- [路由](../../reference-guides/monitoring-v2-configuration/routes.md) +- [PrometheusRule](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md) +- [Prometheus](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md) +- [Alertmanager](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md) + +### 配置 Helm Chart 选项 + +有关 `rancher-monitoring` Chart 选项的更多信息，包括设置资源限制和请求的选项，请参阅 [Helm Chart 选项](../../reference-guides/monitoring-v2-configuration/helm-chart-options.md)。 + +## Windows 集群支持 + +如果 Monitoring 部署到 RKE1 Windows 集群，Monitoring V2 将自动部署 [windows-exporter](https://github.com/prometheus-community/windows_exporter) DaemonSet 并设置 ServiceMonitor，以从每个部署的 Pod 中收集指标。这将使用 `windows_` 指标填充 Prometheus，这些指标与 [node_exporter](https://github.com/prometheus/node_exporter) 为 Linux 主机导出的 `node_` 指标类似。 + +为了能够为 Windows 完全部署 Monitoring V2，你的所有 Windows 主机都必须至少具有 v0.1.0 的 [wins](https://github.com/rancher/wins) 版本。 + +有关如何在现有 Windows 主机上升级 wins 版本的更多信息，请参阅 [Windows 集群对 Monitoring V2 的支持](windows-support.md)。 + + +## 已知问题 + +有一个[已知问题](https://github.com/rancher/rancher/issues/28787#issuecomment-693611821)，即 K3s 集群需要的内存超过分配的默认内存。如果你在 K3s 集群上启用 Monitoring，将 `prometheus.prometheusSpec.resources.memory.limit` 设置为 2500 Mi，并将 `prometheus.prometheusSpec.resources.memory.request` 设置为 1750 Mi。 + +如需获取意见和建议，请参阅[调试高内存使用情况](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/about-the-api.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/about-the-api.md new file mode 100644 index 00000000000..78c59974cde --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/about-the-api.md @@ -0,0 +1,84 @@ +--- +title: API +--- + + + + + +## 如何使用 API + +API 有自己的用户界面，你可以从 Web 浏览器访问它。这是查看资源、执行操作以及查看等效 cURL 或 HTTP 请求和响应的一种简单的方法。要访问它： + + + + +1. 单击右上角的用户头像。 +1. 单击**账号 & API 密钥**。 +1. 在 **API 密钥**下，找到 **API 端点**字段并单击链接。该链接类似于 `https:///v3`，其中 `` 是 Rancher deployment 的完全限定域名。 + + + + +转到位于 `https:///v3` 的 URL 端点，其中 `` 是你的 Rancher deployment 的完全限定域名。 + + + + +## 认证 + +API 请求必须包含认证信息。认证是通过 [API 密钥](../user-settings/api-keys.md)使用 HTTP 基本认证完成的。API 密钥可以创建新集群并通过 `/v3/clusters/` 访问多个集群。[集群和项目角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)会应用于这些键，并限制账号可以查看的集群和项目以及可以执行的操作。 + +默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。有关如何使 API 令牌失效的详细信息，请参阅 [API 令牌](api-tokens.md)。 + +## 发出请求 + +该 API 通常是 RESTful 的，但是还具有多种功能。这些功能可以使客户端发现所有内容，因此可以编写通用客户端，而不必为每种资源编写特定代码。有关通用 API 规范的详细信息，请参阅[此处](https://github.com/rancher/api-spec/blob/master/specification.md)。 + +- 每种类型都有一个 Schema，这个 Schema 描述了以下内容： + - 用于获取此类资源集合的 URL + - 资源可以具有的每个字段及其类型、基本验证规则、是必填还是可选字段等 + - 在此类资源上可以执行的每个操作，以及它们的输入和输出（也作为 schema） + - 允许过滤的每个字段 + - 集合本身或集合中的单个资源可以使用的 HTTP 操作方法 + + +- 因此，你可以只加载 schema 列表并了解 API 的所有信息。实际上，这是 API 的 UI 工作方式，它不包含特定于 Rancher 本身的代码。每个 HTTP 响应中的 `X-Api-Schemas` 标头都会发送获取 Schemas 的 URL。你可以按照每个 schema 上的 `collection` 链接了解要在哪里列出资源，并在返回资源中的其他 `links` 中获取其他信息。 + +- 在实践中，你可能只想构造 URL 字符串。我们强烈建议将此限制为在顶层列出的集合 (`/v3/`)，或获取特定资源 (`/v3//`)。除此之外的任何内容都可能在将来的版本中发生更改。 + +- 资源之间相互之间有联系，称为链接（links）。每个资源都包含一个 `links` 映射，其中包含链接名称和用于检索该信息的 URL。同样，你应该 `GET` 资源并遵循 `links` 映射中的 URL，而不是自己构造这些字符串。 + +- 大多数资源都有操作（action），表示可以执行某个操作或改变资源的状态。要使用操作，请将 HTTP `POST` 请求发送到 `actions` 映射中你想要的操作的 URL。某些操作需要输入或生成输出，请参阅每种类型的独立文档或 schema 以获取具体信息。 + +- 要编辑资源，请将 HTTP `PUT` 请求发送到资源上的 `links.update` 链接，其中包含要更改的字段。如果链接丢失，则你无权更新资源。未知字段和不可编辑的字段将被忽略。 + +- 要删除资源，请将 HTTP `DELETE` 请求发送到资源上的 `links.remove` 链接。如果链接丢失，则你无权更新资源。 + +- 要创建新资源，HTTP `POST` 到 schema（即 `/v3/`）中的集合 URL。 + +## 过滤 + +你可以使用 HTTP 查询参数的公共字段在服务器端过滤大多数集合。`filters` 映射显示了可以过滤的字段，以及过滤后的值在你发起的请求中是什么。API UI 具有设置过滤和显示适当请求的控件。对于简单的 "equals" 匹配，它只是 `field=value`。你可以将修饰符添加到字段名称，例如 `field_gt=42` 表示“字段大于 42”。详情请参阅 [API 规范](https://github.com/rancher/api-spec/blob/master/specification.md#filtering)。 + +## 排序 + +你可以使用 HTTP 查询参数的公共字段在服务器端排序大多数集合。`sortLinks` 映射显示了可用的排序，以及用于获取遵循该排序的集合的 URL。它还包括当前响排序依据的信息（如果指定）。 + +## 分页 + +默认情况下，API 响应以每页 100 个资源的限制进行分页。你可以通过 `limit` 查询参数进行更改，最大为 1000，例如 `/v3/pods?limit=1000`。集合响应中的 `pagination` 映射能让你知道你是否拥有完整的结果集，如果没有，则会指向下一页的链接。 + +## 捕获 Rancher API 调用 + +你可以使用浏览器开发人员工具来捕获 Rancher API 的调用方式。例如，你可以按照以下步骤使用 Chrome 开发人员工具来获取用于配置 RKE 集群的 API 调用： + +1. 在 Rancher UI 中，转到**集群管理**并单击**创建**。 +1. 单击某个集群类型。此示例使用 Digital Ocean。 +1. 使用集群名称和节点模板填写表单，但不要单击**创建**。 +1. 在创建集群之前，你需要打开开发人员工具才能看到正在记录的 API 调用。要打开工具，右键单击 Rancher UI，然后单击**检查**。 +1. 在开发者工具中，单击 **Network** 选项卡。 +1. 在 **Network** 选项卡上，确保选择了 **Fetch/XHR**。 +1. 在 Rancher UI 中，单击**创建**。在开发者工具中，你应该会看到一个名为 `cluster?_replace=true` 的新网络请求。 +1. 右键单击 `cluster?_replace=true` 并单击**复制 > 复制为 cURL**。 +1. 将结果粘贴到文本编辑器中。你将能够看到 POST 请求，包括被发送到的 URL、所有标头以及请求的完整正文。此命令可用于从命令行创建集群。请注意，请求包含凭证，因此请将请求存储在安全的地方。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/api-tokens.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/api-tokens.md index 24aa62e782c..6ff249f6b54 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/api-tokens.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/about-the-api/api-tokens.md @@ -2,6 +2,10 @@ title: API 令牌 --- + + + + 默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。令牌不会因为更改密码而失效。 要停用 API 令牌，你可以删除令牌或停用用户账号。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/backup-restore-configuration/backup-restore-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/backup-restore-configuration/backup-restore-configuration.md new file mode 100644 index 00000000000..6fbc1f202af --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/backup-restore-configuration/backup-restore-configuration.md @@ -0,0 +1,12 @@ +--- +title: Rancher 备份配置参考 +--- + + + + + +- [备份配置](backup-configuration.md) +- [还原配置](restore-configuration.md) +- [存储位置配置](storage-configuration.md) +- [Backup 和 Restore 自定义资源示例](examples.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/best-practices.md new file mode 100644 index 00000000000..11f4ee82e41 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/best-practices.md @@ -0,0 +1,21 @@ +--- +title: 最佳实践 +--- + + + + + +本节介绍 Rancher 实现的最佳实践，其中包括对 Kubernetes、Docker、容器等技术的使用建议。最佳实践旨在利用 Rancher 及其客户的运营经验，助你更好地实现 Rancher。 + +如果你对用例的实际应用有任何疑问，请联系客户成功经理或支持中心。 + +你可以在左侧导航栏快速找到管理和部署 Rancher Server 的最佳实践。 + +如需查看更多最佳实践指南，请参见： + +- [安全类文档](../rancher-security/rancher-security.md) +- [Rancher 博客](https://www.suse.com/c/rancherblog/) +- [Rancher 论坛](https://forums.rancher.com/) +- [Rancher 用户的 Slack 群组](https://slack.rancher.io/) +- [B 站](https://space.bilibili.com/430496045/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md new file mode 100644 index 00000000000..e12f1db2498 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md @@ -0,0 +1,23 @@ +--- +title: Rancher 管理集群的最佳实践 +--- + + + + + +### Logging + +有关集群级别日志和应用日志的建议，请参见 [Logging 最佳实践](logging-best-practices.md)。 + +### Monitoring + +配置合理的监控和告警规则对于安全、可靠地运行生产环境中的工作负载至关重要。有关更多建议，请参阅[最佳实践](monitoring-best-practices.md)。 + +### 设置容器的技巧 + +配置良好的容器可以极大地提高环境的整体性能和安全性。有关容器设置的建议，请参见[设置容器的技巧](tips-to-set-up-containers.md)。 + +### Rancher 管理 vSphere 集群的最佳实践 + +[Rancher 管理 vSphere 集群的最佳实践](rancher-managed-clusters-in-vsphere.md)概述了在 vSphere 环境中配置下游 Rancher 集群的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/rancher-server.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/rancher-server.md new file mode 100644 index 00000000000..d297b395a0a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/rancher-server.md @@ -0,0 +1,21 @@ +--- +title: Rancher Server 的最佳实践 +--- + + + + + +本指南介绍了让 Rancher 管理下游 Kubernetes 集群的 Rancher Server 运行建议。 + +### 推荐的架构和基础设施 + +有关在高可用 Kubernetes 集群上设置 Rancher Server 的通用建议，请参见[本指南](tips-for-running-rancher.md)。 + +### 部署策略 + +[本指南](rancher-deployment-strategy.md)旨在帮助你选择部署策略（区域部署/中心辐射型部署），来让 Rancher Server 更好地管理下游 Kubernetes 集群。 + +### 在 vSphere 环境中安装 Rancher + +[本指南](on-premises-rancher-in-vsphere.md)介绍了在 vSphere 环境中安装 Rancher 的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md new file mode 100644 index 00000000000..616d007e115 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md @@ -0,0 +1,117 @@ +--- +title: Rancher 大规模部署的调优和最佳实践 +--- + + + + + +本指南介绍了扩容 Rancher 相关场景的最佳实践和调优方法。随着系统规模的不断增长，性能自然会降低，但是可以采取一些步骤将 Rancher 的负载最小化，以优化 Rancher 管理较大基础设施的能力。 + +## 优化 Rancher 性能 + +* 及时升级 Rancher 的 Patch 更新。我们会不断的对 Rancher 进行性能增强和错误修复，最新的 Rancher 版本包含了基于开发人员和用户反馈的所有性能和稳定性的优化改进。 +* 逐渐的执行扩容操作，在操作的过程中观察并监控任何变化，在性能刚出现异常时发现问题并修复，避免其他干扰因素。 +* 尽可能地减少上游 Rancher 集群和下游集群之间的网络延时。需要注意的是，排除掉其他因素，延时与地理距离成正比，如果你的集群或节点分布在全球各地，请考虑改为安装多个 Rancher。 + +## 最小化上游集群的负载 + +在 Rancher 扩容时，一个典型的性能瓶颈是上游（local）Kubernetes 集群的资源增长。上游集群包含所有下游集群的数据信息，许多对下游集群的操作会在上游集群中创建新的对象，并需要在上游集群中进行计算处理。 + +### 最大限度地减少上游集群上的第三方软件 + +大规模运行 Rancher 可能会给内部 Kubernetes 组件（例如 `etcd` 或 `kubeapiserver`）带来大量负载。如果第三方软件干扰了这些组件或 Rancher 的性能，则可能会出现性能问题。 + +每个第三方软件都存在干扰性能的风险。为了防止上游集群出现性能问题，你应该避免运行除 Kubernetes 系统组件和 Rancher 本身之外的任何应用程序或组件。 + +以下类别的软件通常不会干扰 Rancher 或 Kubernetes 系统性能： + * Rancher 内部组件，例如 Fleet + * Rancher 扩展 + * 集群 API 组件 + * CNI 网络插件 + * 云控制器管理器 + * 观察和监控工具（`prometheus-rancher-exporter` 除外） + +除此之外，已发现以下软件会在 Rancher 扩容时影响性能： + * [CrossPlane](https://www.crossplane.io/) + * [Argo CD](https://argoproj.github.io/cd/) + * [Flux](https://fluxcd.io/) + * [prometheus-rancher-exporter](https://github.com/David-VTUK/prometheus-rancher-exporter)（请参阅 [issue 33](https://github.com/David-VTUK/prometheus-rancher-exporter/issues/33)） + +### 管理你的 Object 计数 + +Etcd 是 Kubernetes 和 Rancher 的后端数据库，该数据库可能会遇到单个 Kubernetes 资源类型数量的限制，确切的限制因素各不相同，取决于诸多因素。经验表明，一旦单个资源类型的对象数量超过 60000，通常会出现性能问题，通常该资源类型是 RoleBinding 对象。 + +这在 Rancher 中很常见，因为许多操作会在上游集群中创建新的 RoleBinding 对象。 + +你可以通过以下方法减少上游集群的 `RoleBinding` 数量： +* 减少使用 [Restricted Admin（受限管理员）](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#受限管理员) 角色，改为使用其他角色。 +* 如果你使用了 [外部认证](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)，配置其按组分配角色。 +* 仅在必要情况下将用户添加到集群和项目中。 +* 移除不需要的集群和项目。 +* 仅在必要情况下使用自定义角色。 +* 在自定义角色中，尽可能的减少规则数量。 +* 避免为用户添加多余的角色。 +* 考虑使用数量更少，但性能更强大的集群。 +* Kubernetes 权限始终是 “附加”（允许列表）而不是“减去”（拒绝列表）。尽量减少允许访问集群、项目或命名空间等方面的配置，因为这将导致创建大量的 RoleBinding 对象。 +* 实验一下，创建新项目或集群后，在你的特定用例场景是否表现出更少的 RoleBinding 的效果。 + +### RoleBinding 计数估计 + +预测给定的配置将创建多少个 RoleBinding 对象很复杂，但是以下注意事项可以提供粗略的估算： +* 对于最小的数量估计，请使用公式 `32C + U + 2UaC + 8P + 5Pa`。 + * `C` 是集群数量。 + * `U` 是用户数量。 + * `Ua` 是集群中具有成员资格的用户的平均数量。 + * `P` 是项目总数。 + * `Pa` 是项目中具有成员资格的平均用户数。 +* 受限管理员角色（Restricted Admin）遵循不同的公式，因为具有此角色的每个用户都会额外产生至少 `7C + 2P + 2` 个 `RoleBinding` 对象。 +* `RoleBinding` 的数量会随着集群、项目和用户的数量线性增加。 + +### 使用新的应用代替旧版应用 + +Rancher 使用两个 Kubernetes 应用程序资源：`apps.projects.cattle.io` 和 `apps.cattle.cattle.io`。以`apps.projects.cattle.io` 为代表的旧版应用程序在低版本的 Cluster Manager UI 中引入，现已弃用。新的应用程序（由 `apps.catalog.cattle.io` 表示）可以在 Cluster Explorer UI 中安装部署。新的 `apps.cattle.cattle.io` 应用程序数据保存在下游集群中，这可以减少上游集群中的资源数量。 + +你应当删除 Cluster Manager UI 中遗留的所有旧版应用程序，并将其替换为 Cluster Explorer UI 中的应用程序。只在 Cluster Explorer UI 中创建任何新应用程序。 + +### 使用授权集群端点 (ACE) + +[授权集群端点](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点) (ACE) 提供了 Rancher 部署的 RKE、RKE2 和 K3s 集群的 Kubernetes API 访问。启用后，ACE 会为生成的 `kubeconfig` 文件配置直接访问下游集群 Endpoint，从而绕过 Rancher 代理。在可以直接访问下游集群 Kubernetes API 的场景下，可以减少 Rancher 负载。有关更多信息，请参阅[授权集群端点](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)配置说明。 + +### 减少 Event Handler 执行 + +Rancher 的大部分逻辑发生在 Event Handler 上。每当资源对象产生更新或 Rancher 启动时，这些资源对应的 Event Handler 都会执行。除此之外，它们会每隔 15 小时在 Rancher 计划的同步缓存时再运行一次，这可能会导致 Rancher 运行过程中出现大量性能消耗。可使用 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量禁用计划的 Handler 处理程序执行。如果每 15 小时出现一次性能资源高峰，此设置会有所帮助。 + +`CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 的值可被设置为以下内容，以逗号分隔。这些值代表了处理程序的种类，将处理程序添加到该变量会禁止其在定期的缓存重新同步过程中运行。 + +* `mgmt`：在 Rancher 节点上运行的 Management 管理控制器。 +* `user`：所有集群运行的用户控制器。其中一部分与 Management 管理控制器运行在同一节点上，而另一部分运行在下游集群中，该选项针对的是前者。 +* `scaled`：每个 Rancher 节点上运行的规模控制器。因规模控制器负责关键功能，应当避免设置此值。如果设置可能会破坏集群稳定。 + +简而言之，如果你发现 CPU 使用率每 15 小时出现一次峰值，请将 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量添加到 Rancher Deployment 中（添加至 `spec.containers.env` 列表），其值为 `mgmt,user`。 + +## Rancher 之外的优化 + +集群底层自身的配置也是影响性能的重要因素。如果上游集群存在错误配置，会带来 Rancher 软件所无法解决的性能瓶颈。 + +### 使用 RKE2 直接管理上游集群节点 + +由于 Rancher 对上游集群的要求非常高，尤其是在大规模部署场景，你需要拥有上游集群和节点的所有管理员权限，要找出资源消耗过高的根本原因，请使用标准的 Linux 故障排除工具，这有助于区分是 Rancher、Kubernetes 还是操作系统组件出现的问题。 + +尽管托管 Kubernetes 服务使部署和运行 Kubernetes 集群变得更加容易，但在大规模场景中，不鼓励将其用于上游集群。 托管 Kubernetes 服务通常会限制对单个节点和服务配置的访问。 + +建议在大规模用例场景中使用 RKE2 集群。 + +### 及时更新 Kubernetes 版本 + +你应当及时更新上游集群的 Kubernetes 版本，以确保你的集群具备最新的性能增强和问题修复。 + +### 优化 Etcd + +Etcd 是 Kubernetes 和 Rancher 的后端数据库，在 Rancher 性能中扮演重要的角色。 + +[Etcd 性能](https://etcd.io/docs/v3.4/op-guide/performance/)的两个主要瓶颈是磁盘和网络速度。Etcd 应当在具有高速网络和高读写速度 (IOPS) SSD 硬盘的专用节点上运行。有关 etcd 性能的更多信息，请参阅 [etcd 性能缓慢（性能测试和优化）](https://www.suse.com/support/kb/doc/?id=000020100)和[为大型安装进行 etcd 调优](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md)。有关磁盘的信息可以在[安装要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#磁盘)中找到。 + +根据 etcd 的[复制机制](https://etcd.io/docs/v3.5/faq/#what-is-maximum-cluster-size)，建议在三个节点上运行 etcd，运行在更多的节点上反而会降低速度。 + +Etcd 性能也会受节点之间的网络延迟影响，因此 etcd 节点应与 Rancher 节点部署在一起。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/cli-with-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/cli-with-rancher.md new file mode 100644 index 00000000000..51f50ec2dca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/cli-with-rancher.md @@ -0,0 +1,9 @@ +--- +title: Rancher CLI +--- + + + + + +Rancher CLI 是一个命令行工具，用于在工作站中与 Rancher 进行交互。以下文档将描述 [Rancher CLI](rancher-cli.md) 和 [kubectl实用程序](kubectl-utility.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/kubectl-utility.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/kubectl-utility.md index 62377d846c6..cd311579a24 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/kubectl-utility.md @@ -2,6 +2,10 @@ title: kubectl 实用程序 --- + + + + ## kubectl kubectl 用于与 Rancher 进行交互。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/rancher-cli.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/rancher-cli.md index 03c9137205e..86d0f053092 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/rancher-cli.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cli-with-rancher/rancher-cli.md @@ -3,6 +3,10 @@ title: Rancher CLI description: Rancher CLI 是一个命令行工具，用于在工作站中与 Rancher 进行交互。 --- + + + + Rancher CLI（命令行界面）是一个命令行工具，可用于与 Rancher 进行交互。使用此工具，你可以使用命令行而不用通过 GUI 来操作 Rancher。 ### 下载 Rancher CLI diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/cluster-configuration.md new file mode 100644 index 00000000000..99fd92c6ae4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/cluster-configuration.md @@ -0,0 +1,32 @@ +--- +title: 集群配置 +--- + + + + + +使用 Rancher 配置 Kubernetes 集群后，你仍然可以编辑集群的选项和设置。 + +有关编辑集群成员资格的信息，请转至[此页面](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md)。 + +### 集群配置参考 + +集群配置选项取决于 Kubernetes 集群的类型： + +- [RKE 集群配置](rancher-server-configuration/rke1-cluster-configuration.md) +- [RKE2 集群配置](rancher-server-configuration/rke2-cluster-configuration.md) +- [K3s 集群配置](rancher-server-configuration/k3s-cluster-configuration.md) +- [EKS 集群配置](rancher-server-configuration/eks-cluster-configuration.md) +- [GKE 集群配置](rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md) +- [AKS 集群配置](rancher-server-configuration/aks-cluster-configuration.md) + +### 不同类型集群的管理功能 + +对于已有集群而言，可提供的选项和设置取决于你配置集群的方法。 + +下表总结了每一种类型的集群和对应的可编辑的选项和设置： + +import ClusterCapabilitiesTable from '../../shared-files/_cluster-capabilities-table.md'; + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md new file mode 100644 index 00000000000..c3482cad893 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md @@ -0,0 +1,9 @@ +--- +title: 下游集群配置 +--- + + + + + +以下文档将讨论[节点模板配置](node-template-configuration/node-template-configuration.md)和[主机配置](machine-configuration/machine-configuration.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md new file mode 100644 index 00000000000..7669ec23377 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md @@ -0,0 +1,9 @@ +--- +title: 主机配置 +--- + + + + + +主机配置指的是如何将资源分配给虚拟机。请参阅 [Amazon EC2](amazon-ec2.md)、[DigitalOcean](digitalocean.md) 和 [Azure](azure.md) 的文档以了解更多信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md new file mode 100644 index 00000000000..35779a5d3ae --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md @@ -0,0 +1,9 @@ +--- +title: 节点模板配置 +--- + + + + + +要了解节点模板配置，请参阅[EC2 节点模板配置](amazon-ec2.md)、[DigitalOcean 节点模板配置](digitalocean.md)、[Azure 节点模板配置](azure.md)、[vSphere 节点模板配置](vsphere.md)和 [Nutanix 节点模板配置](nutanix.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md new file mode 100644 index 00000000000..80081aefe75 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -0,0 +1,324 @@ +--- +title: GKE 集群配置参考 +--- + + + + + +## Rancher 2.6 变更 + +- 支持额外的配置选项： + - 项目网络隔离 + - 网络标签 + +## 集群位置 + +| 值 | 描述 | +|--------|--------------| +| 位置类型 | 地区 (zone) 或区域 (region)。借助 GKE，你可以根据工作负载的可用性要求和预算创建一个量身定制的集群。默认情况下，集群的节点在单个计算区域中运行。选择多个区域时，集群的节点将跨越多个计算区域，而 controlplane 则只位于单个区域中。区域集群也增加了 controlplane 的可用性。有关选择集群可用性类型的帮助，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane)。 | +| 地区 | 计算引擎中的每个区域都包含多地区。有关可用区域和可用区的更多信息，请参阅[这些文档](https://cloud.google.com/compute/docs/regions-zones#available)。 | +| 其他地区 | 对于地区性集群，你可以选择其他地区来创建[多地区集群](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters)。 | +| 区域 | 对于[区域性集群](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters)，你可以选择一个区域。有关可用区域和可用区的更多信息，请参阅[本节](https://cloud.google.com/compute/docs/regions-zones#available)。地区名称的前面部分是区域的名称。 | + +## 集群选项 + +### Kubernetes 版本 + +_可变：是_ + +有关 GKE Kubernetes 版本的更多信息，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/versioning)。 + +### 容器地址范围 + +_可变：否_ + +集群中 Pod 的 IP 地址范围。必须是有效的 CIDR 范围，例如 10.42.0.0/16。如果未指定，则会自动从 10.0.0.0/8 中选择一个随机范围，并排除已分配给 VM、其他集群或路由的范围。自动选择的范围可能与预留的 IP 地址、动态路由或与集群对等的 VPC 中的路由发生冲突。 + +### 网络 + +_可变：否_ + +集群连接的 Compute Engine 网络。将使用此网络创建路由和防火墙。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，与你的项目共享的 VPC 网络将显示在此处。你将可以在此字段中进行选择。有关详细信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### 节点子网/子网 + +_可变：否_ + +集群连接到的 Compute Engine 子网。该子网必须属于**网络**字段中指定的网络。选择一个现有的子网，或选择“自动创建子网”来自动创建一个子网。如果不使用现有网络，则需要使用**子网名称**来生成一个。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，与你的项目共享的 VPC 子网将显示在此处。如果使用共享 VPC 网络，则无法选择“自动创建子网”。如需更多信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### 子网名称 + +_可变：否_ + +使用提供的名称自动创建子网。如果为**节点子网**或**子网**选择了“自动创建子网”，则为必填。有关子网的更多信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### IP 别名 + +_可变：否_ + +启用[别名 IP](https://cloud.google.com/vpc/docs/alias-ip)。这将启用 VPC 原生流量路由。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，则为必填。 + +### 网络策略 + +_可变：是_ + +在集群上启用的网络策略。网络策略定义了集群中 pod 和 service 之间可以发生的通信级别。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy)。 + +### 项目网络隔离 + +_可变：是_ + +选择启用或禁用项目间通信。请注意，如果启用**项目网络隔离**，则将自动启用**网络策略**和**网络策略配置**，反之则不然。 + +### 节点 IPv4 CIDR 块 + +_可变：否_ + +此集群中实例 IP 的 IP 地址范围。如果为**节点子网**或**子网**选择了“自动创建子网”，则可以进行设置。必须是有效的 CIDR 范围，例如 10.96.0.0/14。有关如何确定 IP 地址范围的详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing)。 + +### 集群次要范围名称 + +_可变：否_ + +Pod IP 地址的现有次要范围的名称。如果选中，将自动填充**集群 Pod 地址范围**。如果使用共享 VPC 网络，则为必填。 + +### 集群 Pod 地址范围 + +_可变：否_ + +分配给集群中 pod 的 IP 地址范围。必须是有效的 CIDR 范围，例如 10.96.0.0/11。如果未提供，将自动创建。如果使用共享 VPC 网络，则必须提供。有关如何确定 pod 的 IP 地址范围的更多信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_pods)。 + +### Service 次要范围名称 + +_可变：否_ + +Service IP 地址的现有次要范围的名称。如果选中，将自动填充 **Service 地址范围**。如果使用共享 VPC 网络，则为必填。 + +### Service 地址范围 + +_可变：否_ + +分配给集群中 Service 的地址范围。必须是有效的 CIDR 范围，例如 10.94.0.0/18。如果未提供，将自动创建。如果使用共享 VPC 网络，则必须提供。有关如何确定 Service 的 IP 地址范围的详细信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_svcs)。 + +### 私有集群 + +_可变：否_ + +:::caution + +私有集群需要在 Rancher 之外进行额外的规划和配置。请参阅[私有集群指南](gke-private-clusters.md)。 + +::: + +仅分配节点内部 IP 地址。除非在 GCP 中执行了额外的联网步骤，否则私有集群节点无法访问公共互联网。 + +### 启用私有端点 + +:::caution + +私有集群需要在 Rancher 之外进行额外的规划和配置。请参阅[私有集群指南](gke-private-clusters.md)。 + +::: + +_可变：否_ + +锁定对 controlplane 端点的外部访问。仅当**私有集群**也被选中时可用。如果选中，并且 Rancher 无法直接访问集群所在的虚拟私有云网络，Rancher 将提供在集群上运行的注册命令，以使 Rancher 能够连接到集群。 + +### 主 IPV4 CIDR 块 + +_可变：否_ + +controlplane VPC 的 IP 范围。 + +### 主授权网络 + +_可变：是_ + +启用 controlplane 授权网络，以阻止不受信任的非 GCP 源 IP 通过 HTTPS 访问 Kubernetes master。如果选择，则可以添加额外的授权网络。如果集群是使用公共端点创建的，则此选项可用于将公共端点的访问锁定到特定网络（例如运行 Rancher 服务的网络）。如果集群只有一个私有端点，则需要此设置。 + +## 其他选项 + +### 集群插件 + +其他 Kubernetes 集群组件。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster.AddonsConfig)。 + +#### 水平 Pod 自动缩放 + +_可变：是_ + +Horizo​​ntal Pod Autoscaler 通过自动增加或减少 Pod 的数量来调整 Kubernetes 工作负载，从而响应工作负载的 CPU 或内存消耗，以及 Kubernetes 内部报告的自定义指标或集群外部设置的指标。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler)。 + +#### HTTP (L7) 负载均衡 + +_可变：是_ + +HTTP (L7) 负载均衡将 HTTP 和 HTTPS 流量分配到托管在 GKE 上的后端。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer)。 + +#### 网络策略配置（仅限 master） + +_可变：是_ + +NetworkPolicy 的配置。仅跟踪 master 节点上是否启用了插件，不跟踪是否为节点启用了网络策略。 + +### 集群特征（Alpha 功能） + +_可变：否_ + +打开集群的所有 Kubernetes alpha API 组和功能。启用后，集群无法升级，并且会在 30 天后自动删除。由于 GKE SLA 未支持 alpha 集群，因此不建议将 Alpha 集群用于生产环境。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters)。 + +### Logging 服务 + +_可变：是_ + +集群用于写入日志的日志管理服务。要么使用 [Cloud Logging](https://cloud.google.com/logging)，要么不使用日志管理服务（不会从集群中导出日志）。 + +### 监控服务 + +_可变：是_ + +集群用于写入指标的监控服务。要么使用 [Cloud Monitoring](https://cloud.google.com/monitoring)，要么不使用集群监控服务（不会从集群中导出指标）。 + + +### 维护窗口 + +_可变：是_ + +设置时长 4 小时的维护窗口的开始时间。使用 HH:MM 格式在 UTC 时区中指定时间。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions)。 + +## 节点池 + +在此部分中，输入描述节点池中每个节点的配置的详细信息。 + +### Kubernetes 版本 + +_可变：是_ + +节点池中每个节点的 Kubernetes 版本。有关 GKE Kubernetes 版本的更多信息，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/versioning)。 + +### 镜像类型 + +_可变：是_ + +节点操作系统镜像。有关 GKE 为每个操作系统提供的节点镜像选项，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images)。 + +:::note + +默认选项是 “Container-Optimized OS with Docker”。GCP Container-Optimized OS 上的只读文件系统与 Rancher 中的 [legacy logging](/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) 实现不兼容。如果你需要使用旧版日志管理功能，请选择 “Ubuntu with Docker” 或 “Ubuntu with Containerd”。[current logging feature](../../../../integrations-in-rancher/logging/logging.md) 与 Container-Optimized OS 镜像兼容。 + +::: + +:::note + +如果节点池镜像类型选择 “Windows Long Term Service Channel” 或 “Windows Semi-Annual Channel”，还必须至少添加一个 Container-Optimized OS 或 Ubuntu 节点池。 + +::: + +### 主机类型 + +_可变：否_ + +节点实例可用的虚拟化硬件资源。有关 Google Cloud 主机类型的详细信息，请参阅[此页面](https://cloud.google.com/compute/docs/machine-types#machine_types)。 + +### 根磁盘类型 + +_可变：否_ + +标准永久性磁盘由标准磁盘驱动器 (HDD) 支持，而 SSD 永久性磁盘由固态硬盘 (SSD) 支持。有关详细信息，请参阅[本节](https://cloud.google.com/compute/docs/disks)。 + +### 本地 SSD 磁盘 + +_可变：否_ + +配置每个节点的本地 SSD 磁盘存储（以 GB 为单位）。本地 SSD 物理连接到托管你的 VM 实例的服务器。与标准永久性磁盘或 SSD 永久性磁盘相比，本地 SSD 具有更高的吞吐量和更低的延迟。存储在本地 SSD 上的数据只会保留到实例停止或删除。有关详细信息，请参阅[本节](https://cloud.google.com/compute/docs/disks#localssds)。 + +### 抢占式节点（beta） + +_可变：否_ + +抢占式节点也称为抢占式虚拟机。通常是最长持续 24 小时的 Compute Engine 虚拟机实例，不提供可用性保证。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms)。 + +### 污点 + +_可变：否_ + +将污点应用于节点时，仅允许容忍该污点的 Pod 在该节点上运行。在 GKE 集群中，你可以将污点应用到节点池，这会将污点应用到池中的所有节点。 + +### 节点标签 + +_可变：否_ + +你可以将标签应用到节点池，这会将标签应用到池中的所有节点。 + +无效标签会阻止升级，或阻止 Rancher 启动。有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +### 网络标签 + +_可变：否_ + +你可以将网络标签添加到节点池以制定防火墙规则和子网之间的路由。标签将应用于池中的所有节点。 + +有关标签语法和要求的详细信息，请参阅 [Kubernetes 文档](https://cloud.google.com/vpc/docs/add-remove-network-tags)。 + +## 组详细信息 + +在此部分中，输入描述节点池的详细信息。 + +### 名称 + +_可变：否_ + +输入节点池的名称。 + +### 初始节点数 + +_可变：是_ + +节点池中初始节点数的整数。 + +### 每个节点的最大 Pod 数量 + +_可变：否_ + +GKE 的硬性限制是每个节点 110 个 Pod。有关 Kubernetes 限制的更多信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#dimension_limits)。 + +### 自动缩放 + +_可变：是_ + +节点池自动缩放会根据工作负载的需求动态创建或删除节点。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-autoscaler)。 + +### 自动修复 + +_可变：是_ + +GKE 的节点自动修复功能可帮助你将集群中的节点保持在健康的运行状态。启用后，GKE 会定期检查集群中每个节点的运行状况。如果某个节点在较长时间段内连续未通过健康检查，GKE 会为该节点启动修复过程。有关详细信息，请参阅[自动修复节点](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair)。 + +### 自动升级 + +_可变：是_ + +启用后，当你的 controlplane [按照你的需求更新](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades)时，自动升级功能会使集群中的节点与集群 controlplane（master）版本保持同步。有关自动升级节点的更多信息，参见[此页面。](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) + +### 访问范围 + +_可变：否_ + +设置访问范围是为你的节点指定权限的旧版方法。 + +- **允许默认访问**：新集群的默认访问是 [Compute Engine 默认 ServiceAccount](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account)。 +- **允许完全访问所有 Cloud API**：通常，你只需设置云平台访问范围来允许完全访问所有 Cloud API，然后仅授予 ServiceAccount 相关的 IAM 角色。授予虚拟机实例的访问范围和授予 ServiceAccount 的 IAM 角色的组合决定了 ServiceAccount 对该实例的访问量。 +- **为每个 API 设置访问权限**：或者，你可以设置服务将调用的特定 API 方法的访问范围。 + +有关详细信息，请参阅[为 VM 启用 ServiceAccount](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)。 + + +### 配置刷新间隔 + +刷新间隔可以通过 “gke-refresh” 来配置，它是一个代表秒的整数。 + +默认值为 300 秒。 + +你可以通过运行 `kubectl edit setting gke-refresh` 来更改同步间隔。 + +刷新窗口越短，争用条件发生的可能性就越小。但这确实增加了遇到 GCP API 可能存在的请求限制的可能性。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md new file mode 100644 index 00000000000..4efbf1bb06b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md @@ -0,0 +1,16 @@ +--- +title: Rancher Server 配置 +--- + + + + + +- [RKE1 集群配置](rke1-cluster-configuration.md) +- [RKE2 集群配置](rke2-cluster-configuration.md) +- [K3s 集群配置](k3s-cluster-configuration.md) +- [EKS 集群配置](eks-cluster-configuration.md) +- [AKS 集群配置](aks-cluster-configuration.md) +- [GKE 集群配置](gke-cluster-configuration/gke-cluster-configuration.md) +- [使用现有节点](use-existing-nodes/use-existing-nodes.md) +- [同步集群](sync-clusters.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md new file mode 100644 index 00000000000..ab39f7867b0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md @@ -0,0 +1,141 @@ +--- +title: 在现有自定义节点上启动 Kubernetes +description: 要创建具有自定义节点的集群，你需要访问集群中的服务器，并根据 Rancher 的要求配置服务器。 +--- + + + + + +创建自定义集群时，Rancher 使用 RKE（Rancher Kubernetes Engine）在本地裸机服务器、本地虚拟机或云服务器节点中创建 Kubernetes 集群。 + +要使用此选项，你需要访问要在 Kubernetes 集群中使用的服务器。请根据[要求](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)配置每台服务器，其中包括硬件要求和 Docker 要求。在每台服务器上安装 Docker 后，你还需要在每台服务器上运行 Rancher UI 中提供的命令，从而将每台服务器转换为 Kubernetes 节点。 + +本节介绍如何设置自定义集群。 + +## 使用自定义节点创建集群 + +:::note 使用 Windows 主机作为 Kubernetes Worker 节点？ + +在开始之前，请参阅[配置 Windows 自定义集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 + +::: + +### 1. 配置 Linux 主机 + +你可以通过配置 Linux 主机，来创建自定义集群。你的主机可以是： + +- 云虚拟机 +- 本地虚拟机 +- 裸机服务器 + +如果要重复使用之前的自定义集群中的节点，请在复用之前[清理节点](../../../../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md)。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +根据[安装要求](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)和[生产就绪集群的检查清单](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md)配置主机。 + +如果你使用 Amazon EC2 作为主机，并希望使用[双栈 (dual-stack)](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) 功能，则需要满足配置主机的其他[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + +### 2. 创建自定义集群 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击**自定义**。 +1. 输入**集群名称**。 +1. 在**集群配置**中，选择 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。 + + :::note 你使用 Windows 主机作为 Kubernetes Worker 节点？ + + - 请参阅[启用 Windows 支持选项](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 + - 支持 Windows 集群的唯一网络插件是 Flannel。 + + ::: + + :::note Amazon EC2 上的双栈： + + 如果你使用 Amazon EC2 作为主机，并希望使用[双栈 (dual-stack)](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) 功能，则需要满足配置 RKE 的其他[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + + ::: + +6. 点击**下一步**。 + +4. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 + +7. 从**节点角色**中，选择要由集群节点充当的角色。你必须为 `etcd`、`worker` 和 `controlplane` 角色配置至少一个节点。自定义集群需要所有三个角色才能完成配置。有关角色的详细信息，请参阅[本节](../../../kubernetes-concepts.md#kubernetes-集群中节点的角色)。 + +:::note + +- 使用 Windows 主机作为 Kubernetes Worker 节点？请参阅[本节](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 +- 裸机服务器提醒：如果你想将裸机服务器专用于每个角色，则必须为每个角色配置一个裸机服务器（即配置多个裸机服务器）。 + +::: + +8. **可选**：点击[显示高级选项](rancher-agent-options.md)来指定注册节点时使用的 IP 地址，覆盖节点的主机名，或将[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)或[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)添加到节点。 + +9. 将屏幕上显示的命令复制到剪贴板。 + +10. 使用你惯用的 shell（例如 PuTTy 或远程终端）登录到你的 Linux 主机。粘贴剪贴板的命令并运行。 + +:::note + +如果要将特定主机专用于特定节点角色，请重复步骤 7-10。根据需要多次重复这些步骤。 + +::: + +11. 在 Linux 主机上运行完命令后，单击**完成**。 + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +### 3. 仅限亚马逊：标签资源 + +如果你已将集群配置为使用 Amazon 作为**云提供商**，请使用集群 ID 标记你的 AWS 资源。 + +[Amazon 文档：标记你的 Amazon EC2 资源](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) + +:::note + +你可以使用 Amazon EC2 实例，而无需在 Kubernetes 中配置云提供商。如果你想使用特定的 Kubernetes 云提供商功能，配置云提供商即可。如需更多信息，请参阅 [Kubernetes 云提供商](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md)。 + +::: + +以下资源需要使用 `ClusterID` 进行标记： + +- **Nodes**：Rancher 中添加的所有主机。 +- **Subnet**：集群使用的子网。 +- **Security Group**：用于你的集群的安全组。 + +:::note + +不要标记多个安全组。创建 Elastic Load Balancer 时，标记多个组会导致错误。 + +::: + +应该使用的标签是： + +``` +Key=kubernetes.io/cluster/, Value=owned +``` + +`` 可以是你选择的任何字符串。但是，必须在你标记的每个资源上使用相同的字符串。将值设置为 `owned` 会通知集群所有带有 `` 标记的资源都由该集群拥有和管理。 + +如果你在集群之间共享资源，你可以将标签更改为： + +``` +Key=kubernetes.io/cluster/CLUSTERID, Value=shared +``` + +## 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md new file mode 100644 index 00000000000..ce8ca4671a4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md @@ -0,0 +1,15 @@ +--- +title: Monitoring 配置参考 +--- + + + + + +以下将说明在 Rancher 中如何配置 Monitoring V2 的基本重要选项： + +- [接收器配置](receivers.md) +- [路由配置](routes.md) +- [ServiceMonitor 和 PodMonitor 配置](servicemonitors-and-podmonitors.md) +- [Helm Chart 选项](helm-chart-options.md) +- [示例](examples.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/pipelines/pipelines.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/pipelines/pipelines.md new file mode 100644 index 00000000000..a9cbd188c64 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/pipelines/pipelines.md @@ -0,0 +1,278 @@ +--- +title: 流水线 +--- + +:::note 备注 + +- 从 Rancher v2.5 开始，基于 Git 部署的流水线现已弃用。我们建议使用由 [Fleet](../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md) 提供支持的 Rancher Continuous Delivery 来处理流水线。要访问 Rancher 中的 Fleet，请点击 ☰ > 持续交付。 + +- 流水线在 Kubernetes 1.21+ 中不再支持。 + +- Fleet 不会取代 Rancher 流水线，区别在于 Rancher 流水线现在由 Fleet 提供支持。 + +::: + +Rancher 的流水线提供了简单的 CI/CD 体验，但它不能替代企业级 Jenkins 或团队使用的其他 CI 工具，也不能提供全部的功能和灵活性。 + +设置流水线可以帮助开发人员尽可能快速高效地交付新软件。使用 Rancher，可以与 GitHub 存储库集成以设置持续集成（CI）流水线。 + +配置 Rancher 和 GitHub 后，你可以部署运行 Jenkins 的容器来自动执行流水线： + +- 使用代码构建应用程序镜像。 +- 验证你的构建。 +- 将构建镜像部署到集群。 +- 运行单元测试。 +- 运行回归测试。 + +:::note + +Rancher 的流水线提供了简单的 CI/CD 体验，但它不能替代企业级 Jenkins 或团队使用的其他 CI 工具，也不能提供全部的功能和灵活性。 + +::: + +## 概念 + +有关本节中使用的概念和术语的解释，请参阅[本页。](concepts.md) + +## 流水线如何工作 + +在项目中开启流水线后，可以在每个项目中配置多个流水线。每个流水线都是唯一的，可以独立配置。 + +流水线是根据签入源代码存储库的一组文件配置的。用户可以通过 Rancher UI 或在仓库中添加 `.rancher-pipeline.yml` 来配置他们的流水线。 + +在配置流水线之前，你需要配置对版本控制提供程序（例如 GitHub、GitLab、Bitbucket）的认证。如果尚未配置版本控制提供程序，则始终可以使用 [Rancher 的示例存储库](example-repositories.md)查看一些常见的流水线部署。 + +在其中一个项目中配置流水线时，将自动创建专门用于流水线的命名空间。将以下组件部署到其中： + +- **Jenkins:** + + 流水线的构建引擎。由于项目用户不直接与 Jenkins 交互，因此它是托管和锁定的。 + + :::note + + 无法使用现有 Jenkins deployments 作为流水线引擎。 + + ::: + +- **Docker Registry:** + + 开箱即用，生成-发布步骤的默认目标是内部 Docker Registry。但是，你可以进行配置以推送到远程 registry。内部 Docker Registry 只能从集群节点访问，用户无法直接访问。镜像不会在流水线的生存期之后保留，并且只能在流水线运行中使用。如果需要在流水线运行之外访问镜像，请推送到外部 registry。 + +- **Minio:** + + Minio 存储用于存储流水线执行的日志。 + +:::note + +托管的 Jenkins 实例以无状态方式工作，因此无需担心其数据持久性。默认情况下，Docker Registry 和 Minio 实例使用临时卷，这对于大多数用例来说都很好。如果要确保流水线日志能够在节点故障后继续运行，可以为它们配置持久卷，如[流水线组件的数据持久性](configure-persistent-data.md)中所述。 + +::: + +## 流水线基于角色的访问控制 + +如果可以访问项目，则可以使存储库开始构建流水线。 + +仅[管理员](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)，[集群所有者或成员](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles)，或[项目成员](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles)可以配置版本控制提供程序并管理全局流水线执行设置。 + +项目成员只能配置存储库和流水线。 + +## 设置流水线 + +### 先决条件 + +:::note legacy 功能标志： + +由于流水线应用程序已被弃用，取而代之的是 Fleet，因此你需要在使用流水线之前打开 legacy 功能的功能标志。 请注意，Kubernetes 1.21+ 中不再支持流水线。 + +1. 点击左上角 **☰ > 全局设置**。 +1. 点击 **功能开关**。 +1. 转到 `legacy` 功能标志并点击 **⋮ > 激活**。 + +::: + +1. [配置版本控制提供程序](#1-配置版本控制提供程序) +2. [配置存储库](#2-配置存储库) +3. [配置流水线](#3-配置流水线) + +### 1. 配置版本控制提供程序 + +在开始为存储库配置流水线之前，你必须配置并授权版本控制提供程序： + +- GitHub +- GitLab +- Bitbucket + +选择下面你的提供商的选项卡并按照说明进行操作。 + + + + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 点击 **配置** 选项卡。 +1. 按照显示的说明 **设置 Github 应用程序**。Rancher 会重定向到 Github，在 Github 中设置 OAuth 应用。 +1. 在 GitHub 中，复制 **Client ID** 和 **Client Secret**。将它们粘贴到 Rancher 中。 +1. 如果你使用的是 GitHub 企业版，请选择 **使用私有 github 企业版安装**。输入 GitHub 安装的主机地址。 +1. 点击 **认证**。 + + + + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 点击 **配置** 选项卡。 +1. 点击 **GitLab**。 +1. 按照显示的说明 **设置 GitLab 应用程序**。Rancher 会重定向到 GitLab。 +1. 从 GitLab 中复制 **Application ID** 和 **Secret**。将它们粘贴到 Rancher 中。 +1. 如果你使用的是 GitLab 企业版，请选择 **使用私有 gitlab 企业版安装**。输入 GitLab 安装的主机地址。 +1. 点击 **认证**。 + +:::note 备注： + +1.流水线使用 Gitlab [v4 API](https://docs.gitlab.com/ee/api/v3_to_v4.html)，支持的 Gitlab 版本为 9.0+。 2. 如果你使用的是 GitLab 10.7+，并且你的 Rancher 设置位于本地网络中，请在 GitLab 管理员设置中启用 **允许从钩子和服务向本地网络发出请求** 选项。 + +::: + + + + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 点击 **配置** 选项卡。 +1. 点击 **Bitbucket** 并默认选中 **使用 Bitbucket Cloud**。 +1. 按照显示的说明进行 **设置 Bitbucket Cloud 应用程序**。Rancher 会重定向到 Bitbucket，以便在 Bitbucket 中设置 OAuth 使用者。 +1. 从 Bitbucket 中，复制使用者 **Key** 和 **Secret**。将它们粘贴到 Rancher 中。 +1. 点击 **认证**。 + + + + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 点击 **配置** 选项卡。 +1. 点击 **Bitbucket** 并选择 **使用私有 Bitbucket Server 设置** 选项。 +1. 按照显示的说明进行 **设置 Bitbucket Server 应用程序**。 +1. 输入 Bitbucket Server 安装的主机地址。 +1. 点击 **认证**。 + +:::note + +Bitbucket server 在向 Rancher 发送 Webhook 时需要进行 SSL 验证。请确保 Rancher server 的证书是 Bitbucket server 信任的。有两种选择： + +1. 使用来自受信任 CA 的证书设置 Rancher server。 +1. 如果你使用的是自签名证书，请将 Rancher server 的证书导入 Bitbucket server。有关说明，请参阅[配置自签名证书](https://confluence.atlassian.com/bitbucketserver/if-you-use-self-signed-certificates-938028692.html)的 Bitbucket server 文档。 + +::: + + + + +**结果:** 对版本控制提供程序进行认证后，系统将自动重定向到开始配置要开始与流水线一起使用的存储库。 + +### 2. 配置存储库 + +在对版本控制提供程序进行授权后，系统会自动将你重定向到开始配置要开始使用流水线的存储库。即使其他人设置了版本控制提供程序，你也会看到他们的存储库，并可以生成流水线。 + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 点击 **配置** 选项卡。 + +1. 将显示存储库列表。如果你是第一次配置存储库，请单击 **授权并获取你自己的存储库** 来获取存储库列表。 + +1. 对于要设置流水线的每个存储库，单击 **启用**。 + +1. 完成所有存储库的启用后，点击 **完成**。 + +**结果:** 你有一个存储库列表，可以开始为其配置流水线。 + +### 3. 配置流水线 + +现在，存储库已添加到你的项目中，你可以通过添加自动化阶段和步骤来开始配置流水线。为方便起见，有多种内置步骤类型用于专用任务。 + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 找到要为其设置流水线的存储库。 +1. 通过 UI 或使用仓库中的 yaml 文件配置流水线，即 `.rancher-pipeline.yml` 或 `.rancher-pipeline.yaml`。流水线配置分为多个阶段和步骤。在进入下一阶段之前，阶段必须完全完成，但阶段中的步骤会同时运行。对于每个阶段，你可以添加不同的步骤类型。注意：在构建每个步骤时，根据步骤类型有不同的高级选项。高级选项包括触发规则、环境变量和密文。有关通过 UI 或 YAML 文件配置流水线的详细信息，请参阅[流水线配置参考。](pipeline-configuration.md) + + - 如果要使用 UI，请选择 **⋮ > 编辑配置** 以使用 UI 配置流水线。配置流水线后，必须查看 YAML 文件并将其推送到存储库。 + - 如果要使用 YAML 文件，请选择 **⋮ > 查看/编辑 YAML** 来配置流水线。如果选择使用 YAML 文件，则需要在进行任何更改后将其推送到存储库，以便在存储库中更新它。编辑流水线配置时，Rancher 需要一些时间来检查现有的流水线配置。 + +1. 从分支列表中选择要使用的`分支`。 + +1. 可选：设置通知。 + +1. 设置流水线的触发规则。 + +1. 输入流水线的 **超时**。 + +1. 配置完所有阶段和步骤后，单击 **完成**。 + +**结果:** 你的流水线已经配置完毕，可以运行了。 + +## 流水线配置参考 + +有关如何将流水线配置为以下的详细信息，请参阅[此页面](pipeline-configuration.md)： + +- 运行脚本 +- 构建和发布镜像 +- 发布 catalog 模板 +- 部署 YAML +- 部署 catalog app + +配置参考还介绍了如何配置： + +- 通知 +- 超时 +- 触发流水线的规则 +- 环境变量 +- 密文 + +## 运行流水线 + +首次运行流水线。找到流水线并选择 **⋮ > Run**。 + +在此初始运行期间，将测试流水线，并将以下流水线组件作为专用于流水线的新命名空间中的工作负载部署到项目中： + +- `docker-registry` +- `jenkins` +- `minio` + +此过程需要几分钟时间。完成后，可以从项目 **Workloads** 选项卡查看每个流水线组件。 + +## 触发流水线 + +启用存储库后，会在版本控制提供程序中自动设置 Webhook。默认情况下，流水线由存储库的 **push** 事件触发，但你可以修改触发运行流水线的事件。 + +可用事件： + +- **Push**: 每当提交推送到仓库中的分支时，都会触发流水线。 +- **Pull Request**: 每当向仓库发出拉取请求时，都会触发流水线。 +- **Tag**: 在仓库中创建标签时，会触发流水线。 + +:::note + +Rancher 的[示例存储库](example-repositories.md)不存在此选项。 + +::: + +### 修改存储库的事件触发器 + +1. 点击左上角 **☰ > 集群管理**。 +1. 进入要配置流水线的集群，然后点击 **浏览**。 +1. 在顶部导航栏的下拉菜单中，选择要配置流水线的项目。 +1. 在左侧导航栏中，点击 **Legacy > Project >流水线**。 +1. 找到要修改事件触发器的存储库。选择 **⋮ > Setting**. +1. 选择要为存储库触发的事件 (**Push**, **Pull Request** 或 **Tag**)。 +1. 点击 **保存**. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/prometheus-federator/prometheus-federator.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/prometheus-federator/prometheus-federator.md new file mode 100644 index 00000000000..557869c066f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/prometheus-federator/prometheus-federator.md @@ -0,0 +1,108 @@ +--- +title: Prometheus Federator +--- + + + + + +Prometheus Federator（也称为 Project Monitoring V2）基于 [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) 部署一个 Helm Project Operator。该 Operator 管理 Helm Chart 的部署，每个 Operator 都包含一个 Project Monitoring Stack，而每个堆栈都包含： + +- [Prometheus](https://prometheus.io/)（由 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 在外部管理） +- [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)（由 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 在外部管理） +- [Grafana](https://github.com/helm/charts/tree/master/stable/grafana)（通过嵌入式 Helm Chart 部署） +- 基于 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus/) 社区策划资源集合的默认 PrometheusRules 和 Grafana 仪表板 +- 监视已部署资源的默认 ServiceMonitor + +:::note 重要提示： + +Prometheus Federator 适合在已安装 Prometheus Operator CRD 的集群中与现有的 Prometheus Operator Deployment 一起部署。 + +::: + +## Operator 工作原理 + +1. 在部署此 Chart 时，用户可以创建 ProjectHelmCharts CR，并在**项目 Registration 命名空间 (`cattle-project-`)** 中将 `spec.helmApiVersion` 设置为 `monitoring.cattle.io/v1alpha1`（在 Rancher UI 中也称为“项目监控”）。 +2. 在看到每个 ProjectHelmChartCR 时，Operator 会代表项目所有者在**项目 Release 命名空间 (`cattle-project--monitoring`)** 中自动部署一个 Project Prometheus 堆栈（基于 ProjectHelmChart 控制器在 **Operator / System Namespace** 中创建的 HelmChart CR 和 HelmRelease CR）。 +3. RBAC 将自动分配到项目 Release 命名空间中，从而允许用户查看 Prometheus、Alertmanager 以及已部署的 Project Monitoring Stack 的 Grafana UI（基于在项目 Registration 命名空间上针对[面向用户的默认 Kubernetes 角色](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)定义的 RBAC）。有关详细信息，请参阅[配置 RBAC](rbac.md)。 + +### 什么是项目？ + +在 Prometheus Federator 中，项目是一组可以由 `metav1.LabelSelector` 标识的命名空间。默认情况下，用于标识项目的标签是 `field.cattle.io/projectId`，该标签用于标识给定 Rancher 项目中包含的命名空间。 + +### 配置由 ProjectHelmChart 创建的 Helm 版本 + +此 ProjectHelmChart 资源的 `spec.values` 对应于为底层 Helm Chart 配置的 `values.yaml` 覆盖，该 Helm Chart 是 Operator 代表用户部署的。要查看底层 Chart 的 `values.yaml` 规范，你可以选择以下其中一种方式： + +- 查看位于 [`charts/rancher-project-monitoring` 中的 `rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator/blob/main/charts/rancher-project-monitoring) 的 Chart 定义（Chart 版本会绑定到 Operator 版本）。 +- 查找在每个项目 Registration 命名空间中自动创建的名为 `monitoring.cattle.io.v1alpha1` 的 ConfigMap，其中包含用于配置 Chart（直接嵌入到 `prometheus-federator` 二进制文件中）的`values.yaml` 和 `questions.yaml`。 + +### 命名空间 + +Prometheus Federator 是基于 [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) 的 Project Operator，Prometheus Federator 提供了三类命名空间供 Operator 查找： + +1. **Operator / System 命名空间**：部署 Operator 的命名空间（例如 `cattle-monitoring-system`）。此命名空间将包含该 Operator 监视的所有 ProjectHelmChart 的所有 HelmChart 和 HelmRelease。**只有集群管理员才能访问此命名空间**。 + +2. **项目 Registration 命名空间 (`cattle-project-`)**：Operator 在这些命名空间中监视 ProjectHelmChart。对于在项目发布命名空​​间中创建的自动分配的 RBAC，应用于此命名空间的 RoleBinding 和 ClusterRoleBinding 也会作为 RBAC 的真实来源。有关详细信息，请参阅 [RBAC 页面](rbac.md)。**项目所有者（admin）、项目成员（edit）和只读成员（view）应该有权访问此命名空间。** + + :::note 注意事项： + + - 如果提供了 `.Values.global.cattle.projectLabel`（默认设置为 `field.cattle.io/projectId`），则 Operator 会自动生成项目注册命名空间，并将它导入到命名空间绑定的项目中。换言之，如果观察到至少一个带有该标签的命名空间，则 Operator 会创建一个项目 Registration 命名空间。除非出现以下两种情况，否则 Operator 不会让这些命名空间被删除。第一种情况是带有该标签的所有命名空间都消失了（例如，这是该项目中的最后一个命名空间，在这种情况下，命名空间将标有标签 `"helm.cattle.io/helm-project-operator-orphaned": "true"`，表示可以删除）。第二种情况是由于项目 ID 是在 `.Values.helmProjectOperator.otherSystemProjectLabelValues` 下提供的（用作项目的拒绝名单），导致 Operator 不再监视该项目。这些命名空间不会被自动删除，这样能避免破坏用户数据。如果需要，建议用户在创建或删除项目时手动清理这些命名空间。 + + - 如果未提供 `.Values.global.cattle.projectLabel`，则 Operator / System 命名空间也是项目注册命名空间。 + + ::: + +3. **项目发布命名空​​间（`cattle-project--monitoring`）**：Operator 代表 ProjectHelmChart 在其中部署项目监控堆栈的命名空间集。Operator 还将根据在项目 Registration 命名空间中找到的绑定，自动为项目监控堆栈在此命名空间中创建的角色分配 RBAC。**只有集群管理员才能访问这个命名空间。部署的 Helm Chart 和 Prometheus Federator 将为项目所有者（admin）、项目成员（edit）和只读成员（view）分配该命名空间的有限访问权限。** + + :::note 注意事项： + + - 项目发布命名空间会自动部署并导入到 ID 在 `.Values.helmProjectOperator.projectReleaseNamespaces.labelValue` 下指定的项目中，如果未指定，且项目注册命名空间中指定了 ProjectHelmChart，则默认为 `.Values.global.cattle.systemProjectId` 的值。 + + - 项目发布命名空​​间的孤立约定与项目注册命名空间的相同（参见上面的注释）。 + + - 如果 `.Values.projectReleaseNamespaces.enabled` 为 false，则项目发布命名空​​间与项目注册命名空间是相同的。 + + ::: + +### Helm 资源（HelmChart、HelmRelease） + +在部署 ProjectHelmChart 时，Prometheus Federator 将自动创建和管理两个子自定义资源，它们依次管理以下底层 Helm 资源： + +- HelmChart CR（通过 Operator 中的嵌入式 [k3s-io​​/helm-contoller](https://github.com/k3s-io/helm-controller) 管理）：此自定义资源会根据应用到 HelmChart CR 的变更，在触发 `helm install`、`helm upgrade` 或 `helm uninstall` 的同一命名空间中自动创建一个 Job。此 CR 会根据 ProjectHelmChart 的更改（例如，修改 `values.yaml`）或底层项目定义的更改（例如，从项目中添加或删除命名空间）自动更新。 + +:::note 重要提示： + +如果 ProjectHelmChart 没有部署或更新底层项目监控堆栈，你可以先使用此资源在 Operator / System 命名空间中创建的 Job 来检查 Helm 操作是否有问题。通常只能由**集群管理员访问**。 + +::: + +- HelmRelease CR（通过 Operator 中的嵌入式 [rancher/helm-locker](https://github.com/rancher/helm-locker) 管理）：此自定义资源会自动锁定已部署的 Helm 版本并自动覆盖对底层资源的更新，除非更改是 Helm 操作导致的（`helm install`、`helm upgrade` 或 `helm uninstall` 由 HelmChart CR 执行）。 + +:::note + +HelmRelease CR 会发出 Kubernetes 事件，用于检测底层 Helm 版本修改并将其锁定回原位。要查看这些事件，你可以使用 `kubectl describe helmrelease -n `。你还可以查看此 Operator 的日志，了解检测到更改的时间以及哪些资源被尝试更改。 + +::: + +这两种资源都是为 Operator / System 命名空间中的所有 Helm Chart 创建的，用于避免低权限用户的权限升级。 + +### 高级 Helm Project Operator 配置 + +有关高级配置的更多信息，请参阅[此页面](https://github.com/rancher/prometheus-federator/blob/main/charts/prometheus-federator/0.0.1/README.md#advanced-helm-project-operator-configuration)。 + + + +### Local 集群上的 Prometheus Federator + +Prometheus Federator 是一个资源密集型应用程序。你可以将其安装到 Local 集群（**不推荐**）。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md new file mode 100644 index 00000000000..442efff377e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md @@ -0,0 +1,21 @@ +--- +title: 架构 +--- + + + + + +本章节重点介绍 [Rancher Server 及其组件](rancher-server-and-components.md) 以及 [Rancher 如何与下游 Kubernetes 集群通信](communicating-with-downstream-user-clusters.md)。 + +有关安装 Rancher 的不同方式的信息，请参见[安装选项概述](../../getting-started/installation-and-upgrade/installation-and-upgrade.md#安装方式概述)。 + +有关 Rancher API Server 的主要功能，请参见[概述](../../getting-started/overview.md#rancher-api-server-的功能)。 + +有关如何为 Rancher Server 设置底层基础架构，请参见[架构推荐](architecture-recommendations.md)。 + +:::note + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../kubernetes-concepts.md)。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/kubernetes-security-best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/kubernetes-security-best-practices.md index af9746e899f..326a1789802 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/kubernetes-security-best-practices.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/kubernetes-security-best-practices.md @@ -2,6 +2,10 @@ title: Kubernetes 安全最佳实践 --- + + + + ### 限制云元数据 API 访问 AWS、Azure、DigitalOcean 或 GCP 等云提供商通常会在本地向实例公开元数据服务。默认情况下，此端点可被运行在云实例上的 pod 访问，包括在托管的 Kubernetes（如 EKS、AKS、DigitalOcean Kubernetes 或 GKE）中的 pod，并且可以包含该节点的云凭证、配置数据（如 kubelet 凭证）以及其他敏感数据。为了降低在云平台上运行的这种风险，请遵循 [Kubernetes 安全建议](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/#restricting-cloud-metadata-api-access)，即限制授予实例凭证的权限，使用网络策略限制 pod 对元数据 API 的访问，并避免使用配置数据来传递密文。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-security.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-security.md new file mode 100644 index 00000000000..5b8a0466a00 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-security.md @@ -0,0 +1,87 @@ +--- +title: Rancher 安全指南 +--- + + + + + + + + + + + +
+

安全策略

+

Rancher Labs 会负责任地披露问题，并致力于在合理的时间内解决所有问题。

+		 +

报告流程

+

请将安全问题发送至 security-rancher@suse.com。

+		 +

公告

+

订阅 Rancher 公告论坛以获取版本更新。

+
+ +安全是 Rancher 全部功能的基础。Rancher 集成了全部主流认证工具和服务，并提供了企业级的 [RBAC 功能](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)，让你的 Kubernetes 集群更加安全。 + +本文介绍了安全相关的文档以及资源，让你的 Rancher 安装和下游 Kubernetes 集群更加安全。 + +### NeuVector 与 Rancher 的集成 + +_v2.6.5 中的新功能_ + +NeuVector 是一个开源的、以容器为中心的安全应用程序，现已集成到 Rancher 中。NeuVector 提供生产安全、DevOps 漏洞保护和容器防火墙等功能。请参阅 [Rancher 文档](../../integrations-in-rancher/neuvector.md) 和 [NeuVector 文档](https://open-docs.neuvector.com/)了解更多信息。 + +### 在 Kubernetes 集群上运行 CIS 安全扫描 + +Rancher 使用 [kube-bench](https://github.com/aquasecurity/kube-bench) 来运行安全扫描，从而检查 Kubernetes 是否按照 [CIS](https://www.cisecurity.org/cis-benchmarks/)（Center for Internet Security，互联网安全中心）Kubernetes Benchmark 中定义的安全最佳实践进行部署。 + +CIS Kubernetes Benchmark 是一个参考文档，用于为 Kubernetes 建立安全配置基线。 + +CIS 是一个 501(c\)(3) 非营利组织，成立于 2000 年 10 月，其使命是识别、开发、验证、促进和维持网络防御的最佳实践方案，并建立和指导社区，以在网络空间中营造信任的环境。 + +CIS Benchmark 是目标系统安全配置的最佳实践。CIS Benchmark 是由安全专家、技术供应商、公开和私人社区成员，以及 CIS Benchmark 开发团队共同志愿开发的。 + +Benchmark 提供两种类型的建议，分别是自动（Automated）和手动（Manual）。我们只运行 Automated 相关的测试。 + +Rancher 在集群上运行 CIS 安全扫描时会生成一份报告，该报告会显示每个测试的结果，包括测试概要以及 `passed`、`skipped` 和 `failed` 的测试数量。报告还包括失败测试的修正步骤。 + +有关详细信息，请参阅[安全扫描](../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)。 + +### SELinux RPM + +[安全增强型 Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全增强。被政府机构使用之后，SELinux 已成为行业标准，并在 CentOS 7 和 8 上默认启用。 + +我们提供了 `rancher-selinux` 和 `rke2-selinux` 两个 RPM（Red Hat 软件包），让 Rancher 产品能够在 SELinux 主机上正常运行。有关详细信息，请参阅[此页面](selinux-rpm/selinux-rpm.md)。 + +### Rancher 加固指南 + +Rancher 加固指南基于 CIS Kubernetes Benchmark。 + +加固指南为加固 Rancher 的生产安装提供了说明性指导。有关安全管控的完整列表，请参阅 Rancher 的 [CIS Kubernetes Benchmark 自我评估](#cis-benchmark-和自我评估)指南。 + +> 加固指南描述了如何保护集群中的节点，建议在安装 Kubernetes 之前参考加固指南中的步骤。 + +每个加固指南版本都针对特定的 CIS Kubernetes Benchmark、Kubernetes 和 Rancher 版本。 + +### CIS Benchmark 和自我评估 + +Benchmark 自我评估是 Rancher 安全加固指南的辅助。加固指南展示了如何加固集群，而 Benchmark 指南旨在帮助你评估加固集群的安全级别。 + +由于 Rancher 和 RKE 将 Kubernetes 服务安装为 Docker 容器，因此 CIS Kubernetes Benchmark 中的许多管控验证检查都不适用。本指南将介绍各种 controls，并提供更新的示例命令来审计 Rancher 创建的集群的合规性。你可以前往 [CIS 网站](https://www.cisecurity.org/benchmark/kubernetes/)下载原始的 Benchmark 文档。 + +Rancher 自我评估指南的每个版本都对应于强化指南、Rancher、Kubernetes 和 CIS Benchmark 的特定版本。 + +### 第三方渗透测试报告 + +Rancher 会定期聘请第三方对 Rancher 2.x 软件栈进行安全审计和渗透测试。被测环境遵循 Rancher 在测试时提供的强化指南。以前的渗透测试报告如下。 + +结果： + +- [Cure53 渗透测试 - 2019 年 7 月](https://releases.rancher.com/documents/security/pen-tests/2019/RAN-01-cure53-report.final.pdf) +- [Untamed Theory 渗透测试 - 2019 年 3 月](https://releases.rancher.com/documents/security/pen-tests/2019/UntamedTheory-Rancher_SecurityAssessment-20190712_v5.pdf) + +### Rancher 安全公告和 CVE + +Rancher 致力于向社区通报我们产品中的安全问题。有关我们已解决的问题的 CVE（常见漏洞和暴露）列表，请参阅[此页](security-advisories-and-cves.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rancher-v2.6-hardening-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rancher-v2.6-hardening-guides.md new file mode 100644 index 00000000000..e4bb63592cf --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rancher-v2.6-hardening-guides.md @@ -0,0 +1,50 @@ +--- +title: Rancher v2.6 的自我评估和强化指南 +--- + +Rancher 为每个受支持的 Rancher 的 Kubernetes 发行版提供了特定的安全强化指南。 + +## Rancher Kubernetes 发行版 + +Rancher 使用以下 Kubernetes 发行版： + +- [**RKE**](https://rancher.com/docs/rke/latest/en/), Rancher Kubernetes Engine 是一个经过 CNCF 认证的 Kubernetes 发行版，完全在 Docker 容器中运行。 +- [**RKE2**](https://docs.rke2.io/) 是一个完全符合的 Kubernetes 发行版，专注于安全性和合规性。 +- [**K3s**](https://rancher.com/docs/k3s/latest/en/) 是一个完全合规的，轻量级 Kubernetes 发行版。它易于安装，内存需求只有上游 Kubernetes 的一半，所有组件都在一个小于 100 MB 的二进制文件中。 + +要加固运行未列出的发行版的 Kubernetes 集群，请参阅 Kubernetes 提供商文档。 + +## 强化指南和 Benchmark 版本 + +这些指南已经与 Rancher v2.6 版本一起进行了测试。每个自我评估指南都附有强化指南，并在特定的 Kubernetes 版本和 CIS 基准版本上进行了测试。如果 CIS 基准尚未针对你的 Kubernetes 版本进行验证，你可以选择使用现有指南，直到添加更新版本。 + +### RKE 指南 + +| Kubernetes 版本 | CIS Benchmark 版本 | 自我评估指南 | 强化指南 | +| ------------------------- | ------------------ | ------------------------------------------------------------- | ------------------------------------------------------- | +| Kubernetes v1.18 至 v1.23 | CIS v1.6 | [链接](rke1-self-assessment-guide-with-cis-v1.6-benchmark.md) | [链接](rke1-hardening-guide-with-cis-v1.6-benchmark.md) | + +:::note + +- Kubernetes v1.19 和 v1.20 的 CIS v1.20 Benchmark 测试版本尚未作为 Rancher 的 CIS Benchmark chart 中的配置文件发布。 + +::: + +### RKE2 指南 + +| 类型 | Kubernetes 版本 | CIS Benchmark 版本 | 自我评估指南 | 强化指南 | +| -------------------------------- | ------------------------- | ------------------ | ------------------------------------------------------------- | ------------------------------------------------------- | +| Rancher provisioned RKE2 cluster | Kubernetes v1.21 至 v1.23 | CIS v1.6 | [链接](rke2-self-assessment-guide-with-cis-v1.6-benchmark.md) | [链接](rke2-hardening-guide-with-cis-v1.6-benchmark.md) | +| Standalone RKE2 | Kubernetes v1.21 至 v1.23 | CIS v1.6 | [链接](https://docs.rke2.io/security/cis_self_assessment16) | [链接](https://docs.rke2.io/security/hardening_guide) | + +### K3s 指南 + +| Kubernetes 版本 | CIS Benchmark 版本 | 自我评估指南 | 强化指南 | +| ------------------------- | ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| Kubernetes v1.21 和 v1.22 | CIS v1.6 | [链接](https://rancher.com/docs/k3s/latest/en/security/self_assessment/) | [链接](https://rancher.com/docs/k3s/latest/en/security/hardening_guide/) | + +## 在 SELinux 上使用 Rancher + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全性增强。SELinux 在历史上被政府机构使用后，现在是行业标准，并且在 RHEL 和 CentOS 上默认启用。 + +要将 Rancher 与 SELinux 结合使用，我们建议按照[此页面](../selinux-rpm/about-rancher-selinux.md#installing-the-rancher-selinux-rpm)上的说明安装 `rancher-selinux`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/security-advisories-and-cves.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/security-advisories-and-cves.md index a105e1f0ce1..dfee73d487d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/security-advisories-and-cves.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/security-advisories-and-cves.md @@ -2,10 +2,18 @@ title: 安全公告和 CVE --- + + + + Rancher 致力于向社区披露我们产品的安全问题。我们会针对已解决的问题发布安全公告和 CVE（Common Vulnerabilities and Exposures，通用漏洞披露）。Rancher GitHub 上的[安全页面](https://github.com/rancher/rancher/security/advisories)也会发布新的安全公告。 | ID | 描述 | 日期 | 解决 | |----|-------------|------|------------| +| [CVE-2023-32193](https://github.com/rancher/norman/security/advisories/GHSA-r8f4-hv23-6qp6) | 在 Rancher 2.6.13、2.7.9 和 2.8.1 及之前的版本中发现了一个问题。多个 Cross-Site Scripting (XSS) 漏洞可通过 Rancher UI (Norman) 进行利用。 | 2024 年 2 月 8 日 | Rancher [v2.8.2](https://github.com/rancher/rancher/releases/tag/v2.8.2)、[v2.7.10](https://github.com/rancher/rancher/releases/tag/v2.7.10) 和 [v2.6.14](https://github.com/rancher/rancher/releases/tag/v2.6.14) | +| [CVE-2023-32192](https://github.com/rancher/apiserver/security/advisories/GHSA-833m-37f7-jq55) | 在 Rancher 2.6.13、2.7.9 和 2.8.1 及之前的版本中发现了一个问题。多个 Cross-Site Scripting (XSS) 漏洞，可以通过 Rancher UI (Apiserver) 进行利用 | 2024 年 2 月 8 日 | Rancher [v2.8.2](https://github.com/rancher/rancher/releases/tag/v2.8.2)、[v2.7.10](https://github.com/rancher/rancher/releases/tag/v2.7.10) 和 [v2.6.14](https://github.com/rancher/rancher/releases/tag/v2.6.14) | +| [CVE-2023-22649](https://github.com/rancher/rancher/security/advisories/GHSA-xfj7-qf8w-2gcr) | 在 Rancher 2.6.13、2.7.9 和 2.8.1 及之前的版本中发现了一个问题。敏感数据可能会泄漏到 Rancher 的审计日志中。 | 2024 年 2 月 8 日 | Rancher [v2.8.2](https://github.com/rancher/rancher/releases/tag/v2.8.2)、[v2.7.10](https://github.com/rancher/rancher/releases/tag/v2.7.10) 和 [v2.6.14](https://github.com/rancher/rancher/releases/tag/v2.6.14) | +| [CVE-2023-32194](https://github.com/rancher/rancher/security/advisories/GHSA-c85r-fwc7-45vc) | 在 Rancher 2.6.13、2.7.9 和 2.8.1 及之前的版本中发现了一个问题。当为 “namespace” 资源类型授予 `create` 或 `*` 全局角色时，任何 API 组中拥有权限的用户可以管理核心 API 组中的 namespace。 | 2024 年 2 月 8 日 | Rancher [v2.8.2](https://github.com/rancher/rancher/releases/tag/v2.8.2)、[v2.7.10](https://github.com/rancher/rancher/releases/tag/v2.7.10) 和 [v2.6.14](https://github.com/rancher/rancher/releases/tag/v2.6.14) | | [CVE-2023-22648](https://github.com/rancher/rancher/security/advisories/GHSA-vf6j-6739-78m8) | 在 Rancher 2.6.12 和 2.7.3 及之前的版本中发现了一个问题。在用户注销并重新登录到 Rancher UI 之前，Azure AD 中的权限更改不会反映给用户。 | 2023 年 5 月 31 日 | Rancher [v2.6.13](https://github.com/rancher/rancher/releases/tag/v2.6.13) | | [CVE-2022-43760](https://github.com/rancher/rancher/security/advisories/GHSA-46v3-ggjg-qq3x) | 在 Rancher 2.6.12 和 2.7.3 及之前的版本中发现了一个问题。攻击者可以通过 Rancher UI 利用多个跨站脚本 (XSS) 漏洞。 | 2023 年 5 月 31 日 | Rancher [v2.6.13](https://github.com/rancher/rancher/releases/tag/v2.6.13) | | [CVE-2020-10676](https://github.com/rancher/rancher/security/advisories/GHSA-8vhc-hwhc-cpj4) | 在 Rancher 2.6.12 和 2.7.3 及之前的版本中发现了一个问题。具有更新命名空间权限的用户可以将该命名空间移动到他们无权访问的项目中。 | 2023 年 5 月 31 日 | Rancher [v2.6.13](https://github.com/rancher/rancher/releases/tag/v2.6.13) | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md new file mode 100644 index 00000000000..2c96bf912ee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md @@ -0,0 +1,20 @@ +--- +title: SELinux RPM +--- + + + + + +[安全增强型 Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全增强。 + +它由 Red Hat 开发，是 Linux 上 MAC（mandatory access controls，强制访问控制）的实现。系统管理员可以使用 MAC 设置应用程序和用户是如何访问不同资源的，例如文件、设备、网络和进程间的通信。SELinux 还通过默认限制操作系统来增强安全性。 + +被政府机构使用之后，SELinux 已成为行业标准，并在 CentOS 7 和 8 上默认启用。要检查 SELinux 是否在你的系统上启用和执行，请使用 `getenforce`： + +``` +# getenforce +Enforcing +``` + +我们提供了 [`rancher-selinux`](about-rancher-selinux.md) 和 [`rke2-selinux`](about-rke2-selinux.md) 两个 RPM（Red Hat 软件包），让 Rancher 产品能够在 SELinux 主机上正常运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md new file mode 100644 index 00000000000..e272daa1ca4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md @@ -0,0 +1,9 @@ +--- +title: Docker 中的单节点 Rancher +--- + + + + + +以下文档将讨论 Docker 安装的 [HTTP 代理配置](http-proxy-configuration.md)和[高级选项](advanced-options.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/user-settings/user-settings.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/user-settings/user-settings.md new file mode 100644 index 00000000000..47ff9cb2518 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/reference-guides/user-settings/user-settings.md @@ -0,0 +1,19 @@ +--- +title: 用户设置 +--- + + + + + +在 Rancher 中，每个用户都有很多与登录相关的设置，例如个人偏好、API 密钥等。你可以从**用户设置**菜单中配置这些设置。你可以单击主菜单中的头像来打开此菜单。 + +![用户设置菜单](/img/user-settings.png) + +可用的用户设置包括： + +- [API & 密钥](api-keys.md)：如果你想以编程方式与 Rancher 交互，你需要一个 API 密钥。你可以按照本节中的说明获取密钥。 +- [云凭证](manage-cloud-credentials.md)：管理[节点模板](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)使用的云凭证，从而[为集群配置节点](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 +- [节点模板](manage-node-templates.md)：管理 [Rancher 用来为集群配置节点](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的模板。 +- [偏好设置](user-preferences.md)：设置 Rancher UI 的表面首选项。 +- 登出：结束你的用户会话。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/shared-files/_cluster-capabilities-table.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/shared-files/_cluster-capabilities-table.md index c418e1eaf54..0895bb7dc74 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/shared-files/_cluster-capabilities-table.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/shared-files/_cluster-capabilities-table.md @@ -1,22 +1,22 @@ -| 操作 | Rancher 启动的 Kubernetes 集群 | EKS、GKE 和 AKS 集群1 | 其他托管的 Kubernetes 集群 | 非 EKS 或 GKE 注册集群 | +| 操作 | Rancher 启动的 Kubernetes 集群 | EKS, GKE 和 AKS 集群1 | 其他托管的 Kubernetes 集群 | 非 EKS 或 GKE 注册集群 | | --- | --- | ---| ---|----| | [使用 kubectl 和 kubeconfig 文件来访问集群](../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) | ✓ | ✓ | ✓ | ✓ | | [管理集群成员](../how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md) | ✓ | ✓ | ✓ | ✓ | -| [编辑和升级集群](../pages-for-subheaders/cluster-configuration.md) | ✓ | ✓ | ✓ | ✓2 | +| [编辑和升级集群](../reference-guides/cluster-configuration/cluster-configuration.md) | ✓ | ✓ | ✓ | ✓2 | | [管理节点](../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md) | ✓ | ✓ | ✓ | ✓3 | -| [管理持久卷和存储类](../pages-for-subheaders/create-kubernetes-persistent-storage.md) | ✓ | ✓ | ✓ | ✓ | +| [管理持久卷和存储类](../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) | ✓ | ✓ | ✓ | ✓ | | [管理项目、命名空间和工作负载](../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md) | ✓ | ✓ | ✓ | ✓ | -| [使用应用目录](../pages-for-subheaders/helm-charts-in-rancher.md) | ✓ | ✓ | ✓ | ✓ | -| 配置工具（[Alerts、Notifiers、Monitoring](../pages-for-subheaders/monitoring-and-alerting.md)、[Logging](../pages-for-subheaders/logging.md) 和 [Istio](../pages-for-subheaders/istio.md)） | ✓ | ✓ | ✓ | ✓ | -| [运行安全扫描](../pages-for-subheaders/cis-scan-guides.md) | ✓ | ✓ | ✓ | ✓ | -| [轮换证书](../how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md) | ✓ | ✓ | | | -| [备份](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md)和[恢复](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Rancher 启动的集群 | ✓ | ✓ | | ✓4 | +| [使用应用目录](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) | ✓ | ✓ | ✓ | ✓ | +| 配置工具 ([Alerts, Notifiers, Monitoring](../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md), [Logging](../integrations-in-rancher/logging/logging.md), [Istio](../integrations-in-rancher/istio/istio.md)) | ✓ | ✓ | ✓ | ✓ | +| [运行安全扫描](../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md) | ✓ | ✓ | ✓ | ✓ | +| [轮换证书](../how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md) | ✓ | ✓ | | | +| [备份](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) 和 [恢复](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Rancher 启动的集群 | ✓ | ✓ | | ✓4 | | [在 Rancher 无法访问集群时清理 Kubernetes 组件](../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md) | ✓ | | | | -| [配置 Pod 安全策略](../how-to-guides/new-user-guides/manage-clusters/add-a-pod-security-policy.md) | ✓ | ✓ | | +| [配置 Pod 安全策略](../how-to-guides/new-user-guides/manage-clusters/add-a-pod-security-policy.md) | ✓ | ✓ | || 1. 注册的 EKS、GKE 和 AKS 集群与从 Rancher UI 创建的 EKS、GKE 和 AKS 集群的可用选项一致。不同之处是，从 Rancher UI 中删除已注册的集群后，集群不会被销毁。 -2. 无法编辑已注册的集群的集群配置选项（[K3s 和 RKE2 集群](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md)除外）。 +2. 无法编辑已注册的集群的集群配置选项，[K3s 和 RKE2 集群](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md)除外。 3. Rancher UI 为已注册的集群节点提供了封锁、清空和编辑节点的功能。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.6/troubleshooting/kubernetes-components/kubernetes-components.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/troubleshooting/kubernetes-components/kubernetes-components.md new file mode 100644 index 00000000000..38bcba2810d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6/troubleshooting/kubernetes-components/kubernetes-components.md @@ -0,0 +1,21 @@ +--- +title: Kubernetes 组件 +--- + + + + + +本文列出的命令和步骤适用于 [Rancher 启动的 Kubernetes](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 集群上的核心 Kubernetes 组件。 + +本文包括以下类别的故障排除提示： + +- [etcd 节点故障排除](troubleshooting-etcd-nodes.md) +- [Controlplane 节点故障排除](troubleshooting-controlplane-nodes.md) +- [nginx-proxy 节点故障排除](troubleshooting-nginx-proxy.md) +- [Worker 节点和通用组件故障排除](troubleshooting-worker-nodes-and-generic-components.md) + +## Kubernetes 组件图 + +![集群图](/img/clusterdiagram.svg)
+线条表示组件之间的通信。而颜色纯粹用于视觉辅助。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md index 94b0333f481..d8a570455bc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md @@ -48,4 +48,4 @@ Rancher 支持几家主要的云提供商，但默认情况下，这些主机驱 还有其他几个默认禁用的主机驱动，但打包在 Rancher 中： -* [Harvester](../../../../integrations-in-rancher/harvester/overview.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 +* [Harvester](../../../../integrations-in-rancher/harvester.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md index d0e1b83f979..c99e275b0f6 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md @@ -198,3 +198,7 @@ Enter the values that you copied to your [text file](#tip). 1. Click **Authenticate with Azure**. **Result:** Azure Active Directory authentication is configured. + +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). \ No newline at end of file diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md index 3e8f19a0b6e..f20f4ee12e3 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md @@ -202,6 +202,9 @@ Enter the values that you copied to your [text file](#tip). **Result:** Azure Active Directory authentication is configured. +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). ### Migrating from Azure AD Graph API to Microsoft Graph API diff --git a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md index 94ca0e5b46b..3fb511703c5 100644 --- a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -230,6 +230,9 @@ From the Rancher UI, enter information about your AD instance hosted in Azure to **Result:** Azure Active Directory authentication is configured. +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). ### Migrating from Azure AD Graph API to Microsoft Graph API diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md index 87b27a419c4..9974414f1a5 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -226,6 +226,9 @@ To complete configuration, enter information about your AD instance in the Ranch **Result:** Azure Active Directory authentication is configured. +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). ### Migrating from Azure AD Graph API to Microsoft Graph API diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index 9114b037d56..75aa6307fee 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -6,7 +6,7 @@ title: Using API Tokens -Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform, and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. @@ -49,7 +49,7 @@ Set the `kubeconfig-generate-token` setting to `false`. This setting instructs R ## Token Hashing -Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluating in a test environment first. +Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups before enabling and/or evaluating in a test environment first. To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). diff --git a/versioned_docs/version-2.8/api/quickstart.md b/versioned_docs/version-2.8/api/quickstart.md index 3077a51188a..2b215857a39 100644 --- a/versioned_docs/version-2.8/api/quickstart.md +++ b/versioned_docs/version-2.8/api/quickstart.md @@ -6,7 +6,7 @@ title: RK-API Quick Start Guide -You can access Rancher's resources through the Kubernetes API. This guide will help you get started on using this API as a Rancher user. +You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user. 1. In the upper left corner, click **☰ > Global Settings**. 2. Find and copy the address in the `server-url` field. @@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. ::: -4. The following commands will convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: +4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: ```bash export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 730a5b29e72..6dfa4d0c61a 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -8,14 +8,14 @@ title: Previous v3 Rancher API Guide ## How to Use the API -The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it: +The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it: -1. Click on your user avatar in the upper right corner. -1. Click **Account & API Keys**. -1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. +1. Click your user avatar in the upper right corner. +1. Click **Account & API Keys**. +1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. @@ -29,11 +29,11 @@ Go to the URL endpoint at `https:///v3`, where `` is API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. -By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). +By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). ## Making requests -The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md). +The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md). - Every type has a Schema which describes: - The URL to get to the collection of this type of resources @@ -43,31 +43,31 @@ The API is generally RESTful but has several features to make the definition of - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. +- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. -- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +- In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. - Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information. +- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Certain actions require input or produce output, see the individual documentation for each type or the schemas for specific information. -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. +- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. +- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). ## Filtering -Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. ## Sorting -Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. ## Pagination -API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. +API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. ## Capturing Rancher API Calls @@ -76,18 +76,18 @@ You can use browser developer tools to capture how the Rancher API is called. Fo 1. In the Rancher UI, go to **Cluster Management** and click **Create.** 1. Click one of the cluster types. This example uses Digital Ocean. 1. Fill out the form with a cluster name and node template, but don't click **Create**. -1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.** +1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.** 1. In the developer tools, click the **Network** tab. 1. On the **Network** tab, make sure **Fetch/XHR** is selected. 1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. 1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** -1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials. +1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials. ### Enable View in API You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: -1. Click on your **User Tile** in the top right corner of the UI and select **Preferences** from the dropdown menu. +1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu. 2. Under the **Advanced Features** section, click **Enable "View in API"** -Once checked, the **View in API** link will now appear under the **⋮** sub-menu on resource pages in the UI. +Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md index de153cd50e1..70c35e18d34 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -18,16 +18,16 @@ Some feature flags require a restart of the Rancher container. Features that req The following is a list of feature flags available in Rancher. If you've upgraded from a previous Rancher version, you may see additional flags in the Rancher UI, such as `proxy` or `dashboard` (both [discontinued](/versioned_docs/version-2.5/reference-guides/installation-references/feature-flags.md)): -- `continuous-delivery`: Allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. -- `fleet`: The Rancher provisioning framework in v2.6 and later requires Fleet. The flag will be automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. -- `harvester`: Manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. -- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. -- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. -- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. -- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. -- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: Enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. -- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. +- `continuous-delivery`: allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. +- `fleet`: the Rancher provisioning framework in v2.6 and later requires Fleet. The flag is automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. +- `harvester`: manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. +- `istio-virtual-service-ui`: enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. +- `legacy`: enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features scheduled to be available in newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. +- `multi-cluster-management`: allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. +- `rke1-custom-node-cleanup`: enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. +- `rke2`: enables provisioning RKE2 clusters. This flag is enabled by default. +- `token-hashing`: enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `unsupported-storage-drivers`: enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md index d9950de322d..817a490ecda 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -225,6 +225,9 @@ To complete configuration, enter information about your AD instance in the Ranch **Result:** Azure Active Directory authentication is configured. +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). ### Migrating from Azure AD Graph API to Microsoft Graph API diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md index 588f33fb030..a573ed9edb7 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -19,9 +19,9 @@ The kubeconfig file and its contents are specific to each cluster. It can be dow 1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row. 1. Select **Download KubeConfig** from the submenu. -You will need a separate kubeconfig file for each cluster that you have access to in Rancher. +You need a separate kubeconfig file for each cluster that you have access to in Rancher. -After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. +After you download the kubeconfig file, you are then able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](./authorized-cluster-endpoint.md) to be present in your PATH. @@ -36,7 +36,7 @@ For RKE clusters, the kubeconfig file allows you to be authenticated in two ways This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher. -To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) +To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters. diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md index 461e56b0381..54ebd32444c 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -100,7 +100,7 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster. -1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH will be downloaded. +1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH is then downloaded. 1. Extract the ZIP file to any location. 1. Open Terminal. Change your location to the extracted ZIP file. 1. Enter the following command: @@ -111,13 +111,13 @@ For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-ranch ## Cordoning a Node -_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. +_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. ## Draining a Node _Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption. -- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod. +- For pods with a replica set, the pod is replaced by a new pod that is scheduled to a new node. Additionally, if the pod is part of a service, then clients are automatically redirected to the new pod. - For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it. @@ -127,20 +127,21 @@ However, you can override the conditions draining when you initiate the drain. Y ### Aggressive and Safe Draining Options -When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled. +When you configure the upgrade strategy for the cluster, you are able to enable node draining. If node draining is enabled, you are able to configure how pods are deleted and rescheduled. - **Aggressive Mode** In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. - Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods. + Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir is deleted once the pod is removed from the node. Choosing aggressive mode deletes these pods. - **Safe Mode** - If a node has standalone pods or ephemeral data it will be cordoned but not drained. + If a node has stand-alone pods or ephemeral data it is cordoned but not drained. + ### Grace Period -The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used. +The timeout given to each pod for cleaning things up so they have the chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to an external storage. If negative, the default value specified in the pod is used. ### Timeout @@ -156,17 +157,17 @@ The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was n If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node. -If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to `cordoned`. +If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which stops the drain process and changes the node's state to `cordoned`. -Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node. +Once drain successfully completes, the node is in a state of `drained`. You can then power off or delete the node. **Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/). ## Labeling a Node to be Ignored by Rancher -Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. +Certain solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. -Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI. +Since the node never finishes registering, it is always shown as unhealthy in the Rancher UI. In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing. @@ -181,16 +182,16 @@ There is an [open issue](https://github.com/rancher/rancher/issues/24172) in whi ### Labeling Nodes to be Ignored with kubectl -To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label: +To add a node that is ignored by Rancher, use `kubectl` to create a node that has the following label: ``` cattle.rancher.io/node-status: ignore ``` -**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`. +**Result**: If you add the node to a cluster, Rancher skips syncing with this node. The node can still be part of the cluster and can be listed with `kubectl`. -If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI. +If the label is added before the node is added to the cluster, the node is not shown in the Rancher UI. -If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI. +If the label is added after the node is added to a Rancher cluster, the node is not removed from the UI. -If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`. +If you delete the node from the Rancher server using the Rancher UI or API, the node is not removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`. diff --git a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md index 356439ad59f..2cab973b406 100644 --- a/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md +++ b/versioned_docs/version-2.8/reference-guides/user-settings/api-keys.md @@ -35,9 +35,9 @@ Users may opt to enable [token hashing](../../api/api-tokens.md). The API key won't be valid after expiration. Shorter expiration periods are more secure. - Expiration period will be bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period. + Expiration period is bound by `v3/settings/auth-token-max-ttl-minutes`. If it exceeds the max-ttl, API key is created with max-ttl as the expiration period. - A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information. + A scope limits the API key so that it only works against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you are able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information. 4. Click **Create**. @@ -49,7 +49,7 @@ Users may opt to enable [token hashing](../../api/api-tokens.md). ## What's Next? -- Enter your API key information into the application that will send requests to the Rancher API. +- Enter your API key information into the application that sends requests to the Rancher API. - Learn more about the Rancher endpoints and parameters by selecting **View in API** for an object in the Rancher UI. - API keys are used for API calls and [Rancher CLI](../cli-with-rancher/cli-with-rancher.md). From d23161c4cba6711575042a1f4a56bda5b5b2f6f9 Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 10 May 2024 10:38:33 -0700 Subject: [PATCH 21/25] Updating feature flag page as incorrect vale syntax change was applied. Signed-off-by: Sunil Singh --- .../installation-references/feature-flags.md | 20 +++++++++---------- .../installation-references/feature-flags.md | 20 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md index 70c35e18d34..ecc870fb48a 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -18,16 +18,16 @@ Some feature flags require a restart of the Rancher container. Features that req The following is a list of feature flags available in Rancher. If you've upgraded from a previous Rancher version, you may see additional flags in the Rancher UI, such as `proxy` or `dashboard` (both [discontinued](/versioned_docs/version-2.5/reference-guides/installation-references/feature-flags.md)): -- `continuous-delivery`: allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. -- `fleet`: the Rancher provisioning framework in v2.6 and later requires Fleet. The flag is automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. -- `harvester`: manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. -- `istio-virtual-service-ui`: enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. -- `legacy`: enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features scheduled to be available in newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. -- `multi-cluster-management`: allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. -- `rke1-custom-node-cleanup`: enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. -- `rke2`: enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. -- `unsupported-storage-drivers`: enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. +- `continuous-delivery`: Allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. +- `fleet`: The Rancher provisioning framework in v2.6 and later requires Fleet. The flag will be automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. +- `harvester`: Manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. +- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. +- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. +- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. +- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. +- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md index 70c35e18d34..ecc870fb48a 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -18,16 +18,16 @@ Some feature flags require a restart of the Rancher container. Features that req The following is a list of feature flags available in Rancher. If you've upgraded from a previous Rancher version, you may see additional flags in the Rancher UI, such as `proxy` or `dashboard` (both [discontinued](/versioned_docs/version-2.5/reference-guides/installation-references/feature-flags.md)): -- `continuous-delivery`: allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. -- `fleet`: the Rancher provisioning framework in v2.6 and later requires Fleet. The flag is automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. -- `harvester`: manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. -- `istio-virtual-service-ui`: enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. -- `legacy`: enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features scheduled to be available in newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. -- `multi-cluster-management`: allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. -- `rke1-custom-node-cleanup`: enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. -- `rke2`: enables provisioning RKE2 clusters. This flag is enabled by default. -- `token-hashing`: enables token hashing. Once enabled, existing tokens are hashed and all new tokens are hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. -- `unsupported-storage-drivers`: enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. +- `continuous-delivery`: Allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. +- `fleet`: The Rancher provisioning framework in v2.6 and later requires Fleet. The flag will be automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. +- `harvester`: Manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. +- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. +- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. +- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. +- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster. +- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: From 02f808a998419a93e60ad48a85978bcb4f2aaaaa Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 10 May 2024 13:03:57 -0700 Subject: [PATCH 22/25] Updating after review and syncing versions. Signed-off-by: Sunil Singh --- docs/api/api-tokens.md | 2 +- docs/api/quickstart.md | 2 +- versioned_docs/version-2.8/api/api-tokens.md | 4 +--- versioned_docs/version-2.8/api/quickstart.md | 2 +- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index 6552eca4156..fa5c797ab3d 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -49,7 +49,7 @@ Set the `kubeconfig-generate-token` setting to `false`. This setting instructs R ## Token Hashing -You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups before enabling and/or evaluating in a test environment first. +You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling. This feature affects all tokens which include, but are not limited to, the following: diff --git a/docs/api/quickstart.md b/docs/api/quickstart.md index 2b215857a39..5bb3057183e 100644 --- a/docs/api/quickstart.md +++ b/docs/api/quickstart.md @@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. ::: -4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: +4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file: ```bash export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG diff --git a/versioned_docs/version-2.8/api/api-tokens.md b/versioned_docs/version-2.8/api/api-tokens.md index 75aa6307fee..ae51e67aa93 100644 --- a/versioned_docs/version-2.8/api/api-tokens.md +++ b/versioned_docs/version-2.8/api/api-tokens.md @@ -49,9 +49,7 @@ Set the `kubeconfig-generate-token` setting to `false`. This setting instructs R ## Token Hashing -Users can enable token hashing, where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. It is advisable to take backups before enabling and/or evaluating in a test environment first. - -To enable token hashing, refer to [this section](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). +You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling. This feature affects all tokens which include, but are not limited to, the following: diff --git a/versioned_docs/version-2.8/api/quickstart.md b/versioned_docs/version-2.8/api/quickstart.md index 2b215857a39..5bb3057183e 100644 --- a/versioned_docs/version-2.8/api/quickstart.md +++ b/versioned_docs/version-2.8/api/quickstart.md @@ -129,7 +129,7 @@ To ensure that your tools can recognize Rancher's CA certificates, most setups r If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. ::: -4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: +4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file: ```bash export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG From b3a1b40374cb6c23933358967f54da1068b2616f Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 10 May 2024 13:36:33 -0700 Subject: [PATCH 23/25] Updating phrasing/syntax after review. Signed-off-by: Sunil Singh --- docs/api/v3-rancher-api-guide.md | 29 ++++++++--------- .../version-2.8/api/v3-rancher-api-guide.md | 31 ++++++++++--------- 2 files changed, 31 insertions(+), 29 deletions(-) diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 3976657a7db..4ceb12c4b1b 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -6,6 +6,8 @@ title: Previous v3 Rancher API Guide +Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](../quickstart.md) and [reference guide](../api-reference.mdx). + ## How to Use the API The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it: @@ -31,31 +33,30 @@ API requests must include authentication information. Authentication is done wit By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). -## Making requests +## Making Requests The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md). - Every type has a Schema which describes: - - The URL to get to the collection of this type of resources + - The URL to get to the collection of this type of resource. - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). - - Every field that filtering is allowed on + - Every field that allows filtering. - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. +The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information. -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. +In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information. -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Certain actions require input or produce output, see the individual documentation for each type or the schemas for specific information. +To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. +To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - -- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). +To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). ## Filtering @@ -69,9 +70,9 @@ Most collections can be sorted on the server-side by common fields using HTTP qu API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. -## Capturing Rancher API Calls +## Capturing v3 API Calls -You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: +You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: 1. In the Rancher UI, go to **Cluster Management** and click **Create.** 1. Click one of the cluster types. This example uses Digital Ocean. @@ -85,7 +86,7 @@ You can use browser developer tools to capture how the Rancher API is called. Fo ### Enable View in API -You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: +You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: 1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu. 2. Under the **Advanced Features** section, click **Enable "View in API"** diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 6dfa4d0c61a..4ceb12c4b1b 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -6,6 +6,8 @@ title: Previous v3 Rancher API Guide +Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](../quickstart.md) and [reference guide](../api-reference.mdx). + ## How to Use the API The previous v3 API has its own user interface accessible from a [web browser](./v3-rancher-api-guide.md#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it: @@ -27,35 +29,34 @@ Go to the URL endpoint at `https:///v3`, where `` is ## Authentication -API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). -## Making requests +## Making Requests The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md). - Every type has a Schema which describes: - - The URL to get to the collection of this type of resources + - The URL to get to the collection of this type of resource. - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). - - Every field that filtering is allowed on + - Every field that allows filtering. - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. +The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information. -- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information. +In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. -- In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. +Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. -- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. +Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information. -- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Certain actions require input or produce output, see the individual documentation for each type or the schemas for specific information. +To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. -- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. +To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. -- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. - -- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). +To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). ## Filtering @@ -69,9 +70,9 @@ Most collections can be sorted on the server-side by common fields using HTTP qu API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. -## Capturing Rancher API Calls +## Capturing v3 API Calls -You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: +You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster: 1. In the Rancher UI, go to **Cluster Management** and click **Create.** 1. Click one of the cluster types. This example uses Digital Ocean. @@ -85,7 +86,7 @@ You can use browser developer tools to capture how the Rancher API is called. Fo ### Enable View in API -You can also view captured Rancher API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: +You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: 1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu. 2. Under the **Advanced Features** section, click **Enable "View in API"** From a537499c5517d96f5af31c2d786a6671251c6b6e Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Fri, 10 May 2024 13:42:43 -0700 Subject: [PATCH 24/25] Fixing the relative links. Signed-off-by: Sunil Singh --- docs/api/v3-rancher-api-guide.md | 2 +- versioned_docs/version-2.8/api/v3-rancher-api-guide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 4ceb12c4b1b..7b1755e7e71 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -6,7 +6,7 @@ title: Previous v3 Rancher API Guide -Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](../quickstart.md) and [reference guide](../api-reference.mdx). +Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). ## How to Use the API diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 4ceb12c4b1b..7b1755e7e71 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -6,7 +6,7 @@ title: Previous v3 Rancher API Guide -Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](../quickstart.md) and [reference guide](../api-reference.mdx). +Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). ## How to Use the API From d60fec6c549874436f95d0a44880bdb7d854a97f Mon Sep 17 00:00:00 2001 From: Sunil Singh Date: Mon, 13 May 2024 11:38:14 -0700 Subject: [PATCH 25/25] Updating the config with consolidated redirects and fixing version syntax. Signed-off-by: Sunil Singh --- docs/api/v3-rancher-api-guide.md | 2 +- docusaurus.config.js | 12 ++---------- .../version-2.8/api/v3-rancher-api-guide.md | 2 +- 3 files changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/api/v3-rancher-api-guide.md b/docs/api/v3-rancher-api-guide.md index 7b1755e7e71..995d66822e4 100644 --- a/docs/api/v3-rancher-api-guide.md +++ b/docs/api/v3-rancher-api-guide.md @@ -6,7 +6,7 @@ title: Previous v3 Rancher API Guide -Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). +Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). ## How to Use the API diff --git a/docusaurus.config.js b/docusaurus.config.js index 3bbbcf3c55c..a28562c49ee 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1717,10 +1717,6 @@ module.exports = { to: '/v2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates', from: '/v2.8/pages-for-subheaders/about-rke1-templates' }, - { - to: '/v2.8/api/v3-rancher-api-guide', - from: '/v2.8/pages-for-subheaders/about-the-api' - }, { to: '/v2.8/how-to-guides/new-user-guides/manage-clusters/access-clusters', from: '/v2.8/pages-for-subheaders/access-clusters' @@ -2061,10 +2057,6 @@ module.exports = { to: '/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates', from: '/pages-for-subheaders/about-rke1-templates' }, - { - to: '/api/v3-rancher-api-guide', - from: '/pages-for-subheaders/about-the-api' - }, { to: '/how-to-guides/new-user-guides/manage-clusters/access-clusters', from: '/pages-for-subheaders/access-clusters' @@ -3456,7 +3448,7 @@ module.exports = { // Redirects for restructure from PR #1147 (start) { to: '/v2.8/api/v3-rancher-api-guide', - from: '/v2.8/reference-guides/about-the-api' + from: ['/v2.8/reference-guides/about-the-api', '/v2.8/pages-for-subheaders/about-the-api'] }, { to: '/v2.8/api/api-tokens', @@ -3464,7 +3456,7 @@ module.exports = { }, { to: '/api/v3-rancher-api-guide', - from: '/reference-guides/about-the-api' + from: ['/reference-guides/about-the-api', '/pages-for-subheaders/about-the-api'] }, { to: '/api/api-tokens', diff --git a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md index 7b1755e7e71..995d66822e4 100644 --- a/versioned_docs/version-2.8/api/v3-rancher-api-guide.md +++ b/versioned_docs/version-2.8/api/v3-rancher-api-guide.md @@ -6,7 +6,7 @@ title: Previous v3 Rancher API Guide -Rancher 2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). +Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). ## How to Use the API