diff --git a/docs/en/admin-settings/authentication/ad/ad.md b/docs/en/admin-settings/authentication/ad/ad.md index f68ccca9766..2e89ec0afd8 100644 --- a/docs/en/admin-settings/authentication/ad/ad.md +++ b/docs/en/admin-settings/authentication/ad/ad.md @@ -21,15 +21,17 @@ Usually a (non-admin) **Domain User** account should be used for this purpose, a Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain. -> **Using TLS?** -> -> - If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. -> -> - Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15. -> -> - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0". -> -> - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container. +:::note Using TLS? + +- If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. + +- Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15. + + - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0". + + - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container. + +::: ## Configuration Steps ### Open Active Directory Configuration diff --git a/docs/en/admin-settings/authentication/azure-ad/azure-ad.md b/docs/en/admin-settings/authentication/azure-ad/azure-ad.md index 10b846aa428..b87723397e0 100644 --- a/docs/en/admin-settings/authentication/azure-ad/azure-ad.md +++ b/docs/en/admin-settings/authentication/azure-ad/azure-ad.md @@ -5,19 +5,29 @@ weight: 1115 If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher. ->**Note:** Azure AD integration only supports Service Provider initiated logins. +:::note Prerequisite: ->**Prerequisite:** Have an instance of Azure AD configured. +Have an instance of Azure AD configured. ->**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). +::: + +:::note Notes + +- Azure AD integration only supports Service Provider initiated logins. + +- Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). + +::: ## Azure Active Directory Configuration Outline Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started. - +:::tip ->**Tip:** Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later. +Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later. + +::: @@ -50,11 +60,19 @@ Before enabling Azure AD within Rancher, you must register Rancher with Azure. 1. In the **Redirect URI** section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `/verify-auth-azure`. - >**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD). + :::tip + + You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD). + + ::: 1. Click **Register**. ->**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. +:::note + +It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. + +::: ### 2. Create a new client secret @@ -110,7 +128,11 @@ Next, set API permissions for Rancher within Azure. 1. From **API permissions**, click **Grant admin consent**. Then click **Yes**. - >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings. + :::note + + You must be signed in as an Azure administrator to successfully save your permission settings. + + ::: ### 4. Add a Reply URL @@ -124,13 +146,21 @@ To use Azure AD with Rancher you must whitelist Rancher with Azure. You can comp 1. From the **Reply URLs** blade, enter the URL of your Rancher Server, appended with the verification path: `/verify-auth-azure`. - >**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD). + :::tip + + You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD). + + ::: 1. Click **Save**. **Result:** Your reply URL is saved. ->**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. +:::note + +It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. + +::: ### 5. Copy Azure Application Data @@ -170,7 +200,11 @@ As your final step in Azure, copy the data that you'll use to configure Rancher - **OAuth 2.0 token endpoint (v1)** (Token Endpoint) - **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint) ->**Note:** Copy the v1 version of the endpoints +:::note + +Copy the v1 version of the endpoints + +::: ### 6. Configure Azure AD in Rancher @@ -184,9 +218,13 @@ Enter the values that you copied to your [text file](#tip). 1. Click **AzureAD**. 1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data). - >**Important:** When entering your Graph Endpoint, remove the tenant ID from the URL, like below. - > - >https://graph.windows.net/abb5adde-bee8-4821-8b03-e63efdc7701c + :::note Important + + When entering your Graph Endpoint, remove the tenant ID from the URL, like below. + + https://graph.windows.net/abb5adde-bee8-4821-8b03-e63efdc7701c + + ::: The following table maps the values you copied in the Azure portal to the fields in Rancher. diff --git a/docs/en/admin-settings/authentication/freeipa/freeipa.md b/docs/en/admin-settings/authentication/freeipa/freeipa.md index 40de727fac5..052313f9c57 100644 --- a/docs/en/admin-settings/authentication/freeipa/freeipa.md +++ b/docs/en/admin-settings/authentication/freeipa/freeipa.md @@ -5,11 +5,13 @@ weight: 1114 If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials. ->**Prerequisites:** -> ->- You must have a [FreeIPA Server](https://www.freeipa.org/) configured. ->- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key. ->- Read [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). +:::note Prerequisites: + +- You must have a [FreeIPA Server](https://www.freeipa.org/) configured. +- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key. +- Read [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + +::: 1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). 1. In the top left corner, click **☰ > Users & Authentication**. @@ -19,28 +21,36 @@ If your organization uses FreeIPA for user authentication, you can configure Ran You may need to log in to your domain controller to find the information requested in the form. - >**Using TLS?** - >If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate. -
-
- >**User Search Base vs. Group Search Base** - > - >Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters. - > - >* If your users and groups are in the same search base, complete only the User Search Base. - >* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required. + :::note Using TLS? + + If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate. + + ::: + + :::note User Search Base vs. Group Search Base + + Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters. + + * If your users and groups are in the same search base, complete only the User Search Base. + * If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required. + + ::: 1. If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step. - >**Search Attribute** The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field. - > - >The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields. - > - > * `uid`: User ID - > * `sn`: Last Name - > * `givenName`: First Name - > - > With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field. + :::note Search Attribute + + The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field. + + The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields. + + * `uid`: User ID + * `sn`: Last Name + * `givenName`: First Name + + With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field. + + ::: 1. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication. 1. Click **Enable**. diff --git a/docs/en/admin-settings/authentication/github/github.md b/docs/en/admin-settings/authentication/github/github.md index a5b5ba93281..61b0ab03d45 100644 --- a/docs/en/admin-settings/authentication/github/github.md +++ b/docs/en/admin-settings/authentication/github/github.md @@ -5,7 +5,11 @@ weight: 1116 In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials. ->**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). +:::note Prerequisites: + +Read [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + +::: 1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). 1. In the top left corner, click **☰ > Users & Authentication**. @@ -13,17 +17,21 @@ In environments using GitHub, you can configure Rancher to allow sign on using G 1. Click **GitHub**. 1. Follow the directions displayed to set up a GitHub Application. Rancher redirects you to GitHub to complete registration. - >**What's an Authorization Callback URL?** - > - >The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen). + :::note What's an Authorization Callback URL? + + The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen). - >When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application. + When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application. + + ::: 1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher. - >**Where do I find the Client ID and Client Secret?** - > - >From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. + :::note Where do I find the Client ID and Client Secret? + + From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. + + ::: 1. Click **Authenticate with GitHub**. diff --git a/docs/en/admin-settings/authentication/keycloak-oidc/keycloak-oidc.md b/docs/en/admin-settings/authentication/keycloak-oidc/keycloak-oidc.md index a56af63a28e..aa31c4bdd40 100644 --- a/docs/en/admin-settings/authentication/keycloak-oidc/keycloak-oidc.md +++ b/docs/en/admin-settings/authentication/keycloak-oidc/keycloak-oidc.md @@ -64,7 +64,11 @@ If you have an existing configuration using the SAML protocol and want to switch Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration. - >**Note:** You may need to disable your popup blocker to see the IdP login page. + :::note + + You may need to disable your popup blocker to see the IdP login page. + + ::: **Result:** Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign into Rancher using their Keycloak logins. @@ -114,7 +118,11 @@ Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first Configure Rancher to use Keycloak (OIDC) by following the steps in [this section](#configuring-keycloak-in-rancher). -> **Note:** After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated. +:::note + +After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated. + +::: ## Annex: Troubleshooting diff --git a/docs/en/admin-settings/authentication/keycloak-saml/keycloak-saml.md b/docs/en/admin-settings/authentication/keycloak-saml/keycloak-saml.md index ca2952111fb..75a3c5cf97c 100644 --- a/docs/en/admin-settings/authentication/keycloak-saml/keycloak-saml.md +++ b/docs/en/admin-settings/authentication/keycloak-saml/keycloak-saml.md @@ -116,7 +116,11 @@ The following is an example process for Firefox, but will vary slightly for othe Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration. - >**Note:** You may have to disable your popup blocker to see the IdP login page. + :::note + + You may have to disable your popup blocker to see the IdP login page. + + ::: **Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins. @@ -135,9 +139,13 @@ The following is an example process for Firefox, but will vary slightly for othe | Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. | | IDP-metadata | The `metadata.xml` file that you exported from your IdP server. | ->**Tip:** You can generate a key/certificate pair using an openssl command. For example: -> -> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert +:::tip + +You can generate a key/certificate pair using an openssl command. For example: + +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert + +::: ## Annex: Troubleshooting diff --git a/docs/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/rancher-adfs-setup.md b/docs/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/rancher-adfs-setup.md index d7424d986fd..47ecea1e0a6 100644 --- a/docs/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/rancher-adfs-setup.md +++ b/docs/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/rancher-adfs-setup.md @@ -5,11 +5,13 @@ weight: 1205 After you complete [Configuring Microsoft AD FS for Rancher]({{}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher. ->**Important Notes For Configuring Your ADFS Server:** -> ->- The SAML 2.0 WebSSO Protocol Service URL is: `https:///v1-saml/adfs/saml/acs` ->- The Relying Party Trust identifier URL is: `https:///v1-saml/adfs/saml/metadata` ->- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https:///federationmetadata/2007-06/federationmetadata.xml` +:::note Important Notes For Configuring Your ADFS Server: + +- The SAML 2.0 WebSSO Protocol Service URL is: `https:///v1-saml/adfs/saml/acs` +- The Relying Party Trust identifier URL is: `https:///v1-saml/adfs/saml/metadata` +- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https:///federationmetadata/2007-06/federationmetadata.xml` + +::: 1. In the top left corner, click **☰ > Users & Authentication**. 1. In the left navigation menu, click **Auth Provider**. @@ -19,8 +21,12 @@ After you complete [Configuring Microsoft AD FS for Rancher]({{}}/ranch Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration. - >**Note:** You may have to disable your popup blocker to see the AD FS login page. + :::note + + You may have to disable your popup blocker to see the AD FS login page. + ::: + **Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins. # Configuration diff --git a/docs/en/admin-settings/branding/branding.md b/docs/en/admin-settings/branding/branding.md index 4e5cff17e20..667db8ecde6 100644 --- a/docs/en/admin-settings/branding/branding.md +++ b/docs/en/admin-settings/branding/branding.md @@ -13,7 +13,11 @@ Rancher v2.6 introduced the ability to customize Rancher’s branding and naviga # Changing Brand Settings -> **Prerequisite:** You will need to have at least cluster member permissions. +:::note Prerequisite: + +You will need to have at least cluster member permissions. + +::: To configure the brand settings, @@ -71,7 +75,11 @@ Links can be created at the top level and multiple links can be grouped together ### Adding a Custom Navigation Link -> **Prerequisite:** You will need to have at least cluster member or project member permissions. +:::note Prerequisite: + +You will need to have at least cluster member or project member permissions. + +::: 1. Click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you would like to add custom navigation links and click **Explore**. diff --git a/docs/en/admin-settings/cluster-templates/cluster-templates.md b/docs/en/admin-settings/cluster-templates/cluster-templates.md index ae050be8a8f..acccba1c949 100644 --- a/docs/en/admin-settings/cluster-templates/cluster-templates.md +++ b/docs/en/admin-settings/cluster-templates/cluster-templates.md @@ -36,10 +36,12 @@ The example repository for an RKE2 cluster template is [here](https://github.com In this section, you'll learn how to add the cluster template to the `local` cluster's chart repo list. The result is that Rancher will include the cluster template as an option when users install new Kubernetes clusters. -> **Prerequisites:** -> -> - You will need permission to install Helm charts on the `local` Kubernetes cluster that Rancher is installed on. -> - In order for the chart to appear in the form for creating new clusters, the chart must have the annotation `catalog.cattle.io/type: cluster-template`. +:::note Prerequisites: + +- You will need permission to install Helm charts on the `local` Kubernetes cluster that Rancher is installed on. +- In order for the chart to appear in the form for creating new clusters, the chart must have the annotation `catalog.cattle.io/type: cluster-template`. + +::: 1. Go to a cluster template example repository. Rancher's examples are in [this GitHub repository.](https://github.com/rancher/cluster-template-examples) As of Rancher v2.6.0, we provide an RKE2 cluster template and add to more in the future. 1. Fork the repository. @@ -56,15 +58,21 @@ In this section, you'll learn how to add the cluster template to the `local` clu **Result:** The cluster template available from the **Apps & Marketplace** in Rancher's `local` cluster. It can now be used to deploy clusters. -> * **Restricted Admin access:** If you are a restricted admin and don’t have access to the `local` cluster, you may still add new RKE2 templates and manage cluster repositories. To navigate to the chart repository, go to the left navigation bar and click **☰ > Cluster Management > Advanced > Repositories**. You will bypass steps 1 - 6 above, then proceed to follow steps 7 - 12 to create the cluster template. +:::note Restricted Admin access: + +If you are a restricted admin and don’t have access to the `local` cluster, you may still add new RKE2 templates and manage cluster repositories. To navigate to the chart repository, go to the left navigation bar and click **☰ > Cluster Management > Advanced > Repositories**. You will bypass steps 1 - 6 above, then proceed to follow steps 7 - 12 to create the cluster template. + +::: # Creating a Cluster from a Cluster Template -> **Prerequisites:** -> -> - You will need permission to provision new Kubernetes clusters. -> - You will need cloud credentials for provisioning infrastructure using the template. -> - In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type: cluster-template` annotation. +:::note Prerequisites: + +- You will need permission to provision new Kubernetes clusters. +- You will need cloud credentials for provisioning infrastructure using the template. +- In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type: cluster-template` annotation. + +::: 1. Click **☰ > Cluster Management**. 1. On the **Clusters** page, click **Create.** @@ -79,14 +87,16 @@ You can update any clusters using a template from the **Apps & Marketplace > Ins # Deploying Clusters from a Template with Fleet -> **Prerequisites:** -> -> - You will need permission to provision new Kubernetes clusters. -> - You will need cloud credentials for provisioning infrastructure using the template. -> - In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type:cluster-template` annotation. -> - In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the `fleet-local` namespace of the `local` cluster. -> - All values must be set in the `values.yaml` of the template. -> - Fleet repositories must follow the guidelines on [this page.](http://fleet.rancher.io/gitrepo-structure/) For RKE2 cluster templates, that means a `fleet.yaml` file must be added to the repository. +:::note Prerequisites: + +- You will need permission to provision new Kubernetes clusters. +- You will need cloud credentials for provisioning infrastructure using the template. +- In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type:cluster-template` annotation. +- In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the `fleet-local` namespace of the `local` cluster. +- All values must be set in the `values.yaml` of the template. +- Fleet repositories must follow the guidelines on [this page.](http://fleet.rancher.io/gitrepo-structure/) For RKE2 cluster templates, that means a `fleet.yaml` file must be added to the repository. + +::: 1. Click **☰ > Cluster Management**. 1. On the **Clusters** page, click **Create.** diff --git a/docs/en/admin-settings/config-private-registry/config-private-registry.md b/docs/en/admin-settings/config-private-registry/config-private-registry.md index cd36201d114..bdac208ef0d 100644 --- a/docs/en/admin-settings/config-private-registry/config-private-registry.md +++ b/docs/en/admin-settings/config-private-registry/config-private-registry.md @@ -9,7 +9,7 @@ There are two main ways to set up private registries in Rancher: by setting up t This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed. -For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the [air gapped installation guide]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap). +For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the [air-gapped installation guide]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap). If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to [pass in the registry credentials through the advanced cluster options](#setting-a-private-registry-with-credentials-when-deploying-a-cluster) every time you create a new cluster. diff --git a/docs/en/admin-settings/drivers/cluster-drivers/cluster-drivers.md b/docs/en/admin-settings/drivers/cluster-drivers/cluster-drivers.md index 7bc22f30cfc..a5ef92605a5 100644 --- a/docs/en/admin-settings/drivers/cluster-drivers/cluster-drivers.md +++ b/docs/en/admin-settings/drivers/cluster-drivers/cluster-drivers.md @@ -9,10 +9,14 @@ If there are specific cluster drivers that you do not want to show your users, y ### Managing Cluster Drivers ->**Prerequisites:** To create, edit, or delete cluster drivers, you need _one_ of the following permissions: -> ->- [Administrator Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) ->- [Custom Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned. +:::note Prerequisites: + +To create, edit, or delete cluster drivers, you need _one_ of the following permissions: + +- [Administrator Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) +- [Custom Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned. + +::: ## Activating/Deactivating Cluster Drivers diff --git a/docs/en/admin-settings/drivers/node-drivers/node-drivers.md b/docs/en/admin-settings/drivers/node-drivers/node-drivers.md index 6dbd01a200b..05a19659436 100644 --- a/docs/en/admin-settings/drivers/node-drivers/node-drivers.md +++ b/docs/en/admin-settings/drivers/node-drivers/node-drivers.md @@ -9,10 +9,14 @@ If there are specific node drivers that you don't want to show to your users, yo #### Managing Node Drivers ->**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions: -> ->- [Administrator Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) ->- [Custom Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned. +:::note Prerequisites: + +To create, edit, or delete drivers, you need _one_ of the following permissions: + +- [Administrator Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) +- [Custom Global Permissions]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned. + +::: ## Activating/Deactivating Node Drivers diff --git a/docs/en/admin-settings/k8s-metadata/k8s-metadata.md b/docs/en/admin-settings/k8s-metadata/k8s-metadata.md index 29302bf7013..7ef4e1cfa7f 100644 --- a/docs/en/admin-settings/k8s-metadata/k8s-metadata.md +++ b/docs/en/admin-settings/k8s-metadata/k8s-metadata.md @@ -5,13 +5,21 @@ weight: 30 The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6. -> **Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions. +:::note + +The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions. + +::: Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates**. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine]({{}}/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions. This table below describes the CRDs that are affected by the periodic data sync. -> **Note:** Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised. +:::note + +Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised. + +::: | Resource | Description | Rancher API URL | |----------|-------------|-----------------| @@ -39,7 +47,11 @@ You can configure Rancher to only refresh metadata when desired by setting `refr ### Configuring the Metadata Synchronization -> Only administrators can change these settings. +:::caution + +Only administrators can change these settings. + +::: The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`. diff --git a/docs/en/admin-settings/rbac/cluster-project-roles/cluster-project-roles.md b/docs/en/admin-settings/rbac/cluster-project-roles/cluster-project-roles.md index c2767b8a66f..f54b0a817b3 100644 --- a/docs/en/admin-settings/rbac/cluster-project-roles/cluster-project-roles.md +++ b/docs/en/admin-settings/rbac/cluster-project-roles/cluster-project-roles.md @@ -16,7 +16,11 @@ The projects and clusters accessible to non-administrative users is determined b When you create a cluster or project, Rancher automatically assigns you as the `Owner` for it. Users assigned the `Owner` role can assign other users roles in the cluster or project. -> **Note:** Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership. +:::note + +Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership. + +::: ### Cluster Roles @@ -70,8 +74,11 @@ For details on how each cluster role can access Kubernetes resources, you can lo 1. Click the **Cluster** tab. 1. Click the name of an individual role. The table shows all of the operations and resources that are permitted by the role. -> **Note:** ->When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. +:::note + +When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + +::: ### Giving a Custom Cluster Role to a Cluster Member @@ -123,17 +130,21 @@ _Project roles_ are roles that can be used to grant users access to a project. T These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members. - >**Note:** - > - >By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces. + :::note + + By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces. + + ::: - **Read Only:** These users can view everything in the project but cannot create, update, or delete anything. - >**Caveat:** - > - >Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `owner` or `member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + :::note Caveat + + Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `owner` or `member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + + ::: #### Custom Project Roles @@ -165,11 +176,13 @@ The following table lists each built-in custom project role available in Rancher | View Volumes | ✓ | ✓ | ✓ | | View Workloads | ✓ | ✓ | ✓ | -> **Notes:** -> ->- Each project role listed above, including `Owner`, `Member`, and `Read Only`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page. ->- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. ->- The `Manage Project Members` role allows the project owner to manage any members of the project **and** grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually. +:::note Notes: + +- Each project role listed above, including `Owner`, `Member`, and `Read Only`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page. +- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. +- The `Manage Project Members` role allows the project owner to manage any members of the project **and** grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually. + +::: ### Defining Custom Roles As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both. @@ -188,10 +201,12 @@ There are two methods for changing default cluster/project roles: For example, instead of assigning a role that inherits other roles (such as `cluster owner`), you can choose a mix of individual roles (such as `manage nodes` and `manage storage`). ->**Note:** -> ->- Although you can [lock]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles/) a default role, the system still assigns the role to users who create a cluster/project. ->- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles. +:::note + +- Although you can [lock]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles/) a default role, the system still assigns the role to users who create a cluster/project. +- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles. + +::: ### Configuring Default Roles for Cluster and Project Creators