diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md index 4448a2d739e..8d367774725 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -160,7 +160,8 @@ helm repo update # Install the cert-manager Helm chart helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ - --create-namespace + --create-namespace \ + --set installCRDs=true ``` Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 1dcd9426ef5..fe5deede281 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -78,7 +78,7 @@ A restore is performed by creating a Restore custom resource. 1. In the left navigation bar, click **Rancher Backups > Restore**. :::note - If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#charts) for more information. + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#access-charts) for more information. ::: diff --git a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md index 9e5a5333e06..4ccc34749e7 100644 --- a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md +++ b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 1a4519e1bfe..bc679f07a08 100644 --- a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index b458a86bc73..03a7b0cbba2 100644 --- a/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -6,14 +6,10 @@ title: Upgrading Rancher Installed with Docker + + The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -:::caution - -**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) before upgrading. - -::: - ## Prerequisites - **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#known-upgrade-issues)** section in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums](https://forums.rancher.com/c/announcements/12). Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported. diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md index ba159df89cf..b5c95f85af0 100644 --- a/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md +++ b/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -1,20 +1,48 @@ --- -title: Helm Charts in Rancher +title: Helm Charts and Apps --- -In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using **Apps**. It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. +In this section, you'll learn how to manage Helm chart repositories and apps in Rancher. + +## How Helm Charts Work in Rancher + +Helm chart repositories in Rancher are managed using **Apps**. + +Rancher uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. + +### Catalogs, Apps, and the Rancher UI + +[Rancher v2.4 and earlier](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), repositories of ready-to-deploy applications were called "catalogs". These repositories were managed through the **Catalogs** section of the UI. + +Rancher v2.5 replaced the former catalog system with a new **Apps & Marketplace** feature. + +Since Rancher v2.6.5, the **Apps & Marketplace** feature is named **Apps** in the UI. ### Versioning Scheme The Rancher feature charts versioning scheme is centered around the major version of the charts and the `+up` annotation for upstream charts, where applicable. -**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps** charts are also upgraded to the correct release line for the chart. +**Major Version:** The major versions of feature charts are tied to particular minor versions of Rancher. When you upgrade to a new Rancher minor version, you should ensure that all of your feature charts are also upgraded to the correct release line for the chart. -**Feature Charts:** +**Charts based on upstream:** When you upgrade, make sure that the upstream chart version is compatible with your Rancher version. The `+up` annotation for the chart indicates which upstream version the Rancher chart is tracking. For example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some additional Rancher patches. + +When upgrading Rancher versions, don't downgrade the version of the chart that you are using. For example, if you are using a version of Monitoring that is later than `16.6.0` in Rancher v2.5, you shouldn't upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. + +#### Prerelease Versions + +Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. + +To display prerelease versions: + +1. Click on your user avatar in the upper right corner. +1. Click **Preferences**. +1. Under **Helm Charts**, select **Include Prerelease Versions**. + +### Feature Charts | **Name** | **Supported Minimum Version** | **Supported Maximum Version** | | ---------------- | ------------ | ------------ | @@ -35,73 +63,82 @@ The Rancher feature charts versioning scheme is centered around the major versio | rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 | | rancher-wins-upgrader | 0.0.100 | 100.0.1+up0.0.1 | -
-**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also. +## Access Charts -- As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it. +The **Charts** page contains all Rancher, Partner, and Custom charts. You can filter charts by selecting the left-most dropdown menu: -- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. +* Rancher tools such as Logging or Monitoring are listed under the **Rancher** label. +* Partner charts are under the **Partners** label. +* Custom charts are listed under the name of their respective repository. -### Prerelease Versions - -Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. - -To display prerelease versions: - -1. Click on your user avatar in the upper right corner. -1. Click **Preferences**. -1. Under **Helm Charts**, select **Include Prerelease Versions**. - -### Charts - -From the top-left menu select _"Apps"_ and you will be taken to the Charts page. - -The charts page contains all Rancher, Partner, and Custom Charts. - -* Rancher tools such as Logging or Monitoring are included under the Rancher label -* Partner charts reside under the Partners label -* Custom charts will show up under the name of the repository - -All three types are deployed and managed in the same way. +All three types of charts are deployed and managed in the same way. :::note -Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) should continue to be managed only by the Cluster Manager, and apps managed with Apps in the new UI must be managed only by Apps. +Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) continue to be managed only by the Cluster Manager, and apps managed with **Apps** in the new UI must be managed only by **Apps**. ::: -### Repositories +To access the **Charts** page: -From the left sidebar select _"Repositories"_. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. -These items represent Helm repositories, and can be either traditional Helm endpoints which have an index.yaml, or Git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository. +## Manage Repositories -#### Add Custom Git Repositories +The **Repositories** page lists your Helm repositories. These include traditional Helm endpoints which have an index.yaml, and Git repositories that are cloned and point to a specific branch. To use custom charts, add your repository here. After you add a repository, you can access custom charts in the **Charts** page, listed under the name of the repository. -Click **Create** and select the target, **Git repository containing Helm chart...** to add a custom Git repository that contains your Helm charts or cluster template definitions. +To access the **Repositories** page: -You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from the default, `main`. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. -Whenever you add a chart repository to Rancher, it becomes available immediately. +### Add Custom Git Repositories -#### Add Custom Helm Chart Repositories +To add a custom Git repository that contains your Helm charts or cluster template definitions: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **Git repository containing Helm chart...**. +1. You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is named either `main` or `master`. +1. Click **Create** to add the repository. + +After you add a chart repository to Rancher, it becomes available immediately. + +### Add Custom Helm Chart Repositories You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. For more information on Helm chart repositories, see the [official Helm docs](https://helm.sh/docs/topics/chart_repository/). -To add a custom Helm chart repository to Rancher, click **Create** and select **http(s) URL to an index generated by Helm** as the target. Enter a repo name and the index URL address of the chart repository. +To add a custom Helm chart repository to Rancher: -#### Add Private Git/Helm Chart Repositories +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **http(s) URL to an index generated by Helm**. +1. Enter a repo name and the index URL address of the chart repository. +1. Click **Create** to add the repository. + +### Add Private Git/Helm Chart Repositories You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. -#### Add a Private CA to Repositories +### Add a Private CA to Repositories -To add a private CA to Helm chart repositories: +To add a private CA to Helm chart repositories, you must add a base64 encoded copy of the CA certificate in DER format to the `spec.caBundle field` of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Instructions are the same for both Git-based and HTTP-based repositories: -- **HTTP-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the row associated with the Git-based or HTTP-based repository you want to add a private CA to, and click **⋮ > Edit YAML**. +1. Set the `caBundle` value, as in the following example: + + ```yaml [...] spec: caBundle: @@ -109,25 +146,13 @@ To add a private CA to Helm chart repositories: ... nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= [...] - ``` - - -- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` - [...] - spec: - caBundle: - MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT - ... - nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= - [...] - ``` + ``` :::note Helm chart repositories with authentication -The Repo.Spec contains a `disableSameOriginCheck` value that allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. +The Repo.Spec contains a `disableSameOriginCheck` value. This value allows you to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories, such as those that have redirects to a different origin URL. -To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. +To use this feature for an existing Helm chart repository, follow previous steps up to edit the YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. ```yaml [...] @@ -142,37 +167,51 @@ spec: Only Helm 3 compatible charts are supported. +## Deploy and Upgrade Charts -### Deployment and Upgrades +To install and deploy a chart: -From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Select a chart, and click **Install**. -To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs. +Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files. However, all chart installations can modify the values.yaml and other basic settings. After you click **Install**, a Helm operation job is deployed, and the console for the job is displayed. -After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. +To view all recent changes, click **Apps > Recent Operations** in the left navigation menu. From there you can view the calls, conditions, events, and logs. -Most Rancher tools have additional pages located in the toolbar below the _"Apps"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. +After installing a chart, you can view it by clicking **Apps > Installed Apps** in the left navigation menu. You can upgrade or delete the installation, and see further details. Upgrading uses the same forms and values as you saw during inital installation. + +Most Rancher tools have additional pages located in the toolbar below the **Apps** section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. :::caution -If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: +If you are upgrading your chart using **Customize Helm options before upgrade**, and your chart contains immutable fields, using the `--force` option may result in errors. This is because some objects in Kubernetes can't be changed after they're created. To prevent this error: - * use the default upgrade option ( i.e do not use _"--force"_ option ) - * uninstall the existing chart and install the upgraded chart - * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade + * Use the default upgrade option (i.e don't use `--force`). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing a forced upgrade. ::: -#### Legacy Apps +### Legacy Apps -The upgrade button has been removed for legacy apps from the **Apps > Installed Apps** page. +The upgrade button isn't available for legacy apps on the **Apps > Installed Apps** page. -If you have a legacy app installed and want to upgrade it: +If you want to upgrade an installed legacy app, the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on. This flag is automatically turned on if you had a legacy app already running before you upgraded Rancher. -- The legacy [feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading) -- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps** -- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there +1. Enable the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md), if it isn't enabled already. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose apps you want to access. Click **Explore** at the end of the cluster's row. +1. Click **Legacy > Project > Apps**. -### Limitations +If you don't see **Apps** listed under **Legacy > Project**, click the project/namespace search bar in the top navigation and select the relevant project from the dropdown menu. -Dashboard apps or Rancher feature charts **cannot** be installed using the Rancher CLI. +To upgrade legacy multi-cluster apps: + +1. Click **☰**. +1. Under **Legacy Apps**, click **Multi-cluster Apps**. + +## Limitations + +Dashboard apps or Rancher feature charts can't be installed using the Rancher CLI. diff --git a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md index 267d9b1c1ba..0ce4e450f6b 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md @@ -6,9 +6,9 @@ title: Migrating Amazon In-tree to Out-of-tree -Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes 1.27 and later, the in-tree cloud providers have been removed. +Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes v1.27 and later, the in-tree cloud providers have been removed. The Rancher UI allows you to upgrade to Kubernetes v1.27 when you migrate from an in-tree to out-of-tree provider. -You can migrate from an in-tree to an out-of-tree AWS cloud provider on Kubernetes 1.26 and earlier. All existing clusters must migrate prior to upgrading to v1.27 in order to stay functional. +However, if you're performing a manual migration, existing clusters must upgrade to Kubernetes v1.27 after you migrate in order to remain functional. To migrate from the in-tree cloud provider to the out-of-tree AWS cloud provider, you must stop the existing cluster's kube controller manager and install the AWS cloud controller manager. There are many ways to do this. Refer to the official AWS documentation on the [external cloud controller manager](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for details. @@ -52,7 +52,7 @@ spec: 2. Cordon control plane nodes so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider: ```shell -kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" ``` 3. To install the AWS cloud controller manager with leader migration enabled, follow Steps 1-3 for [deploying the cloud controller manager chart](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider). From Kubernetes 1.22 onwards, the kube-controller-manager will utilize a default configuration which will satisfy the controller-to-manager migration. Update container args of the `aws-cloud-controller-manager` under `spec.rkeConfig.additionalManifest` to enable leader migration: diff --git a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md index 47c6d950b2d..00857004174 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md @@ -352,9 +352,9 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' args: - --configure-cloud-routes=false - --use-service-account-credentials=true @@ -639,7 +639,7 @@ kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager - get ``` -9. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: +9. Rancher-provisioned RKE2 nodes are tainted `node-role.kubernetes.io/control-plane`. Update tolerations and the nodeSelector: ```yaml tolerations: @@ -648,13 +648,13 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane ``` ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` :::note @@ -663,7 +663,7 @@ There's currently a [known issue](https://github.com/rancher/dashboard/issues/92 ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` ::: diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md b/docs/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md index 6c0b1c1d0d2..69398199394 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md @@ -18,7 +18,7 @@ In clusters that store data on GlusterFS volumes, you may experience an issue wh - The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use) ``` -docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version +docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run -v /usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3 -v /lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.26.14-rancher1 --version ``` :::caution @@ -32,6 +32,8 @@ services: kubelet: extra_binds: - "/usr/bin/systemd-run:/usr/bin/systemd-run" + - "/usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3" + - "/lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so" ``` After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline: diff --git a/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index 6a325ef79a8..9669219ec33 100644 --- a/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -20,6 +20,9 @@ In order to deploy and run the adapter successfully, you need to ensure its vers | Rancher Version | Adapter Version | |-----------------|:----------------:| | v2.8.0 | v103.0.0+up3.0.0 | +| v2.8.1 | v103.0.0+up3.0.0 | +| v2.8.2 | v103.0.0+up3.0.0 | +| v2.8.3 | v103.0.1+up3.0.1 | ### 1. Gain Access to the Local Cluster diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index b2237a1d442..c028ec47514 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -19,6 +19,7 @@ Each Rancher version is designed to be compatible with a single version of the w | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| +| v2.8.3 | v0.4.3 | ✗ | ✓ | | v2.8.2 | v0.4.2 | ✓ | ✓ | | v2.8.1 | v0.4.2 | ✓ | ✓ | | v2.8.0 | v0.4.2 | ✗ | ✓ | diff --git a/docs/troubleshooting/other-troubleshooting-tips/rancher-ha.md b/docs/troubleshooting/other-troubleshooting-tips/rancher-ha.md index 8917f80da4d..d0c3957cf62 100644 --- a/docs/troubleshooting/other-troubleshooting-tips/rancher-ha.md +++ b/docs/troubleshooting/other-troubleshooting-tips/rancher-ha.md @@ -74,10 +74,15 @@ kubectl -n ingress-nginx logs -l app=ingress-nginx ### Leader election -The leader is determined by a leader election process. After the leader has been determined, the leader (`holderIdentity`) is saved in the `cattle-controllers` ConfigMap (in this example, `rancher-7dbd7875f7-qbj5k`). +The leader is determined by a leader election process. After the leader has been determined, the leader (`holderIdentity`) is saved in the `cattle-controllers` Lease in the `kube-system` namespace (in this example, `rancher-dbc7ff869-gvg6k`). ``` -kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}' -{"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0} +kubectl -n kube-system get lease cattle-controllers ``` +Example output: + +``` +NAME HOLDER AGE +cattle-controllers rancher-dbc7ff869-gvg6k 6h10m +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current.json b/i18n/zh/docusaurus-plugin-content-docs/current.json index dbdfd9aa227..a1e3cb35335 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current.json @@ -64,26 +64,26 @@ "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": "身份验证配置", + "sidebar.tutorialSidebar.category.Configuring Authentication": { + "message": "配置认证", "description": "The label for category Authentication Config 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" }, - "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" }, - "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" }, - "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" }, @@ -382,5 +382,9 @@ "sidebar.tutorialSidebar.category.Continuous Delivery with Fleet": { "message": "使用 Fleet 进行持续交付", "description": "The label for category Continuous Delivery with Fleet in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Example Workflows": { + "message": "工作流程示例", + "description": "The label for category Example Workflows in sidebar tutorialSidebar" } } diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/api-reference.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/api/api-reference.mdx new file mode 100644 index 00000000000..df4dc6e4f93 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/api-reference.mdx @@ -0,0 +1,17 @@ +--- +title: API 参考 +--- + + + + + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +import ApiDocMdx from '@theme/ApiDocMdx'; + + \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/quickstart.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/quickstart.md new file mode 100644 index 00000000000..20ca51cc34f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/quickstart.md @@ -0,0 +1,152 @@ +--- +title: API 快速入门指南 +--- + + + + + +你可以通过 Kubernetes API 访问 Rancher 的资源。本指南将帮助你以 Rancher 用户的身份开始使用此 API。 + +1. 在左上角，点击 **☰ > 全局设置**. +2. 找到 `server-url` 字段并复制其地址。 +3. [创建](../reference-guides/user-settings/api-keys.md#创建-api-密钥)一个没有作用域的 Rancher API 密钥。 + + :::danger + + 没有作用域的 Rancher API 密钥授予用户可以访问的所有资源的无限制的访问权限。为防止未经授权的使用，此密钥应安全存储并经常轮换。 + + ::: + +4. 创建一个 `kubeconfig.yaml` 文件，将 `$SERVER_URL` 替换成上面从全局设置中复制的地址，并且将 `$API_KEY` 替换为上面创建的 Rancher API 密钥： + + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: "rancher" + cluster: + server: "$SERVER_URL" + + users: + - name: "rancher" + user: + token: "$API_KEY" + + contexts: + - name: "rancher" + context: + user: "rancher" + cluster: "rancher" + + current-context: "rancher" + ``` + +你可以使用任何兼容的工具来引用这个文件，例如 kubectl 或 [client-go](https://github.com/kubernetes/client-go)。快速演示内容请参阅 [kubectl 示例](#api-kubectl-示例) + +更多有关处理更复杂证书的设置信息，请参阅[指定 CA 证书](#指定-ca-证书)。 + +更多关于可用的 kubeconfig 选项，请参阅[上游文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)。 + +## API kubectl 示例 + +在此示例中，我们将展示如何使用 kubectl 创建一个项目，然后删除它。关于其他可用的 Rancher 资源列表，请参阅 [API 参考](./api-reference.mdx)。 + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +1. 将 KUBECONFIG 环境变量设置为刚才创建的 kubeconfig 文件： + + ```bash + export KUBECONFIG=$(pwd)/kubeconfig.yaml + ``` + +2. 使用 `kubectl explain` 查看项目的可用字段，或者复杂资源的子字段： + + ```bash + kubectl explain projects + kubectl explain projects.spec + ``` + +不是所有的资源都有详细的输出。 + +3. 在名称为 `project.yaml` 的文件中添加以下内容： + + ```yaml + apiVersion: management.cattle.io/v3 + kind: Project + metadata: + # name 应在每个集群的所有项目中都是唯一的 + name: p-abc123 + # generateName 可以替代 `name` 来随机生成一个名称 + # generateName: p- + # namespace 应与 spec.ClusterName 匹配 + namespace: local + spec: + # clusterName 应与目标集群的 `metadata.Name` 匹配 + clusterName: local + description: Example Project + # displayName 是人类可读的名称并且从 UI 中显示 + displayName: Example + ``` + +4. 创建项目： + + ```bash + kubectl create -f project.yaml + ``` + +5. 删除项目： + + 项目删除的方式取决于项目名称的创建方式。 + + **A. 如果在创建项目时使用 `name`**： + + ```bash + kubectl delete -f project.yaml + ``` + + **B. 如果你使用 `generateName`**： + + 将 `$PROJECT_NAME` 替换为 kubectl 创建项目后随机生成的项目名称。 + + ```bash + kubectl delete project $PROJECT_NAME -n local + ``` + +## 指定 CA 证书 + +为确保你的工具能够识别 Rancher 的 CA 证书，大多数设置都需要对上述模板进行额外修改。 + +1. 在左上角点击 **☰ > 全局设置**. +2. 查找并复制 `ca-certs` 字段中的值。 +3. 将复制的值保存在名称为 `rancher.crt` 的文件中。 + + :::note + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并将其添加到 kubeconfig 文件中，如步骤 5 所示。 + ::: + +4. 以下命令会将 `rancher.crt` 转换为 base64 输出，除去所有换行符，并使用证书内容更新 kubeconfig 中的 cluster 选项，然后删除 `rancher.crt` 文件： + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n') + rm rancher.crt + ``` +5. （可选项）如果你使用不受系统信任的自签名证书，则可以通过 kubectl 在 kubeconfig 中设置不安全选项： + + :::danger + + 此选项不应该在生产环境中使用，因为它存在安全风险。 + + ::: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.insecure-skip-tls-verify true + ``` + + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并如上面演示的方法，将其添加到 kubeconfig 文件中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/workflows/projects.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/workflows/projects.md new file mode 100644 index 00000000000..27cd6e5c2a9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/workflows/projects.md @@ -0,0 +1,135 @@ +--- +title: 项目 +--- + + + + + +## 创建项目 + +项目资源只能在管理集群上创建，请参考下文了解如何[在管理集群中的项目下创建命名空间](#在项目中创建命名空间) + +### 创建一个基本项目 + +```bash +kubectl create -f - <:` + +## 删除项目 + +在集群命名空间中查找要删除的项目： + +```bash +kubectl --namespace c-m-abcde get projects +``` + +删除集群命名空间下的项目： + +```bash +kubectl --namespace c-m-abcde delete project p-vwxyz +``` + +请注意此命令不会删除以前属于该项目的命名空间和资源。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md new file mode 100644 index 00000000000..710abfc58ec --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md @@ -0,0 +1,127 @@ +--- +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` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +对于 Kubernetes v1.25 或更高版本，使用 Rancher v2.7.2-v2.7.4 时，将 `global.cattle.psp.enabled` 设置为 `false`。对于 Rancher v2.7.5 及更高版本来说，这不是必需的，但你仍然可以手动设置该选项。 + +``` +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/current/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/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md new file mode 100644 index 00000000000..94b0333f481 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/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/overview.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md new file mode 100644 index 00000000000..b9997d6e7b4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/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/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md new file mode 100644 index 00000000000..5838ed66fed --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md @@ -0,0 +1,85 @@ +--- +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 后，我们不支持修改它。请格外小心的设置此项配置。 + +::: + +## 认证 + +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 配置项可以在顶部的导航栏中找到。 + +点击左上角的 **☰** ，然后选择 **全局设置**，查看和配置以下设置： + +- **设置**: 各种 Rancher 默认值，例如用户密码的最小长度 (`password-min-length`)。在修改这些设置项时应该谨慎，因为设置无效的值可能会破坏 Rancher 的安装。 +- **功能开关**: 可以打开或关闭 Rancher 的某些功能，一些标志用于 [实验性功能](#启用实验性功能). +- **横幅**: 可以添加到门户上固定位置的元素，例如你可以使用这些选项在用户登录 Rancher 时为他们设置[自定义的横幅](custom-branding.md#固定横幅)。 +- **品牌**: 你可以[自定义](custom-branding.md) Rancher UI 的设计元素，你可以增加一个自定义的 logo 或 favicon，也可以修改 UI 的颜色。 +- **性能**: Rancher UI 的性能设置，例如增量资源加载。 +- **主页链接**: Rancher UI **主页**页面上显示的链接，你可以修改默认链接的可见性或者增加自己的链接。 + +### 启用实验性功能 + +Rancher 包含一些默认处于实验性和/或禁用的功能，功能开关允许你启用这些特性。更多信息请参考[功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +### 全局配置 + +仅在激活 **legacy** [功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) 时才可以看见**全局配置**选项。在 v2.6 及更新版本新安装的 Rancher 已经默认禁用了 **legacy** 特性。如果你是从早期的 Rancher 版本升级，或者在 Rancher v2.6 及更新版本上启用了 **legacy** 特性，顶部导航菜单中将会显示**全局配置**： + +1. 点击左上角的 **☰**。 +1. 在 **旧版应用** 中选择 **全局配置**。 + +**全局配置**提供以下功能： + +- **应用商店** +- **全局 DNS 条目** +- **全局 DNS 提供商** + +由于这些是旧版特性，请参考 Rancher v2.0-v2.4 的[应用商店](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), [全局 DNS 条目](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#adding-a-global-dns-entry), 以及 [全局 DNS 提供商](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#editing-a-global-dns-provider)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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/current/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/current/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/current/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..83bcfee396b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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 服务器。 @@ -34,7 +38,7 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher ![](/img/adfs/adfs-add-rpt-7.png) -1. 本教程不涉及多重身份验证。如果你想配置多重身份验证，请参见 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)。 +1. 本教程不涉及多重身份认证。如果你想配置多重身份认证，请参见 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)。 ![](/img/adfs/adfs-add-rpt-8.png) @@ -46,7 +50,6 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher ![](/img/adfs/adfs-add-rpt-10.png) - 1. 选择 **Open the Edit Claim Rules...**。然后单击 **Close**。 ![](/img/adfs/adfs-add-rpt-11.png) @@ -61,17 +64,19 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher 1. 将 **Claim rule name** 设置为所需的名称（例如 `Rancher Attributes`）并选择 **Active Directory** 作为 **Attribute store**。创建对应下表的映射： - | LDAP 属性 | 传出声明类型 | - | -------------------------------------------- | ------------------- | - | Given-Name | Given Name | - | User-Principal-Name | UPN | - | Token-Groups - Qualified by Long Domain Name | Group | - | SAM-Account-Name | 名称 | + | LDAP 属性 | 传出声明类型 | + | -------------------------------------------- | ------------ | + | Given-Name | Given Name | + | User-Principal-Name | UPN | + | Token-Groups - Qualified by Long Domain Name | Group | + | SAM-Account-Name | 名称 | +
![](/img/adfs/adfs-add-tcr-2.png) 1. 从 AD 服务器的以下位置下载 `federationmetadata.xml`： + ``` https:///federationmetadata/2007-06/federationmetadata.xml ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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..26e89e2058d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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 服务器的重要说明： @@ -30,16 +34,15 @@ title: 2. 在 Rancher 中配置 Microsoft AD FS ## 配置 -| 字段 | 描述 | -|---------------------------|-----------------| -| 显示名称字段 | 包含用户显示名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | -| 用户名字段 | 包含用户名/给定名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | -| UID 字段 | 每个用户独有的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | -| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`http://schemas.xmlsoap.org/claims/Group` | -| Rancher API 主机 | Rancher Server 的 URL。 | -| 私钥/证书 | 在 Rancher 和你的 AD FS 之间创建安全外壳（SSH）的密钥/证书对。确保将 Common Name (CN) 设置为 Rancher Server URL。

[证书创建命令](#cert-command) | -| 元数据 XML | 从 AD FS 服务器导出的 `federationmetadata.xml` 文件。

你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 找到该文件。 | - +| 字段 | 描述 | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 显示名称字段 | 包含用户显示名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | +| 用户名字段 | 包含用户名/给定名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | +| UID 字段 | 每个用户独有的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | +| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`http://schemas.xmlsoap.org/claims/Group` | +| Rancher API 主机 | Rancher Server 的 URL。 | +| 私钥/证书 | 在 Rancher 和你的 AD FS 之间创建安全外壳（SSH）的密钥/证书对。确保将 Common Name (CN) 设置为 Rancher Server URL。

[证书创建命令](#cert-command) | +| 元数据 XML | 从 AD FS 服务器导出的 `federationmetadata.xml` 文件。

你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 找到该文件。 | @@ -51,4 +54,4 @@ title: 2. 在 Rancher 中配置 Microsoft AD FS openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" ``` -::: \ No newline at end of file +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md b/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md index 581a85efc2c..24c338fe708 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -2,17 +2,20 @@ title: OpenLDAP 配置参考 --- + + + + 有关配置 OpenLDAP 认证的更多详细信息，请参见[官方文档](https://www.openldap.org/doc/)。 -> 在开始之前，请熟悉[外部身份验证配置和主体用户](../../../../pages-for-subheaders/authentication-config.md#外部身份验证配置和用户主体)的概念。 - +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 ## 背景：OpenLDAP 认证流程 1. 当用户尝试使用其 LDAP 凭证登录时，Rancher 会使用具有搜索目录和读取用户/组属性权限的 ServiceAccount，创建与 LDAP 服务器的初始绑定。 2. 然后，Rancher 使用搜索筛选器根据用户名和配置的属性映射为用户搜索目录。 -3. 找到用户后，将使用用户的 DN 和提供的密码，通过另一个 LDAP 绑定请求对用户进行身份验证。 -4. 身份验证成功后，Rancher 将基于用户对象的成员属性和配置的用户映射属性执行组搜索，来解析组成员。 +3. 找到用户后，将使用用户的 DN 和提供的密码，通过另一个 LDAP 绑定请求对用户进行身份认证。 +4. 认证成功后，Rancher 将基于用户对象的成员属性和配置的用户映射属性执行组搜索，来解析组成员。 ## OpenLDAP 服务器配置 @@ -26,16 +29,16 @@ title: OpenLDAP 配置参考
OpenLDAP 服务器参数
-| 参数 | 描述 | -|:--|:--| -| 主机名 | 指定 OpenLDAP 服务器的主机名或 IP 地址。 | -| 端口 | 指定 OpenLDAP 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | -| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。如果服务器使用自签名/企业签名的证书，则还需要粘贴 CA 证书。 | -| 服务器连接超时 | Rancher 在认为无法访问服务器之前等待的时间（秒）。 | -| ServiceAccount 标识名称 | 输入用于绑定，搜索和检索 LDAP 条目的用户的标识名称（DN）。 | -| ServiceAccount 密码 | ServiceAccount 的密码。 | -| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | -| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则，将此字段留空。例如："ou=groups,dc=acme,dc=com"。 | +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| 主机名 | 指定 OpenLDAP 服务器的主机名或 IP 地址。 | +| 端口 | 指定 OpenLDAP 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | +| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。如果服务器使用自签名/企业签名的证书，则还需要粘贴 CA 证书。 | +| 服务器连接超时 | Rancher 在认为无法访问服务器之前等待的时间（秒）。 | +| ServiceAccount 标识名称 | 输入用于绑定，搜索和检索 LDAP 条目的用户的标识名称（DN）。 | +| ServiceAccount 密码 | ServiceAccount 的密码。 | +| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | +| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则，将此字段留空。例如："ou=groups,dc=acme,dc=com"。 | ## 用户/组 Schema 配置 @@ -51,15 +54,15 @@ title: OpenLDAP 配置参考
用户 Schema 配置参数
-| 参数 | 描述 | -|:--|:--| -| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | -| Username Attribute | 用户属性的值适合作为显示名称。 | -| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。通常是 `uid`。 | -| User Member Attribute | 包含用户所属组的标识名称的用户属性。通常是 `memberOf` 或 `isMemberOf`。 | -| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 LDAP 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。 | -| User Enabled Attribute | 如果 OpenLDAP 服务器的 Schema 支持使用用户属性的值来评估账号是禁用还是关闭，请输入该属性的名称。默认的 OpenLDAP Schema 不支持此功能，因此此字段通常留空。 | -| Disabled Status Bitmask | 禁用/锁定的用户账号的值。如果 `User Enabled Attribute` 是空的，则忽略此参数。 | +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Username Attribute | 用户属性的值适合作为显示名称。 | +| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。通常是 `uid`。 | +| User Member Attribute | 包含用户所属组的标识名称的用户属性。通常是 `memberOf` 或 `isMemberOf`。 | +| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 LDAP 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。 | +| User Enabled Attribute | 如果 OpenLDAP 服务器的 Schema 支持使用用户属性的值来评估账号是禁用还是关闭，请输入该属性的名称。默认的 OpenLDAP Schema 不支持此功能，因此此字段通常留空。 | +| Disabled Status Bitmask | 禁用/锁定的用户账号的值。如果 `User Enabled Attribute` 是空的，则忽略此参数。 | ### 组 Schema 配置 @@ -67,12 +70,12 @@ title: OpenLDAP 配置参考
组 Schema 配置参数
-| 参数 | 描述 | -|:--|:--| -| Object Class | 域中用于组条目的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | -| Name Attribute | 名称属性的值适合作为显示名称。 | -| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | -| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | -| Search Attribute | 在 UI 中将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | -| Group DN Attribute | 组属性的名称，其格式与用户的组成员属性中的值匹配。参见 `User Member Attribute`。 | -| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组）。如果你使用 Shibboleth，此选项会被禁用。 | \ No newline at end of file +| 参数 | 描述 | +| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于组条目的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Name Attribute | 名称属性的值适合作为显示名称。 | +| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | +| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | +| Search Attribute | 在 UI 中将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | +| Group DN Attribute | 组属性的名称，其格式与用户的组成员属性中的值匹配。参见 `User Member Attribute`。 | +| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组）。如果你使用 Shibboleth，此选项会被禁用。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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/current/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/current/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/current/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/current/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/current/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/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md index 3fb65c5d7e0..7f7606413f1 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -2,6 +2,10 @@ title: 全局权限 --- + + + + _权限_ 是你在为用户选择自定义权限时可以分配的个人访问权限。 全局权限定义用户在任何特定集群之外的授权。Rancher 提供四种开箱即用的默认全局权限：`Administrator` (管理员)、`Restricted Admin` (受限管理员)、`Standard User` (标准用户) 和 `User-Base` 用户。 @@ -16,8 +20,280 @@ _权限_ 是你在为用户选择自定义权限时可以分配的个人访问 你无法更新或删除内置的全局权限。 +## 分配全局权限 + +本地用户的全局权限分配与使用外部认证登录 Rancher 的用户不同。 + +### 新本地用户的全局权限 + +在创建新本地用户时，请在填写**添加用户**表单时为他分配全局权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在**全局**选项卡的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认全局权限来满足你的需要](#配置默认的全局权限) + +### 使用外部认证登录的用户的全局权限 + +当用户首次使用外部认证登录 Rancher 时，他们会自动分配到**新用户的默认角色**的全局权限。默认情况下，Rancher 为新用户分配 **Standard User** 权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在每个页面的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认权限来满足你的需要](#配置默认的全局权限) + +你可以按照[步骤](#为单个用户配置全局权限)操作来将权限分配给单个用户。 + +如果外部认证服务支持组，你可以[同时为组中的每个成员分配角色](#为组配置全局权限)。 + +## 自定义全局权限 + +使用自定义权限可以为用户提供 Rancher 中更为受限或特定的访问权限。 + +当来自[外部认证](../authentication-config/authentication-config.md)的用户首次登录 Rancher 时，他们会自动分配到一组全局权限（以下简称权限）。默认情况下，用户第一次登录后会被创建为用户，并分配到默认的`用户`权限。标准的`用户`权限允许用户登录和创建集群。 + +但是，在某些组织中，这些权限可能会被认为权限过大。你可以为用户分配一组更具限制性的自定义全局权限，而不是为用户分配 `Administrator` 或 `Standard User` 的默认全局权限。 + +默认角色（管理员和标准用户）都内置了多个全局权限。系统管理员角色包括所有全局权限，而默认用户角色包括三个全局权限，分别是创建集群、使用应用商店模板和 User Base（登录 Rancher 的最低权限）。换句话说，自定义全局权限是模块化的，因此，如果你要更改默认用户角色权限，你可以选择需要包括在新的默认用户角色中的全局权限子集。 + +管理员可以通过多种方式强制执行自定义全局权限： + +- [创建自定义全局角色](#自定义全局角色). +- [更改新用户的默认权限](#配置默认的全局权限). +- [为单个用户配置全局权限](#为单个用户配置全局权限). +- [为组配置全局权限](#为组配置全局权限). + +### 结合内置的全局角色 + +Rancher 提供了多个全局角色，它们为某些常见的用户场景授予了精细的权限。下表列出了每个内置的全局角色（`Administrator`, `Standard User` 和 `User-Base`）以及它包含的默认全局权限 + +| 自定义全局权限 | Administrator | Standard User | User-Base | +| --------------------------- | ------------- | ------------- | --------- | +| 创建集群 | ✓ | ✓ | | +| 创建 RKE 模板 | ✓ | ✓ | | +| 管理认证 | ✓ | | | +| 管理应用商店 | ✓ | | | +| 管理集群驱动 | ✓ | | | +| 管理主机驱动 | ✓ | | | +| 管理 PodSecurityPolicy 模板 | ✓ | | | +| 管理角色 | ✓ | | | +| 管理设置 | ✓ | | | +| Manage Users | ✓ | | | +| 使用应用商店模板 | ✓ | ✓ | | +| User-Base (基本登录访问) | ✓ | ✓ | | + +如果需要查看每个全局权限对应哪些 Kubernetes 资源： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 如果单击单个角色的名称，表格会显示该角色授权的所有操作和资源。 + +:::note 注意事项： + +- 上面列出的每个权限都包含多个未在 Rancher UI 中列出的权限。如果需要获取完整权限列表以及组成权限的规则，请通过 `/v3/globalRoles` API 进行访问。 +- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 + +::: + +### 自定义全局角色 + +当内置的全局角色无法直接满足你的需求时，可以创建自定义全局角色。 + +通过 UI 或自动化（例如 Rancher Kubernetes API） 创建自定义全局角色，你可以指定使用与上游角色和集群角色相同的规则。 + +#### Escalate 与 Bind + +当授予全局角色权限时，请注意 Rancher 遵循 `escalate` 与 `bind`，其方式类似于 [Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update)。 + +在全局角色提供的这两项配置，都可以授予用户绕过 Rancher 提升校验的权限。这可能允许用户成为管理员。由于这有着极高的安全风险，因此应非常谨慎地将 `bind` 和 `escalate` 权限分发给用户。 + +`escalate` 允许用户更改全局角色并添加任何授权，即使用户没有当前或新版本的全局角色权限。 + +`bind` 允许用户对指定的全局角色进行授权（创建 ClusterRoleBinding），即使该用户没有访问全局角色的权限。 + +:::danger + +通配符动词 `*` 也包括 `bind` 和 `escalate`。这意味着为用户的全局角色设置 `*` 也会提供 `escalate` 和 `bind`。 + +::: + +##### 自定义全局角色示例 + +仅为名称为 `test-gr` 的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "escalate" +``` + +为所有的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "escalate" +``` + +仅为名称为 `test-gr` 的全局角色授予创建角色绑定（绕过 escalation 检查）的权限 + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "bind" + - apiGroups: + - "management.cattle.io" + resources: + - "globalrolebindings" + verbs: + - "create" +``` + +授予 `*` 权限（同时包含 `escalate` 与 `bind`） + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "*" +``` + +#### 下游集群的全局角色权限 + +全局角色可以通过 `inheritedClusterRoles` 字段在每个下游集群上授予一个或多个 RoleTemplate。此字段中引用的值必须是集群级别的 RoleTemplate 并且在集群 `context` 中存在。 + +通过此字段，用户将获取当前或未来的所有下游集群的指定权限，例如以下的全局角色示例： + +```yaml +apiVersion: management.cattle.io/v3 +kind: GlobalRole +displayName: All Downstream Owner +metadata: + name: all-downstream-owner +inheritedClusterRoles: + - cluster-owner +``` + +任何具有此权限的用户都将是所有下游集群的所有者（cluster-owner）。如果添加了新的集群，无论是什么类型的集群，用户也将是这个集群的所有者。 + +:::danger + +在[默认的全局角色](#配置默认的全局权限)中使用此字段可能会导致用户获得过多的权限。 + +::: + +### 配置默认的全局权限 + +如果你想限制新用户的默认权限，你可以删除作为默认角色的`用户`权限，然后分配多个单独的权限作为默认权限。你也可以在一组其他标准权限之上添加管理权限。 + +:::note + +默认角色仅分配给从外部认证登录的用户。对于本地用户，在将用户添加到 Rancher 时，必须显式分配全局权限。你可以在添加用户时自定义这些全局权限。 + +::: + +要更改在外部用户首次登录时分配给他们的默认全局权限，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。在**角色**页面上，确保选择了**全局**选项卡。 +1. 查找要添加或删除的默认权限集。然后，通过选择 **⋮ > 编辑配置**来编辑权限。 +1. 如果要将权限添加为默认权限，请选择**是：新用户的默认角色**，然后单击**保存**。如果要删除默认权限，请编辑该权限并选择**否**。 + +**结果**：默认全局权限已根据你的更改配置。分配给新用户的权限会在**新用户的默认角色**列中显示为复选标记。 + +### 为单个用户配置全局权限 + +要为单个用户配置权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 找到要更改访问级别的用户，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**和**内置角色**部分中，选中你希望用户拥有的权限的复选框。如果你在**角色**页面创建了角色，这些角色将出现在**自定义**部分，你也可以选择这些角色。 +1. 单击**保存**。 + +**结果**：用户的全局权限已更新。 + +### 为组配置全局权限 + +如果你有一组需要在 Rancher 中有相同访问权限的用户，你可以一次性将权限分配给整个组来节省时间。这样，组中的用户在第一次登录 Rancher 时能拥有相应级别的访问权限。 + +将自定义全局角色分配给组后，该角色将在组中用户登录 Rancher 时分配给用户。 + +对于现有用户，新权限将在用户退出 Rancher 并重新登录时，或当管理员[刷新用户组成员名单](#刷新用户组成员名单)时生效。 + +对于新用户，新权限在用户首次登录 Rancher 时生效。除了**新用户的默认角色**全局权限外，来自该组的新用户还将获得自定义全局角色的权限。默认情况下，**新用户的默认角色**权限等同于 **Standard User** 全局角色，但默认权限可以[配置。](#配置默认的全局权限) + +如果从外部认证服务中将用户从组中删除，该用户将失去分配给该组的自定义全局角色的权限。他们将继续拥有分配给他们的其他剩余角色，这通常包括标记为**新用户的默认角色**的角色。Rancher 将在用户登出或管理员[刷新用户组成员名单](#刷新用户组成员名单)时删除与组关联的权限。 + +:::note 先决条件： + +只有在以下情况下，你才能将全局角色分配给组： + +- 你已设置[外部认证](../authentication-config/authentication-config.md#external-vs-local-authentication) +- 外部认证服务支持[用户组](../authentication-config/manage-users-and-groups.md) +- 你已使用外部认证服务设置了至少一个用户组。 + +::: + +要将自定义全局角色分配给组，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**组**。 +1. 转到你要分配自定义全局角色的组，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**，**自定义**和/或**内置角色**部分中，选择该组应具有的权限。 +1. 单击**创建**。 + +**结果**：自定义全局角色会在组内用户登录 Rancher 时生效。 + +### 刷新用户组成员名单 + +当管理员更新组的全局权限时，更改将在组成员退出 Rancher 并重新登录后生效。 + +如果要让更改立即生效，管理员或集群所有者可以刷新用户组成员名单。 + +如果用户已经从外部认证服务中的组中删除，管理员也需要刷新用户组成员名单。在这种情况下，刷新操作会让 Rancher 知道用户已从组中删除。 + +要刷新用户组成员名单： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 单击**刷新用户组成员名单**。 + +**结果**：对组成员权限的所有更改都会生效。 + ## 受限管理员 +:::warning 已弃用 + +受限管理员角色已弃用，并将在未来的 Rancher 版本（2.10 或更高版本）中删除。你应该创建具有所需权限的自定义角色，而不是依赖此项内置角色。 + +::: + Rancher 2.5 创建了一个新的 `restricted-admin` 角色，以防止本地 Rancher Server Kubernetes 集群的权限提升。此角色对 Rancher 管理的所有下游集群具有完全管理员权限，但没有更改本地 Kubernetes 集群的权限。 `restricted-admin` 可以创建其他具有同样访问权限的 `restricted-admin` 用户。 @@ -29,9 +305,10 @@ Rancher 还增加了一个新设置，来将初始启动的管理员设置为 `r ``` CATTLE_RESTRICTED_DEFAULT_ADMIN=true ``` -### `restricted-admin` 的权限列表 -下表列出了 `restricted-admin` 与 `Administrator` 和 `Standard User` 角色相比应具有的权限和操作： +### `受限管理员` 的权限列表 + +下表列出了 `受限管理员` 与 `全局管理员` 和 `普通用户` 角色相比应具有的权限和操作： | 类别 | 操作 | 全局管理员 | 普通用户 | 受限管理员 | 受限管理员的注意事项 | | -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- | @@ -42,7 +319,7 @@ CATTLE_RESTRICTED_DEFAULT_ADMIN=true | | 访问 CRD 和 CR 的管理集群 | 是 | 否 | 是 | | | | 另存为 RKE 模板 | 是 | 否 | 否 | | | 安全 | | | | | | -| 启用身份验证 | 配置身份验证 | 是 | 否 | 是 | | +| 启用认证 | 配置认证 | 是 | 否 | 是 | | | 角色 | 创建/分配 GlobalRoles | 是 | 否（可列出） | 是 | 认证 Webhook 允许为已经存在的权限创建 globalrole | | | 创建/分配 ClusterRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | | | 创建/分配 ProjectRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | @@ -81,167 +358,8 @@ CATTLE_RESTRICTED_DEFAULT_ADMIN=true ### 将全局管理员更改为受限管理员 -如果 Rancher 已经有一个全局管理员，则应该将所有全局管理员更改为新的 `restricted-admin`。 +在之前的版本中，文档建议如果管理员角色正在使用中，应将所有用户都更改为受限管理员。现在鼓励用户使用集群权限的功能构建自定义的全局角色，并将受限管理员迁移到新的自定义角色使用。 你可以前往**安全 > 用户**，并将所有管理员角色转为受限管理员。 已登录的用户可以根据需要将自己更改为 `restricted-admin`，但这应该是他们的最后一步操作，否则他们将没有进行该操作的权限。 - -## 分配全局权限 - -本地用户的全局权限分配与使用外部身份验证登录 Rancher 的用户不同。 - -### 新本地用户的全局权限 - -在创建新本地用户时，请在填写**添加用户**表单时为他分配全局权限。 - -如果需要查看新用户的默认权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在**全局**选项卡的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 - -你可以[更改默认全局权限来满足你的需要](#配置默认全局权限)。 - -### 使用外部身份验证程序的用户的全局权限 - -当用户首次使用外部身份验证提供程序登录 Rancher 时，他们会自动分配到**新用户的默认角色**的全局权限。默认情况下，Rancher 为新用户分配 **Standard User** 权限。 - -如果需要查看新用户的默认权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在每个页面的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 - -你可以[更改默认权限来满足你的需要](#配置默认全局权限)。 - -权限可以[分配](#为单个用户配置全局权限)给单个用户。 - -如果外部身份验证提供程序支持组，你可以[同时为组中的每个成员分配角色](#为组配置全局权限)。 - -## 自定义全局权限 - -使用自定义权限可以为用户配置在 Rancher 中的更受限或指定的访问权限。 - -当来自[外部身份验证系统](../../../../pages-for-subheaders/authentication-config.md)的用户首次登录 Rancher 时，他们会自动分配到一组全局权限（以下简称权限）。默认情况下，用户第一次登录后会被创建为用户，并分配到默认的`用户`权限。标准的`用户`权限允许用户登录和创建集群。 - -但是，在某些组织中，这些权限可能会被认为权限过大。你可以为用户分配一组更具限制性的自定义全局权限，而不是为用户分配 `Administrator` 或 `Standard User` 的默认全局权限。 - -默认角色（管理员和标准用户）都内置了多个全局权限。系统管理员角色包括所有全局权限，而默认用户角色包括三个全局权限，分别是创建集群，使用应用商店模板，和 User Base（登录 Rancher 的最低权限）。换句话说，自定义全局权限是模块化的，因此，如果你要更改默认用户角色权限，你可以选择需要包括在新的默认用户角色中的全局权限子集。 - -管理员可以通过多种方式强制执行自定义全局权限： - -- [更改新用户的默认权限](#配置默认全局权限) -- [为单个用户配置全局权限](#为单个用户配置全局权限) -- [为组配置全局权限](#为组配置全局权限) - -### 自定义全局权限参考 - -下表列出了每个可用的自定义全局权限，以及该权限是否包含在默认全局权限 `Administrator`、`Standard User` 和 `User-Base` 中： - -| 自定义全局权限 | 管理员 | 普通用户 | User-Base | -| ---------------------------------- | ------------- | ------------- |-----------| -| 创建集群 | ✓ | ✓ | | -| 创建 RKE 模板 | ✓ | ✓ | | -| 管理身份验证 | ✓ | | | -| 管理应用商店 | ✓ | | | -| 管理集群驱动 | ✓ | | | -| 管理主机驱动 | ✓ | | | -| 管理 PodSecurityPolicy 模板 | ✓ | | | -| 管理角色 | ✓ | | | -| 管理设置 | ✓ | | | -| 管理用户 | ✓ | | | -| 使用应用商店模板 | ✓ | ✓ | | -| User-Base（基本登录访问） | ✓ | ✓ | | - -如果需要查看每个全局权限对应哪些 Kubernetes 资源： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. 如果单击单个角色的名称，表格会显示该角色授权的所有操作和资源。 - -:::note 注意事项： - -- 上面列出的每个权限都包含多个未在 Rancher UI 中列出的权限。如果需要获取完整权限列表以及组成权限的规则，请通过 `/v3/globalRoles` API 进行访问。 -- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 - -::: - -### 配置默认全局权限 - -如果你想限制新用户的默认权限，你可以删除作为默认角色的`用户`权限，然后分配多个单独的权限作为默认权限。你也可以在一组其他标准权限之上添加管理权限。 - -:::note - -默认角色仅分配给从外部身份验证提供程序添加的用户。对于本地用户，在将用户添加到 Rancher 时，必须显式分配全局权限。你可以在添加用户时自定义这些全局权限。 - -::: - -要更改在外部用户首次登录时分配给他们的默认全局权限，请执行以下步骤： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。在**角色**页面上，确保选择了**全局**选项卡。 -1. 查找要添加或删除的默认权限集。然后，通过选择 **⋮ > 编辑配置**来编辑权限。 -1. 如果要将权限添加为默认权限，请选择**是：新用户的默认角色**，然后单击**保存**。如果要删除默认权限，请编辑该权限并选择**否**。 - -**结果**：默认全局权限已根据你的更改配置。分配给新用户的权限会在**新用户的默认角色**列中显示为复选标记。 - -### 为单个用户配置全局权限 - -要为单个用户配置权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**用户**。 -1. 找到要更改访问级别的用户，然后单击 **⋮ > 编辑配置**。 -1. 在**全局权限**和**内置角色**部分中，选中你希望用户拥有的权限的复选框。如果你在**角色**页面创建了角色，这些角色将出现在**自定义**部分，你也可以选择这些角色。 -1. 单击**保存**。 - -**结果**：用户的全局权限已更新。 - -### 为组配置全局权限 - -如果你有一组需要在 Rancher 中有相同访问权限的用户，你可以一次性将权限分配给整个组来节省时间。这样，组中的用户在第一次登录 Rancher 时能拥有相应级别的访问权限。 - -将自定义全局角色分配给组后，该角色将在组中用户登录 Rancher 时分配给用户。 - -对于现有用户，新权限将在用户退出 Rancher 并重新登录时，或当管理员[刷新用户组成员名单](#刷新用户组成员名单)时生效。 - -对于新用户，新权限在用户首次登录 Rancher 时生效。除了**新用户的默认角色**全局权限外，来自该组的新用户还将获得自定义全局角色的权限。默认情况下，**新用户的默认角色**权限等同于 **Standard User** 全局角色，但默认权限可以[配置。](#配置默认全局权限) - -如果从外部身份验证提供程序组中删除用户，该用户将失去分配给该组的自定义全局角色的权限。他们将继续拥有分配给他们的所有剩余角色，这通常包括标记为**新用户的默认角色**的角色。Rancher 将在用户登出或管理员[刷新用户组成员名单](#刷新用户组成员名单)时删除与组关联的权限。 - -:::note 先决条件： - -只有在以下情况下，你才能将全局角色分配给组： - -* 你已设置[外部身份验证提供程序](../../../../pages-for-subheaders/authentication-config.md#外部验证与本地验证)。 -* 外部身份验证提供程序支持[用户组](../authentication-config/manage-users-and-groups.md)。 -* 你已使用身份验证提供程序设置了至少一个用户组。 - -::: - -要将自定义全局角色分配给组，请执行以下步骤： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**组**。 -1. 转到你要分配自定义全局角色的组，然后单击 **⋮ > 编辑配置**。 -1. 在**全局权限**，**自定义**和/或**内置角色**部分中，选择该组应具有的权限。 -1. 单击**创建**。 - -**结果**：自定义全局角色会在组内用户登录 Rancher 时生效。 - -### 刷新用户组成员名单 - -当管理员更新组的全局权限时，更改将在组成员退出 Rancher 并重新登录后生效。 - -如果要让更改立即生效，管理员或集群所有者可以刷新用户组成员名单。 - -如果用户已经从外部身份验证服务中的组中删除，管理员也可能需要刷新用户组成员名单。在这种情况下，刷新操作会让 Rancher 知道用户已从组中删除。 - -要刷新用户组成员名单： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**用户**。 -1. 单击**刷新用户组成员名单**。 - -**结果**：对组成员权限的所有更改都会生效。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/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/current/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/current/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/current/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/current/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..dd034e3daf8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/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/current/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md new file mode 100644 index 00000000000..cc4e205c941 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md @@ -0,0 +1,84 @@ +--- +title: 使用 Rancher 启动 Kubernetes +--- + + + + + +Rancher 可以使用任意节点启动 Kubernetes 集群。在 Rancher 中将 Kubernetes 部署到这些节点上时，你可以选择 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) 或 [RKE2](https://docs.rke2.io) 发行版。Rancher 可以在任何计算机上启动 Kubernetes，包括： + +- 裸金属服务器 +- 本地虚拟机 +- 由云厂商托管的虚拟机 + +Rancher 可以在现有节点上安装 Kubernetes，也可以在云厂商中动态配置节点并安装 Kubernetes。 + +Rancher 还可以创建节点池。在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +## RKE + +### 要求 + +如果你使用 RKE 建立集群，节点必须满足下游集群的[节点要求](../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)。 + +### 在云厂商的新节点上启动 Kubernetes + +使用 Rancher，你可以基于[节点模板](use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此节点模板定义了要用于在云厂商中启动节点的参数。 + +在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +有关详细信息，请参阅[在新节点上启动 Kubernetes](use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)。 + +### 在现有自定义节点上启动 Kubernetes + +在这种情况下，你希望将 Kubernetes 安装到裸机服务器、本地虚拟机或云厂商中已存在的虚拟机上。使用此选项，你将在主机上运行 Rancher Agent Docker 容器。 + +如果要重复使用之前的自定义集群中的节点，请在复用之前[清理节点](../manage-clusters/clean-cluster-nodes.md)。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +有关详细信息，请参阅[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)。 + +### 以编程方式创建 RKE 集群 + +通过 Rancher 以编程方式部署 RKE 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 + +## RKE2 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。在 Rancher 2.6.4 及更早版本中，RKE2 配置还处于技术预览阶段。 + +在 Rancher 2.6.5 中，RKE2 已经 GA。 + +### 要求 + +如果你使用 RKE2 建立集群，节点必须满足下游集群的[节点要求](https://docs.rke2.io/install/requirements)。 + +### 在云厂商的新节点上启动 Kubernetes + +RKE2 基于使用上游[集群 API](https://github.com/kubernetes-sigs/cluster-api) 项目的新配置框架。这个新配置框架支持： + +- 将 RKE2 集群配置到 Rancher 具有主机驱动的任何提供商上 +- 完全在 Rancher 中配置 RKE2 集群 +- 除了 Canal 之外，还可以选择 CNI 选项， Calico、Cilium 和 Multus + +RKE2 配置还包括在具有 Windows 节点的集群上安装 RKE2。 + +RKE2 的 Windows 功能包括： + +- Windows 支持 vSphere 主机驱动 +- 用于 Windows RKE2 自定义集群的 Calico CNI +- Calico 的项目网络隔离 (PNI) +- 由 containerd 提供支持的使用 RKE2 的 Windows 容器 +- 通过 Terraform 配置 Windows RKE2 集群 +- 直接从 Rancher UI 配置 Windows RKE2 自定义集群 + +要使 Windows 支持 RKE2 自定义集群，请选择 Calico 作为 CNI。 + +### 在现有自定义节点上启动 Kubernetes + +RKE2 还支持在预配置的虚拟机或裸机节点上安装自定义集群。 + +如果要重复使用之前的自定义集群中的节点，请在复用之前清理节点。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +### 以编程方式创建 RKE2 集群 + +通过 Rancher 以编程方式部署 RKE2 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/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 b/i18n/zh/docusaurus-plugin-content-docs/current/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 new file mode 100644 index 00000000000..5bc6d65b953 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/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 @@ -0,0 +1,156 @@ +--- +title: 在云厂商的新节点上启动 Kubernetes +--- + + + + + +在 Rancher 中使用节点模板来创建 RKE 或 RKE2 集群时，每个生成的节点池都会显示在新的**主机池**选项卡中。你可以通过执行以下操作来查看主机池： + +1. 点击**☰ > 集群管理**。 +1. 单击 RKE 或 RKE2 集群的名称。 + +## RKE 集群 + +使用 Rancher，你可以基于[节点模板](use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此节点模板定义了要用于在基础设施提供商或云厂商中启动节点的参数。 + +在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +可用于创建节点模板的云提供商是由[主机驱动](use-new-nodes-in-an-infra-provider.md#主机驱动)决定的。 + +### 节点模板 + +节点模板保存了用于在特定云提供商中配置节点时要使用的参数。这些节点可以从 UI 启动。Rancher 使用 [Docker Machine](https://docs.docker.com/machine/) 来配置这些节点。可用于创建节点模板的云提供商取决于 Rancher 中状态是 Active 的主机驱动。 + +在 Rancher 中创建节点模板后，模板会被保存，以便你可以再次使用该模板来创建节点池。节点模板绑定到你的登录名。添加模板后，你可以将其从用户配置文件中删除。 + +#### 节点标签 + +你可以为每个节点模板添加[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)，这样，使用节点模板创建的节点都会自动带有这些标签。 + +无效标签会阻止升级，或阻止 Rancher 启动。有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +#### 节点污点 + +你可以为每个节点模板添加[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，这样，使用节点模板创建的节点都会自动带有这些污点。 + +由于污点可以同时添加到节点模板和节点池中，因此如果添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点模板的管理员控制 + +管理员可以控制所有节点模板。现在，管理员可以维护 Rancher 中的所有节点模板。当节点模板所有者不再使用 Rancher 时，他们创建的节点模板可以由管理员管理，以便继续更新和维护集群。 + +要访问所有节点模板，管理员需要执行以下操作： + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 + +**结果**：列出所有节点模板。你可以通过单击 **⋮** 来编辑或克隆模板。 + +### 节点池 + +使用 Rancher，你可以基于[节点模板](#节点模板)创建节点池。 + +节点模板定义了节点的配置，例如要使用的操作系统、CPU 数量和内存量。 + +使用节点池的好处是，如果一个节点被销毁或删除，你可以增加 Active 节点的数量来补偿丢失的节点。节点池可以帮助你确保节点池的计数符合要求。 + +每个节点池必须分配一个或多个节点角色。 + +每个节点角色（即 etcd、controlplane 和 worker）都应分配给不同的节点池。虽然你可以将多个节点角色分配给同一个节点池，但不要在生产集群中执行此操作。 + +推荐的设置： + +- 具有 etcd 角色且计数为 3 的节点池 +- 具有 controlplane 角色且计数至少为 2 的节点池 +- 具有 worker 角色且计数至少为 2 的节点池 + +**离线环境中的 RKE1 下游集群节点**： + +默认情况下，在配置 RKE1 下游集群节点时（例如在 vSphere 中），Rancher 会尝试运行 Docker 安装脚本。但是，Rancher Docker 安装脚本在离线环境中会运行失败。要解决此问题，如果 Docker 已预安装到 VM 镜像上，你可以选择在创建节点模板时跳过安装 Docker。为此，你可以在 Rancher UI **引擎选项**下的 `Docker 安装 URL` 下拉列表中选择 **无**。 + +
**引擎选项下拉列表**
+ +![引擎选项下拉列表](/img/node-template-engine-options-rke1.png) + +#### 节点池污点 + +如果你没有在节点模板上定义[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，则可以为每个节点池添加污点。将污点添加到节点池的好处是你可以更改节点模板，而不需要先确保污点存在于新模板中。 + +每个污点都将自动添加到节点池中已创建的节点。因此，如果你在已有节点的节点池中添加污点，污点不会应用到已有的节点，但是添加到该节点池中的新节点都将获得该污点。 + +如果污点同时添加到节点模板和节点池中，且添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点自动替换 + +Rancher 可以自动替换节点池中无法访问的节点。如果节点在指定的时间中处于 Inactive 状态，Rancher 将使用该节点池的节点模板来重新创建节点。 + +:::caution + +自我修复节点池的功能帮助你替换无状态应用的 worker 节点。不建议在 master 节点或连接了持久卷的节点的节点池上启用节点自动替换，因为虚拟机会被临时处理。节点池中的节点与集群断开连接时，其持久卷将被破坏，从而导致有状态应用的数据丢失。 + +::: + +节点自动替换基于 Kubernetes 节点控制器工作。节点控制器定期检查所有节点的状态（可通过 `kube-controller` 的 `--node-monitor-period` 标志配置）。一个节点不可访问时，节点控制器将污染该节点。发生这种情况时，Rancher 将开始其删除倒计时。你可以配置 Rancher 等待删除节点的时间。如果在删除倒计时结束前污点没有被删除，Rancher 将继续删除该节点。Rancher 会根据节点池设置的数量来创建新的节点。 + +#### 启用节点自动替换 + +创建节点池时，你可以指定 Rancher 替换无响应节点的等待时间（以分钟为单位）。 + +1. 在创建或编辑集群的表单中，转到**节点池**。 +1. 转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 Rancher 在替换节点之前应该等待节点响应的分钟数。 +1. 填写表单的其余部分以创建或编辑集群。 + +**结果** ：已为节点池启用节点自动替换。 + +#### 禁用节点自动替换 + +你可以执行以下步骤从 Rancher UI 禁用节点自动替换： + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要禁用节点自动替换的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**节点池**部分中，转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 0。 +1. 单击**保存**。 + +**结果**：已禁用节点池的节点自动替换。 + +### 云凭证 + +节点模板可以使用云凭证，来存储用于在云提供商中启动节点的凭证，其优点是： + +- 凭证会存储为更安全的 Kubernetes 密文，而且你无需每次都输入凭证便可编辑节点模板。 + +- 创建云凭证后，你可以重新使用该凭证来创建其他节点模板。 + +- 多个节点模板可以使用相同的云凭证来创建节点池。如果你的密钥被泄露或过期，则可以在一个位置更新云凭证，从而一次更新所有使用该凭证的节点模板。 + +创建云凭证后，用户可以[管理创建的云凭证](../../../../reference-guides/user-settings/manage-cloud-credentials.md)。 + +### 主机驱动 + +如果你找不到想要的主机驱动，你可以在 Rancher 的[内置主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#激活停用主机驱动)中查看并激活它，也可以[添加自定义主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#添加自定义主机驱动)。 + +## RKE2 集群 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。 + +:::note + +对于 RKE2 集群模板，请参阅[此页面](../../manage-clusters/manage-cluster-templates.md#rke2-集群模板)了解更多信息。 + +::: + +### 节点角色 + +RKE2 CLI 公开了 `server` 和 `agent` 两个角色，它们分别代表 Kubernetes 节点角色 `etcd` + `controlplane` 和 `worker`。通过 Rancher 2.6 中的 RKE2 集成，RKE2 节点池可以分配更细粒度的角色，例如 `etcd` 和 `controlplane`。 + +你可以在 RKE2 CLI 中使用标志和节点污染，来控制调度工作负载和 Kubernetes master 节点的位置，从而使用 `etcd`，`controlplane` 和 `worker` 节点功能。这些角色没有在 RKE2 CLI 中实现为第一级角色的原因是，RKE2 被概念化为一组原始构建块，使用 Rancher 等编排系统得到最佳利用。 + +在 Rancher 中实现这三个节点角色，表示 Rancher 管理的 RKE2 集群能够轻松使用为 RKE 集群推荐的相同架构的所有最佳实践。 + +在[推荐的集群架构](../../kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md)中，我们概述了每个角色集群应该有多少节点： + +- 至少拥有三个角色为 etcd 的节点，来确保失去一个节点时仍能存活。 +- 至少两个节点具有 controlplane 角色，以实现主组件高可用性。 +- 至少两个具有 worker 角色的节点，用于在节点故障时重新安排工作负载。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/new-user-guides.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/new-user-guides.md new file mode 100644 index 00000000000..91cfa77fe1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/new-user-guides.md @@ -0,0 +1,13 @@ +--- +title: 新用户指南 +--- + + + + + +新用户指南，也称为 **教程**，描述了用户在完成一些具体操作时要遵循的实用步骤。这些文档被称为“以学习为导向”的文档，用户通过“实际操作”来学习。 + +新用户指南旨在指导初学者或 Rancher 的日常用户通过一系列步骤来学习如何做某件事。目标是让用户可以通过易于操作、有意义的、可重复的指示来学习如何完成任务。这些指南将帮助用户完成工作，然后立即获得承诺的结果。 + +普通的 Rancher 用户的技术水平高于“初学者”，但是新用户指南旨在同等的帮助新用户、初学者以及经验丰富的 Rancher 客户，这是通过结合使用高级和技术语言来介绍主题并指导用户完成每个 Rancher 用户都必须了解的一般任务来实现的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/troubleshooting/kubernetes-components/kubernetes-components.md b/i18n/zh/docusaurus-plugin-content-docs/current/troubleshooting/kubernetes-components/kubernetes-components.md new file mode 100644 index 00000000000..38bcba2810d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/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/current/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/current/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md index 9c370685084..d64215cebd2 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md @@ -2,6 +2,10 @@ title: etcd 节点故障排除 --- + + + + 本文介绍了对具有 `etcd` 角色的节点进行故障排除的命令和提示。 @@ -47,13 +51,6 @@ docker logs etcd docker exec etcd etcdctl member list ``` -输出示例： -``` -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -``` - ### 检查端点状态 `RAFT TERM` 的值应该是相等的，而且 `RAFT INDEX` 相差不能太大。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8.json b/i18n/zh/docusaurus-plugin-content-docs/version-2.8.json index 42af6504026..2518b00a8d9 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8.json +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8.json @@ -64,26 +64,26 @@ "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": "身份验证配置", + "sidebar.tutorialSidebar.category.Configuring Authentication": { + "message": "配置认证", "description": "The label for category Authentication Config 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" }, - "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" }, - "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" }, - "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" }, @@ -382,6 +382,10 @@ "sidebar.tutorialSidebar.category.Continuous Delivery with Fleet": { "message": "使用 Fleet 进行持续交付", "description": "The label for category Continuous Delivery with Fleet in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.Example Workflows": { + "message": "工作流程示例", + "description": "The label for category Example Workflows in sidebar tutorialSidebar" } } \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/api-reference.mdx b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/api-reference.mdx new file mode 100644 index 00000000000..df4dc6e4f93 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/api-reference.mdx @@ -0,0 +1,17 @@ +--- +title: API 参考 +--- + + + + + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +import ApiDocMdx from '@theme/ApiDocMdx'; + + \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/quickstart.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/quickstart.md new file mode 100644 index 00000000000..20ca51cc34f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/quickstart.md @@ -0,0 +1,152 @@ +--- +title: API 快速入门指南 +--- + + + + + +你可以通过 Kubernetes API 访问 Rancher 的资源。本指南将帮助你以 Rancher 用户的身份开始使用此 API。 + +1. 在左上角，点击 **☰ > 全局设置**. +2. 找到 `server-url` 字段并复制其地址。 +3. [创建](../reference-guides/user-settings/api-keys.md#创建-api-密钥)一个没有作用域的 Rancher API 密钥。 + + :::danger + + 没有作用域的 Rancher API 密钥授予用户可以访问的所有资源的无限制的访问权限。为防止未经授权的使用，此密钥应安全存储并经常轮换。 + + ::: + +4. 创建一个 `kubeconfig.yaml` 文件，将 `$SERVER_URL` 替换成上面从全局设置中复制的地址，并且将 `$API_KEY` 替换为上面创建的 Rancher API 密钥： + + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: "rancher" + cluster: + server: "$SERVER_URL" + + users: + - name: "rancher" + user: + token: "$API_KEY" + + contexts: + - name: "rancher" + context: + user: "rancher" + cluster: "rancher" + + current-context: "rancher" + ``` + +你可以使用任何兼容的工具来引用这个文件，例如 kubectl 或 [client-go](https://github.com/kubernetes/client-go)。快速演示内容请参阅 [kubectl 示例](#api-kubectl-示例) + +更多有关处理更复杂证书的设置信息，请参阅[指定 CA 证书](#指定-ca-证书)。 + +更多关于可用的 kubeconfig 选项，请参阅[上游文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)。 + +## API kubectl 示例 + +在此示例中，我们将展示如何使用 kubectl 创建一个项目，然后删除它。关于其他可用的 Rancher 资源列表，请参阅 [API 参考](./api-reference.mdx)。 + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +1. 将 KUBECONFIG 环境变量设置为刚才创建的 kubeconfig 文件： + + ```bash + export KUBECONFIG=$(pwd)/kubeconfig.yaml + ``` + +2. 使用 `kubectl explain` 查看项目的可用字段，或者复杂资源的子字段： + + ```bash + kubectl explain projects + kubectl explain projects.spec + ``` + +不是所有的资源都有详细的输出。 + +3. 在名称为 `project.yaml` 的文件中添加以下内容： + + ```yaml + apiVersion: management.cattle.io/v3 + kind: Project + metadata: + # name 应在每个集群的所有项目中都是唯一的 + name: p-abc123 + # generateName 可以替代 `name` 来随机生成一个名称 + # generateName: p- + # namespace 应与 spec.ClusterName 匹配 + namespace: local + spec: + # clusterName 应与目标集群的 `metadata.Name` 匹配 + clusterName: local + description: Example Project + # displayName 是人类可读的名称并且从 UI 中显示 + displayName: Example + ``` + +4. 创建项目： + + ```bash + kubectl create -f project.yaml + ``` + +5. 删除项目： + + 项目删除的方式取决于项目名称的创建方式。 + + **A. 如果在创建项目时使用 `name`**： + + ```bash + kubectl delete -f project.yaml + ``` + + **B. 如果你使用 `generateName`**： + + 将 `$PROJECT_NAME` 替换为 kubectl 创建项目后随机生成的项目名称。 + + ```bash + kubectl delete project $PROJECT_NAME -n local + ``` + +## 指定 CA 证书 + +为确保你的工具能够识别 Rancher 的 CA 证书，大多数设置都需要对上述模板进行额外修改。 + +1. 在左上角点击 **☰ > 全局设置**. +2. 查找并复制 `ca-certs` 字段中的值。 +3. 将复制的值保存在名称为 `rancher.crt` 的文件中。 + + :::note + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并将其添加到 kubeconfig 文件中，如步骤 5 所示。 + ::: + +4. 以下命令会将 `rancher.crt` 转换为 base64 输出，除去所有换行符，并使用证书内容更新 kubeconfig 中的 cluster 选项，然后删除 `rancher.crt` 文件： + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n') + rm rancher.crt + ``` +5. （可选项）如果你使用不受系统信任的自签名证书，则可以通过 kubectl 在 kubeconfig 中设置不安全选项： + + :::danger + + 此选项不应该在生产环境中使用，因为它存在安全风险。 + + ::: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.insecure-skip-tls-verify true + ``` + + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并如上面演示的方法，将其添加到 kubeconfig 文件中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/workflows/projects.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/workflows/projects.md new file mode 100644 index 00000000000..27cd6e5c2a9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/api/workflows/projects.md @@ -0,0 +1,135 @@ +--- +title: 项目 +--- + + + + + +## 创建项目 + +项目资源只能在管理集群上创建，请参考下文了解如何[在管理集群中的项目下创建命名空间](#在项目中创建命名空间) + +### 创建一个基本项目 + +```bash +kubectl create -f - <:` + +## 删除项目 + +在集群命名空间中查找要删除的项目： + +```bash +kubectl --namespace c-m-abcde get projects +``` + +删除集群命名空间下的项目： + +```bash +kubectl --namespace c-m-abcde delete project p-vwxyz +``` + +请注意此命令不会删除以前属于该项目的命名空间和资源。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md new file mode 100644 index 00000000000..710abfc58ec --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md @@ -0,0 +1,127 @@ +--- +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` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +对于 Kubernetes v1.25 或更高版本，使用 Rancher v2.7.2-v2.7.4 时，将 `global.cattle.psp.enabled` 设置为 `false`。对于 Rancher v2.7.5 及更高版本来说，这不是必需的，但你仍然可以手动设置该选项。 + +``` +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.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md new file mode 100644 index 00000000000..94b0333f481 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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/overview.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md new file mode 100644 index 00000000000..b9997d6e7b4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md new file mode 100644 index 00000000000..5838ed66fed --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md @@ -0,0 +1,85 @@ +--- +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 后，我们不支持修改它。请格外小心的设置此项配置。 + +::: + +## 认证 + +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 配置项可以在顶部的导航栏中找到。 + +点击左上角的 **☰** ，然后选择 **全局设置**，查看和配置以下设置： + +- **设置**: 各种 Rancher 默认值，例如用户密码的最小长度 (`password-min-length`)。在修改这些设置项时应该谨慎，因为设置无效的值可能会破坏 Rancher 的安装。 +- **功能开关**: 可以打开或关闭 Rancher 的某些功能，一些标志用于 [实验性功能](#启用实验性功能). +- **横幅**: 可以添加到门户上固定位置的元素，例如你可以使用这些选项在用户登录 Rancher 时为他们设置[自定义的横幅](custom-branding.md#固定横幅)。 +- **品牌**: 你可以[自定义](custom-branding.md) Rancher UI 的设计元素，你可以增加一个自定义的 logo 或 favicon，也可以修改 UI 的颜色。 +- **性能**: Rancher UI 的性能设置，例如增量资源加载。 +- **主页链接**: Rancher UI **主页**页面上显示的链接，你可以修改默认链接的可见性或者增加自己的链接。 + +### 启用实验性功能 + +Rancher 包含一些默认处于实验性和/或禁用的功能，功能开关允许你启用这些特性。更多信息请参考[功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +### 全局配置 + +仅在激活 **legacy** [功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) 时才可以看见**全局配置**选项。在 v2.6 及更新版本新安装的 Rancher 已经默认禁用了 **legacy** 特性。如果你是从早期的 Rancher 版本升级，或者在 Rancher v2.6 及更新版本上启用了 **legacy** 特性，顶部导航菜单中将会显示**全局配置**： + +1. 点击左上角的 **☰**。 +1. 在 **旧版应用** 中选择 **全局配置**。 + +**全局配置**提供以下功能： + +- **应用商店** +- **全局 DNS 条目** +- **全局 DNS 提供商** + +由于这些是旧版特性，请参考 Rancher v2.0-v2.4 的[应用商店](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), [全局 DNS 条目](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#adding-a-global-dns-entry), 以及 [全局 DNS 提供商](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#editing-a-global-dns-provider)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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.8/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.8/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.8/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..83bcfee396b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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 服务器。 @@ -34,7 +38,7 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher ![](/img/adfs/adfs-add-rpt-7.png) -1. 本教程不涉及多重身份验证。如果你想配置多重身份验证，请参见 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)。 +1. 本教程不涉及多重身份认证。如果你想配置多重身份认证，请参见 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)。 ![](/img/adfs/adfs-add-rpt-8.png) @@ -46,7 +50,6 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher ![](/img/adfs/adfs-add-rpt-10.png) - 1. 选择 **Open the Edit Claim Rules...**。然后单击 **Close**。 ![](/img/adfs/adfs-add-rpt-11.png) @@ -61,17 +64,19 @@ title: 1. 在 Microsoft AD FS 中配置 Rancher 1. 将 **Claim rule name** 设置为所需的名称（例如 `Rancher Attributes`）并选择 **Active Directory** 作为 **Attribute store**。创建对应下表的映射： - | LDAP 属性 | 传出声明类型 | - | -------------------------------------------- | ------------------- | - | Given-Name | Given Name | - | User-Principal-Name | UPN | - | Token-Groups - Qualified by Long Domain Name | Group | - | SAM-Account-Name | 名称 | + | LDAP 属性 | 传出声明类型 | + | -------------------------------------------- | ------------ | + | Given-Name | Given Name | + | User-Principal-Name | UPN | + | Token-Groups - Qualified by Long Domain Name | Group | + | SAM-Account-Name | 名称 | +
![](/img/adfs/adfs-add-tcr-2.png) 1. 从 AD 服务器的以下位置下载 `federationmetadata.xml`： + ``` https:///federationmetadata/2007-06/federationmetadata.xml ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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..26e89e2058d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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 服务器的重要说明： @@ -30,16 +34,15 @@ title: 2. 在 Rancher 中配置 Microsoft AD FS ## 配置 -| 字段 | 描述 | -|---------------------------|-----------------| -| 显示名称字段 | 包含用户显示名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | -| 用户名字段 | 包含用户名/给定名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | -| UID 字段 | 每个用户独有的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | -| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`http://schemas.xmlsoap.org/claims/Group` | -| Rancher API 主机 | Rancher Server 的 URL。 | -| 私钥/证书 | 在 Rancher 和你的 AD FS 之间创建安全外壳（SSH）的密钥/证书对。确保将 Common Name (CN) 设置为 Rancher Server URL。

[证书创建命令](#cert-command) | -| 元数据 XML | 从 AD FS 服务器导出的 `federationmetadata.xml` 文件。

你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 找到该文件。 | - +| 字段 | 描述 | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 显示名称字段 | 包含用户显示名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | +| 用户名字段 | 包含用户名/给定名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | +| UID 字段 | 每个用户独有的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | +| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`http://schemas.xmlsoap.org/claims/Group` | +| Rancher API 主机 | Rancher Server 的 URL。 | +| 私钥/证书 | 在 Rancher 和你的 AD FS 之间创建安全外壳（SSH）的密钥/证书对。确保将 Common Name (CN) 设置为 Rancher Server URL。

[证书创建命令](#cert-command) | +| 元数据 XML | 从 AD FS 服务器导出的 `federationmetadata.xml` 文件。

你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 找到该文件。 | @@ -51,4 +54,4 @@ title: 2. 在 Rancher 中配置 Microsoft AD FS openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" ``` -::: \ No newline at end of file +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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.8/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.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md index 581a85efc2c..24c338fe708 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -2,17 +2,20 @@ title: OpenLDAP 配置参考 --- + + + + 有关配置 OpenLDAP 认证的更多详细信息，请参见[官方文档](https://www.openldap.org/doc/)。 -> 在开始之前，请熟悉[外部身份验证配置和主体用户](../../../../pages-for-subheaders/authentication-config.md#外部身份验证配置和用户主体)的概念。 - +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 ## 背景：OpenLDAP 认证流程 1. 当用户尝试使用其 LDAP 凭证登录时，Rancher 会使用具有搜索目录和读取用户/组属性权限的 ServiceAccount，创建与 LDAP 服务器的初始绑定。 2. 然后，Rancher 使用搜索筛选器根据用户名和配置的属性映射为用户搜索目录。 -3. 找到用户后，将使用用户的 DN 和提供的密码，通过另一个 LDAP 绑定请求对用户进行身份验证。 -4. 身份验证成功后，Rancher 将基于用户对象的成员属性和配置的用户映射属性执行组搜索，来解析组成员。 +3. 找到用户后，将使用用户的 DN 和提供的密码，通过另一个 LDAP 绑定请求对用户进行身份认证。 +4. 认证成功后，Rancher 将基于用户对象的成员属性和配置的用户映射属性执行组搜索，来解析组成员。 ## OpenLDAP 服务器配置 @@ -26,16 +29,16 @@ title: OpenLDAP 配置参考
OpenLDAP 服务器参数
-| 参数 | 描述 | -|:--|:--| -| 主机名 | 指定 OpenLDAP 服务器的主机名或 IP 地址。 | -| 端口 | 指定 OpenLDAP 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | -| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。如果服务器使用自签名/企业签名的证书，则还需要粘贴 CA 证书。 | -| 服务器连接超时 | Rancher 在认为无法访问服务器之前等待的时间（秒）。 | -| ServiceAccount 标识名称 | 输入用于绑定，搜索和检索 LDAP 条目的用户的标识名称（DN）。 | -| ServiceAccount 密码 | ServiceAccount 的密码。 | -| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | -| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则，将此字段留空。例如："ou=groups,dc=acme,dc=com"。 | +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| 主机名 | 指定 OpenLDAP 服务器的主机名或 IP 地址。 | +| 端口 | 指定 OpenLDAP 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | +| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。如果服务器使用自签名/企业签名的证书，则还需要粘贴 CA 证书。 | +| 服务器连接超时 | Rancher 在认为无法访问服务器之前等待的时间（秒）。 | +| ServiceAccount 标识名称 | 输入用于绑定，搜索和检索 LDAP 条目的用户的标识名称（DN）。 | +| ServiceAccount 密码 | ServiceAccount 的密码。 | +| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | +| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则，将此字段留空。例如："ou=groups,dc=acme,dc=com"。 | ## 用户/组 Schema 配置 @@ -51,15 +54,15 @@ title: OpenLDAP 配置参考
用户 Schema 配置参数
-| 参数 | 描述 | -|:--|:--| -| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | -| Username Attribute | 用户属性的值适合作为显示名称。 | -| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。通常是 `uid`。 | -| User Member Attribute | 包含用户所属组的标识名称的用户属性。通常是 `memberOf` 或 `isMemberOf`。 | -| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 LDAP 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。 | -| User Enabled Attribute | 如果 OpenLDAP 服务器的 Schema 支持使用用户属性的值来评估账号是禁用还是关闭，请输入该属性的名称。默认的 OpenLDAP Schema 不支持此功能，因此此字段通常留空。 | -| Disabled Status Bitmask | 禁用/锁定的用户账号的值。如果 `User Enabled Attribute` 是空的，则忽略此参数。 | +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Username Attribute | 用户属性的值适合作为显示名称。 | +| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。通常是 `uid`。 | +| User Member Attribute | 包含用户所属组的标识名称的用户属性。通常是 `memberOf` 或 `isMemberOf`。 | +| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 LDAP 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。 | +| User Enabled Attribute | 如果 OpenLDAP 服务器的 Schema 支持使用用户属性的值来评估账号是禁用还是关闭，请输入该属性的名称。默认的 OpenLDAP Schema 不支持此功能，因此此字段通常留空。 | +| Disabled Status Bitmask | 禁用/锁定的用户账号的值。如果 `User Enabled Attribute` 是空的，则忽略此参数。 | ### 组 Schema 配置 @@ -67,12 +70,12 @@ title: OpenLDAP 配置参考
组 Schema 配置参数
-| 参数 | 描述 | -|:--|:--| -| Object Class | 域中用于组条目的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | -| Name Attribute | 名称属性的值适合作为显示名称。 | -| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | -| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | -| Search Attribute | 在 UI 中将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | -| Group DN Attribute | 组属性的名称，其格式与用户的组成员属性中的值匹配。参见 `User Member Attribute`。 | -| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组）。如果你使用 Shibboleth，此选项会被禁用。 | \ No newline at end of file +| 参数 | 描述 | +| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于组条目的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Name Attribute | 名称属性的值适合作为显示名称。 | +| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | +| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | +| Search Attribute | 在 UI 中将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | +| Group DN Attribute | 组属性的名称，其格式与用户的组成员属性中的值匹配。参见 `User Member Attribute`。 | +| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组）。如果你使用 Shibboleth，此选项会被禁用。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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.8/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.8/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.8/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.8/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.8/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.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md index 3fb65c5d7e0..7f7606413f1 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -2,6 +2,10 @@ title: 全局权限 --- + + + + _权限_ 是你在为用户选择自定义权限时可以分配的个人访问权限。 全局权限定义用户在任何特定集群之外的授权。Rancher 提供四种开箱即用的默认全局权限：`Administrator` (管理员)、`Restricted Admin` (受限管理员)、`Standard User` (标准用户) 和 `User-Base` 用户。 @@ -16,8 +20,280 @@ _权限_ 是你在为用户选择自定义权限时可以分配的个人访问 你无法更新或删除内置的全局权限。 +## 分配全局权限 + +本地用户的全局权限分配与使用外部认证登录 Rancher 的用户不同。 + +### 新本地用户的全局权限 + +在创建新本地用户时，请在填写**添加用户**表单时为他分配全局权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在**全局**选项卡的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认全局权限来满足你的需要](#配置默认的全局权限) + +### 使用外部认证登录的用户的全局权限 + +当用户首次使用外部认证登录 Rancher 时，他们会自动分配到**新用户的默认角色**的全局权限。默认情况下，Rancher 为新用户分配 **Standard User** 权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在每个页面的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认权限来满足你的需要](#配置默认的全局权限) + +你可以按照[步骤](#为单个用户配置全局权限)操作来将权限分配给单个用户。 + +如果外部认证服务支持组，你可以[同时为组中的每个成员分配角色](#为组配置全局权限)。 + +## 自定义全局权限 + +使用自定义权限可以为用户提供 Rancher 中更为受限或特定的访问权限。 + +当来自[外部认证](../authentication-config/authentication-config.md)的用户首次登录 Rancher 时，他们会自动分配到一组全局权限（以下简称权限）。默认情况下，用户第一次登录后会被创建为用户，并分配到默认的`用户`权限。标准的`用户`权限允许用户登录和创建集群。 + +但是，在某些组织中，这些权限可能会被认为权限过大。你可以为用户分配一组更具限制性的自定义全局权限，而不是为用户分配 `Administrator` 或 `Standard User` 的默认全局权限。 + +默认角色（管理员和标准用户）都内置了多个全局权限。系统管理员角色包括所有全局权限，而默认用户角色包括三个全局权限，分别是创建集群、使用应用商店模板和 User Base（登录 Rancher 的最低权限）。换句话说，自定义全局权限是模块化的，因此，如果你要更改默认用户角色权限，你可以选择需要包括在新的默认用户角色中的全局权限子集。 + +管理员可以通过多种方式强制执行自定义全局权限： + +- [创建自定义全局角色](#自定义全局角色). +- [更改新用户的默认权限](#配置默认的全局权限). +- [为单个用户配置全局权限](#为单个用户配置全局权限). +- [为组配置全局权限](#为组配置全局权限). + +### 结合内置的全局角色 + +Rancher 提供了多个全局角色，它们为某些常见的用户场景授予了精细的权限。下表列出了每个内置的全局角色（`Administrator`, `Standard User` 和 `User-Base`）以及它包含的默认全局权限 + +| 自定义全局权限 | Administrator | Standard User | User-Base | +| --------------------------- | ------------- | ------------- | --------- | +| 创建集群 | ✓ | ✓ | | +| 创建 RKE 模板 | ✓ | ✓ | | +| 管理认证 | ✓ | | | +| 管理应用商店 | ✓ | | | +| 管理集群驱动 | ✓ | | | +| 管理主机驱动 | ✓ | | | +| 管理 PodSecurityPolicy 模板 | ✓ | | | +| 管理角色 | ✓ | | | +| 管理设置 | ✓ | | | +| Manage Users | ✓ | | | +| 使用应用商店模板 | ✓ | ✓ | | +| User-Base (基本登录访问) | ✓ | ✓ | | + +如果需要查看每个全局权限对应哪些 Kubernetes 资源： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 如果单击单个角色的名称，表格会显示该角色授权的所有操作和资源。 + +:::note 注意事项： + +- 上面列出的每个权限都包含多个未在 Rancher UI 中列出的权限。如果需要获取完整权限列表以及组成权限的规则，请通过 `/v3/globalRoles` API 进行访问。 +- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 + +::: + +### 自定义全局角色 + +当内置的全局角色无法直接满足你的需求时，可以创建自定义全局角色。 + +通过 UI 或自动化（例如 Rancher Kubernetes API） 创建自定义全局角色，你可以指定使用与上游角色和集群角色相同的规则。 + +#### Escalate 与 Bind + +当授予全局角色权限时，请注意 Rancher 遵循 `escalate` 与 `bind`，其方式类似于 [Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update)。 + +在全局角色提供的这两项配置，都可以授予用户绕过 Rancher 提升校验的权限。这可能允许用户成为管理员。由于这有着极高的安全风险，因此应非常谨慎地将 `bind` 和 `escalate` 权限分发给用户。 + +`escalate` 允许用户更改全局角色并添加任何授权，即使用户没有当前或新版本的全局角色权限。 + +`bind` 允许用户对指定的全局角色进行授权（创建 ClusterRoleBinding），即使该用户没有访问全局角色的权限。 + +:::danger + +通配符动词 `*` 也包括 `bind` 和 `escalate`。这意味着为用户的全局角色设置 `*` 也会提供 `escalate` 和 `bind`。 + +::: + +##### 自定义全局角色示例 + +仅为名称为 `test-gr` 的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "escalate" +``` + +为所有的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "escalate" +``` + +仅为名称为 `test-gr` 的全局角色授予创建角色绑定（绕过 escalation 检查）的权限 + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "bind" + - apiGroups: + - "management.cattle.io" + resources: + - "globalrolebindings" + verbs: + - "create" +``` + +授予 `*` 权限（同时包含 `escalate` 与 `bind`） + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "*" +``` + +#### 下游集群的全局角色权限 + +全局角色可以通过 `inheritedClusterRoles` 字段在每个下游集群上授予一个或多个 RoleTemplate。此字段中引用的值必须是集群级别的 RoleTemplate 并且在集群 `context` 中存在。 + +通过此字段，用户将获取当前或未来的所有下游集群的指定权限，例如以下的全局角色示例： + +```yaml +apiVersion: management.cattle.io/v3 +kind: GlobalRole +displayName: All Downstream Owner +metadata: + name: all-downstream-owner +inheritedClusterRoles: + - cluster-owner +``` + +任何具有此权限的用户都将是所有下游集群的所有者（cluster-owner）。如果添加了新的集群，无论是什么类型的集群，用户也将是这个集群的所有者。 + +:::danger + +在[默认的全局角色](#配置默认的全局权限)中使用此字段可能会导致用户获得过多的权限。 + +::: + +### 配置默认的全局权限 + +如果你想限制新用户的默认权限，你可以删除作为默认角色的`用户`权限，然后分配多个单独的权限作为默认权限。你也可以在一组其他标准权限之上添加管理权限。 + +:::note + +默认角色仅分配给从外部认证登录的用户。对于本地用户，在将用户添加到 Rancher 时，必须显式分配全局权限。你可以在添加用户时自定义这些全局权限。 + +::: + +要更改在外部用户首次登录时分配给他们的默认全局权限，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。在**角色**页面上，确保选择了**全局**选项卡。 +1. 查找要添加或删除的默认权限集。然后，通过选择 **⋮ > 编辑配置**来编辑权限。 +1. 如果要将权限添加为默认权限，请选择**是：新用户的默认角色**，然后单击**保存**。如果要删除默认权限，请编辑该权限并选择**否**。 + +**结果**：默认全局权限已根据你的更改配置。分配给新用户的权限会在**新用户的默认角色**列中显示为复选标记。 + +### 为单个用户配置全局权限 + +要为单个用户配置权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 找到要更改访问级别的用户，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**和**内置角色**部分中，选中你希望用户拥有的权限的复选框。如果你在**角色**页面创建了角色，这些角色将出现在**自定义**部分，你也可以选择这些角色。 +1. 单击**保存**。 + +**结果**：用户的全局权限已更新。 + +### 为组配置全局权限 + +如果你有一组需要在 Rancher 中有相同访问权限的用户，你可以一次性将权限分配给整个组来节省时间。这样，组中的用户在第一次登录 Rancher 时能拥有相应级别的访问权限。 + +将自定义全局角色分配给组后，该角色将在组中用户登录 Rancher 时分配给用户。 + +对于现有用户，新权限将在用户退出 Rancher 并重新登录时，或当管理员[刷新用户组成员名单](#刷新用户组成员名单)时生效。 + +对于新用户，新权限在用户首次登录 Rancher 时生效。除了**新用户的默认角色**全局权限外，来自该组的新用户还将获得自定义全局角色的权限。默认情况下，**新用户的默认角色**权限等同于 **Standard User** 全局角色，但默认权限可以[配置。](#配置默认的全局权限) + +如果从外部认证服务中将用户从组中删除，该用户将失去分配给该组的自定义全局角色的权限。他们将继续拥有分配给他们的其他剩余角色，这通常包括标记为**新用户的默认角色**的角色。Rancher 将在用户登出或管理员[刷新用户组成员名单](#刷新用户组成员名单)时删除与组关联的权限。 + +:::note 先决条件： + +只有在以下情况下，你才能将全局角色分配给组： + +- 你已设置[外部认证](../authentication-config/authentication-config.md#external-vs-local-authentication) +- 外部认证服务支持[用户组](../authentication-config/manage-users-and-groups.md) +- 你已使用外部认证服务设置了至少一个用户组。 + +::: + +要将自定义全局角色分配给组，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**组**。 +1. 转到你要分配自定义全局角色的组，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**，**自定义**和/或**内置角色**部分中，选择该组应具有的权限。 +1. 单击**创建**。 + +**结果**：自定义全局角色会在组内用户登录 Rancher 时生效。 + +### 刷新用户组成员名单 + +当管理员更新组的全局权限时，更改将在组成员退出 Rancher 并重新登录后生效。 + +如果要让更改立即生效，管理员或集群所有者可以刷新用户组成员名单。 + +如果用户已经从外部认证服务中的组中删除，管理员也需要刷新用户组成员名单。在这种情况下，刷新操作会让 Rancher 知道用户已从组中删除。 + +要刷新用户组成员名单： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 单击**刷新用户组成员名单**。 + +**结果**：对组成员权限的所有更改都会生效。 + ## 受限管理员 +:::warning 已弃用 + +受限管理员角色已弃用，并将在未来的 Rancher 版本（2.10 或更高版本）中删除。你应该创建具有所需权限的自定义角色，而不是依赖此项内置角色。 + +::: + Rancher 2.5 创建了一个新的 `restricted-admin` 角色，以防止本地 Rancher Server Kubernetes 集群的权限提升。此角色对 Rancher 管理的所有下游集群具有完全管理员权限，但没有更改本地 Kubernetes 集群的权限。 `restricted-admin` 可以创建其他具有同样访问权限的 `restricted-admin` 用户。 @@ -29,9 +305,10 @@ Rancher 还增加了一个新设置，来将初始启动的管理员设置为 `r ``` CATTLE_RESTRICTED_DEFAULT_ADMIN=true ``` -### `restricted-admin` 的权限列表 -下表列出了 `restricted-admin` 与 `Administrator` 和 `Standard User` 角色相比应具有的权限和操作： +### `受限管理员` 的权限列表 + +下表列出了 `受限管理员` 与 `全局管理员` 和 `普通用户` 角色相比应具有的权限和操作： | 类别 | 操作 | 全局管理员 | 普通用户 | 受限管理员 | 受限管理员的注意事项 | | -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- | @@ -42,7 +319,7 @@ CATTLE_RESTRICTED_DEFAULT_ADMIN=true | | 访问 CRD 和 CR 的管理集群 | 是 | 否 | 是 | | | | 另存为 RKE 模板 | 是 | 否 | 否 | | | 安全 | | | | | | -| 启用身份验证 | 配置身份验证 | 是 | 否 | 是 | | +| 启用认证 | 配置认证 | 是 | 否 | 是 | | | 角色 | 创建/分配 GlobalRoles | 是 | 否（可列出） | 是 | 认证 Webhook 允许为已经存在的权限创建 globalrole | | | 创建/分配 ClusterRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | | | 创建/分配 ProjectRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | @@ -81,167 +358,8 @@ CATTLE_RESTRICTED_DEFAULT_ADMIN=true ### 将全局管理员更改为受限管理员 -如果 Rancher 已经有一个全局管理员，则应该将所有全局管理员更改为新的 `restricted-admin`。 +在之前的版本中，文档建议如果管理员角色正在使用中，应将所有用户都更改为受限管理员。现在鼓励用户使用集群权限的功能构建自定义的全局角色，并将受限管理员迁移到新的自定义角色使用。 你可以前往**安全 > 用户**，并将所有管理员角色转为受限管理员。 已登录的用户可以根据需要将自己更改为 `restricted-admin`，但这应该是他们的最后一步操作，否则他们将没有进行该操作的权限。 - -## 分配全局权限 - -本地用户的全局权限分配与使用外部身份验证登录 Rancher 的用户不同。 - -### 新本地用户的全局权限 - -在创建新本地用户时，请在填写**添加用户**表单时为他分配全局权限。 - -如果需要查看新用户的默认权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在**全局**选项卡的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 - -你可以[更改默认全局权限来满足你的需要](#配置默认全局权限)。 - -### 使用外部身份验证程序的用户的全局权限 - -当用户首次使用外部身份验证提供程序登录 Rancher 时，他们会自动分配到**新用户的默认角色**的全局权限。默认情况下，Rancher 为新用户分配 **Standard User** 权限。 - -如果需要查看新用户的默认权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在每个页面的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 - -你可以[更改默认权限来满足你的需要](#配置默认全局权限)。 - -权限可以[分配](#为单个用户配置全局权限)给单个用户。 - -如果外部身份验证提供程序支持组，你可以[同时为组中的每个成员分配角色](#为组配置全局权限)。 - -## 自定义全局权限 - -使用自定义权限可以为用户配置在 Rancher 中的更受限或指定的访问权限。 - -当来自[外部身份验证系统](../../../../pages-for-subheaders/authentication-config.md)的用户首次登录 Rancher 时，他们会自动分配到一组全局权限（以下简称权限）。默认情况下，用户第一次登录后会被创建为用户，并分配到默认的`用户`权限。标准的`用户`权限允许用户登录和创建集群。 - -但是，在某些组织中，这些权限可能会被认为权限过大。你可以为用户分配一组更具限制性的自定义全局权限，而不是为用户分配 `Administrator` 或 `Standard User` 的默认全局权限。 - -默认角色（管理员和标准用户）都内置了多个全局权限。系统管理员角色包括所有全局权限，而默认用户角色包括三个全局权限，分别是创建集群，使用应用商店模板，和 User Base（登录 Rancher 的最低权限）。换句话说，自定义全局权限是模块化的，因此，如果你要更改默认用户角色权限，你可以选择需要包括在新的默认用户角色中的全局权限子集。 - -管理员可以通过多种方式强制执行自定义全局权限： - -- [更改新用户的默认权限](#配置默认全局权限) -- [为单个用户配置全局权限](#为单个用户配置全局权限) -- [为组配置全局权限](#为组配置全局权限) - -### 自定义全局权限参考 - -下表列出了每个可用的自定义全局权限，以及该权限是否包含在默认全局权限 `Administrator`、`Standard User` 和 `User-Base` 中： - -| 自定义全局权限 | 管理员 | 普通用户 | User-Base | -| ---------------------------------- | ------------- | ------------- |-----------| -| 创建集群 | ✓ | ✓ | | -| 创建 RKE 模板 | ✓ | ✓ | | -| 管理身份验证 | ✓ | | | -| 管理应用商店 | ✓ | | | -| 管理集群驱动 | ✓ | | | -| 管理主机驱动 | ✓ | | | -| 管理 PodSecurityPolicy 模板 | ✓ | | | -| 管理角色 | ✓ | | | -| 管理设置 | ✓ | | | -| 管理用户 | ✓ | | | -| 使用应用商店模板 | ✓ | ✓ | | -| User-Base（基本登录访问） | ✓ | ✓ | | - -如果需要查看每个全局权限对应哪些 Kubernetes 资源： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。 -1. 如果单击单个角色的名称，表格会显示该角色授权的所有操作和资源。 - -:::note 注意事项： - -- 上面列出的每个权限都包含多个未在 Rancher UI 中列出的权限。如果需要获取完整权限列表以及组成权限的规则，请通过 `/v3/globalRoles` API 进行访问。 -- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 - -::: - -### 配置默认全局权限 - -如果你想限制新用户的默认权限，你可以删除作为默认角色的`用户`权限，然后分配多个单独的权限作为默认权限。你也可以在一组其他标准权限之上添加管理权限。 - -:::note - -默认角色仅分配给从外部身份验证提供程序添加的用户。对于本地用户，在将用户添加到 Rancher 时，必须显式分配全局权限。你可以在添加用户时自定义这些全局权限。 - -::: - -要更改在外部用户首次登录时分配给他们的默认全局权限，请执行以下步骤： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**角色**。在**角色**页面上，确保选择了**全局**选项卡。 -1. 查找要添加或删除的默认权限集。然后，通过选择 **⋮ > 编辑配置**来编辑权限。 -1. 如果要将权限添加为默认权限，请选择**是：新用户的默认角色**，然后单击**保存**。如果要删除默认权限，请编辑该权限并选择**否**。 - -**结果**：默认全局权限已根据你的更改配置。分配给新用户的权限会在**新用户的默认角色**列中显示为复选标记。 - -### 为单个用户配置全局权限 - -要为单个用户配置权限： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**用户**。 -1. 找到要更改访问级别的用户，然后单击 **⋮ > 编辑配置**。 -1. 在**全局权限**和**内置角色**部分中，选中你希望用户拥有的权限的复选框。如果你在**角色**页面创建了角色，这些角色将出现在**自定义**部分，你也可以选择这些角色。 -1. 单击**保存**。 - -**结果**：用户的全局权限已更新。 - -### 为组配置全局权限 - -如果你有一组需要在 Rancher 中有相同访问权限的用户，你可以一次性将权限分配给整个组来节省时间。这样，组中的用户在第一次登录 Rancher 时能拥有相应级别的访问权限。 - -将自定义全局角色分配给组后，该角色将在组中用户登录 Rancher 时分配给用户。 - -对于现有用户，新权限将在用户退出 Rancher 并重新登录时，或当管理员[刷新用户组成员名单](#刷新用户组成员名单)时生效。 - -对于新用户，新权限在用户首次登录 Rancher 时生效。除了**新用户的默认角色**全局权限外，来自该组的新用户还将获得自定义全局角色的权限。默认情况下，**新用户的默认角色**权限等同于 **Standard User** 全局角色，但默认权限可以[配置。](#配置默认全局权限) - -如果从外部身份验证提供程序组中删除用户，该用户将失去分配给该组的自定义全局角色的权限。他们将继续拥有分配给他们的所有剩余角色，这通常包括标记为**新用户的默认角色**的角色。Rancher 将在用户登出或管理员[刷新用户组成员名单](#刷新用户组成员名单)时删除与组关联的权限。 - -:::note 先决条件： - -只有在以下情况下，你才能将全局角色分配给组： - -* 你已设置[外部身份验证提供程序](../../../../pages-for-subheaders/authentication-config.md#外部验证与本地验证)。 -* 外部身份验证提供程序支持[用户组](../authentication-config/manage-users-and-groups.md)。 -* 你已使用身份验证提供程序设置了至少一个用户组。 - -::: - -要将自定义全局角色分配给组，请执行以下步骤： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**组**。 -1. 转到你要分配自定义全局角色的组，然后单击 **⋮ > 编辑配置**。 -1. 在**全局权限**，**自定义**和/或**内置角色**部分中，选择该组应具有的权限。 -1. 单击**创建**。 - -**结果**：自定义全局角色会在组内用户登录 Rancher 时生效。 - -### 刷新用户组成员名单 - -当管理员更新组的全局权限时，更改将在组成员退出 Rancher 并重新登录后生效。 - -如果要让更改立即生效，管理员或集群所有者可以刷新用户组成员名单。 - -如果用户已经从外部身份验证服务中的组中删除，管理员也可能需要刷新用户组成员名单。在这种情况下，刷新操作会让 Rancher 知道用户已从组中删除。 - -要刷新用户组成员名单： - -1. 在左上角，单击 **☰ > 用户 & 认证**。 -1. 在左侧导航栏中，单击**用户**。 -1. 单击**刷新用户组成员名单**。 - -**结果**：对组成员权限的所有更改都会生效。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/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.8/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.8/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.8/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..dd034e3daf8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md new file mode 100644 index 00000000000..cc4e205c941 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md @@ -0,0 +1,84 @@ +--- +title: 使用 Rancher 启动 Kubernetes +--- + + + + + +Rancher 可以使用任意节点启动 Kubernetes 集群。在 Rancher 中将 Kubernetes 部署到这些节点上时，你可以选择 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) 或 [RKE2](https://docs.rke2.io) 发行版。Rancher 可以在任何计算机上启动 Kubernetes，包括： + +- 裸金属服务器 +- 本地虚拟机 +- 由云厂商托管的虚拟机 + +Rancher 可以在现有节点上安装 Kubernetes，也可以在云厂商中动态配置节点并安装 Kubernetes。 + +Rancher 还可以创建节点池。在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +## RKE + +### 要求 + +如果你使用 RKE 建立集群，节点必须满足下游集群的[节点要求](../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)。 + +### 在云厂商的新节点上启动 Kubernetes + +使用 Rancher，你可以基于[节点模板](use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此节点模板定义了要用于在云厂商中启动节点的参数。 + +在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +有关详细信息，请参阅[在新节点上启动 Kubernetes](use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)。 + +### 在现有自定义节点上启动 Kubernetes + +在这种情况下，你希望将 Kubernetes 安装到裸机服务器、本地虚拟机或云厂商中已存在的虚拟机上。使用此选项，你将在主机上运行 Rancher Agent Docker 容器。 + +如果要重复使用之前的自定义集群中的节点，请在复用之前[清理节点](../manage-clusters/clean-cluster-nodes.md)。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +有关详细信息，请参阅[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)。 + +### 以编程方式创建 RKE 集群 + +通过 Rancher 以编程方式部署 RKE 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 + +## RKE2 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。在 Rancher 2.6.4 及更早版本中，RKE2 配置还处于技术预览阶段。 + +在 Rancher 2.6.5 中，RKE2 已经 GA。 + +### 要求 + +如果你使用 RKE2 建立集群，节点必须满足下游集群的[节点要求](https://docs.rke2.io/install/requirements)。 + +### 在云厂商的新节点上启动 Kubernetes + +RKE2 基于使用上游[集群 API](https://github.com/kubernetes-sigs/cluster-api) 项目的新配置框架。这个新配置框架支持： + +- 将 RKE2 集群配置到 Rancher 具有主机驱动的任何提供商上 +- 完全在 Rancher 中配置 RKE2 集群 +- 除了 Canal 之外，还可以选择 CNI 选项， Calico、Cilium 和 Multus + +RKE2 配置还包括在具有 Windows 节点的集群上安装 RKE2。 + +RKE2 的 Windows 功能包括： + +- Windows 支持 vSphere 主机驱动 +- 用于 Windows RKE2 自定义集群的 Calico CNI +- Calico 的项目网络隔离 (PNI) +- 由 containerd 提供支持的使用 RKE2 的 Windows 容器 +- 通过 Terraform 配置 Windows RKE2 集群 +- 直接从 Rancher UI 配置 Windows RKE2 自定义集群 + +要使 Windows 支持 RKE2 自定义集群，请选择 Calico 作为 CNI。 + +### 在现有自定义节点上启动 Kubernetes + +RKE2 还支持在预配置的虚拟机或裸机节点上安装自定义集群。 + +如果要重复使用之前的自定义集群中的节点，请在复用之前清理节点。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +### 以编程方式创建 RKE2 集群 + +通过 Rancher 以编程方式部署 RKE2 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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 b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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 new file mode 100644 index 00000000000..5bc6d65b953 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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 @@ -0,0 +1,156 @@ +--- +title: 在云厂商的新节点上启动 Kubernetes +--- + + + + + +在 Rancher 中使用节点模板来创建 RKE 或 RKE2 集群时，每个生成的节点池都会显示在新的**主机池**选项卡中。你可以通过执行以下操作来查看主机池： + +1. 点击**☰ > 集群管理**。 +1. 单击 RKE 或 RKE2 集群的名称。 + +## RKE 集群 + +使用 Rancher，你可以基于[节点模板](use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此节点模板定义了要用于在基础设施提供商或云厂商中启动节点的参数。 + +在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +可用于创建节点模板的云提供商是由[主机驱动](use-new-nodes-in-an-infra-provider.md#主机驱动)决定的。 + +### 节点模板 + +节点模板保存了用于在特定云提供商中配置节点时要使用的参数。这些节点可以从 UI 启动。Rancher 使用 [Docker Machine](https://docs.docker.com/machine/) 来配置这些节点。可用于创建节点模板的云提供商取决于 Rancher 中状态是 Active 的主机驱动。 + +在 Rancher 中创建节点模板后，模板会被保存，以便你可以再次使用该模板来创建节点池。节点模板绑定到你的登录名。添加模板后，你可以将其从用户配置文件中删除。 + +#### 节点标签 + +你可以为每个节点模板添加[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)，这样，使用节点模板创建的节点都会自动带有这些标签。 + +无效标签会阻止升级，或阻止 Rancher 启动。有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +#### 节点污点 + +你可以为每个节点模板添加[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，这样，使用节点模板创建的节点都会自动带有这些污点。 + +由于污点可以同时添加到节点模板和节点池中，因此如果添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点模板的管理员控制 + +管理员可以控制所有节点模板。现在，管理员可以维护 Rancher 中的所有节点模板。当节点模板所有者不再使用 Rancher 时，他们创建的节点模板可以由管理员管理，以便继续更新和维护集群。 + +要访问所有节点模板，管理员需要执行以下操作： + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 + +**结果**：列出所有节点模板。你可以通过单击 **⋮** 来编辑或克隆模板。 + +### 节点池 + +使用 Rancher，你可以基于[节点模板](#节点模板)创建节点池。 + +节点模板定义了节点的配置，例如要使用的操作系统、CPU 数量和内存量。 + +使用节点池的好处是，如果一个节点被销毁或删除，你可以增加 Active 节点的数量来补偿丢失的节点。节点池可以帮助你确保节点池的计数符合要求。 + +每个节点池必须分配一个或多个节点角色。 + +每个节点角色（即 etcd、controlplane 和 worker）都应分配给不同的节点池。虽然你可以将多个节点角色分配给同一个节点池，但不要在生产集群中执行此操作。 + +推荐的设置： + +- 具有 etcd 角色且计数为 3 的节点池 +- 具有 controlplane 角色且计数至少为 2 的节点池 +- 具有 worker 角色且计数至少为 2 的节点池 + +**离线环境中的 RKE1 下游集群节点**： + +默认情况下，在配置 RKE1 下游集群节点时（例如在 vSphere 中），Rancher 会尝试运行 Docker 安装脚本。但是，Rancher Docker 安装脚本在离线环境中会运行失败。要解决此问题，如果 Docker 已预安装到 VM 镜像上，你可以选择在创建节点模板时跳过安装 Docker。为此，你可以在 Rancher UI **引擎选项**下的 `Docker 安装 URL` 下拉列表中选择 **无**。 + +
**引擎选项下拉列表**
+ +![引擎选项下拉列表](/img/node-template-engine-options-rke1.png) + +#### 节点池污点 + +如果你没有在节点模板上定义[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，则可以为每个节点池添加污点。将污点添加到节点池的好处是你可以更改节点模板，而不需要先确保污点存在于新模板中。 + +每个污点都将自动添加到节点池中已创建的节点。因此，如果你在已有节点的节点池中添加污点，污点不会应用到已有的节点，但是添加到该节点池中的新节点都将获得该污点。 + +如果污点同时添加到节点模板和节点池中，且添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点自动替换 + +Rancher 可以自动替换节点池中无法访问的节点。如果节点在指定的时间中处于 Inactive 状态，Rancher 将使用该节点池的节点模板来重新创建节点。 + +:::caution + +自我修复节点池的功能帮助你替换无状态应用的 worker 节点。不建议在 master 节点或连接了持久卷的节点的节点池上启用节点自动替换，因为虚拟机会被临时处理。节点池中的节点与集群断开连接时，其持久卷将被破坏，从而导致有状态应用的数据丢失。 + +::: + +节点自动替换基于 Kubernetes 节点控制器工作。节点控制器定期检查所有节点的状态（可通过 `kube-controller` 的 `--node-monitor-period` 标志配置）。一个节点不可访问时，节点控制器将污染该节点。发生这种情况时，Rancher 将开始其删除倒计时。你可以配置 Rancher 等待删除节点的时间。如果在删除倒计时结束前污点没有被删除，Rancher 将继续删除该节点。Rancher 会根据节点池设置的数量来创建新的节点。 + +#### 启用节点自动替换 + +创建节点池时，你可以指定 Rancher 替换无响应节点的等待时间（以分钟为单位）。 + +1. 在创建或编辑集群的表单中，转到**节点池**。 +1. 转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 Rancher 在替换节点之前应该等待节点响应的分钟数。 +1. 填写表单的其余部分以创建或编辑集群。 + +**结果** ：已为节点池启用节点自动替换。 + +#### 禁用节点自动替换 + +你可以执行以下步骤从 Rancher UI 禁用节点自动替换： + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要禁用节点自动替换的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**节点池**部分中，转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 0。 +1. 单击**保存**。 + +**结果**：已禁用节点池的节点自动替换。 + +### 云凭证 + +节点模板可以使用云凭证，来存储用于在云提供商中启动节点的凭证，其优点是： + +- 凭证会存储为更安全的 Kubernetes 密文，而且你无需每次都输入凭证便可编辑节点模板。 + +- 创建云凭证后，你可以重新使用该凭证来创建其他节点模板。 + +- 多个节点模板可以使用相同的云凭证来创建节点池。如果你的密钥被泄露或过期，则可以在一个位置更新云凭证，从而一次更新所有使用该凭证的节点模板。 + +创建云凭证后，用户可以[管理创建的云凭证](../../../../reference-guides/user-settings/manage-cloud-credentials.md)。 + +### 主机驱动 + +如果你找不到想要的主机驱动，你可以在 Rancher 的[内置主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#激活停用主机驱动)中查看并激活它，也可以[添加自定义主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#添加自定义主机驱动)。 + +## RKE2 集群 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。 + +:::note + +对于 RKE2 集群模板，请参阅[此页面](../../manage-clusters/manage-cluster-templates.md#rke2-集群模板)了解更多信息。 + +::: + +### 节点角色 + +RKE2 CLI 公开了 `server` 和 `agent` 两个角色，它们分别代表 Kubernetes 节点角色 `etcd` + `controlplane` 和 `worker`。通过 Rancher 2.6 中的 RKE2 集成，RKE2 节点池可以分配更细粒度的角色，例如 `etcd` 和 `controlplane`。 + +你可以在 RKE2 CLI 中使用标志和节点污染，来控制调度工作负载和 Kubernetes master 节点的位置，从而使用 `etcd`，`controlplane` 和 `worker` 节点功能。这些角色没有在 RKE2 CLI 中实现为第一级角色的原因是，RKE2 被概念化为一组原始构建块，使用 Rancher 等编排系统得到最佳利用。 + +在 Rancher 中实现这三个节点角色，表示 Rancher 管理的 RKE2 集群能够轻松使用为 RKE 集群推荐的相同架构的所有最佳实践。 + +在[推荐的集群架构](../../kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md)中，我们概述了每个角色集群应该有多少节点： + +- 至少拥有三个角色为 etcd 的节点，来确保失去一个节点时仍能存活。 +- 至少两个节点具有 controlplane 角色，以实现主组件高可用性。 +- 至少两个具有 worker 角色的节点，用于在节点故障时重新安排工作负载。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/new-user-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/new-user-guides.md new file mode 100644 index 00000000000..91cfa77fe1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/how-to-guides/new-user-guides/new-user-guides.md @@ -0,0 +1,13 @@ +--- +title: 新用户指南 +--- + + + + + +新用户指南，也称为 **教程**，描述了用户在完成一些具体操作时要遵循的实用步骤。这些文档被称为“以学习为导向”的文档，用户通过“实际操作”来学习。 + +新用户指南旨在指导初学者或 Rancher 的日常用户通过一系列步骤来学习如何做某件事。目标是让用户可以通过易于操作、有意义的、可重复的指示来学习如何完成任务。这些指南将帮助用户完成工作，然后立即获得承诺的结果。 + +普通的 Rancher 用户的技术水平高于“初学者”，但是新用户指南旨在同等的帮助新用户、初学者以及经验丰富的 Rancher 客户，这是通过结合使用高级和技术语言来介绍主题并指导用户完成每个 Rancher 用户都必须了解的一般任务来实现的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/troubleshooting/kubernetes-components/kubernetes-components.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/troubleshooting/kubernetes-components/kubernetes-components.md new file mode 100644 index 00000000000..38bcba2810d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/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.8/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md index 9c370685084..d64215cebd2 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.8/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.8/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md @@ -2,6 +2,10 @@ title: etcd 节点故障排除 --- + + + + 本文介绍了对具有 `etcd` 角色的节点进行故障排除的命令和提示。 @@ -47,13 +51,6 @@ docker logs etcd docker exec etcd etcdctl member list ``` -输出示例： -``` -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001 -``` - ### 检查端点状态 `RAFT TERM` 的值应该是相等的，而且 `RAFT INDEX` 相差不能太大。 diff --git a/shared-files/_cni-popularity.md b/shared-files/_cni-popularity.md index 1135809c068..3240101493b 100644 --- a/shared-files/_cni-popularity.md +++ b/shared-files/_cni-popularity.md @@ -1,10 +1,10 @@ -The following table summarizes different GitHub metrics to give you an idea of each project's popularity and activity levels. This data was collected in February 2024. +The following table summarizes different GitHub metrics to give you an idea of each project's popularity and activity levels. This data was collected in March 2024. | Provider | Project | Stars | Forks | Contributors | | ---- | ---- | ---- | ---- | ---- | -| Canal | https://github.com/projectcalico/canal | 708 | 103 | 20 | +| Canal | https://github.com/projectcalico/canal | 708 | 100 | 20 | | Flannel | https://github.com/flannel-io/flannel | 8.4k | 2.9k | 231 | -| Calico | https://github.com/projectcalico/calico | 5.3k | 1.2k | 336 | -| Weave | https://github.com/weaveworks/weave/ | 6.6k | 679 | 87 | -| Cilium | https://github.com/cilium/cilium | 18k | 2.6k | 706 | +| Calico | https://github.com/projectcalico/calico | 5.4k | 1.2k | 339 | +| Weave | https://github.com/weaveworks/weave/ | 6.6k | 661 | 87 | +| Cilium | https://github.com/cilium/cilium | 18.2k | 2.6k | 717 | diff --git a/shared-files/_docker-support-warning.md b/shared-files/_docker-support-warning.md new file mode 100644 index 00000000000..2e34cb9b51c --- /dev/null +++ b/shared-files/_docker-support-warning.md @@ -0,0 +1,5 @@ +:::warning + +**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. + +::: diff --git a/sidebars.js b/sidebars.js index 8fb2bbca81e..a7cf29f8353 100644 --- a/sidebars.js +++ b/sidebars.js @@ -625,7 +625,7 @@ const sidebars = { }, { type: 'category', - label: 'Helm Charts in Rancher', + label: 'Helm Charts and Apps', link: { type: 'doc', id: "how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher", diff --git a/src/pages/versions.md b/src/pages/versions.md index dabdd309ecb..7eabe972ae3 100644 --- a/src/pages/versions.md +++ b/src/pages/versions.md @@ -4,7 +4,7 @@ title: Rancher Documentation Versions -### Current versions +### Current Versions Here you can find links to supporting documentation for the current released version of Rancher v2.8, and its availability for [Rancher Prime](/v2.8/getting-started/quick-start-guides/deploy-rancher-manager/prime) and the Community version of Rancher: @@ -18,11 +18,11 @@ Here you can find links to supporting documentation for the current released ver Community - v2.8.2 + v2.8.3 Documentation - Release Notes - Support Matrix -
✓
+ Release Notes +
N/A
+
N/A
✓
@@ -39,10 +39,10 @@ Here you can find links to supporting documentation for the current released ver Community - v2.7.11 + v2.7.12 Documentation - Release Notes - Support Matrix + Release Notes + Support Matrix
✓
N/A
@@ -65,7 +65,7 @@ Here you can find links to supporting documentation for the current released ver -### Past versions +### Past Versions Here you can find links to supporting documentation for previous versions of Rancher v2.8, and their availability for [Rancher Prime](/v2.8/getting-started/quick-start-guides/deploy-rancher-manager/prime) and the Community version of Rancher: @@ -78,6 +78,14 @@ Here you can find links to supporting documentation for previous versions of Ran Prime Community + + v2.8.2 + Documentation + Release Notes + Support Matrix +
✓
+
✓
+ v2.8.1 Documentation @@ -109,6 +117,14 @@ Here you can find links to supporting documentation for previous versions of Ran Prime Community + + v2.7.11 + Documentation + Release Notes + Support Matrix +
✓
+
N/A
+ v2.7.10 Documentation @@ -298,7 +314,7 @@ Here you can find links to supporting documentation for previous versions of Ran
-### Legacy versions (EOL) +### Legacy Versions (EOL) Here you can find links to supporting documentation for legacy versions of Rancher v2.5: diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 6097946a3f8..b5ef8bfde0f 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -10,6 +10,7 @@ import CNIPopularityTable from '/shared-files/_cni-popularity.md'; import DeprecationOPAGatekeeper from '/shared-files/_deprecation-opa-gatekeeper.md'; import DeprecationWeave from '/shared-files/_deprecation-weave.md'; import DeprecationHelm2 from '/shared-files/_deprecation-helm2.md'; +import DockerSupportWarning from '/shared-files/_docker-support-warning.md'; export default { // Re-use the default mapping @@ -25,4 +26,5 @@ export default { DeprecationOPAGatekeeper, DeprecationWeave, DeprecationHelm2, + DockerSupportWarning, }; diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md index 30e65741813..de758c081e3 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 1bcb85610cc..e775b3e306d 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](./upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index 3a39e0dbffe..73230383e6a 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -8,6 +8,8 @@ title: Upgrading Rancher Installed with Docker The following instructions will guide you through upgrading a Rancher server that was installed with Docker. + + ## Prerequisites - **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md index 860088f4f8b..3bdfb5f34b2 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -139,6 +139,7 @@ helm repo update helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ + --set installCRDs=true \ --version v1.5.1 ``` diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md index da5c32aef57..eedb19faa40 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 65c443840c5..e91cd30559a 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index 61ff84eaec6..7c49b81257a 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -8,6 +8,8 @@ title: Upgrading Rancher Installed with Docker The following instructions will guide you through upgrading a Rancher server that was installed with Docker. + + ## Prerequisites - **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/helm-charts-in-rancher.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/helm-charts-in-rancher.md index 80fe5d50471..19629bab673 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/helm-charts-in-rancher.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/helm-charts-in-rancher.md @@ -1,50 +1,52 @@ --- -title: Helm Charts in Rancher +title: Helm Charts and Apps --- -In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. +In this section, you'll learn how to manage Helm chart repositories and apps in Rancher. -### Changes in Rancher v2.5 +## Catalogs and Changes in Rancher v2.5 -In Rancher v2.5, the Apps and Marketplace feature replaced the catalog system. +In Rancher v2.5, the **Apps and Marketplace** feature replaces the catalog system. -In the cluster manager, Rancher uses a catalog system to import bundles of charts and then uses those charts to either deploy custom helm applications or Rancher's tools such as Monitoring or Istio. The catalog system is still available in the cluster manager in Rancher v2.5, but it is deprecated. +In the cluster manager, Rancher uses a catalog system to import bundles of charts and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. The catalog system is still available in the cluster manager in Rancher v2.5, but it is deprecated. + +### How Helm Charts Work in Rancher Now in the Cluster Explorer, Rancher uses a similar but simplified version of the same system. Repositories can be added in the same way that catalogs were, but are specific to the current cluster. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. -### Charts +## Charts -From the top-left menu select _"Apps & Marketplace"_ and you will be taken to the Charts page. +From the top-left menu select **Apps & Marketplace** and you will be taken to the **Charts** page. -The charts page contains all Rancher, Partner, and Custom Charts. +The **Charts** page contains all Rancher, Partner, and Custom charts. -* Rancher tools such as Logging or Monitoring are included under the Rancher label -* Partner charts reside under the Partners label -* Custom charts will show up under the name of the repository +* Rancher tools such as Logging or Monitoring are included under the Rancher label. +* Partner charts reside under the Partners label. +* Custom charts will show up under the name of the repository. All three types are deployed and managed in the same way. > Apps managed by the Cluster Manager should continue to be managed only by the Cluster Manager, and apps managed with the Cluster Explorer must be managed only by the Cluster Explorer. -### Repositories +## Repositories -From the left sidebar select _"Repositories"_. +From the left sidebar select **Repositories**. These items represent Helm repositories, and can be either traditional Helm endpoints which have an index.yaml, or Git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository. -#### Add Custom Git Repositories +### Add Custom Git Repositories Click **Create** and select the target, **Git repository containing Helm chart...** to add a custom Git repository that contains your Helm charts or cluster template definitions. -You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from the default, `main`. +You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is either `main` or `master`. Whenever you add a chart repository to Rancher, it becomes available immediately. -#### Add Custom Helm Chart Repositories +### Add Custom Helm Chart Repositories You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. @@ -52,11 +54,11 @@ For more information on Helm chart repositories, see the [official Helm docs](ht To add a custom Helm chart repository to Rancher, click **Create** and select **http(s) URL to an index generated by Helm** as the target. Enter a repo name and the index URL address of the chart repository. -#### Add Private Git/Helm Chart Repositories +### Add Private Git/Helm Chart Repositories You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. -#### Add a Private CA to Repositories +### Add a Private CA to Repositories To add a private CA to Helm chart repositories: @@ -79,35 +81,41 @@ To add a private CA to Helm chart repositories: [...] ``` -> **Note:** Helm chart repositories with authentication -> -> As of Rancher v2.5.12, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. -> -> To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. -> -> ```yaml +:::note Helm chart repositories with authentication + +As of Rancher v2.5.12, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. + +To use this feature for an existing Helm chart repository, click **⋮ > Edit YAML**. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. + +```yaml [...] spec: disableSameOriginCheck: true [...] ``` -### Helm Compatibility +::: + +## Helm Compatibility The Cluster Explorer only supports Helm 3 compatible charts. +## Deploy and Upgrade Charts -### Deployment and Upgrades +From the **Charts** tab select a chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. -From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. +To view all recent changes, go to the **Recent Operations** tab. From there you can view the call that was made, conditions, events, and logs. -To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs. +After installing a chart, you can find it in the **Installed Apps** tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. -After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. +Most Rancher tools have additional pages located in the toolbar below the **Apps & Marketplace** section to help manage and use features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. -Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. +:::caution -> If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: - * use the default upgrade option ( i.e do not use _"--force"_ option ) - * uninstall the existing chart and install the upgraded chart - * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade +If you are upgrading your chart using **Customize Helm options before upgrade**, please be aware that using the `--force` option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: + + * Use the default upgrade option ( i.e do not use `--force` option ). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing the `--force` upgrade. + +::: diff --git a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md index 01dbf360e55..d5acd5adfe2 100644 --- a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -166,6 +166,7 @@ helm repo update helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ + --set installCRDs=true \ --version v1.11.0 ``` diff --git a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 09ba8e7b904..e4c6f6556a6 100644 --- a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -29,7 +29,7 @@ A restore is performed by creating a Restore custom resource. 1. In the left navigation bar, click **Rancher Backups > Restore**. :::note - If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps & Marketplace** (Rancher before v2.6.5) or **Apps** (Rancher v2.6.5+). Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#charts) for more information. + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps & Marketplace** (Rancher before v2.6.5) or **Apps** (Rancher v2.6.5+). Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#access-charts) for more information. ::: diff --git a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/versioned_docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/versioned_docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/versioned_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/versioned_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 index 9e5a5333e06..4ccc34749e7 100644 --- a/versioned_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/versioned_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 @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/versioned_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/versioned_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 1a4519e1bfe..bc679f07a08 100644 --- a/versioned_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/versioned_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 @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/versioned_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/versioned_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 6d51ee592fe..0213fe654ca 100644 --- a/versioned_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/versioned_docs/version-2.6/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -8,11 +8,7 @@ title: Upgrading Rancher Installed with Docker The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -:::caution - -**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) before upgrading. - -::: + ## Prerequisites diff --git a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/versioned_docs/version-2.6/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/versioned_docs/version-2.6/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md index 691c25eb268..26ac92608de 100644 --- a/versioned_docs/version-2.6/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md +++ b/versioned_docs/version-2.6/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -1,18 +1,32 @@ --- -title: Helm Charts in Rancher +title: Helm Charts and Apps --- -In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using **Apps & Marketplace** (Rancher before v2.6.5) or **Apps** (Rancher v2.6.5+). It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. +In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. -### Changes in Rancher v2.6 +## How Helm Charts Work in Rancher -Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts was implemented. The changes are centered around the major version of the charts and the +up annotation for upstream charts, where applicable. +Rancher uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. -**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps & Marketplace** (Rancher before v2.6.5) or **Apps** (Rancher v2.6.5+) charts are also upgraded to the correct release line for the chart. +### Catalogs, Apps, and the Rancher UI + +[Rancher v2.4 and earlier](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), repositories of ready-to-deploy applications were called "catalogs". These repositories were managed through the **Catalogs** section of the UI. + +Helm chart repositories are now managed using **Apps & Marketplace** (before Rancher v2.6.5) or **Apps** (Rancher v2.6.5 and later). + +### Versioning Changes in Rancher v2.6 + +Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts was implemented. The changes are centered around the major version of the charts and the `+up` annotation for upstream charts, where applicable. + +**Major Version:** The major versions of feature charts are tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your charts are also upgraded to the correct release line for the chart. + +**Charts based on upstream:** When you upgrade, make sure that the upstream chart version is compatible with your Rancher version. The `+up` annotation for the chart indicates which upstream version the Rancher chart is tracking. For example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some additional Rancher patches. + +When upgrading Rancher versions, don't downgrade the version of the chart that you are using. For example, if you are using a version of Monitoring that is later than `16.6.0` in Rancher v2.5, you shouldn't upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. :::note @@ -20,7 +34,7 @@ Any major versions that are less than the ones mentioned in the table below are ::: -**Feature Charts:** +### Feature Charts | **Name** | **Supported Minimum Version** | **Supported Maximum Version** | | ---------------- | ------------ | ------------ | @@ -41,36 +55,28 @@ Any major versions that are less than the ones mentioned in the table below are | rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 | | rancher-wins-upgrader | 0.0.100 | 100.0.1+up0.0.1 | -
-**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also. - -- As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it. - -- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. - - -### Charts +## Access Charts -From the top-left menu select **Apps** and you will be taken to the Charts page. +From the top-left menu select **Apps** and you will be taken to the **Charts** page. -From the top-left menu select **Apps & Marketplace** and you will be taken to the Charts page. +From the top-left menu select **Apps & Marketplace** and you will be taken to the **Charts** page. -The charts page contains all Rancher, Partner, and Custom Charts. +The **Charts** page contains all Rancher, Partner, and Custom charts. You can filter charts by selecting the left-most dropdown menu: -* Rancher tools such as Logging or Monitoring are included under the Rancher label -* Partner charts reside under the Partners label -* Custom charts will show up under the name of the repository +* Rancher tools such as Logging or Monitoring are listed under the **Rancher** label. +* Partner charts are under the **Partners** label. +* Custom charts are listed under the name of their respective repository. -All three types are deployed and managed in the same way. +All three types of charts are deployed and managed in the same way. :::note @@ -78,38 +84,48 @@ Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) s ::: -### Repositories +## Manage Repositories -From the left sidebar select _"Repositories"_. +The **Repositories** page lists your Helm repositories. These include traditional Helm endpoints which have an index.yaml, and Git repositories that are cloned and point to a specific branch. To use custom charts, add your repository here. After you add a repository, you can access custom charts in the **Charts** page, listed under the name of the repository. -These items represent Helm repositories, and can be either traditional Helm endpoints which have an index.yaml, or Git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository. +To access the **Repositories** page, select **Repositories** from the left nevigation menu. -#### Add Custom Git Repositories +### Add Custom Git Repositories -Click **Create** and select the target, **Git repository containing Helm chart...** to add a custom Git repository that contains your Helm charts or cluster template definitions. +To add a custom Git repository that contains your Helm charts or cluster template definitions: -You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from the default, `main`. +1. Select **Repositories** from the left nevigation menu. +1. Click **Create**. +1. Select the target, **Git repository containing Helm chart...**. +1. You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is named either `main` or `master`. +1. Click **Create** to add the repository. -Whenever you add a chart repository to Rancher, it becomes available immediately. +After you add a chart repository to Rancher, it becomes available immediately. -#### Add Custom Helm Chart Repositories +### Add Custom Helm Chart Repositories You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. For more information on Helm chart repositories, see the [official Helm docs](https://helm.sh/docs/topics/chart_repository/). -To add a custom Helm chart repository to Rancher, click **Create** and select **http(s) URL to an index generated by Helm** as the target. Enter a repo name and the index URL address of the chart repository. +1. Select **Repositories** from the left nevigation menu. +1. Click **Create**. +1. Select the target, **http(s) URL to an index generated by Helm**. +1. Enter a repo name and the index URL address of the chart repository. -#### Add Private Git/Helm Chart Repositories +### Add Private Git/Helm Chart Repositories You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. -#### Add a Private CA to Repositories +### Add a Private CA to Repositories To add a private CA to Helm chart repositories: -- **HTTP-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` +1. Select **Repositories** from the left nevigation menu. +1. Find the row associated with the Git or HTTP-based repository you want to add a private CA to, and click **⋮ > Edit YAML**. +1. Set the `caBundle` value, as in the following example: + + ```yaml [...] spec: caBundle: @@ -117,26 +133,13 @@ To add a private CA to Helm chart repositories: ... nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= [...] - ``` - - -- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` - [...] - spec: - caBundle: - MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT - ... - nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= - [...] - ``` - + ``` :::note Helm chart repositories with authentication As of Rancher v2.6.3, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. -To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. +To use this feature for an existing Helm chart repository, click **⋮ > Edit YAML**. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. ```yaml [...] @@ -147,41 +150,39 @@ spec: ::: -### Helm Compatibility +## Helm Compatibility Only Helm 3 compatible charts are supported. +## Deploy and Upgrade Charts -### Deployment and Upgrades +From the **Charts** tab select a chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. After you click install, a Helm operation job is deployed, and the console for the job is displayed. -From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. +To view all recent changes, go to the **Recent Operations** tab. From there you can view the call that was made, conditions, events, and logs. -To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs. +After installing a chart, you can find it in the **Installed Apps** tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. -After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. - -Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. +Most Rancher tools have additional pages located in the toolbar below the **Apps & Marketplace** section to help manage and use features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. :::caution -If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: +If you are upgrading your chart using **Customize Helm options before upgrade**, please be aware that using the `--force` option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed after they are created. To ensure you do not get this error you can: - * use the default upgrade option ( i.e do not use _"--force"_ option ) - * uninstall the existing chart and install the upgraded chart - * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade + * Use the default upgrade option ( i.e do not use `--force` option ). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing the `--force` upgrade. ::: -#### Changes in Rancher v2.6.3 +### Changes in Rancher v2.6.3 -The upgrade button has been removed for legacy apps from the **Apps & Marketplace > Installed Apps** page. +The upgrade button isn't available for legacy apps on the **Apps > Installed Apps** page. -If you have a legacy app installed and want to upgrade it: +If you want to upgrade an installed legacy app, the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on. This flag is automatically turned on if you had a legacy app already running before you upgraded Rancher. -- The legacy [feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading) -- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps** -- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there +- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps**. +- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there. -### Limitations +## Limitations -Dashboard apps or Rancher feature charts **cannot** be installed using the Rancher CLI. +Dashboard apps or Rancher feature charts can't be installed using the Rancher CLI. diff --git a/versioned_docs/version-2.6/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.6/reference-guides/about-the-api/api-tokens.md index c833cd47cb3..f58b437df74 100644 --- a/versioned_docs/version-2.6/reference-guides/about-the-api/api-tokens.md +++ b/versioned_docs/version-2.6/reference-guides/about-the-api/api-tokens.md @@ -10,8 +10,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`. @@ -19,7 +20,7 @@ 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 | | ----------------- | -------------------------------------------------------------------------------------- | @@ -30,12 +31,12 @@ Here is the complete list of tokens that are generated with `ttl=0`: | `helm-token-*` | Token for Helm chart deployment | | `*-pipeline*` | Pipeline token for project | | `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. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `0`, which means that tokens never expire. :::note @@ -43,49 +44,55 @@ 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](../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. 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 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. +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 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 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 removed in 2.8.0.** Rancher v2.8 and later instead use `kubeconfig-default-token-ttl-minutes` 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. +### 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). +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). The default value is `0`, which means that tokens never expire. **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).** +### kubeconfig-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 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 rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). +**Deprecated since Rancher v2.6.6.** -#### 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). +### 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`. Auth tokens are tokens created for authenticating API requests. The default value is `0`, which means that tokens never expire. +**Rancher v2.6.6 and later: Applies to all kubeconfig tokens and api tokens.** + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, the kubeconfig contains 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.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md index 4448a2d739e..8d367774725 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -160,7 +160,8 @@ helm repo update # Install the cert-manager Helm chart helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ - --create-namespace + --create-namespace \ + --set installCRDs=true ``` Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index b24a756b86d..e5334e94708 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -78,7 +78,7 @@ A restore is performed by creating a Restore custom resource. 1. In the left navigation bar, click **Rancher Backups > Restore**. :::note - If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#charts) for more information. + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#access-charts) for more information. ::: diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md index 9e5a5333e06..4ccc34749e7 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 1a4519e1bfe..bc679f07a08 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index b458a86bc73..a30c2cbf747 100644 --- a/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -8,11 +8,7 @@ title: Upgrading Rancher Installed with Docker The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -:::caution - -**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) before upgrading. - -::: + ## Prerequisites diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md index ba159df89cf..6bd70830564 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -1,20 +1,48 @@ --- -title: Helm Charts in Rancher +title: Helm Charts and Apps --- -In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using **Apps**. It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. +In this section, you'll learn how to manage Helm chart repositories and apps in Rancher. + +## How Helm Charts Work in Rancher + +Helm chart repositories in Rancher are managed using **Apps**. + +Rancher uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. + +### Catalogs, Apps, and the Rancher UI + +[Rancher v2.4 and earlier](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), repositories of ready-to-deploy applications were called "catalogs". These repositories were managed through the **Catalogs** section of the UI. + +Rancher v2.5 replaced the former catalog system with a new **Apps & Marketplace** feature. + +Since Rancher v2.6.5, the **Apps & Marketplace** feature is named **Apps** in the UI. ### Versioning Scheme The Rancher feature charts versioning scheme is centered around the major version of the charts and the `+up` annotation for upstream charts, where applicable. -**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps** charts are also upgraded to the correct release line for the chart. +**Major Version:** The major versions of feature charts are tied to particular minor versions of Rancher. When you upgrade to a new Rancher minor version, you should ensure that all of your feature charts are also upgraded to the correct release line for the chart. -**Feature Charts:** +**Charts based on upstream:** When you upgrade, make sure that the upstream chart version is compatible with your Rancher version. The `+up` annotation for the chart indicates which upstream version the Rancher chart is tracking. For example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some additional Rancher patches. + +When upgrading Rancher versions, don't downgrade the version of the chart that you are using. For example, if you are using a version of Monitoring that is later than `16.6.0` in Rancher v2.5, you shouldn't upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. + +#### Prerelease Versions + +Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. + +To display prerelease versions: + +1. Click on your user avatar in the upper right corner. +1. Click **Preferences**. +1. Under **Helm Charts**, select **Include Prerelease Versions**. + +### Feature Charts | **Name** | **Supported Minimum Version** | **Supported Maximum Version** | | ---------------- | ------------ | ------------ | @@ -35,73 +63,82 @@ The Rancher feature charts versioning scheme is centered around the major versio | rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 | | rancher-wins-upgrader | 0.0.100 | 100.0.1+up0.0.1 | -
-**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also. +## Access Charts -- As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it. +The **Charts** page contains all Rancher, Partner, and Custom charts. You can filter charts by selecting the left-most dropdown menu: -- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. +* Rancher tools such as Logging or Monitoring are listed under the **Rancher** label. +* Partner charts are under the **Partners** label. +* Custom charts are listed under the name of their respective repository. -### Prerelease Versions - -Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. - -To display prerelease versions: - -1. Click on your user avatar in the upper right corner. -1. Click **Preferences**. -1. Under **Helm Charts**, select **Include Prerelease Versions**. - -### Charts - -From the top-left menu select _"Apps"_ and you will be taken to the Charts page. - -The charts page contains all Rancher, Partner, and Custom Charts. - -* Rancher tools such as Logging or Monitoring are included under the Rancher label -* Partner charts reside under the Partners label -* Custom charts will show up under the name of the repository - -All three types are deployed and managed in the same way. +All three types of charts are deployed and managed in the same way. :::note -Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) should continue to be managed only by the Cluster Manager, and apps managed with Apps in the new UI must be managed only by Apps. +Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) continue to be managed only by the Cluster Manager, and apps managed with **Apps** in the new UI must be managed only by **Apps**. ::: -### Repositories +To access the **Charts** page: -From the left sidebar select _"Repositories"_. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. -These items represent Helm repositories, and can be either traditional Helm endpoints which have an index.yaml, or Git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository. +## Manage Repositories -#### Add Custom Git Repositories +The **Repositories** page lists your Helm repositories. These include traditional Helm endpoints which have an index.yaml, and Git repositories that are cloned and point to a specific branch. To use custom charts, add your repository here. After you add a repository, you can access custom charts in the **Charts** page, listed under the name of the repository. -Click **Create** and select the target, **Git repository containing Helm chart...** to add a custom Git repository that contains your Helm charts or cluster template definitions. +To access the **Repositories** page: -You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from the default, `main`. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. -Whenever you add a chart repository to Rancher, it becomes available immediately. +### Add Custom Git Repositories -#### Add Custom Helm Chart Repositories +To add a custom Git repository that contains your Helm charts or cluster template definitions: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **Git repository containing Helm chart...**. +1. You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is named either `main` or `master`. +1. Click **Create** to add the repository. + +After you add a chart repository to Rancher, it becomes available immediately. + +### Add Custom Helm Chart Repositories You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. For more information on Helm chart repositories, see the [official Helm docs](https://helm.sh/docs/topics/chart_repository/). -To add a custom Helm chart repository to Rancher, click **Create** and select **http(s) URL to an index generated by Helm** as the target. Enter a repo name and the index URL address of the chart repository. +To add a custom Helm chart repository to Rancher: -#### Add Private Git/Helm Chart Repositories +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **http(s) URL to an index generated by Helm**. +1. Enter a repo name and the index URL address of the chart repository. +1. Click **Create** to add the repository. + +### Add Private Git/Helm Chart Repositories You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. -#### Add a Private CA to Repositories +### Add a Private CA to Repositories -To add a private CA to Helm chart repositories: +To add a private CA to Helm chart repositories, you must add a base64 encoded copy of the CA certificate in DER format to the `spec.caBundle field` of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Instructions are the same for both Git-based and HTTP-based repositories: -- **HTTP-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the row associated with the Git or HTTP-based repository you want to add a private CA to, and click **⋮ > Edit YAML**. +1. Set the `caBundle` value, as in the following example: + + ```yaml [...] spec: caBundle: @@ -109,25 +146,13 @@ To add a private CA to Helm chart repositories: ... nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= [...] - ``` - - -- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
- ``` - [...] - spec: - caBundle: - MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT - ... - nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= - [...] - ``` + ``` :::note Helm chart repositories with authentication -The Repo.Spec contains a `disableSameOriginCheck` value that allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. +The Repo.Spec contains a `disableSameOriginCheck` value. This value allows you to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories, such as those that have redirects to a different origin URL. -To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. +To use this feature for an existing Helm chart repository, follow previous steps up to edit the YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. ```yaml [...] @@ -142,37 +167,51 @@ spec: Only Helm 3 compatible charts are supported. +## Deploy and Upgrade Charts -### Deployment and Upgrades +To install and deploy a chart: -From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Select a chart, and click **Install**. -To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs. +Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files. However, all chart installations can modify the values.yaml and other basic settings. After you click **Install**, a Helm operation job is deployed, and the console for the job is displayed. -After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. +To view all recent changes, click **Apps > Recent Operations** in the left navigation menu. From there you can view the calls, conditions, events, and logs. -Most Rancher tools have additional pages located in the toolbar below the _"Apps"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. +After installing a chart, you can view it by clicking **Apps > Installed Apps** in the left navigation menu. You can upgrade or delete the installation, and see further details. Upgrading uses the same forms and values as you saw during inital installation. + +Most Rancher tools have additional pages located in the toolbar below the **Apps** section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. :::caution -If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: +If you are upgrading your chart using **Customize Helm options before upgrade**, and your chart contains immutable fields, using the `--force` option may result in errors. This is because some objects in Kubernetes can't be changed after they're created. To prevent this error: - * use the default upgrade option ( i.e do not use _"--force"_ option ) - * uninstall the existing chart and install the upgraded chart - * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade + * Use the default upgrade option (i.e don't use `--force`). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing a forced upgrade. ::: -#### Legacy Apps +### Legacy Apps -The upgrade button has been removed for legacy apps from the **Apps > Installed Apps** page. +The upgrade button isn't available for legacy apps on the **Apps > Installed Apps** page. -If you have a legacy app installed and want to upgrade it: +If you want to upgrade an installed legacy app, the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on. This flag is automatically turned on if you had a legacy app already running before you upgraded Rancher. -- The legacy [feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading) -- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps** -- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there +1. Enable the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md), if it isn't enabled already. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose apps you want to access. Click **Explore** at the end of the cluster's row. +1. Click **Legacy > Project > Apps**. -### Limitations +If you don't see **Apps** listed under **Legacy > Project**, click the project/namespace search bar in the top navigation and select the relevant project from the dropdown menu. -Dashboard apps or Rancher feature charts **cannot** be installed using the Rancher CLI. +To upgrade legacy multi-cluster apps: + +1. Click **☰**. +1. Under **Legacy Apps**, click **Multi-cluster Apps**. + +## Limitations + +Dashboard apps or Rancher feature charts can't be installed using the Rancher CLI. diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md index 4bae5b14832..4fd1d0368e6 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md @@ -7,12 +7,12 @@ title: Migrating Amazon In-tree to Out-of-tree :::note -Rancher Prime provides access to Rancher v2.7.11, a version of Rancher v2.7.x which supports Kubernetes 1.27. If you use Rancher v2.7.11 and upgrade to Kubernetes 1.27, you must use an out-of-tree cloud provider. +Rancher Prime provides access to Rancher v2.7.11, a version of Rancher v2.7.x which supports Kubernetes v1.27. If you use Rancher v2.7.11 and upgrade to Kubernetes 1.27, you must use an out-of-tree cloud provider. ::: -Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes 1.27 and later, the in-tree cloud providers have been removed. +Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes 1.27 and later, the in-tree cloud providers have been removed. The Rancher UI allows you to upgrade to Kubernetes v1.27 when you migrate from an in-tree to out-of-tree provider. -You can migrate from an in-tree to an out-of-tree AWS cloud provider on Kubernetes 1.26 and earlier. All existing clusters must migrate prior to upgrading to v1.27 in order to stay functional. +However, if you're performing a manual migration, existing clusters must upgrade to Kubernetes v1.27 after you migrate in order to remain functional. To migrate from the in-tree cloud provider to the out-of-tree AWS cloud provider, you must stop the existing cluster's kube controller manager and install the AWS cloud controller manager. There are many ways to do this. Refer to the official AWS documentation on the [external cloud controller manager](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for details. @@ -56,7 +56,7 @@ spec: 2. Cordon control plane nodes so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider: ```shell -kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" ``` 3. To install the AWS cloud controller manager with leader migration enabled, follow Steps 1-3 for [deploying the cloud controller manager chart](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider). From Kubernetes 1.22 onwards, the kube-controller-manager will utilize a default configuration which will satisfy the controller-to-manager migration. Update container args of the `aws-cloud-controller-manager` under `spec.rkeConfig.additionalManifest` to enable leader migration: 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 064eec4332b..3483b28f07d 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 @@ -352,9 +352,9 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' args: - --configure-cloud-routes=false - --use-service-account-credentials=true @@ -639,7 +639,7 @@ kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager - get ``` -9. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: +9. Rancher-provisioned RKE2 nodes are tainted `node-role.kubernetes.io/control-plane`. Update tolerations and the nodeSelector: ```yaml tolerations: @@ -648,13 +648,13 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane ``` ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` :::note @@ -663,7 +663,7 @@ There's currently a [known issue](https://github.com/rancher/dashboard/issues/92 ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` ::: diff --git a/versioned_docs/version-2.7/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md b/versioned_docs/version-2.7/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md index 6c0b1c1d0d2..69398199394 100644 --- a/versioned_docs/version-2.7/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md +++ b/versioned_docs/version-2.7/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md @@ -18,7 +18,7 @@ In clusters that store data on GlusterFS volumes, you may experience an issue wh - The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use) ``` -docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version +docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run -v /usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3 -v /lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.26.14-rancher1 --version ``` :::caution @@ -32,6 +32,8 @@ services: kubelet: extra_binds: - "/usr/bin/systemd-run:/usr/bin/systemd-run" + - "/usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3" + - "/lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so" ``` After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline: diff --git a/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/aws-marketplace-payg-integration.md b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/aws-marketplace-payg-integration.md index 46400992753..039e904b920 100644 --- a/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/aws-marketplace-payg-integration.md +++ b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/aws-marketplace-payg-integration.md @@ -2,10 +2,6 @@ title: AWS Marketplace Pay-as-you-go (PAYG) Integration --- - - - - ## Overview Rancher Prime integrates with the [AWS Marketplace](https://aws.amazon.com/marketplace) as a pay-as-you-go (PAYG) offering. This brings the value of running and managing Kubernetes environments to AWS customers, benefiting from a new pay-monthly pricing model available through the AWS Marketplace. This listing will enable you to manage any CNCF-certified Kubernetes distribution in AWS, on-prem, or at the edge. To learn more, see our non-EMEA and EMEA AWS Marketplace offerings for Rancher Prime: @@ -13,6 +9,10 @@ Rancher Prime integrates with the [AWS Marketplace](https://aws.amazon.com/marke - [Rancher Prime](https://aws.amazon.com/marketplace/pp/prodview-f2bvszurj2p2c) - [Rancher Prime (EMEA Orders Only)](https://aws.amazon.com/marketplace/pp/prodview-ocgjwd5c2aj5i) +## FAQ + +For more details on how Rancher pay-as-you-go offerings work, refer to the [pay-as-you-go FAQ](../cloud-marketplace-payg-integration.md#faq). + ## Limitations - Currently, you must be running Rancher v2.7.9. When you deploy a supported PAYG version, you can update to newer versions of Rancher when the listing is updated. @@ -21,489 +21,3 @@ Rancher Prime integrates with the [AWS Marketplace](https://aws.amazon.com/marke 1. Complete the [prerequisite steps](prerequisites.md). 2. [Install the Rancher Prime PAYG offering on the AWS Marketplace](installing-rancher-prime.md). - -## FAQ - -The following is a list of frequently asked questions. - -### Marketplace Listing - -#### What is the Rancher Prime listing on the AWS Marketplace? - -By selecting the Rancher Prime listing from the AWS Marketplace, customers can deploy Rancher to their Kubernetes environment with the advantage of having monthly billing via AWS. - -#### Where do I find the Rancher Prime listings? - -There are two listings in the AWS Marketplace. They are: - -- [Rancher Prime](https://aws.amazon.com/marketplace/pp/prodview-f2bvszurj2p2c) -- [Rancher Prime (EMEA Orders Only)](https://aws.amazon.com/marketplace/pp/prodview-ocgjwd5c2aj5i) - -#### Why are there two listings? Which one should I use? - -We have two listings for Rancher Prime, "EU, EEA, or UK Orders" and "non EU, EEA, or UK Orders." You should pick the listing that reflects where your AWS account gets billed. - -#### Are these listings available in all countries? - -No. The Rancher listing on AWS is not available to purchase in all countries. - -Your billing country is based on the AWS Account ID used to do the deployment. - -Please refer to the following lists of countries that can and cannot transact Rancher Prime via the AWS Marketplace. - -
- Countries that can transact SUSE Rancher Support through the AWS Marketplace -
-
  • Australia, AU
    • -
  • Austria, AT
    • -
  • Bangladesh, BD
    • -
  • Belgium, BE
    • -
  • Bulgaria, BG
    • -
  • Cameroon, CM
    • -
  • Canada, CA
    • -
  • Chile, CL
    • -
  • Croatia, HR
    • -
  • Cyprus, CY
    • -
  • Czech Republic, CZ
    • -
  • Denmark, DK
    • -
  • Egypt, EG
    • -
  • Estonia, EE
    • -
  • Finland, FI
    • -
  • France, FR
    • -
  • Germany, DE
    • -
  • Greece, GR
    • -
  • Hungary, HU
    • -
  • Iceland, IS
    • -
  • India, IN
    • -
  • Indonesia, ID
    • -
  • Ireland, IE
    • -
  • Isle of Man, IM
    • -
  • Italy, IT
    • -
  • Kenya, KE
    • -
  • Kingdom of Saudi Arabia, SA
    • -
  • Korea, Republic of, KR
    • -
  • Latvia, LV
    • -
  • Lithuania, LT
    • -
  • Liechtenstein, LI
    • -
  • Luxembourg, LU
    • -
  • Malaysia, MY
    • -
  • Malta, MT
    • -
  • Netherlands, NL
    • -
  • New Zealand, NZ
    • -
  • Norway, NO
    • -
  • Poland, PL
    • -
  • Portugal, PT
    • -
  • Romania, RO
    • -
  • Russian Federation, RU
    • -
  • Singapore, SG
    • -
  • Slovakia, SK
    • -
  • Slovenia, SI
    • -
  • South Africa, ZA
    • -
  • Spain, ES
    • -
  • Sweden, SE
    • -
  • Switzerland, CH
    • -
  • Taiwan, Province of China, TW
    • -
  • Turkey, TR
    • -
  • United Kingdom, GB
    • -
  • United States, US
    • -
    -
    - -
    - Countries that cannot transact SUSE Rancher Support via the AWS Marketplace -
    -
  • Afghanistan, AF
    • -
  • Åland Islands, AX
    • -
  • Albania, AL
    • -
  • Algeria, DZ
    • -
  • American Samoa, AS
    • -
  • Andorra, AD
    • -
  • Angola, AO
    • -
  • Anguilla, AI
    • -
  • Antarctica, AQ
    • -
  • Antigua and Barbuda, AG
    • -
  • Argentina, AR
    • -
  • Armenia, AM
    • -
  • Aruba, AW
    • -
  • Azerbaijan, AZ
    • -
  • Bahamas, BS
    • -
  • Bahrain, BH
    • -
  • Barbados, BB
    • -
  • Belarus, BY
    • -
  • Belize, BZ
    • -
  • Benin, BJ
    • -
  • Bermuda, BM
    • -
  • Bhutan, BT
    • -
  • Bonaire, BQ
    • -
  • Bolivarian Republic of Venezuela, VE
    • -
  • Bosnia and Herzegovina, BA
    • -
  • Botswana, BW
    • -
  • Bouvet Island, BV
    • -
  • Brazil, BR
    • -
  • British Indian Ocean Territory, IO
    • -
  • Brunei Darussalam, BN
    • -
  • Burkina Faso, BF
    • -
  • Burundi, BI
    • -
  • Cambodia, KH
    • -
  • Cape Verde, CV
    • -
  • Cayman Islands, KY
    • -
  • Central African Republic, CF
    • -
  • Chad, TD
    • -
  • China, CN
    • -
  • Christmas Island, CX
    • -
  • Cocos (Keeling) Islands, CC
    • -
  • Colombia, CO
    • -
  • Comoros, KM
    • -
  • Congo, CG
    • -
  • Cook Islands, CK
    • -
  • Costa Rica, CR
    • -
  • Côte d'Ivoire, CI
    • -
  • Curaçao, CW
    • -
  • Democratic Republic of the Congo, CD
    • -
  • Djibouti, DJ
    • -
  • Dominica, DM
    • -
  • Dominican Republic, DO
    • -
  • Ecuador, EC
    • -
  • El Salvador, SV
    • -
  • Equatorial Guinea, GQ
    • -
  • Eritrea, ER
    • -
  • Ethiopia, ET
    • -
  • Falkland Islands (Malvinas), FK
    • -
  • Faroe Islands, FO
    • -
  • Federated States of Micronesia, FM
    • -
  • Fiji, FJ
    • -
  • Former Yugoslav Republic of Macedonia, MK
    • -
  • French Guiana, GF
    • -
  • French Polynesia, PF
    • -
  • French Southern Territories, TF
    • -
  • Gabon, GA
    • -
  • Gambia, GM
    • -
  • Georgia, GE
    • -
  • Ghana, GH
    • -
  • Gibraltar, GI
    • -
  • Greenland, GL
    • -
  • Grenada, GD
    • -
  • Guadeloupe, GP
    • -
  • Guam, GU
    • -
  • Guatemala, GT
    • -
  • Guernsey, GG
    • -
  • Guinea, GN
    • -
  • Guinea-Bissau, GW
    • -
  • Guyana, GY
    • -
  • Haiti, HT
    • -
  • Heard Island and McDonald Islands, HM
    • -
  • Holy See (Vatican City State), VA
    • -
  • Honduras, HN
    • -
  • Hong Kong, HK
    • -
  • Iraq, IQ
    • -
  • Israel, IL
    • -
  • Jamaica, JM
    • -
  • Japan, JP
    • -
  • Jersey, JE
    • -
  • Jordan, JO
    • -
  • Kazakhstan, KZ
    • -
  • Kiribati, KI
    • -
  • Kuwait, KW
    • -
  • Kyrgyzstan, KG
    • -
  • Lao People's Democratic Republic, LA
    • -
  • Lebanon, LB
    • -
  • Lesotho, LS
    • -
  • Liberia, LR
    • -
  • Libyan Arab Jamahiriya, LY
    • -
  • Macao, MO
    • -
  • Madagascar, MG
    • -
  • Malawi, MW
    • -
  • Maldives, MV
    • -
  • Mali, ML
    • -
  • Marshall Islands, MH
    • -
  • Martinique, MQ
    • -
  • Mauritania, MR
    • -
  • Mauritius, MU
    • -
  • Mayotte, YT
    • -
  • Mexico, MX
    • -
  • Mongolia, MN
    • -
  • Montenegro, ME
    • -
  • Montserrat, MS
    • -
  • Morocco, MA
    • -
  • Mozambique, MZ
    • -
  • Myanmar, MM
    • -
  • Namibia, NA
    • -
  • Nauru, NR
    • -
  • Nepal, NP
    • -
  • New Caledonia, NC
    • -
  • Nicaragua, NI
    • -
  • Niger, NE
    • -
  • Nigeria, NG
    • -
  • Niue, NU
    • -
  • Norfolk Island, NF
    • -
  • Northern Mariana Islands, MP
    • -
  • Oman, OM
    • -
  • Pakistan, PK
    • -
  • Palau, PW
    • -
  • Occupied Palestinian Territory, PS
    • -
  • Panama, PA
    • -
  • Papua New Guinea, PG
    • -
  • Paraguay, PY
    • -
  • Peru, PE
    • -
  • Philippines, PH
    • -
  • Pitcairn, PN
    • -
  • Plurinational State of Bolivia, BO
    • -
  • Puerto Rico, PR
    • -
  • Qatar, QA
    • -
  • Republic of Moldova, MD
    • -
  • Réunion, RE
    • -
  • Rwanda, RW
    • -
  • Saint Barthélemy, BL
    • -
  • Saint Helena, Ascension and Tristan da Cunha, SH
    • -
  • Saint Kitts and Nevis, KN
    • -
  • Saint Lucia, LC
    • -
  • Saint Martin, MF
    • -
  • Saint Pierre and Miquelon, PM
    • -
  • Saint Vincent and the Grenadines, VC
    • -
  • Samoa, WS
    • -
  • San Marino, SM
    • -
  • Sao Tome and Principe, ST
    • -
  • Senegal, SN
    • -
  • Serbia, RS
    • -
  • Seychelles, SC
    • -
  • Sierra Leone, SL
    • -
  • Sint Maarten, SX
    • -
  • Solomon Islands, SB
    • -
  • Somalia, SO
    • -
  • South Georgia and the South Sandwich Islands, GS
    • -
  • South Sudan, SS
    • -
  • Sri Lanka, LK
    • -
  • Suriname, SR
    • -
  • Svalbard and Jan Mayen, SJ
    • -
  • Swaziland, SZ
    • -
  • Tajikistan, TJ
    • -
  • Thailand, TH
    • -
  • Timor-Leste, TL
    • -
  • Togo, TG
    • -
  • Tokelau, TK
    • -
  • Tonga, TO
    • -
  • Trinidad and Tobago, TT
    • -
  • Tunisia, TN
    • -
  • Turkmenistan, TM
    • -
  • Turks and Caicos Islands, TC
    • -
  • Tuvalu, TV
    • -
  • Uganda, UG
    • -
  • Ukraine, UA
    • -
  • United Arab Emirates, AE
    • -
  • United Republic of Tanzania, TZ
    • -
  • United States Minor Outlying Islands, UM
    • -
  • Uruguay, UY
    • -
  • Uzbekistan, UZ
    • -
  • Vanuatu, VU
    • -
  • Viet Nam, VN
    • -
  • Virgin Islands, British, VG
    • -
  • Virgin Islands, U.S., VI
    • -
  • Wallis and Futuna, WF
    • -
  • Western Sahara, EH
    • -
  • Yemen, YE
    • -
  • Zambia, ZM
    • -
  • Zimbabwe, ZW
    • -
    -
    - -#### My AWS account is in the USA, but I want to deploy Rancher in another AWS region, a region that is in a country where I currently cannot transact Rancher Prime. Is this possible? - -Yes. As long as your AWS account is billed to one of the allowed countries, it is possible to deploy Rancher in any AWS regions. - -#### Is this listing available in China? - -While it is not possible to transact/bill Rancher Prime in China, it is possible to deploy into AWS regions in China. - -#### Can I still deploy Rancher using the "Rancher Setup" listing from the AWS Marketplace? - -"Rancher Setup" is no longer available via AWS Marketplace. Customers should deploy an EKS Cluster to host Rancher. Follow the steps in this [guide](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md) except for the Rancher installation. The Rancher product installation should be carried out as per [installing the Rancher Prime PAYG offering on Amazon's AWS Marketplace](installing-rancher-prime.md). - -### Billing - -#### I have an existing Rancher Prime subscription. Can I use this on AWS? - -BYOS (Bring Your Own Subscription) Rancher deployments are supported on AWS; however, billing will not be via the AWS Marketplace. Once the existing subscription term ends, you can purchase Rancher Prime via the AWS Marketplace and reconfigure your cluster to support monthly billing via AWS. - -#### I have an existing Rancher Subscription purchased via the ’Rancher Premium Support’ listing on AWS. Isthis transferable to the new model? - -No. A new deployment of Rancher Prime is required to benefit from the new monthly billing model. - -#### I have an existing deployment covered by a Rancher subscription; can I use this new listing in AWS for new deployments? - -Yes. the listing works independently from your existing subscriptions. Please remember that support processes may be different for deployments using your existing subscription and those billed via the AWS Marketplace. - -#### Tell me more about how the billing for Rancher Prime works via AWS? - -When purchasing Rancher Prime via the AWS Marketplace, the billing is as follows: - -- Billing is monthly and handled via AWS Marketplace. -- Managed nodes are counted hourly when Rancher is active and added to a usage -total. -- An average node count is calculated for the month. -- There is a monthly usage charge for each node in the average node count. -- The monthly usage charge depends on the number of nodes in use. -- There is a 5-node minimum; if the average node count is less than 5 nodes, the -charge will be for 5 nodes. - -#### What are the pricing tiers? - -Rancher Prime has different pricing tiers when purchasing via the AWS Marketplace. This is based on the number of nodes which Rancher is managing. Details of the tiers are below. Please check the listing for further pricing information. - -| Tier | Nodes (from) | Nodes (to) | -| :------: | :----------: | :---------: | -| **1** | 5 | 15 | -| **2** | 16 | 50 | -| **3** | 51 | 100 | -| **4** | 101 | 250 | -| **5** | 251 | 1000 | -| **6** | 1001 | | - -#### Is there a way to try Rancher before purchasing? - -If using the Rancher Prime listing in the AWS Marketplace, billing will commence from the time of deployment. - -Rancher can be deployed manually using the standard documentation and repositories. When ready to benefit from a supported platform and have this billed via the AWS Marketplace, follow the available [documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md) to deploy Rancher Prime from the AWS Marketplace and migrate. - -#### How does SUSE calculate the ‘average number of managed nodes’ to bill for? - -The average node count is calculated by adding the number of managed nodes (counted hourly) and dividing by the number of hours Rancher has been active in the billing cycle. - -Below are three examples of how the average node count is calculated. Check the table below for the details. - -:::note - -In our example month, we are using 730 hours; this may differ depending on the number of days in the month and the billing cycle. - -::: - -- **Static usage:** Using Rancher to manage 10 nodes, for 1 month (730 hours) with no additional nodes added in the month. -- **Bursting Model:** Using Rancher to manage 10 nodes for 3 weeks (562 hours) in the month, bursting to 30 nodes for 1 week (168 hours). -- **Transient cluster:** A temporary deployment of Rancher on 20 nodes for 2 weeks (336 hours). - -| | Hours Active (Hours Rancher is active in the month) | Nodes (Managed Nodes counted at each check-in) | Usage total (Sum of nodes reported at each check-in) | Average Node Count (Usage total / hours active) | Note | -| ----------------- | :--: | :------------------------: | :----: | :--: | :------------------------------: | -| **Static Usage** | 730 | 10 | 7300 | 10 | 10 @ Tier 1 | -| **Bursting Model** | 730 | 10 (562 hrs), 30 (168 hrs) | 10660 | 15 | 15 @ Tier 1 (rounded from 14.6) | -| **Transient Cluster** | 336 | 20 | 6720 | 20 | 20 @ Tier 2 | - -#### Are special commercial terms available? - -Depending on the deployment, securing special commercial terms (e.g., an annual subscription) may be possible. This will be handled via an AWS Private offer. Please contact SUSE for more information. - -#### Can my spend on Rancher Prime count towards my AWS Enterprise Discount Program? - -Yes. Please contact your AWS Sales Team for more details. - -#### How do I purchase Rancher for additional nodes? - -Once Rancher has been deployed from the listing on AWS and billing is active, there is no need to make a specific purchase for additional nodes. Billing is dynamic and based on the number of nodes Rancher is managing. Just deploy or onboard additional clusters to Rancher as needed. - -#### Is this an annual commitment, will it auto-renew? - -By default, the Rancher Prime listing in AWS is billed on a monthly cycle, based on usage. Billing is ongoing for as long as Rancher is deployed. - -It is possible to set up an annual commitment via an AWS Private Offer; these will need to be reviewed and renewed at the end of the term, or the deployment will drop back to the default monthly billing cycle. - -### Technical (Billing) - -#### Do I need a Kubernetes cluster running in AWS to install Rancher and be billed via the AWS Marketplace? - -Yes. To benefit from monthly billing via the Marketplace, the primary Rancher cluster must be an EKS Cluster running in your AWS Account. - -#### Which Kubernetes distributions can the AWS Marketplace listing be deployed on? - -The AWS Marketplace listing for Rancher Prime with Marketplace billing must be deployed on Amazon EKS. Downstream clusters / managed worker nodes can run on any CNCF compliant Kubernetes platform, EKS, EKS-A, Rancher Kubernetes Engine, etc. - -#### What is the deployment mechanism? - -The AWS Marketplace listing for Rancher Prime is deployed using Helm. - -#### What is the easiest way to get started? - -One of the easiest ways to get started is to deploy the AWS Marketplace listing for Rancher Prime to an existing EKS cluster. Follow the instructions in the usage section, a Helm chart takes care of the installation and the setup for billing. - -#### What is the minimum version of Rancher required to support AWS Marketplace billing? - -The minimum version supporting marketplace billing is Rancher 2.7.9. - -#### What version of Rancher is installed when using the Marketplace listing? - -The AWS Marketplace listing for Rancher Prime is tied to a specific version of Rancher, typically the latest version available at the time of the listing update. Please check the listing for further information. - -#### I need a prior version of Rancher, can I still use the listing? - -No. There is no choice over the Rancher version when deploying using the AWS Marketplace listing. If a prior version of Rancher is required, this must be installed manually using the standard documentation. - -:::note - -Billing through AWS Marketplace may not be supported with previous versions. - -::: - -#### How often is the listing updated (including the version of Rancher, etc.)? - -The marketplace listing is tied to a specific version of Rancher, usually the latest version available at the time of listing. Typically, these are updated quarterly, or more frequently if there are security issues. - -#### I have many Kubernetes clusters across multiple AWS accounts, does the Rancher Prime billing still work and enable tiered pricing? - -Yes. Downstream clusters managed by Rancher can be deployed across single or multiple AWS accounts, on-premises, or even in other public clouds. Downstream nodes will report up to the primary Rancher deployment. Tiered pricing is enabled and billing will be routed to the AWS account in which the primary cluster is running. - -#### I have multiple independent clusters, each running a separate installation of the AWS Marketplace listing for Rancher Prime. How is this billed? - -As the Rancher Prime deployments are independent, each deployment is billed separately from the others. It is not possible to benefit from tiered pricing. - -#### If managing multiple independent Rancher clusters, consider custom terms from SUSE. How can I benefit from tiered pricing across all Rancher deployments? - -The primary Rancher cluster must be running on EKS in the AWS Cloud and running the AWS Marketplace listing for Rancher. To benefit from tiered pricing, managed clusters (downstream clusters) should be connected to the primary Rancher cluster. - -#### I have purchased multiple SUSE products from the AWS Marketplace (e.g., SUSE Manager, NeuVector Prime and now Rancher Prime). Does the AWS Marketplace billing method still work? - -Yes. The billing mechanism of each deployment is independent, each product will be billed separately via the AWS Marketplace. - -#### I already have an existing EKS cluster in place and want to add Rancher and have this billed via Marketplace. Is this possible? - -Yes. Simply deploy the AWS Marketplace listing for Rancher Prime. - -#### I already have an existing cluster, with Rancher deployed. Can I just install the marketplace version and have support billed via the AWS Marketplace? - -In order to benefit from monthly billing via the AWS Marketplace, the primary Rancher cluster needs to be deployed from the listing, it is then possible to migrate the existing Rancher configuration to the new deployment. - -Please follow the [documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md) and be sure to back up the existing Rancher configuration. - -### Technical (Product) - -#### How do I get support? - -It is very simple to [open a support case](https://scc.suse.com/cloudsupport) with SUSE for Rancher Prime. Create a ‘supportconfig’ via the Rancher UI and upload the output to the SUSE Customer Center. The support config bundle can be exported from the Rancher console using the ‘Get Support’ button at the bottom of the page. For deployments when Rancher is managing multiple downstream clusters, export the support config bundle from the primary cluster only. - -If the billing mechanism on the primary cluster is active, a support case will be opened. Further details can be found in the [documentation](../supportconfig.md). - -#### What are the resource requirements for installing Rancher on EKS? - -Please check the documentation for best practices. - -#### Is there any difference between Rancher Prime from the AWS Marketplace and the versions I can run in my own data center? - -Rancher Prime available in the AWS Marketplace is the same product, with the same functionality that you would run on-premises or with a manual installation. The only difference between deploying manually and deploying via the AWS Marketplace listing is the billing route. - -#### Does the primary cluster (responsible for billing) need to run 24/7? - -To ensure continuity with support, it is recommended that the primary Rancher cluster always remains active. - -#### What if the primary cluster responsible for billing is unable to connect to the AWS Billing framework? - -There may be multiple reasons why the primary cluster is unable to connect to the AWS framework, but it is the customer’s responsibility to ensure that the primary cluster is active and connected. Whilst the cluster is not connected to the billing framework, it is not possible to raise a support request. - -#### My primary cluster has been offline. What will happen with billing when reconnected? - -If the primary cluster is offline or disconnected from the AWS billing framework for a period of time, when it reconnects, the stored usage data will be uploaded to AWS and will appear on your next AWS bill. - -Depending on when in the month the primary cluster gets reconnected you may have several months of usage on your next billing cycle. - -#### Can the managed worker nodes reside on premises, at the edge or even on another cloud provider? - -Yes. Nodes can run anywhere. SUSE Rancher will count the total number of nodes managed regardless of where they are deployed. - -#### How do I get fixes and updates for Rancher? - -To update to the latest version of the Rancher Prime PAYG offering supported in the marketplace listing, please see [upgrading Rancher Prime PAYG cluster in AWS](upgrading-rancher-payg-cluster.md). diff --git a/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/azure-marketplace-payg-integration.md b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/azure-marketplace-payg-integration.md index 33c6cb21924..7991b1dfec8 100644 --- a/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/azure-marketplace-payg-integration.md +++ b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/azure-marketplace-payg-integration.md @@ -2,10 +2,6 @@ title: Azure Marketplace Pay-as-you-go (PAYG) Integration --- - - - - ## Overview Rancher Prime integrates with the [Azure Marketplace](https://azuremarketplace.microsoft.com) as a pay-as-you-go (PAYG) offering. This brings the value of running and managing Kubernetes environments to Azure customers, benefiting from a new pay-monthly pricing model available through the Azure Marketplace. This listing will enable you to manage any CNCF-certified Kubernetes distribution in Azure, on-prem, or at the edge. To learn more, see our non-EMEMA and EMEA Azure Marketplace offerings for Rancher Prime: @@ -13,6 +9,10 @@ Rancher Prime integrates with the [Azure Marketplace](https://azuremarketplace.m - [Rancher Prime with 24x7 Support](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suse.rancher-prime-llc/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suse.rancher-prime-llcpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%221dafcf16-920e-46ea-80c9-dc85c6bd3a17%22%7D/searchTelemetryId/c2300fb7-ba7b-462a-ba57-a37cb5e2822d) - [Rancher Prime with 24x7 Support (EMEA Orders Only)](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suseirelandltd1692213356027.rancher-prime-ltd/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suseirelandltd1692213356027.rancher-prime-ltdpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%22c6b1d79a-b577-47b0-90e5-41e6c49688ab%22%7D/searchTelemetryId/1793144d-e0d9-466e-8e36-dfeddc73163b) +## FAQ + +For more details on how Rancher pay-as-you-go offerings work, refer to the [pay-as-you-go FAQ](../cloud-marketplace-payg-integration.md#faq). + ## Limitations - Currently, you must be running Rancher v2.7.9. When you deploy a supported PAYG version, you can update to newer versions of Rancher when the listing is updated. @@ -21,215 +21,3 @@ Rancher Prime integrates with the [Azure Marketplace](https://azuremarketplace.m 1. Complete the [prerequisite steps](prerequisites.md). 2. [Install the Rancher Prime PAYG offering on the Azure Marketplace](installing-rancher-prime.md). - -## FAQ - -The following is a list of frequently asked questions. - -### Marketplace Listing - -#### What is the Rancher Prime listing on the Azure Marketplace? - -By selecting the Rancher Prime listing in the Azure Marketplace, customers can deploy Rancher to their Microsoft Azure Kubernetes Service (AKS) cluster environment to manage any downstream CNCF-certified Kubernetes distribution with the advantage of having monthly billing for Rancher Prime via Microsoft Azure. - -**Where do I find the Rancher Prime listings?** - -There are two listings in the Azure Marketplace. They are: - -- [Rancher Prime with 24x7 Support](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suse.rancher-prime-llc/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suse.rancher-prime-llcpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%221dafcf16-920e-46ea-80c9-dc85c6bd3a17%22%7D/searchTelemetryId/c2300fb7-ba7b-462a-ba57-a37cb5e2822d) -- [Rancher Prime with 24x7 Support (EMEA Orders Only)](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suseirelandltd1692213356027.rancher-prime-ltd/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suseirelandltd1692213356027.rancher-prime-ltdpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%22c6b1d79a-b577-47b0-90e5-41e6c49688ab%22%7D/searchTelemetryId/1793144d-e0d9-466e-8e36-dfeddc73163b) - -#### Why are there two listings? Which one should I use? - -There are two listings for Rancher Prime to accommodate Microsoft Azure billing regions. You should pick the listing that reflects where your Azure account gets billed. - -#### Are these listings available in all countries? - -No. Due to billing limitations and other restrictions, the Rancher Prime Azure Marketplace listing may not be purchasable in all countries. The Azure account you use for deployment determines your billing country. Contact your Azure Sales Team for more details. - -#### My Azure account is in the USA, but I want to deploy Rancher in another Azure region, a region that is in a country where I currently cannot transact Rancher Prime. Is this possible? - -Yes. As long as your Azure account is billed to one of the allowed countries, it is possible to deploy Rancher Prime in any Azure region. - -#### Is this listing available in China? - -While it is not possible to transact/bill Rancher Prime in China, it is possible to deploy into Azure regions in China. - -### Billing - -#### I have an existing Rancher Prime subscription; can I use this on Azure? - -Self-installed BYOS (Bring Your Own Subscription) Rancher Prime deployments are supported on Azure; however, billing will not be via the Azure Marketplace. Once the existing subscription term ends, you can purchase Rancher Prime via the Azure Marketplace and reconfigure your cluster to support monthly billing via Azure. - -#### I have an existing deployment covered by a Rancher subscription; can I use this new listing in the Azure Marketplace for new deployments? - -Yes. the listing works independently from your existing Rancher Prime subscriptions. Only deployments through the marketplace listing will be billed through Azure. Support is always direct from SUSE. - -#### Tell me more about how the billing for Rancher Prime works via Azure? - -When purchasing Rancher Prime via the Azure Marketplace, the billing is as follows: - -- Billing is monthly and handled via Azure. -- Managed nodes are counted hourly when Rancher is active and added to a usage total. -- An average node count is calculated for the month. -- There is a monthly usage charge for each node in the average node count. -- The monthly usage charge depends on the number of nodes in use. -- There is a 5-node minimum; if the average node count is less than 5 nodes, the charge will be for 5 nodes. - -#### What are the pricing tiers? - -Rancher Prime has different pricing tiers when purchasing via the Azure Marketplace. This is based on the number of nodes that Rancher is managing. Details of the tiers are shown below. Please check the listing for further pricing information. - -| Tier | Nodes (from) | Nodes (to) | -| :------: | :----------: | :---------: | -| **1** | 5 | 15 | -| **2** | 16 | 50 | -| **3** | 51 | 100 | -| **4** | 101 | 250 | -| **5** | 251 | 1000 | -| **6** | 1001 | | - -#### Is there a way to try Rancher before purchasing? - -If using the Rancher Prime listing in the Azure Marketplace, billing will commence from the time of deployment. You can try Rancher by deploying it per standard documentation. When ready to benefit from a supported platform and have this billed through Azure, deploy Rancher Prime via the Azure Marketplace and migrate your configuration. - -#### How does SUSE calculate the ‘average number of managed nodes’ to bill for? - -The average node count is calculated by adding the number of managed nodes (counted hourly) and dividing by the number of hours Rancher has been active in the billing cycle. Three examples are shown in the table below. - -:::note - -In our example month, we are using 730 hours; this may differ depending on the number of days in the month and the billing cycle. - -::: - -- **Static Usage:** -Using Rancher to manage 10 nodes for 1 month (730 hours) with no additional nodes added in the month. -- **Bursting Model:** -Using Rancher to manage 10 nodes for 3 weeks (562 hours) in the month and bursting to 30 nodes for 1 week (168 hours). -- **Transient Cluster:** -A temporary deployment of Rancher on 20 nodes for 2 weeks (336 hours). - -| | Hours Active (Hours Rancher is active in the month) | Nodes (Managed Nodes counted at each check-in) | Usage total (Sum of nodes reported at each check-in) | Average Node Count (Usage total / hours active) | Note | -| ----------------- | :--: | :------------------------: | :----: | :--: | :------------------------------: | -| **Static Usage** | 730 | 10 | 7300 | 10 | 10 @ Tier 1 | -| **Bursting Model** | 730 | 10 (562 hrs), 30 (168 hrs) | 10660 | 15 | 15 @ Tier 1 (rounded from 14.6) | -| **Transient Cluster** | 336 | 20 | 6720 | 20 | 20 @ Tier 2 | - -#### Are special commercial terms available? - -Depending on the deployment, securing special commercial terms (e.g., an annual subscription) may be possible. This will be handled via an Azure private offer. Please contact SUSE for more information. - -#### Can my spend on Rancher Prime count towards my MACC Program? - -Yes. Contact your Azure Sales Team for more details. - -#### How do I purchase Rancher for additional nodes? - -Once Rancher Prime has been deployed from the Azure Marketplace and billing is active, there is no need to make a specific purchase for additional nodes. Billing is dynamic and based on the number of nodes Rancher is managing. Just deploy or onboard additional clusters to Rancher as needed. - -#### Is this an annual commitment, will it auto-renew? - -By default, the Rancher Prime listing is billed on a monthly cycle, based on usage. Billing is ongoing for as long as Rancher Prime is deployed. - -It is possible to set up an annual commitment via an Azure Private Offer; these will need to be reviewed and renewed at the end of the term, or the deployment will drop back to the default monthly billing cycle. - -### Technical - -#### Do I need a Kubernetes cluster running in Azure to install Rancher and be billed via the Azure Marketplace? - -Yes. To benefit from monthly billing via Azure, the primary Rancher cluster must be an Azure Kubernetes Service (AKS) cluster running in your Azure account. - -#### Which Kubernetes distributions can the Rancher Prime Azure Marketplace listing be deployed on? - -The Rancher Prime marketplace listing must be deployed on Azure Kubernetes Service (AKS). Downstream/managed clusters can run any supported Kubernetes platform: RKE, RKE2, EKS, GKE, vanilla Kubernetes, OpenShift, Mirantis Kubernetes Engine, etc. See Supported Platforms for more details. - -#### What is the deployment mechanism? - -The Rancher Prime marketplace listing is deployed using Azure’s CNAB (with Helm inside). - -#### What is the easiest way to get started? - -One of the easiest ways to get started is to deploy the Rancher Prime marketplace listing to an existing AKS cluster. Follow the instructions in the usage section of the listing. A Helm chart takes care of installation and billing setup. - -#### What is the minimum version of Rancher required to support Azure Marketplace billing? - -The minimum version supporting marketplace billing is Rancher 2.7.9. - -#### What version of Rancher is installed when using the marketplace listing? - -The Rancher Prime marketplace listing is tied to a specific version of Rancher, typically the latest version available at the time of the listing update. Check the listing for further information. - -#### I need a prior version of Rancher; can I still use the listing? - -No. There is no choice over the Rancher version when deploying using the Azure Marketplace listing. If a prior version of Rancher is required, this must be installed manually using the standard documentation. - -:::note - -Billing through the Azure Marketplace may not be supported with earlier versions. - -::: - -#### How often is the listing updated (including the version of Rancher, etc.)? - -The marketplace listing is tied to a specific version of Rancher, usually it is the latest version available at the time the listing was last updated. Typically, the marketplace listing is updated quarterly, or more frequently to address any new security issues. - -#### I have many Kubernetes clusters across multiple Azure accounts; does the Rancher Prime billing still work and enable tiered pricing? - -Yes. Downstream/managed clusters can be deployed across single or multiple Azure accounts, on-premises, and in other public clouds. Downstream/managed nodes report up to Rancher Prime, enabling tiered pricing with billing routed to the Azure account in which the managing Rancher Prime cluster is running. - -#### I have multiple independent clusters, each running a separate installation of the Rancher Prime Azure Marketplace listing. How is this billed? - -As the Rancher Prime deployments are independent, each deployment is billed separately from the others. It is not possible to benefit from tiered pricing. If managing multiple independent Rancher Prime clusters, consider custom terms from SUSE. - -#### How can I benefit from tiered pricing across all Rancher deployments? - -The primary Rancher Prime cluster must be running on AKS in Microsoft Azure, deployed through the marketplace listing. To benefit from tiered pricing, downstream/managed clusters should be imported into the primary Rancher Prime cluster. - -#### I have purchased multiple SUSE products from the Azure Marketplace (e.g., SUSE Manager, NeuVector Prime, Rancher Prime). Does the Azure Marketplace billing method still work? - -Yes. The billing mechanisms for the deployments are independent and are billed separately via the Azure Marketplace. - -#### I already have an existing AKS cluster in place and want to add Rancher Prime to it and be billed through the Azure Marketplace. Is this possible? - -Yes. Simply deploy the Rancher Prime to the cluster with the Azure Marketplace listing. - -#### I already deployed Rancher to an existing AKS cluster. Can I just install the marketplace version to enable Azure Marketplace billing? - -No. You need to deploy Rancher Prime with the Azure Marketplace listing and migrate the existing Rancher configuration to this new deployment. Be sure that you back up your existing Rancher configuration. - -### Technical (Product) - -#### How do I get support? - -It is very simple to [open a support case](https://scc.suse.com/cloudsupport) with SUSE for Rancher Prime. Create a ‘supportconfig’ via the Rancher UI (click Get Support under the hamburger menu and follow instructions), then upload the ‘supportconfig’ output to the SUSE Customer Center. If the billing mechanism is active, a support case will be opened. See Supportconfig bundle in the Rancher [documentation](../supportconfig.md) for more details. - -:::note - -For deployments where Rancher Prime is managing multiple downstream clusters, be sure to export the ‘supportconfig’ bundle from the primary cluster only. - -::: - -#### What are the resource requirements for installing Rancher on AKS? - -Check the documentation for [best practices](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#hosted-kubernetes). - -#### Is there any difference between Rancher Prime from Azure Marketplace and the versions I can run in my own data center? - -Rancher Prime available in the Azure Marketplace is the same product, with the same functionality that you would install manually in the cloud or on-premises. The only difference between deploying manually and deploying via the marketplace listing is the billing route. - -#### Does the primary cluster (responsible for billing) need to run 24/7? - -To ensure continuity of support, it is recommended that the primary Rancher Prime cluster always remain active. - -#### What if the primary cluster responsible for billing is unable to connect to the Azure billing framework? - -There may be multiple reasons why the primary cluster is unable to connect to the Azure billing framework, but it is the customer’s responsibility to ensure that the primary cluster is active and connected. While the cluster is not connected to the billing framework, it is not possible to raise a support request. - -#### My primary cluster has been offline. What will happen with billing when reconnected? - -If the Racher Prime cluster is offline or disconnected from the Azure billing framework for a period of time, when it reconnects, the stored usage data will be uploaded to Azure and will appear on your next Azure bill. Depending on the month when the primary cluster gets reconnected you may have several months of usage on your next billing cycle. - -#### How do I get fixes and updates for Rancher? - -To update to the latest version of the Rancher Prime PAYG offering supported in the marketplace listing, please see [upgrading Rancher Prime PAYG cluster in Azure](upgrading-rancher-payg-cluster.md). diff --git a/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/cloud-marketplace-payg-integration.md b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/cloud-marketplace-payg-integration.md new file mode 100644 index 00000000000..98537c38053 --- /dev/null +++ b/versioned_docs/version-2.7/integrations-in-rancher/cloud-marketplace/cloud-marketplace-payg-integration.md @@ -0,0 +1,257 @@ +--- +title: Cloud Marketplace Pay-as-you-go (PAYG) Integration +--- + + + + + +Rancher Prime integrates with the [AWS Marketplace](https://aws.amazon.com/marketplace) and [Azure Marketplace](https://azuremarketplace.microsoft.com/) as a pay-as-you-go (PAYG) offering. This brings the value of running and managing Kubernetes environments to cloud customers, who benefit from a new pay-monthly pricing model available through their preferred cloud provider's marketplace. This listing will enable you to manage any CNCF-certified Kubernetes distribution in AWS, Azure, on-prem, or at the edge. + +## Limitations + +Currently, you must be running Rancher v2.7.9. When you deploy a supported PAYG version, you can update to newer versions of Rancher when the listing is updated. + +## How to Use + + + + +1. Complete the [prerequisite steps](../cloud-marketplace/aws-marketplace-payg-integration/prerequisites.md). +2. [Install the Rancher Prime PAYG offering on the AWS Marketplace](../cloud-marketplace/aws-marketplace-payg-integration/installing-rancher-prime.md). + + + + +1. Complete the [prerequisite steps](../cloud-marketplace/azure-marketplace-payg-integration/prerequisites.md). +2. [Install the Rancher Prime PAYG offering on the Azure Marketplace](../cloud-marketplace/azure-marketplace-payg-integration/installing-rancher-prime.md). + + + + +## FAQ + +The following is a list of frequently asked questions. + +### Marketplace Listings + +#### What is the Rancher Prime listing on the cloud marketplace? + +By selecting the Rancher Prime listing from the AWS or Azure Marketplace, you can deploy Rancher to your Kubernetes environment with the advantage of having monthly billing via the cloud. + +#### Where do I find the Rancher Prime listings? + +There are two listings in each respective cloud marketplace. They are: + +**AWS** +- [Rancher Prime](https://aws.amazon.com/marketplace/pp/prodview-f2bvszurj2p2c) +- [Rancher Prime (EMEA Orders Only)](https://aws.amazon.com/marketplace/pp/prodview-ocgjwd5c2aj5i) + +**Azure** +- [Rancher Prime with 24x7 Support](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suse.rancher-prime-llc/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suse.rancher-prime-llcpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%221dafcf16-920e-46ea-80c9-dc85c6bd3a17%22%7D/searchTelemetryId/c2300fb7-ba7b-462a-ba57-a37cb5e2822d) +- [Rancher Prime with 24x7 Support (EMEA Orders Only)](https://portal.azure.com/#view/Microsoft_Azure_Marketplace/GalleryItemDetailsBladeNopdl/id/suseirelandltd1692213356027.rancher-prime-ltd/selectionMode~/false/resourceGroupId//resourceGroupLocation//dontDiscardJourney~/false/selectedMenuId/home/launchingContext~/%7B%22galleryItemId%22%3A%22suseirelandltd1692213356027.rancher-prime-ltdpay-as-you-go%22%2C%22source%22%3A%5B%22GalleryFeaturedMenuItemPart%22%2C%22VirtualizedTileDetails%22%5D%2C%22menuItemId%22%3A%22home%22%2C%22subMenuItemId%22%3A%22Search%20results%22%2C%22telemetryId%22%3A%22c6b1d79a-b577-47b0-90e5-41e6c49688ab%22%7D/searchTelemetryId/1793144d-e0d9-466e-8e36-dfeddc73163b) + +#### Why are there two listings? Which one should I use? + +We have two listings for Rancher Prime, a EU/EMEA version and a non-EU, non-UK version, due to different regulations in different locations. Whichever listing you choose, the images and support offered are identical. You should pick the listing for the location of your cloud provider account. + +#### Are these listings available in all countries? + +No. The PAYG listing isn't available in all countries. + +Your billing country is based on the cloud provider Account ID for the deployment. + +Please refer to [Geographical availability](https://documentation.suse.com/sle-public-cloud/all/html/public-cloud/countrylist.html) for a list of countries that can and cannot access Rancher Prime via the AWS and Azure cloud marketplaces. + +#### My cloud provider account is in the USA, but I want to deploy Rancher in another region, a region that is in a country where I currently cannot transact Rancher Prime. Is this possible? + +Yes. As long as your account is billed to one of the allowed countries, it is possible to deploy Rancher in any region. + +#### Is this listing available in China? + +While it is not possible to transact or bill Rancher Prime in China, it is possible to deploy into regions in China. + +#### Can I still deploy Rancher using the "Rancher Setup" listing from the AWS Marketplace? + +The Rancher Setup listing is no longer available via AWS Marketplace. Customers should deploy an EKS Cluster to host Rancher. Follow the steps in this [guide](../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md) except for the Rancher installation. The Rancher product installation should be carried out as per [installing the Rancher Prime PAYG offering on Amazon's AWS Marketplace](../cloud-marketplace/aws-marketplace-payg-integration/installing-rancher-prime.md). + +### Billing + +#### I have an existing Rancher Prime subscription. Can I use this on the cloud? + +BYOS (Bring Your Own Subscription) Rancher deployments are supported on the cloud; however, you won't be billed for your BYOS via the cloud marketplace. Once the existing subscription term ends, you can purchase Rancher Prime via the cloud marketplace and reconfigure your cluster to support monthly billing via the cloud. + +#### I have an existing Rancher Subscription purchased via the Rancher Premium Support listing on AWS. Is this transferable to the new model? + +No. A new deployment of Rancher Prime is required to benefit from the new monthly billing model. + +#### I have an existing deployment covered by a Rancher subscription; can I use this new marketplace listing for new deployments? + +Yes. The listing works independently of your existing subscriptions. Please remember that support processes may be different for deployments using your existing subscription and deployments billed via the cloud marketplace. + +#### Can you tell me more about how the billing for Rancher Prime works for the cloud marketplace? + +When purchasing Rancher Prime via the cloud marketplace, the billing is as follows: + +- Billing is monthly and handled via the marketplace. +- Managed nodes are counted hourly when Rancher is active and added to a usage total. +- An average node count is calculated for the month. +- There is a monthly usage charge for each node in the average node count. +- The monthly usage charge depends on the number of nodes in use. +- There is a 5-node minimum; if the average node count is less than 5 nodes, the charge will be for 5 nodes. + +#### What are the pricing tiers? + +Pricing tiers are based on the number of nodes which Rancher is managing. Details of the tiers are below. Please check the respective listing for further price information. + +| Tier | Nodes (from) | Nodes (to) | +| :------: | :----------: | :---------: | +| **1** | 5 | 15 | +| **2** | 16 | 50 | +| **3** | 51 | 100 | +| **4** | 101 | 250 | +| **5** | 251 | 1000 | +| **6** | 1001 | | + +#### Is there a way to try Rancher before purchasing? + +If you use the Rancher Prime listing in a cloud provider marketplace, billing commences from the time of deployment. + +Rancher can be deployed manually using the standard documentation and repositories. When you're ready to benefit from a supported platform and have this billed via the marketplace, follow the available [documentation](../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md) to deploy Rancher Prime from the marketplace and migrate. + +#### How does SUSE calculate the average number of managed nodes to bill for? + +The average node count is calculated by adding together the number of managed nodes (counted hourly), and dividing this sum by the number of hours Rancher has been active in the billing cycle. + +Here are three examples of how the average node count is calculated. Check the following table for details. + +:::note + +In our example month, we are using 730 hours; this may differ depending on the number of days in the month and the billing cycle. + +::: + +- **Static usage:** Using Rancher to manage 10 nodes, for 1 month (730 hours) with no additional nodes added in the month. +- **Bursting Model:** Using Rancher to manage 10 nodes for 3 weeks (562 hours) in the month, bursting to 30 nodes for 1 week (168 hours). +- **Transient cluster:** A temporary deployment of Rancher on 20 nodes for 2 weeks (336 hours). + +| | Hours Active (Hours Rancher is active in the month) | Nodes (Managed Nodes counted at each check-in) | Usage total (Sum of nodes reported at each check-in) | Average Node Count (Usage total / hours active) | Note | +| ----------------- | :--: | :------------------------: | :----: | :--: | :------------------------------: | +| **Static Usage** | 730 | 10 | 7300 | 10 | 10 @ Tier 1 | +| **Bursting Model** | 730 | 10 (562 hrs), 30 (168 hrs) | 10660 | 15 | 15 @ Tier 1 (rounded from 14.6) | +| **Transient Cluster** | 336 | 20 | 6720 | 20 | 20 @ Tier 2 | + +#### Are special commercial terms available? + +Depending on the deployment, and the cloud provider, securing special commercial terms (e.g., an annual subscription) may be possible. For example, in AWS this is handled via an AWS Private offer. Please contact SUSE for more information. + +#### Can my spend on Rancher Prime count towards my cloud provider discount program? + +Yes. This should be possible through the: + +- Azure MACC Program +- AWS Enterprise Discount Program + +Please contact your AWS or Azure sales team for more details. + +#### How do I purchase Rancher for additional nodes? + +Once Rancher is deployed from the listing on the cloud marketplace and billing is active, there is no need to make a specific purchase for additional nodes. Billing is dynamic and based on the number of nodes Rancher is managing. Just deploy or onboard additional clusters to Rancher as needed. + +#### Is this an annual commitment, or does it auto-renew? + +By default, the Rancher Prime listing in the cloud is billed on a monthly cycle, based on usage. Billing is ongoing for as long as Rancher is deployed. + +### Technical (Billing) + +#### Do I need a Kubernetes cluster running in the cloud to install Rancher and be billed via the cloud marketplace? + +Yes. To benefit from monthly billing via the cloud marketplace, the primary Rancher cluster must be an on the cloud provider's Kubernetes service. In AWS an EKS cluster is required, while in Azure an AKS cluster is required. + +#### Which Kubernetes distributions can the marketplace listings be deployed on? + +The cloud marketplace listings for Rancher Prime must be deployed on Amazon EKS or Azure AKS. Downstream clusters and managed worker nodes can run on any CNCF-compliant Kubernetes platform, such as AKS, EKS, EKS-A, or Rancher Kubernetes Engine (RKE). + +#### What is the deployment mechanism? + +The cloud marketplace listings for Rancher Prime are deployed using Helm. + +#### What is the easiest way to get started? + +Deploy a listing for Rancher Prime to an existing EKS or AKS cluster. Follow the instructions in the usage section. a Helm chart takes care of the installation and setup for billing. + +#### What version of Rancher is installed when using a marketplace listing? + +Each marketplace listing for Rancher Prime is tied to a specific version of Rancher, typically the latest version available at the time of the listing update. Please check the listing for further information. + +#### I need a prior version of Rancher, can I still use a marketplace listing? + +No. There is no choice over the Rancher version when deploying Rancher through a cloud marketplace listing. If a prior version of Rancher is required, it must be installed manually using the standard documentation. + +:::note + +Billing through the cloud provider marketplace may not be supported with previous versions. + +::: + +#### How often are the listings updated (including the version of Rancher, etc.)? + +Marketplace listings are tied to a specific version of Rancher, usually the latest version available at the time of listing. Typically, listings are updated quarterly, or more frequently if there are security issues. + +#### I have many Kubernetes clusters across multiple cloud accounts, does the Rancher Prime billing still work and enable tiered pricing? + +Yes. Downstream clusters managed by Rancher can be deployed across single or multiple cloud accounts, on-premises, or even in other public clouds. Downstream nodes report up to the primary Rancher deployment. Tiered pricing is enabled and billing is routed to the cloud account in which the primary cluster is running. + +#### I have multiple independent clusters, each running a separate installation of the marketplace listing for Rancher Prime. How is this billed? + +As the Rancher Prime deployments are independent, each deployment is billed separately from the others within the cloud marketplace. It is not possible to benefit from tiered pricing. Please contact SUSE. + +#### I have purchased multiple SUSE products from the cloud marketplace (e.g., SUSE Manager, NeuVector Prime and now Rancher Prime). Does the cloud marketplace billing method still apply? + +Yes. Since the billing mechanism of each deployment is independent, each product will be billed separately via the cloud marketplace. + +#### I already have an existing cluster, with Rancher deployed. Can I just install the marketplace version and have support billed via the cloud provider marketplace? + +In order to benefit from monthly billing via the marketplace, the primary Rancher cluster needs to be deployed from the listing. It is then possible to migrate the existing Rancher configuration to the new deployment. + +Please follow the [documentation](../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md) and be sure to back up the existing Rancher configuration. + +### Technical (Product) + +#### How do I contact support? + +It is very simple to [open a support case](https://scc.suse.com/cloudsupport) with SUSE for Rancher Prime. Create a support config via the Rancher UI and upload the output to the SUSE Customer Center. The support config bundle can be exported from the Rancher console using the **Get Support** button at the bottom of the page. For deployments where Rancher is managing multiple downstream clusters, export the support config bundle only from the primary cluster. + +If the billing mechanism on the primary cluster is active, a support case will be opened. Further details can be found in the [documentation](../cloud-marketplace/supportconfig.md). + +#### What are the resource requirements for installing Rancher on AKS or EKS? + +Please check the documentation for best practices. + +#### Is there any difference between Rancher Prime from the cloud marketplace and the versions I can run in my own data center? + +Rancher Prime available in the cloud marketplace is the same product, with the same functionality that you would run on-premises or with a manual installation. The only difference between deploying manually and deploying via a marketplace listing is the billing route. + +#### Does the primary cluster (responsible for billing) need to run 24/7? + +To ensure continuity with support, the primary Rancher cluster should always remains active. + +#### What if the primary cluster responsible for billing is unable to connect to the cloud provider billing framework? + +There may be multiple reasons why the primary cluster is unable to connect to the billing framework, but it is the customer’s responsibility to ensure that the primary cluster is active and connected. When the cluster is not connected to the billing framework, it is not possible to raise a support request. + +#### My primary cluster has been offline. What will happen with billing when reconnected? + +If the primary cluster is offline or disconnected from the cloud provider billing framework for a period of time, when it reconnects, the stored usage data will be uploaded and appear on your next marketplace bill. + +Depending on when in the month the primary cluster gets reconnected you may have several months of usage on your next billing cycle. + +#### Can the managed worker nodes reside on premises, at the edge or even on another cloud? + +Yes. Managed nodes (managed clusters) can run anywhere. SUSE Rancher will count the total number of nodes managed regardless of where they are deployed. + +#### How do I get fixes and updates for Rancher? + +To update to the latest supported version of the Rancher Prime PAYG offering, please see: + - [Upgrading Rancher Prime PAYG cluster in AWS](../cloud-marketplace/aws-marketplace-payg-integration/upgrading-rancher-payg-cluster.md) + - [Upgrading Rancher Prime PAYG cluster in Azure](../cloud-marketplace/azure-marketplace-payg-integration/upgrading-rancher-payg-cluster.md) diff --git a/versioned_docs/version-2.7/reference-guides/about-the-api/api-tokens.md b/versioned_docs/version-2.7/reference-guides/about-the-api/api-tokens.md index c6f738d1836..307053a82d3 100644 --- a/versioned_docs/version-2.7/reference-guides/about-the-api/api-tokens.md +++ b/versioned_docs/version-2.7/reference-guides/about-the-api/api-tokens.md @@ -10,8 +10,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`. @@ -19,7 +20,7 @@ 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 | | ----------------- | -------------------------------------------------------------------------------------- | @@ -29,12 +30,12 @@ Here is the complete list of tokens that are generated with `ttl=0`: | `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 -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. The default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `0`, which means that tokens never expire. :::note @@ -42,49 +43,55 @@ 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](../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. 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). +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 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. +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 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). **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 removed in 2.8.0.** Rancher v2.8 and later instead use `kubeconfig-default-token-ttl-minutes` 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). May override `kubeconfig-default-token-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). +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). The default value is `0`, which means that tokens never expire. **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).** +### kubeconfig-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 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 rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). +**Deprecated since Rancher v2.6.6.** -#### 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). +### 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. The default value is `0`, which means that tokens never expire. +**Rancher v2.6.5 and earlier: Applies only to tokens created for authenticating API requests.** + +### 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.7/reference-guides/rancher-webhook.md b/versioned_docs/version-2.7/reference-guides/rancher-webhook.md index 000fd95d554..dad0abf95ff 100644 --- a/versioned_docs/version-2.7/reference-guides/rancher-webhook.md +++ b/versioned_docs/version-2.7/reference-guides/rancher-webhook.md @@ -20,7 +20,8 @@ Each Rancher version is designed to be compatible with a single version of the w | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| -| v2.7.11 | v0.3.7 | ✓ | N/A | +| v2.7.12 | v0.3.7 | ✓ | N/A | +| v2.7.11 | v0.3.7 | ✓ | N/A | | v2.7.10 | v0.3.6 | ✓ | ✓ | | v2.7.9 | v0.3.6 | ✗ | ✓ | | v2.7.8 | v0.3.6 | ✗ | ✓ | diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md index 4448a2d739e..8d367774725 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -160,7 +160,8 @@ helm repo update # Install the cert-manager Helm chart helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ - --create-namespace + --create-namespace \ + --set installCRDs=true ``` Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 8e1dc74b215..44ec2535fb0 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -53,7 +53,7 @@ A restore is performed by creating a Restore custom resource. 1. In the left navigation bar, click **Rancher Backups > Restore**. :::note - If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#charts) for more information. + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#access-charts) for more information. ::: diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md index 72083ce9a70..fe8e3c83294 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -6,7 +6,9 @@ title: Troubleshooting Certificates -### How Do I Know if My Certificates are in PEM Format? + + +## How Do I Know if My Certificates are in PEM Format? You can recognize the PEM format by the following traits: @@ -48,7 +50,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END PRIVATE KEY----- ``` -### Converting a Certificate Key From PKCS8 to PKCS1 +## Converting a Certificate Key From PKCS8 to PKCS1 If you are using a PKCS8 certificate key file, Rancher will log the following line: @@ -64,7 +66,7 @@ openssl rsa -in key.pem -out convertedkey.pem You can now use `convertedkey.pem` as certificate key file for Rancher. -### What is the Order of Certificates if I Want to Add My Intermediate(s)? +## What is the Order of Certificates if I Want to Add My Intermediate(s)? The order of adding certificates is as follows: @@ -77,7 +79,7 @@ The order of adding certificates is as follows: -----END CERTIFICATE----- ``` -### How Do I Validate My Certificate Chain? +## How Do I Validate My Certificate Chain? You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md index 9e5a5333e06..4ccc34749e7 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -3,16 +3,12 @@ title: Installing Rancher on a Single Node Using Docker description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. --- -:::caution - -Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don't use this method to install Rancher in production environments. - -::: - + + Rancher can be installed by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md index 1a4519e1bfe..bc679f07a08 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -6,6 +6,8 @@ title: Rolling Back Rancher Installed with Docker + + If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: - Your previous version of Rancher. diff --git a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index b458a86bc73..a30c2cbf747 100644 --- a/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.8/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -8,11 +8,7 @@ title: Upgrading Rancher Installed with Docker The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -:::caution - -**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) before upgrading. - -::: + ## Prerequisites diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md index 54a2897d38c..ae3be31fa37 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -52,8 +52,6 @@ When you need to make changes to your infrastructure, instead of manually updati - You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. -- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware. - ## Tip for Creating CIS Benchmark Compliant Clusters This section describes one way that you can make security and compliance-related config files standard in your clusters. diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md index ba159df89cf..3508daf41a6 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -1,20 +1,48 @@ --- -title: Helm Charts in Rancher +title: Helm Charts and Apps --- -In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using **Apps**. It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. +In this section, you'll learn how to manage Helm chart repositories and apps in Rancher. + +## How Helm Charts Work in Rancher + +Helm chart repositories in Rancher are managed using **Apps**. + +Rancher uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. + +### Catalogs, Apps, and the Rancher UI + +[Rancher v2.4 and earlier](/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), repositories of ready-to-deploy applications were called "catalogs". These repositories were managed through the **Catalogs** section of the UI. + +Rancher v2.5 replaced the former catalog system with a new **Apps & Marketplace** feature. + +Since Rancher v2.6.5, the **Apps & Marketplace** feature is named **Apps** in the UI. ### Versioning Scheme The Rancher feature charts versioning scheme is centered around the major version of the charts and the `+up` annotation for upstream charts, where applicable. -**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps** charts are also upgraded to the correct release line for the chart. +**Major Version:** The major versions of feature charts are tied to particular minor versions of Rancher. When you upgrade to a new Rancher minor version, you should ensure that all of your feature charts are also upgraded to the correct release line for the chart. -**Feature Charts:** +**Charts based on upstream:** When you upgrade, make sure that the upstream chart version is compatible with your Rancher version. The `+up` annotation for the chart indicates which upstream version the Rancher chart is tracking. For example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some additional Rancher patches. + +When upgrading Rancher versions, don't downgrade the version of the chart that you are using. For example, if you are using a version of Monitoring that is later than `16.6.0` in Rancher v2.5, you shouldn't upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. + +#### Prerelease Versions + +Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. + +To display prerelease versions: + +1. Click on your user avatar in the upper right corner. +1. Click **Preferences**. +1. Under **Helm Charts**, select **Include Prerelease Versions**. + +### Feature Charts | **Name** | **Supported Minimum Version** | **Supported Maximum Version** | | ---------------- | ------------ | ------------ | @@ -35,73 +63,81 @@ The Rancher feature charts versioning scheme is centered around the major versio | rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 | | rancher-wins-upgrader | 0.0.100 | 100.0.1+up0.0.1 | -
    -**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also. +## Access Charts -- As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it. +The **Charts** page contains all Rancher, Partner, and Custom charts. You can filter charts by selecting the left-most dropdown menu: -- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. +* Rancher tools such as Logging or Monitoring are listed under the **Rancher** label. +* Partner charts are under the **Partners** label. +* Custom charts are listed under the name of their respective repository. -### Prerelease Versions - -Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. - -To display prerelease versions: - -1. Click on your user avatar in the upper right corner. -1. Click **Preferences**. -1. Under **Helm Charts**, select **Include Prerelease Versions**. - -### Charts - -From the top-left menu select _"Apps"_ and you will be taken to the Charts page. - -The charts page contains all Rancher, Partner, and Custom Charts. - -* Rancher tools such as Logging or Monitoring are included under the Rancher label -* Partner charts reside under the Partners label -* Custom charts will show up under the name of the repository - -All three types are deployed and managed in the same way. +All three types of charts are deployed and managed in the same way. :::note -Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) should continue to be managed only by the Cluster Manager, and apps managed with Apps in the new UI must be managed only by Apps. +Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) continue to be managed only by the Cluster Manager, and apps managed with **Apps** in the new UI must be managed only by **Apps**. ::: -### Repositories +To access the **Charts** page: -From the left sidebar select _"Repositories"_. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. -These items represent Helm repositories, and can be either traditional Helm endpoints which have an index.yaml, or Git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository. +## Manage Repositories -#### Add Custom Git Repositories +The **Repositories** page lists your Helm repositories. These include traditional Helm endpoints which have an index.yaml, and Git repositories that are cloned and point to a specific branch. To use custom charts, add your repository here. After you add a repository, you can access custom charts in the **Charts** page, listed under the name of the repository. -Click **Create** and select the target, **Git repository containing Helm chart...** to add a custom Git repository that contains your Helm charts or cluster template definitions. +To access the **Repositories** page: -You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from the default, `main`. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. -Whenever you add a chart repository to Rancher, it becomes available immediately. +### Add Custom Git Repositories -#### Add Custom Helm Chart Repositories +To add a custom Git repository that contains your Helm charts or cluster template definitions: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **Git repository containing Helm chart...**. +1. You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is named either `main` or `master`. +1. Click **Create** to add the repository. + +After you add a chart repository to Rancher, it becomes available immediately. + +### Add Custom Helm Chart Repositories You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. For more information on Helm chart repositories, see the [official Helm docs](https://helm.sh/docs/topics/chart_repository/). -To add a custom Helm chart repository to Rancher, click **Create** and select **http(s) URL to an index generated by Helm** as the target. Enter a repo name and the index URL address of the chart repository. +To add a custom Helm chart repository to Rancher: -#### Add Private Git/Helm Chart Repositories +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Click **Create**. +1. Select the target, **http(s) URL to an index generated by Helm**. +1. Enter a repo name and the index URL address of the chart repository. +1. Click **Create** to add the repository. + +### Add Private Git/Helm Chart Repositories You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. -#### Add a Private CA to Repositories +### Add a Private CA to Repositories -To add a private CA to Helm chart repositories: +To add a private CA to Helm chart repositories, you must add a base64 encoded copy of the CA certificate in DER format to the `spec.caBundle field` of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Instructions are the same for both Git-based and HTTP-based repositories: -- **HTTP-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
    - ``` +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the row associated with the Git or HTTP-based repository you want to add a private CA to, and click **⋮ > Edit YAML**. +1. Set the `caBundle` value, as in the following example: + + ```yaml [...] spec: caBundle: @@ -109,25 +145,13 @@ To add a private CA to Helm chart repositories: ... nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= [...] - ``` - - -- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
    - ``` - [...] - spec: - caBundle: - MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT - ... - nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= - [...] - ``` + ``` :::note Helm chart repositories with authentication -The Repo.Spec contains a `disableSameOriginCheck` value that allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. +The Repo.Spec contains a `disableSameOriginCheck` value. This value allows you to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories, such as those that have redirects to a different origin URL. -To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. +To use this feature for an existing Helm chart repository, follow previous steps up to edit the YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. ```yaml [...] @@ -142,37 +166,51 @@ spec: Only Helm 3 compatible charts are supported. +## Deploy and Upgrade Charts -### Deployment and Upgrades +To install and deploy a chart: -From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Select a chart, and click **Install**. -To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs. +Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files. However, all chart installations can modify the values.yaml and other basic settings. After you click **Install**, a Helm operation job is deployed, and the console for the job is displayed. -After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation. +To view all recent changes, click **Apps > Recent Operations** in the left navigation menu. From there you can view the calls, conditions, events, and logs. -Most Rancher tools have additional pages located in the toolbar below the _"Apps"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. +After installing a chart, you can view it by clicking **Apps > Installed Apps** in the left navigation menu. You can upgrade or delete the installation, and see further details. Upgrading uses the same forms and values as you saw during inital installation. + +Most Rancher tools have additional pages located in the toolbar below the **Apps** section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. :::caution -If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: +If you are upgrading your chart using **Customize Helm options before upgrade**, and your chart contains immutable fields, using the `--force` option may result in errors. This is because some objects in Kubernetes can't be changed after they're created. To prevent this error: - * use the default upgrade option ( i.e do not use _"--force"_ option ) - * uninstall the existing chart and install the upgraded chart - * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade + * Use the default upgrade option (i.e don't use `--force`). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing a forced upgrade. ::: -#### Legacy Apps +### Legacy Apps -The upgrade button has been removed for legacy apps from the **Apps > Installed Apps** page. +The upgrade button isn't available for legacy apps on the **Apps > Installed Apps** page. -If you have a legacy app installed and want to upgrade it: +If you want to upgrade an installed legacy app, the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on. This flag is automatically turned on if you had a legacy app already running before you upgraded Rancher. -- The legacy [feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading) -- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps** -- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there +1. Enable the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md), if it isn't enabled already. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose apps you want to access. Click **Explore** at the end of the cluster's row. +1. Click **Legacy > Project > Apps**. -### Limitations +If you don't see **Apps** listed under **Legacy > Project**, click the project/namespace search bar in the top navigation and select the relevant project from the dropdown menu. -Dashboard apps or Rancher feature charts **cannot** be installed using the Rancher CLI. +To upgrade legacy multi-cluster apps: + +1. Click **☰**. +1. Under **Legacy Apps**, click **Multi-cluster Apps**. + +## Limitations + +Dashboard apps or Rancher feature charts can't be installed using the Rancher CLI. \ No newline at end of file diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md index 267d9b1c1ba..0ce4e450f6b 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md @@ -6,9 +6,9 @@ title: Migrating Amazon In-tree to Out-of-tree -Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes 1.27 and later, the in-tree cloud providers have been removed. +Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes v1.27 and later, the in-tree cloud providers have been removed. The Rancher UI allows you to upgrade to Kubernetes v1.27 when you migrate from an in-tree to out-of-tree provider. -You can migrate from an in-tree to an out-of-tree AWS cloud provider on Kubernetes 1.26 and earlier. All existing clusters must migrate prior to upgrading to v1.27 in order to stay functional. +However, if you're performing a manual migration, existing clusters must upgrade to Kubernetes v1.27 after you migrate in order to remain functional. To migrate from the in-tree cloud provider to the out-of-tree AWS cloud provider, you must stop the existing cluster's kube controller manager and install the AWS cloud controller manager. There are many ways to do this. Refer to the official AWS documentation on the [external cloud controller manager](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for details. @@ -52,7 +52,7 @@ spec: 2. Cordon control plane nodes so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider: ```shell -kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" ``` 3. To install the AWS cloud controller manager with leader migration enabled, follow Steps 1-3 for [deploying the cloud controller manager chart](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider). From Kubernetes 1.22 onwards, the kube-controller-manager will utilize a default configuration which will satisfy the controller-to-manager migration. Update container args of the `aws-cloud-controller-manager` under `spec.rkeConfig.additionalManifest` to enable leader migration: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md index 47c6d950b2d..00857004174 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md @@ -352,9 +352,9 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' args: - --configure-cloud-routes=false - --use-service-account-credentials=true @@ -639,7 +639,7 @@ kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager - get ``` -9. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: +9. Rancher-provisioned RKE2 nodes are tainted `node-role.kubernetes.io/control-plane`. Update tolerations and the nodeSelector: ```yaml tolerations: @@ -648,13 +648,13 @@ tolerations: value: 'true' - effect: NoSchedule value: 'true' - key: node-role.kubernetes.io/controlplane + key: node-role.kubernetes.io/control-plane ``` ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` :::note @@ -663,7 +663,7 @@ There's currently a [known issue](https://github.com/rancher/dashboard/issues/92 ```yaml nodeSelector: - node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: 'true' ``` ::: diff --git a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md index 6c0b1c1d0d2..69398199394 100644 --- a/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md +++ b/versioned_docs/version-2.8/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md @@ -18,7 +18,7 @@ In clusters that store data on GlusterFS volumes, you may experience an issue wh - The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use) ``` -docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version +docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run -v /usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3 -v /lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.26.14-rancher1 --version ``` :::caution @@ -32,6 +32,8 @@ services: kubelet: extra_binds: - "/usr/bin/systemd-run:/usr/bin/systemd-run" + - "/usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3" + - "/lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so" ``` After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline: diff --git a/versioned_docs/version-2.8/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/versioned_docs/version-2.8/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index 6a325ef79a8..9669219ec33 100644 --- a/versioned_docs/version-2.8/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/versioned_docs/version-2.8/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -20,6 +20,9 @@ In order to deploy and run the adapter successfully, you need to ensure its vers | Rancher Version | Adapter Version | |-----------------|:----------------:| | v2.8.0 | v103.0.0+up3.0.0 | +| v2.8.1 | v103.0.0+up3.0.0 | +| v2.8.2 | v103.0.0+up3.0.0 | +| v2.8.3 | v103.0.1+up3.0.1 | ### 1. Gain Access to the Local Cluster diff --git a/versioned_docs/version-2.8/reference-guides/rancher-webhook.md b/versioned_docs/version-2.8/reference-guides/rancher-webhook.md index f998b2f2ed7..7aa5dfc4f1c 100644 --- a/versioned_docs/version-2.8/reference-guides/rancher-webhook.md +++ b/versioned_docs/version-2.8/reference-guides/rancher-webhook.md @@ -20,6 +20,7 @@ Each Rancher version is designed to be compatible with a single version of the w | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| +| v2.8.3 | v0.4.3 | ✗ | ✓ | | v2.8.2 | v0.4.2 | ✓ | ✓ | | v2.8.1 | v0.4.2 | ✓ | ✓ | | v2.8.0 | v0.4.2 | ✗ | ✓ | diff --git a/versioned_docs/version-2.8/troubleshooting/other-troubleshooting-tips/rancher-ha.md b/versioned_docs/version-2.8/troubleshooting/other-troubleshooting-tips/rancher-ha.md index 8917f80da4d..d0c3957cf62 100644 --- a/versioned_docs/version-2.8/troubleshooting/other-troubleshooting-tips/rancher-ha.md +++ b/versioned_docs/version-2.8/troubleshooting/other-troubleshooting-tips/rancher-ha.md @@ -74,10 +74,15 @@ kubectl -n ingress-nginx logs -l app=ingress-nginx ### Leader election -The leader is determined by a leader election process. After the leader has been determined, the leader (`holderIdentity`) is saved in the `cattle-controllers` ConfigMap (in this example, `rancher-7dbd7875f7-qbj5k`). +The leader is determined by a leader election process. After the leader has been determined, the leader (`holderIdentity`) is saved in the `cattle-controllers` Lease in the `kube-system` namespace (in this example, `rancher-dbc7ff869-gvg6k`). ``` -kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}' -{"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0} +kubectl -n kube-system get lease cattle-controllers ``` +Example output: + +``` +NAME HOLDER AGE +cattle-controllers rancher-dbc7ff869-gvg6k 6h10m +``` diff --git a/versioned_sidebars/version-2.5-sidebars.json b/versioned_sidebars/version-2.5-sidebars.json index 4209726ff77..ef33985eeb8 100644 --- a/versioned_sidebars/version-2.5-sidebars.json +++ b/versioned_sidebars/version-2.5-sidebars.json @@ -444,7 +444,7 @@ }, { "type": "category", - "label": "Helm Charts in Rancher", + "label": "Helm Charts and Apps", "link": { "type": "doc", "id": "how-to-guides/new-user-guides/helm-charts-in-rancher" diff --git a/versioned_sidebars/version-2.6-sidebars.json b/versioned_sidebars/version-2.6-sidebars.json index 1d8f14f1384..851a06e7444 100644 --- a/versioned_sidebars/version-2.6-sidebars.json +++ b/versioned_sidebars/version-2.6-sidebars.json @@ -578,7 +578,7 @@ }, { "type": "category", - "label": "Helm Charts in Rancher", + "label": "Helm Charts and Apps", "link": { "type": "doc", "id": "how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher" diff --git a/versioned_sidebars/version-2.7-sidebars.json b/versioned_sidebars/version-2.7-sidebars.json index f2463302321..7d677be558d 100644 --- a/versioned_sidebars/version-2.7-sidebars.json +++ b/versioned_sidebars/version-2.7-sidebars.json @@ -589,7 +589,7 @@ }, { "type": "category", - "label": "Helm Charts in Rancher", + "label": "Helm Charts and Apps", "link": { "type": "doc", "id": "how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher" @@ -1116,6 +1116,17 @@ "integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues" ] }, + "integrations-in-rancher/cloud-marketplace/supportconfig" + ] + }, + { + "type": "category", + "label": "Cloud Marketplace Pay-as-you-go (PAYG) Integration", + "link": { + "type": "doc", + "id": "integrations-in-rancher/cloud-marketplace/cloud-marketplace-payg-integration" + }, + "items": [ { "type": "category", "label": "AWS Marketplace Pay-as-you-go (PAYG)", @@ -1124,12 +1135,11 @@ "id": "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/aws-marketplace-payg-integration" }, "items": [ - "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/prerequisites", - "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/installing-rancher-prime", - "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/upgrading-rancher-payg-cluster", - "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/troubleshooting", - "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/common-issues" - + "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/prerequisites", + "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/installing-rancher-prime", + "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/upgrading-rancher-payg-cluster", + "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/troubleshooting", + "integrations-in-rancher/cloud-marketplace/aws-marketplace-payg-integration/common-issues" ] }, { @@ -1140,15 +1150,13 @@ "id": "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/azure-marketplace-payg-integration" }, "items": [ - "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/prerequisites", - "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/installing-rancher-prime", - "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/upgrading-rancher-payg-cluster", - "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/troubleshooting", - "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/common-issues" - + "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/prerequisites", + "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/installing-rancher-prime", + "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/upgrading-rancher-payg-cluster", + "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/troubleshooting", + "integrations-in-rancher/cloud-marketplace/azure-marketplace-payg-integration/common-issues" ] - }, - "integrations-in-rancher/cloud-marketplace/supportconfig" + } ] }, { diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index 9224ae972cf..adba2f701cd 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -589,7 +589,7 @@ }, { "type": "category", - "label": "Helm Charts in Rancher", + "label": "Helm Charts and Apps", "link": { "type": "doc", "id": "how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher"