From 4c8edca04b655b1f7d8c31521c82394c9f83a95d Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 5 Jul 2022 09:58:46 -0400 Subject: [PATCH 01/18] Updating notes to docusaurus format --- .../en/admin-settings/authentication/ad/ad.md | 48 ++++++++++++------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/en/admin-settings/authentication/ad/ad.md b/docs/en/admin-settings/authentication/ad/ad.md index 6ed722deb90..f68ccca9766 100644 --- a/docs/en/admin-settings/authentication/ad/ad.md +++ b/docs/en/admin-settings/authentication/ad/ad.md @@ -7,9 +7,11 @@ If your organization uses Microsoft Active Directory as central user repository, Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the [OpenLDAP authentication]({{}}/rancher/v2.6/en/admin-settings/authentication/openldap) integration. -> **Note:** -> -> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). +:::note + +Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + +::: ## Prerequisites @@ -43,9 +45,11 @@ Note however, that in some locked-down Active Directory configurations this defa In the section titled `1. Configure an Active Directory server`, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter. -> **Note:** -> -> If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch). +:::note + +If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch). + +::: **Table 1: AD Server parameters** @@ -69,9 +73,11 @@ In the section titled `2. Customize Schema` you must provide Rancher with a corr Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain. -> **Note:** -> -> If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values. +:::note + +If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values. + +::: #### User Schema @@ -115,9 +121,11 @@ The table below details the parameters for the group schema configuration. Once you have completed the configuration, proceed by testing the connection to the AD server **using your AD admin account**. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin. -> **Note:** -> -> The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step. +:::note + +The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step. + +::: 1. Enter the **username** and **password** for the AD account that should be mapped to the local principal account. 2. Click **Authenticate with Active Directory** to finalise the setup. @@ -127,9 +135,11 @@ Once you have completed the configuration, proceed by testing the connection to - Active Directory authentication has been enabled. - You have been signed into Rancher as administrator using the provided AD credentials. -> **Note:** -> -> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. +:::note + +You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. + +::: ## Annex: Identify Search Base and Schema using ldapsearch @@ -170,9 +180,11 @@ The output of the above `ldapsearch` query also allows to determine the correct - `Login Attribute`: **sAMAccountName** [3] - `User Member Attribute`: **memberOf** [4] -> **Note:** -> -> If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. +:::note + +If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. + +::: We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name. From 7a2966aea6be64e2232e2d922bd56f4d93c5b2db Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Wed, 6 Jul 2022 13:06:03 -0400 Subject: [PATCH 02/18] Refactoring notes --- .../en/admin-settings/authentication/ad/ad.md | 20 +++--- .../authentication/azure-ad/azure-ad.md | 66 +++++++++++++++---- .../authentication/freeipa/freeipa.md | 58 +++++++++------- .../authentication/github/github.md | 24 ++++--- .../keycloak-oidc/keycloak-oidc.md | 12 +++- .../keycloak-saml/keycloak-saml.md | 16 +++-- .../rancher-adfs-setup/rancher-adfs-setup.md | 18 +++-- docs/en/admin-settings/branding/branding.md | 12 +++- .../cluster-templates/cluster-templates.md | 46 ++++++++----- .../config-private-registry.md | 2 +- .../cluster-drivers/cluster-drivers.md | 12 ++-- .../drivers/node-drivers/node-drivers.md | 12 ++-- .../k8s-metadata/k8s-metadata.md | 18 ++++- .../cluster-project-roles.md | 51 +++++++++----- 14 files changed, 250 insertions(+), 117 deletions(-) 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 From e3d2aff995c5b9e7d25e7b43f48ca59eba4dd8a3 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Wed, 6 Jul 2022 13:39:07 -0400 Subject: [PATCH 03/18] Refactoring notes --- docs/en/admin-settings/admin-settings.md | 6 +++- .../default-custom-roles.md | 20 ++++++++---- .../global-permissions/global-permissions.md | 32 ++++++++++++------- .../applying-templates/applying-templates.md | 6 +++- .../creating-and-revising.md | 9 ++++-- .../rke-templates/enforcement/enforcement.md | 6 +++- 6 files changed, 57 insertions(+), 22 deletions(-) diff --git a/docs/en/admin-settings/admin-settings.md b/docs/en/admin-settings/admin-settings.md index 4b73dc848be..4d1f522a55c 100644 --- a/docs/en/admin-settings/admin-settings.md +++ b/docs/en/admin-settings/admin-settings.md @@ -9,7 +9,11 @@ After installation, the [system administrator]({{}}/rancher/v2.6/en/adm After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself. ->**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care. +:::danger + +After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care. + +::: ## Authentication diff --git a/docs/en/admin-settings/rbac/default-custom-roles/default-custom-roles.md b/docs/en/admin-settings/rbac/default-custom-roles/default-custom-roles.md index 3b6bcb7f837..8326fc3a3fd 100644 --- a/docs/en/admin-settings/rbac/default-custom-roles/default-custom-roles.md +++ b/docs/en/admin-settings/rbac/default-custom-roles/default-custom-roles.md @@ -7,7 +7,11 @@ Within Rancher, _roles_ determine what actions a user can make within a cluster Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access. -> It is possible for a custom role to enable privilege escalation. For details, see [this section.](#privilege-escalation) +:::tip + +It is possible for a custom role to enable privilege escalation. For details, see [this section.](#privilege-escalation) + +::: This section covers the following topics: @@ -99,11 +103,15 @@ When a user in the group logs in, they get the built-in Standard User global rol If a user is removed from the external authentication provider group, they would lose their permissions from the custom role that was assigned to the group. They would continue to have their individual Standard User role. -> **Prerequisites:** You can only assign a global role to a group if: -> -> * You have set up an [external authentication provider]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication) -> * The external authentication provider supports [user groups]({{}}/rancher/v2.6/en/admin-settings/authentication/user-groups/) -> * You have already set up at least one user group with the authentication provider +:::note Prerequisites: + +You can only assign a global role to a group if: + +* You have set up an [external authentication provider]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication) +* The external authentication provider supports [user groups]({{}}/rancher/v2.6/en/admin-settings/authentication/user-groups/) +* You have already set up at least one user group with the authentication provider + +::: To assign a custom role to a group, follow these steps: diff --git a/docs/en/admin-settings/rbac/global-permissions/global-permissions.md b/docs/en/admin-settings/rbac/global-permissions/global-permissions.md index 2a58aa35aef..865e1d3af55 100644 --- a/docs/en/admin-settings/rbac/global-permissions/global-permissions.md +++ b/docs/en/admin-settings/rbac/global-permissions/global-permissions.md @@ -177,16 +177,22 @@ For details on which Kubernetes resources correspond to each global permission, 1. In the left navigation bar, click **Roles**. 1. If you click the name of an individual role, a table shows all of the operations and resources that are permitted by the role. -> **Notes:** -> -> - Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`. -> - 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 Notes: + +- Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`. +- 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. + +::: ### Configuring Default Global Permissions If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions. -> **Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user. +:::note + +Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user. + +::: To change the default global permissions that are assigned to external users upon their first log in, follow these steps: @@ -207,7 +213,7 @@ To configure permission for a user, 1. In the **Global Permissions** and **Built-in** sections, check the boxes for each permission you want the user to have. If you have created roles from the **Roles** page, they will appear in the **Custom** section and you can choose from them as well. 1. Click **Save**. -> **Result:** The user's global permissions have been updated. +**Result:** The user's global permissions have been updated. ### Configuring Global Permissions for Groups @@ -221,11 +227,15 @@ For new users, the new permissions take effect when the users log in to Rancher If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default**. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,](#refreshing-group-memberships) whichever comes first. -> **Prerequisites:** You can only assign a global role to a group if: -> -> * You have set up an [external authentication provider]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication) -> * The external authentication provider supports [user groups]({{}}/rancher/v2.6/en/admin-settings/authentication/user-groups/) -> * You have already set up at least one user group with the authentication provider +:::note Prerequisites: + +You can only assign a global role to a group if: + +* You have set up an [external authentication provider]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication) +* The external authentication provider supports [user groups]({{}}/rancher/v2.6/en/admin-settings/authentication/user-groups/) +* You have already set up at least one user group with the authentication provider + +::: To assign a custom global role to a group, follow these steps: diff --git a/docs/en/admin-settings/rke-templates/applying-templates/applying-templates.md b/docs/en/admin-settings/rke-templates/applying-templates/applying-templates.md index 7d1b8ec8392..5bac40a1b3b 100644 --- a/docs/en/admin-settings/rke-templates/applying-templates/applying-templates.md +++ b/docs/en/admin-settings/rke-templates/applying-templates/applying-templates.md @@ -40,7 +40,11 @@ If a cluster was created from an RKE template, you can edit the cluster to updat An existing cluster's settings can be [saved as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) In that situation, you can also edit the cluster to update the cluster to a new revision of the template. -> **Note:** You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template. +:::note + +You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template. + +::: ### Converting an Existing Cluster to Use an RKE Template diff --git a/docs/en/admin-settings/rke-templates/creating-and-revising/creating-and-revising.md b/docs/en/admin-settings/rke-templates/creating-and-revising/creating-and-revising.md index d1284ad6498..99afcaa0a58 100644 --- a/docs/en/admin-settings/rke-templates/creating-and-revising/creating-and-revising.md +++ b/docs/en/admin-settings/rke-templates/creating-and-revising/creating-and-revising.md @@ -140,8 +140,13 @@ To permanently delete a revision, ### Upgrading a Cluster to Use a New Template Revision -> This section assumes that you already have a cluster that [has an RKE template applied.]({{}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates) -> This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available. +:::note + +This section assumes that you already have a cluster that [has an RKE template applied.]({{}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates) + +This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available. + +::: To upgrade a cluster to use a new template revision, diff --git a/docs/en/admin-settings/rke-templates/enforcement/enforcement.md b/docs/en/admin-settings/rke-templates/enforcement/enforcement.md index cd51f196341..d012fb51fab 100644 --- a/docs/en/admin-settings/rke-templates/enforcement/enforcement.md +++ b/docs/en/admin-settings/rke-templates/enforcement/enforcement.md @@ -25,8 +25,12 @@ To require new clusters to use an RKE template, administrators can turn on RKE t 1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**. 1. Set the value to **True** and click **Save**. - >**Important:** When the admin sets the `cluster-template-enforcement` to True, they also need to share the `clusterTemplates` with users so that users can select one of these templates to create the cluster. + :::note Important: + + When the admin sets the `cluster-template-enforcement` to True, they also need to share the `clusterTemplates` with users so that users can select one of these templates to create the cluster. + ::: + **Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator. # Disabling RKE Template Enforcement From 19e382418516c06523fe11a52aa444c51d9e377f Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 7 Jul 2022 11:39:02 -0400 Subject: [PATCH 04/18] refactoring-nodes --- docs/en/api/api-tokens/api-tokens.md | 12 ++++- .../back-up-rancher/back-up-rancher.md | 27 +++++++++-- docs/en/backups/backups.md | 12 ++++- .../backup-config/backup-config.md | 6 ++- .../restore-config/restore-config.md | 5 +- .../storage-config/storage-config.md | 9 +++- .../docker-restores/docker-restores.md | 6 ++- .../rancher-managed/containers/containers.md | 6 ++- docs/en/cis-scans/cis-scans.md | 24 ++++++---- .../cis-scans/configuration/configuration.md | 12 ++++- .../certificate-rotation.md | 11 ++++- .../cleaning-cluster-nodes.md | 46 ++++++++++++++----- .../cloning-clusters/cloning-clusters.md | 18 ++++++-- .../cluster-members/cluster-members.md | 31 +++++++++---- .../cluster-access/kubectl/kubectl.md | 12 ++++- docs/en/cluster-admin/cluster-admin.md | 6 ++- .../cluster-autoscaler/amazon/amazon.md | 6 ++- .../aks-config-reference.md | 12 ++++- .../eks-config-reference.md | 14 ++++-- .../gke-config-reference.md | 24 ++++++++-- .../private-clusters/private-clusters.md | 21 ++++++--- .../k3s-config-reference.md | 6 ++- .../rke-config-references.md | 24 ++++++++-- .../rke2-config-reference.md | 18 ++++++-- docs/en/cluster-admin/nodes/nodes.md | 26 +++++++++-- .../pod-security-policies.md | 15 ++++-- .../pod-security-policy.md | 22 +++++++-- .../projects-and-namespaces.md | 34 ++++++++++---- 28 files changed, 362 insertions(+), 103 deletions(-) diff --git a/docs/en/api/api-tokens/api-tokens.md b/docs/en/api/api-tokens/api-tokens.md index c682ae8460d..374ad624186 100644 --- a/docs/en/api/api-tokens/api-tokens.md +++ b/docs/en/api/api-tokens/api-tokens.md @@ -38,11 +38,19 @@ Go to the global settings and: 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. The kubeconfig file will now provide a command to login to Rancher. -_**Note:**_ Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI]({{}}/rancher/v2.6/en/cli) to retrieve a short lived token for the cluster. When you use this kubeconfig in a client, such as `kubectl`, the Rancher CLI needs to be installed as well. +:::note + +Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI]({{}}/rancher/v2.6/en/cli) to retrieve a short lived token for the cluster. When you use this kubeconfig in a client, such as `kubectl`, the Rancher CLI needs to be installed as well. + +::: 2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours). -_**Note:**_ This value cannot exceed max-ttl of API tokens.(`https:// When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different. +::: caution + +When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different. + +::: ### Prerequisites @@ -31,7 +35,11 @@ Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, 1. Configure the default storage location. For help, refer to the [storage configuration section.](../configuration/storage-config) 1. Click **Install**. ->**NOTE:** There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround. +:::note + +There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround. + +::: ### 2. Perform a Backup @@ -65,11 +73,20 @@ To perform a backup, a custom resource of type Backup must be created. retentionCount: 10 ``` - > **Note:** When creating the Backup resource using YAML editor, the `resourceSetName` must be set to `rancher-resource-set` + :::note + + When creating the Backup resource using YAML editor, the `resourceSetName` must be set to `rancher-resource-set` - For help configuring the Backup, refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup) + ::: - > **Important:** The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup. + For help configuring the Backup, refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup) + + :::caution + + The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup. + + ::: + 1. Click **Create**. **Result:** The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore. diff --git a/docs/en/backups/backups.md b/docs/en/backups/backups.md index d9e4dd96065..33e8d978dae 100644 --- a/docs/en/backups/backups.md +++ b/docs/en/backups/backups.md @@ -43,13 +43,21 @@ When a Restore custom resource is created, the operator accesses the backup .tar The Backup and Restore custom resources can be created in the Rancher UI, or by using `kubectl apply`. ->**Note:** Refer [here]({{}}/rancher/v2.6/en/backups/migrating-rancher/#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3. +:::note + +Refer [here]({{}}/rancher/v2.6/en/backups/migrating-rancher/#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3. + +::: # Installing the rancher-backup Operator The `rancher-backup` operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the `rancher-backup` Helm chart is installed on the Kubernetes cluster running the Rancher server. It is a cluster-admin only feature and available only for the **local** cluster. (*If you do not see `rancher-backup` in the Rancher UI, you may have selected the wrong cluster.*) ->**NOTE:** There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround. +:::note + +There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround. + +::: ### Installing rancher-backup with the Rancher UI diff --git a/docs/en/backups/configuration/backup-config/backup-config.md b/docs/en/backups/configuration/backup-config/backup-config.md index 90d8e5680a0..d4e410a21b6 100644 --- a/docs/en/backups/configuration/backup-config/backup-config.md +++ b/docs/en/backups/configuration/backup-config/backup-config.md @@ -36,9 +36,13 @@ The rancher-backup gathers resources by making calls to the kube-apiserver. Obje To avoid storing them in plaintext, you can use the same encryptionConfig file that was used for at-rest encryption, to encrypt certain resources in your backup. -> **Important:** You must save the encryptionConfig file, because it won’t be saved by the rancher-backup operator. +:::note Important: + +You must save the encryptionConfig file, because it won’t be saved by the rancher-backup operator. The same encryptionFile needs to be used when performing a restore. +::: + The operator consumes this encryptionConfig as a Kubernetes Secret, and the Secret must be in the operator’s namespace. Rancher installs the `rancher-backup` operator in the `cattle-resources-system` namespace, so create this encryptionConfig secret in that namespace. For the `EncryptionConfiguration`, you can use the [sample file provided in the Kubernetes documentation.](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#understanding-the-encryption-at-rest-configuration) diff --git a/docs/en/backups/configuration/restore-config/restore-config.md b/docs/en/backups/configuration/restore-config/restore-config.md index a3e2ff3a7f7..5c980d904b9 100644 --- a/docs/en/backups/configuration/restore-config/restore-config.md +++ b/docs/en/backups/configuration/restore-config/restore-config.md @@ -57,9 +57,12 @@ The `Encryption Config Secret` dropdown will filter out and list only those Secr | ---------------- | ---------------- | | `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. | -> **Important** +:::note Important: + This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail. +::: + # Prune During Restore * **Prune**: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the **Prune** flag is enabled. Prune is enabled by default and it is recommended to keep it enabled. diff --git a/docs/en/backups/configuration/storage-config/storage-config.md b/docs/en/backups/configuration/storage-config/storage-config.md index 569532510fe..1b2e8d889fc 100644 --- a/docs/en/backups/configuration/storage-config/storage-config.md +++ b/docs/en/backups/configuration/storage-config/storage-config.md @@ -40,17 +40,22 @@ Installing the `rancher-backup` chart by selecting the StorageClass option will For information about creating storage classes refer to [this section.]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/provisioning-new-storage/) -> **Important** +::: note Important: + It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it. +::: + ### Existing Persistent Volume Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to [this section.]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/attaching-existing-storage/#2-add-a-persistent-volume-that-refers-to-the-persistent-storage) -> **Important** +:::note Important: + It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. +::: # Example values.yaml for the rancher-backup Helm Chart diff --git a/docs/en/backups/docker-installs/docker-restores/docker-restores.md b/docs/en/backups/docker-installs/docker-restores/docker-restores.md index 8fa8b8cb302..b89607887be 100644 --- a/docs/en/backups/docker-installs/docker-restores/docker-restores.md +++ b/docs/en/backups/docker-installs/docker-restores/docker-restores.md @@ -50,7 +50,11 @@ Using a [backup]({{}}/rancher/v2.6/en/backups/docker-installs/docker-ba 1. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes. - >**Warning!** This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost. + :::danger + + This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost. + + ::: ``` docker run --volumes-from -v $PWD:/backup \ diff --git a/docs/en/best-practices/rancher-managed/containers/containers.md b/docs/en/best-practices/rancher-managed/containers/containers.md index 15a21d61e3d..323acdb8fdd 100644 --- a/docs/en/best-practices/rancher-managed/containers/containers.md +++ b/docs/en/best-practices/rancher-managed/containers/containers.md @@ -39,7 +39,11 @@ The Kubernetes docs have more information on how resource limits can be set at t ### Define Resource Requirements You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining `resources.requests` in the resource requests field in a pod's container spec. For details, refer to the [Kubernetes docs](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container). -> **Note:** If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace. +:::note + +If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace. + +::: It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load. diff --git a/docs/en/cis-scans/cis-scans.md b/docs/en/cis-scans/cis-scans.md index f9604b61b59..55f6f9710ba 100644 --- a/docs/en/cis-scans/cis-scans.md +++ b/docs/en/cis-scans/cis-scans.md @@ -233,11 +233,13 @@ One can download the report from the Scans list or from the scan detail page. Alerts can be configured to be sent out for a scan that runs on a schedule. -> **Prerequisite:** -> -> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration) -> -> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts) +:::note Prerequisite: + +Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration) + +While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts) + +::: While installing or upgrading the `rancher-cis-benchmark` Helm chart, set the following flag to `true` in the `values.yaml`: @@ -259,11 +261,13 @@ The CIS Benchmark application supports two types of alerts: - Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name. - Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state. -> **Prerequisite:** -> -> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration) -> -> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts) +:::note Prerequisite + +Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration) + +While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts) + +::: To configure alerts for a scan that runs on a schedule, diff --git a/docs/en/cis-scans/configuration/configuration.md b/docs/en/cis-scans/configuration/configuration.md index 26df1932e25..ee6c737d8ea 100644 --- a/docs/en/cis-scans/configuration/configuration.md +++ b/docs/en/cis-scans/configuration/configuration.md @@ -32,7 +32,11 @@ spec: A profile contains the configuration for the CIS scan, which includes the benchmark version to use and any specific tests to skip in that benchmark. -> By default, a few ClusterScanProfiles are installed as part of the `rancher-cis-benchmark` chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles. +:::caution + +By default, a few ClusterScanProfiles are installed as part of the `rancher-cis-benchmark` chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles. + +::: Users can clone the ClusterScanProfiles to create custom profiles. @@ -67,7 +71,11 @@ A `ClusterScanBenchmark` defines the CIS `BenchmarkVersion` name and test config By default, a few `BenchmarkVersion` names and test configurations are packaged as part of the CIS scan application. When this feature is enabled, these default BenchmarkVersions will be automatically installed and available for users to create a ClusterScanProfile. -> If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks. +:::caution + +If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks. + +::: A ClusterScanBenchmark consists of the fields: diff --git a/docs/en/cluster-admin/certificate-rotation/certificate-rotation.md b/docs/en/cluster-admin/certificate-rotation/certificate-rotation.md index c38a4dd0d5b..c0a67823fe9 100644 --- a/docs/en/cluster-admin/certificate-rotation/certificate-rotation.md +++ b/docs/en/cluster-admin/certificate-rotation/certificate-rotation.md @@ -3,7 +3,11 @@ title: Certificate Rotation weight: 2040 --- -> **Warning:** Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window. +:::caution + +Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window. + +::: By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted. @@ -38,8 +42,11 @@ Certificates can be rotated for the following services: {{% /tab %}} {{% /tabs %}} -> **Note:** For users who didn't rotate their webhook certificates, and they have expired after one year, please see this [page]({{}}/rancher/v2.6/en/troubleshooting/expired-webhook-certificates/) for help. +:::note +For users who didn't rotate their webhook certificates, and they have expired after one year, please see this [page]({{}}/rancher/v2.6/en/troubleshooting/expired-webhook-certificates/) for help. + +::: ### Certificate Rotation diff --git a/docs/en/cluster-admin/cleaning-cluster-nodes/cleaning-cluster-nodes.md b/docs/en/cluster-admin/cleaning-cluster-nodes/cleaning-cluster-nodes.md index d1cf15c6581..e09577fb57c 100644 --- a/docs/en/cluster-admin/cleaning-cluster-nodes/cleaning-cluster-nodes.md +++ b/docs/en/cluster-admin/cleaning-cluster-nodes/cleaning-cluster-nodes.md @@ -47,7 +47,11 @@ $ sudo shutdown -r now When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components. ->**Warning:** The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost. +:::danger + +The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost. + +::: ### Removing Rancher Components from Registered Clusters @@ -57,7 +61,11 @@ After the registered cluster is detached from Rancher, the cluster's workloads w {{% tabs %}} {{% tab "By UI / API" %}} ->**Warning:** This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost. +:::danger + +This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost. + +::: After you initiate the removal of a registered cluster using the Rancher UI (or API), the following events occur. @@ -73,9 +81,11 @@ After you initiate the removal of a registered cluster using the Rancher UI (or {{% tab "By Script" %}} Rather than cleaning registered cluster nodes using the Rancher UI, you can run a script instead. ->**Prerequisite:** -> ->Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +:::note Prerequisite: + +Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +::: 1. Open a web browser, navigate to [GitHub](https://github.com/rancher/rancher/blob/master/cleanup/user-cluster.sh), and download `user-cluster.sh`. @@ -91,13 +101,15 @@ Rather than cleaning registered cluster nodes using the Rancher UI, you can run 1. From the same directory, run the script and provide the `rancher/rancher-agent` image version which should be equal to the version of Rancher used to manage the cluster. (``): - >**Tip:** - > - >Add the `-dry-run` flag to preview the script's outcome without making changes. + :::tip + + Add the `-dry-run` flag to preview the script's outcome without making changes. ``` ./user-cluster.sh rancher/rancher-agent: ``` + ::: + **Result:** The script runs. All components listed for registered clusters in [What Gets Removed?](#what-gets-removed) are deleted. {{% /tab %}} @@ -149,7 +161,11 @@ for mount in $(mount | grep tmpfs | grep '/var/lib/kubelet' | awk '{ print $3 }' The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using `rm -rf /directory_name`. ->**Note:** Depending on the role you assigned to the node, some of the directories will or won't be present on the node. +:::note + +Depending on the role you assigned to the node, some of the directories will or won't be present on the node. + +::: Directories | --------| @@ -211,7 +227,11 @@ If you want to know more on (virtual) network interfaces or iptables rules, plea ### Network Interfaces ->**Note:** Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node. +:::note + +Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node. + +::: Interfaces | --------| @@ -239,7 +259,11 @@ ip link delete interface_name ### Iptables ->**Note:** Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node. +:::note + +Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node. + +::: Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state. diff --git a/docs/en/cluster-admin/cloning-clusters/cloning-clusters.md b/docs/en/cluster-admin/cloning-clusters/cloning-clusters.md index 39da7fa7310..26659e11030 100644 --- a/docs/en/cluster-admin/cloning-clusters/cloning-clusters.md +++ b/docs/en/cluster-admin/cloning-clusters/cloning-clusters.md @@ -14,7 +14,11 @@ Duplication of registered clusters is not supported. | [Custom Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes) | ✓ | | [Registered Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/) | | -> **Warning:** During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, _not_ wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure. +:::caution + +During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, **_not_** wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure. + +::: ## Prerequisites @@ -49,11 +53,19 @@ Begin by using Rancher CLI to export the configuration for the cluster that you Use your favorite text editor to modify the cluster configuration in `cluster-template.yml` for your cloned cluster. -> **Note:** Cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) +:::note + +Cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) + +::: 1. Open `cluster-template.yml` (or whatever you named your config) in your favorite text editor. - >**Warning:** Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process. + :::caution + + Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process. + + ::: 1. As depicted in the example below, at the `` placeholder, replace your original cluster's name with a unique name (``). If your cloned cluster has a duplicate name, the cluster will not provision successfully. diff --git a/docs/en/cluster-admin/cluster-access/cluster-members/cluster-members.md b/docs/en/cluster-admin/cluster-access/cluster-members/cluster-members.md index 31d8aaeb564..ecc0d45fd02 100644 --- a/docs/en/cluster-admin/cluster-access/cluster-members/cluster-members.md +++ b/docs/en/cluster-admin/cluster-access/cluster-members/cluster-members.md @@ -5,7 +5,11 @@ weight: 2020 If you want to provide a user with access and permissions to _all_ projects, nodes, and resources within a cluster, assign the user a cluster membership. ->**Tip:** Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members]({{}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/project-members/) instead. +:::tip + +Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members]({{}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/project-members/) instead. + +::: There are two contexts where you can add cluster members: @@ -30,21 +34,32 @@ Cluster administrators can edit the membership for a cluster, controlling which - Rancher returns users from your [external authentication]({{}}/rancher/v2.6/en/admin-settings/authentication/) source as you type. - >**Using AD but can't find your users?** - >There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{}}/rancher/v2.6/en/admin-settings/authentication/ad/). + :::note Using AD but can't find your users? + + There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{}}/rancher/v2.6/en/admin-settings/authentication/ad/). + + ::: - A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of. - >**Note:** If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + :::note + + If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + + ::: 1. Assign the user or group **Cluster** roles. [What are Cluster Roles?]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/) - >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. - > - > - To add roles to the list, [Add a Custom Role]({{}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles/). - > - To remove roles from the list, [Lock/Unlock Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles). + :::tip + + For Custom Roles, you can modify the list of individual roles available for assignment. + + - To add roles to the list, [Add a Custom Role]({{}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles/). + - To remove roles from the list, [Lock/Unlock Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles). + + ::: **Result:** The chosen users are added to the cluster. diff --git a/docs/en/cluster-admin/cluster-access/kubectl/kubectl.md b/docs/en/cluster-admin/cluster-access/kubectl/kubectl.md index 2f030570879..1b770f1c248 100644 --- a/docs/en/cluster-admin/cluster-access/kubectl/kubectl.md +++ b/docs/en/cluster-admin/cluster-access/kubectl/kubectl.md @@ -30,7 +30,11 @@ This section describes how to download your cluster's kubeconfig file, launch ku This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI. -> **Prerequisites:** These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +:::note Prerequisites: + +These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + +::: 1. Log into Rancher. Click **☰ > Cluster Management**. 1. Go to the cluster that you want to access with kubectl and click **Explore**. @@ -54,7 +58,11 @@ This method is only available for RKE clusters that have the [authorized cluster We recommend that as a best practice, you should set up this method to access your RKE cluster, so that just in case you can’t connect to Rancher, you can still access the cluster. -> **Prerequisites:** The following steps assume that you have created a Kubernetes cluster and followed the steps to [connect to your cluster with kubectl from your workstation.](#accessing-clusters-with-kubectl-from-your-workstation) +:::note Prerequisites: + +The following steps assume that you have created a Kubernetes cluster and followed the steps to [connect to your cluster with kubectl from your workstation.](#accessing-clusters-with-kubectl-from-your-workstation) + +::: To find the name of the context(s) in your downloaded kubeconfig file, run: diff --git a/docs/en/cluster-admin/cluster-admin.md b/docs/en/cluster-admin/cluster-admin.md index 7919b01b210..2a4ab74ec8e 100644 --- a/docs/en/cluster-admin/cluster-admin.md +++ b/docs/en/cluster-admin/cluster-admin.md @@ -11,7 +11,11 @@ This page covers the following topics: - [Managing clusters in Rancher](#managing-clusters-in-rancher) - [Configuring tools](#configuring-tools) -> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.6/en/overview/concepts) page. +:::note + +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.6/en/overview/concepts) page. + +::: ## Managing Clusters in Rancher diff --git a/docs/en/cluster-admin/cluster-autoscaler/amazon/amazon.md b/docs/en/cluster-admin/cluster-autoscaler/amazon/amazon.md index ffa5b83b76b..00ad33025f5 100644 --- a/docs/en/cluster-admin/cluster-autoscaler/amazon/amazon.md +++ b/docs/en/cluster-admin/cluster-autoscaler/amazon/amazon.md @@ -516,7 +516,11 @@ Once the manifest file is prepared, deploy it in the Kubernetes cluster (Rancher kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml ``` -**Note:** Cluster-autoscaler deployment can also be set up using [manual configuration](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration) +:::note + +Cluster-autoscaler deployment can also be set up using [manual configuration](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration) + +::: # Testing diff --git a/docs/en/cluster-admin/editing-clusters/aks-config-reference/aks-config-reference.md b/docs/en/cluster-admin/editing-clusters/aks-config-reference/aks-config-reference.md index 1b522f15ad3..d6d6fa90bbb 100644 --- a/docs/en/cluster-admin/editing-clusters/aks-config-reference/aks-config-reference.md +++ b/docs/en/cluster-admin/editing-clusters/aks-config-reference/aks-config-reference.md @@ -19,7 +19,11 @@ Rancher can configure member roles for AKS clusters in the same way as any other # Cloud Credentials -> The configuration information in this section assumes you have already set up a service principal for Rancher. For step-by-step instructions for how to set up the service principal, see [this section.]({{}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/aks/#prerequisites-in-microsoft-azure) +:::note + +The configuration information in this section assumes you have already set up a service principal for Rancher. For step-by-step instructions for how to set up the service principal, see [this section.]({{}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/aks/#prerequisites-in-microsoft-azure) + +::: ### Subscription ID @@ -165,7 +169,11 @@ The first way to ensure that Rancher is running on the same [NAT](https://docs.m The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled. -> **Note:** Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. +:::note + +Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. + +::: For more information about connecting to an AKS private cluster, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) diff --git a/docs/en/cluster-admin/editing-clusters/eks-config-reference/eks-config-reference.md b/docs/en/cluster-admin/editing-clusters/eks-config-reference/eks-config-reference.md index 4eec75f21f7..b49e9ae8694 100644 --- a/docs/en/cluster-admin/editing-clusters/eks-config-reference/eks-config-reference.md +++ b/docs/en/cluster-admin/editing-clusters/eks-config-reference/eks-config-reference.md @@ -107,15 +107,21 @@ If you specify a custom AMI, whether in a launch template or in Rancher, then th If you specify a launch template that does not contain a custom AMI, then Amazon will use the [EKS-optimized AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html) for the Kubernetes version and selected region. You can also select a [GPU enabled instance](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html#gpu-ami) for workloads that would benefit from it. ->**Note** ->The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template. +:::note + +The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template. + +::: #### Spot instances Spot instances are now [supported by EKS](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-capacity-types-spot). If a launch template is specified, Amazon recommends that the template not provide an instance type. Instead, Amazon recommends providing multiple instance types. If the "Request Spot Instances" checkbox is enabled for a node group, then you will have the opportunity to provide multiple instance types. ->**Note** ->Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration. +:::note + +Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration. + +::: #### Node Group Settings diff --git a/docs/en/cluster-admin/editing-clusters/gke-config-reference/gke-config-reference.md b/docs/en/cluster-admin/editing-clusters/gke-config-reference/gke-config-reference.md index b87543a3157..59c09aad32d 100644 --- a/docs/en/cluster-admin/editing-clusters/gke-config-reference/gke-config-reference.md +++ b/docs/en/cluster-admin/editing-clusters/gke-config-reference/gke-config-reference.md @@ -103,13 +103,21 @@ The address range assigned to the services in the cluster. Must be a valid CIDR _Mutable: no_ -> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/). +:::caution + +Private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/). + +::: Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP. ### Enable Private Endpoint -> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/). +:::caution + +Private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/). + +::: _Mutable: no_ @@ -192,9 +200,17 @@ _Mutable: yes_ The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) -> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging]({{}}/rancher/v2.0-v2.4/en/cluster-admin/tools/logging) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature]({{}}/rancher/v2.6/en/logging) is compatible with the Container-Optimized OS image. +:::note -> Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. +The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging]({{}}/rancher/v2.0-v2.4/en/cluster-admin/tools/logging) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature]({{}}/rancher/v2.6/en/logging) is compatible with the Container-Optimized OS image. + +::: + +:::note + +If selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. + +::: ### Machine Type diff --git a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md index 95d9bd39bcc..69ea8f16489 100644 --- a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md +++ b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md @@ -11,15 +11,21 @@ Because the nodes in a private cluster only have internal IP addresses, they wil #### Cloud NAT ->**Note** ->Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). +:::note + +Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +::: If restricting outgoing internet access is not a concern for your organization, use Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service to allow nodes in the private network to access the internet, enabling them to download the required images from Dockerhub and contact the Rancher management server. This is the simplest solution. #### Private registry ->**Note** ->This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient. +:::note + +This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient. + +::: If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image [registry](https://rancher.com/docs/rancher/v2.6/en/installation/other-installation-methods/air-gap/) on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need [direct access](#direct-access) to it. @@ -29,8 +35,11 @@ If the cluster has a public endpoint exposed, Rancher will be able to reach the #### Cloud NAT ->**Note** ->Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). +:::note + +Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +::: As above, if restricting outgoing internet access to the nodes is not a concern, then Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the [kubeconfig](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for the new cluster and run the provided kubectl command on the cluster. Gaining access to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes. diff --git a/docs/en/cluster-admin/editing-clusters/k3s-config-reference/k3s-config-reference.md b/docs/en/cluster-admin/editing-clusters/k3s-config-reference/k3s-config-reference.md index 00d784cfa0c..a95b89c4935 100644 --- a/docs/en/cluster-admin/editing-clusters/k3s-config-reference/k3s-config-reference.md +++ b/docs/en/cluster-admin/editing-clusters/k3s-config-reference/k3s-config-reference.md @@ -15,7 +15,11 @@ You can configure the Kubernetes options one of two ways: # Configuration Options in the Rancher UI -> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the K3s cluster configuration file in YAML. For the complete reference of configurable options for K3s clusters in YAML, see the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/install-options/) +:::tip + +Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the K3s cluster configuration file in YAML. For the complete reference of configurable options for K3s clusters in YAML, see the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/install-options/) + +::: ### Basics #### Kubernetes Version diff --git a/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md b/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md index 27e73a4c408..4888de83817 100644 --- a/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md +++ b/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md @@ -77,7 +77,11 @@ To edit an RKE config file directly from the Rancher UI, # Configuration Options in the Rancher UI -> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE cluster configuration file in YAML. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.]({{}}/rke/latest/en/config-options/) +:::tip + +Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE cluster configuration file in YAML. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.]({{}}/rke/latest/en/config-options/) + +::: ### Kubernetes Version @@ -89,7 +93,11 @@ For more detail, see [Upgrading Kubernetes]({{}}/rancher/v2.6/en/cluste The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. For more details on the different networking providers, please view our [Networking FAQ]({{}}/rancher/v2.6/en/faq/networking/cni-providers/). -> After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications. +:::caution + +After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications. + +::: Out of the box, Rancher is compatible with the following network providers: @@ -112,7 +120,11 @@ Project network isolation is available if you are using any RKE network plugin t You can configure a [Kubernetes cloud provider]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers). If you want to use dynamically provisioned [volumes and storage]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider. ->**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#cluster-config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation]({{}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. +:::note + +If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#cluster-config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation]({{}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. + +::: ### Private Registries @@ -135,7 +147,11 @@ Rancher v2.6 introduced the ability to configure [ECR registries for RKE cluster Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. -> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.6/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. +:::note + +The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.6/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. + +::: This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. diff --git a/docs/en/cluster-admin/editing-clusters/rke2-config-reference/rke2-config-reference.md b/docs/en/cluster-admin/editing-clusters/rke2-config-reference/rke2-config-reference.md index 3e1ee54d5db..dcbdcadca9f 100644 --- a/docs/en/cluster-admin/editing-clusters/rke2-config-reference/rke2-config-reference.md +++ b/docs/en/cluster-admin/editing-clusters/rke2-config-reference/rke2-config-reference.md @@ -15,7 +15,11 @@ You can configure the Kubernetes options in one of the two following ways: # Configuration Options in the Rancher UI -> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE2 cluster configuration file in YAML. For the complete reference of configurable options for RKE2 Kubernetes clusters in YAML, see the [RKE2 documentation.](https://docs.rke2.io/install/install_options/install_options/) +:::tip + +Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE2 cluster configuration file in YAML. For the complete reference of configurable options for RKE2 Kubernetes clusters in YAML, see the [RKE2 documentation.](https://docs.rke2.io/install/install_options/install_options/) + +::: ### Basics #### Kubernetes Version @@ -28,7 +32,11 @@ For more detail, see [Upgrading Kubernetes]({{}}/rancher/v2.6/en/cluste The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. -> After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you to tear down the entire cluster and all its applications. +:::caution + +After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you to tear down the entire cluster and all its applications. + +::: Out of the box, Rancher is compatible with the following network providers: @@ -53,7 +61,11 @@ When using `cilium` or `multus,cilium` as your container network interface provi You can configure a [Kubernetes cloud provider]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers). If you want to use dynamically provisioned [volumes and storage]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider. ->**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#cluster-config-file) to configure the cloud provider. Please reference [this documentation]({{}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. +:::note + +If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#cluster-config-file) to configure the cloud provider. Please reference [this documentation]({{}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. + +::: #### Default Pod Security Policy diff --git a/docs/en/cluster-admin/nodes/nodes.md b/docs/en/cluster-admin/nodes/nodes.md index 9f2243cceab..4bd5167b9aa 100644 --- a/docs/en/cluster-admin/nodes/nodes.md +++ b/docs/en/cluster-admin/nodes/nodes.md @@ -5,7 +5,11 @@ weight: 2030 After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's **Node** tab. Depending on the [option used]({{}}/rancher/v2.6/en/cluster-provisioning/) to provision the cluster, there are different node options available. -> If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters). +:::note + +If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters). + +::: This section covers the following topics: @@ -88,7 +92,11 @@ Use **Delete** to remove defective nodes from the cloud provider. When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and [node auto-replace is enabled.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#about-node-auto-replace) ->**Tip:** If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete. +:::tip + +If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete. + +::: # Scaling Nodes @@ -146,7 +154,11 @@ The timeout given to each pod for cleaning things up, so they will have chance t The amount of time drain should continue to wait before giving up. ->**Kubernetes Known Issue:** The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was not enforced while draining a node before Kubernetes 1.12. +:::note Kubernetes Known Issue: + +The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was not enforced while draining a node before Kubernetes 1.12. + +::: ### Drained and Cordoned State @@ -156,7 +168,7 @@ If the drain continues without error, the node enters a `draining` state. You'll Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node. ->**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#maintenance-on-a-node). +**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#maintenance-on-a-node). # Labeling a Node to be Ignored by Rancher @@ -168,7 +180,11 @@ In that case, you may want to label the node to be ignored by Rancher so that Ra You can label nodes to be ignored by using a setting in the Rancher UI, or by using `kubectl`. -> **Note:** There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state. +:::note + +There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state. + +::: ### Labeling Nodes to be Ignored with kubectl diff --git a/docs/en/cluster-admin/pod-security-policies/pod-security-policies.md b/docs/en/cluster-admin/pod-security-policies/pod-security-policies.md index 4d1b3ca719f..47eec54e59c 100644 --- a/docs/en/cluster-admin/pod-security-policies/pod-security-policies.md +++ b/docs/en/cluster-admin/pod-security-policies/pod-security-policies.md @@ -9,10 +9,17 @@ _Pod Security Policies_ are objects that control security-sensitive aspects of p When you create a new cluster with RKE, you can configure it to apply a PSP immediately. As you create the cluster, use the **Cluster Options** to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster. ->**Prerequisite:** ->Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{}}/rancher/v2.6/en/admin-settings/pod-security-policies/). ->**Note:** ->For security purposes, we recommend assigning a PSP as you create your clusters. +:::Prerequisite: + +Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{}}/rancher/v2.6/en/admin-settings/pod-security-policies/). + +::: + +:::note + +For security purposes, we recommend assigning a PSP as you create your clusters. + +::: To enable a default Pod Security Policy, set the **Pod Security Policy Support** option to **Enabled**, and then make a selection from the **Default Pod Security Policy** drop-down. diff --git a/docs/en/cluster-admin/pod-security-policy/pod-security-policy.md b/docs/en/cluster-admin/pod-security-policy/pod-security-policy.md index 92e320f85e4..24d2e3d9625 100644 --- a/docs/en/cluster-admin/pod-security-policy/pod-security-policy.md +++ b/docs/en/cluster-admin/pod-security-policy/pod-security-policy.md @@ -3,7 +3,11 @@ title: Adding a Pod Security Policy weight: 80 --- -> **Prerequisite:** The options below are available only for clusters that are [launched using RKE.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) +:::note Prerequisite: + +The options below are available only for clusters that are [launched using RKE.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) + +::: When your cluster is running pods with security-sensitive configurations, assign it a [pod security policy]({{}}/rancher/v2.6/en/admin-settings/pod-security-policies/), which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running. @@ -13,7 +17,11 @@ You can assign a pod security policy when you provision a cluster. However, if y 1. Go to the cluster to which you want to apply a pod security policy and click **⋮ > Edit Config**. 1. From **Pod Security Policy Support**, select **Enabled**. - >**Note:** This option is only available for clusters [provisioned by RKE]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). + :::note + + This option is only available for clusters [provisioned by RKE]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). + + ::: 4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster. @@ -23,6 +31,10 @@ You can assign a pod security policy when you provision a cluster. However, if y **Result:** The pod security policy is applied to the cluster and any projects within the cluster. ->**Note:** Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run. -> ->To check if a running workload passes your pod security policy, clone or upgrade it. \ No newline at end of file +:::note + +Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run. + +To check if a running workload passes your pod security policy, clone or upgrade it. + +::: \ No newline at end of file diff --git a/docs/en/cluster-admin/projects-and-namespaces/projects-and-namespaces.md b/docs/en/cluster-admin/projects-and-namespaces/projects-and-namespaces.md index d1ae03863b4..2af182a7594 100644 --- a/docs/en/cluster-admin/projects-and-namespaces/projects-and-namespaces.md +++ b/docs/en/cluster-admin/projects-and-namespaces/projects-and-namespaces.md @@ -8,7 +8,11 @@ A namespace is a Kubernetes concept that allows a virtual cluster within a clust A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster. ->**Note:** As of Rancher v2.6, projects are de-emphasized on the UI because it is no longer required to create any Kubernetes resources within a project scope. However, resources such as [Secrets]({{}}/rancher/v2.6/en/k8s-in-rancher/secrets/#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled. +:::note + +As of Rancher v2.6, projects are de-emphasized on the UI because it is no longer required to create any Kubernetes resources within a project scope. However, resources such as [Secrets]({{}}/rancher/v2.6/en/k8s-in-rancher/secrets/#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled. + +::: This section describes how projects and namespaces work with Rancher. It covers the following topics: @@ -25,7 +29,11 @@ This section describes how projects and namespaces work with Rancher. It covers A namespace is a concept introduced by Kubernetes. According to the [official Kubernetes documentation on namespaces,](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -> Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all. +:::note + +Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all. + +::: Namespaces provide the following functionality: @@ -103,7 +111,11 @@ The `system` project: - Allows you to add more namespaces or move its namespaces to other projects. - Cannot be deleted because it's required for cluster operations. ->**Note:** In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health. +:::note + +In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health. + +::: # Project Authorization @@ -149,13 +161,15 @@ Use the **Members** section to provide other users with project access and roles By default, your user is added as the project `Owner`. ->**Notes on Permissions:** -> ->- 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. -> ->- 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. -> ->- Choose `Custom` to create a custom role on the fly: [Custom Project Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles). +:::note Notes on Permissions: + +- 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. + +- 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. + +- Choose `Custom` to create a custom role on the fly: [Custom Project Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles). + +::: To add members: From 2922d9d6c31bb2b6652d977966bd7fba5259ca66 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 7 Jul 2022 13:46:58 -0400 Subject: [PATCH 05/18] refactoring notes --- .../restoring-etcd/restoring-etcd.md | 6 +++++- .../upgrading-kubernetes.md | 16 +++++++++++----- .../attaching-existing-storage.md | 6 +++++- .../volumes-and-storage/ceph/ceph.md | 6 +++++- .../volumes-and-storage/examples/nfs/nfs.md | 18 ++++++++++++------ .../examples/vsphere/vsphere.md | 8 +++++--- .../glusterfs-volumes/glusterfs-volumes.md | 14 ++++++++++---- .../how-storage-works/how-storage-works.md | 8 ++++++-- .../iscsi-volumes/iscsi-volumes.md | 14 ++++++++------ 9 files changed, 67 insertions(+), 29 deletions(-) diff --git a/docs/en/cluster-admin/restoring-etcd/restoring-etcd.md b/docs/en/cluster-admin/restoring-etcd/restoring-etcd.md index 099fa8295f3..cbf52047c39 100644 --- a/docs/en/cluster-admin/restoring-etcd/restoring-etcd.md +++ b/docs/en/cluster-admin/restoring-etcd/restoring-etcd.md @@ -36,7 +36,11 @@ Snapshots are composed of the cluster data in etcd, the Kubernetes version, and When rolling back to a prior Kubernetes version, the [upgrade strategy options]({{}}/rancher/v2.6/en/cluster-admin/upgrading-kubernetes/#configuring-the-upgrade-strategy) are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state. -> **Prerequisite:** To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{}}/rancher/v2.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots) +:::note Prerequisite: + +To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{}}/rancher/v2.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots) + +::: 1. In the upper left corner, click **☰ > Cluster Management**. 1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster. diff --git a/docs/en/cluster-admin/upgrading-kubernetes/upgrading-kubernetes.md b/docs/en/cluster-admin/upgrading-kubernetes/upgrading-kubernetes.md index 03e871e5b08..f3123e62bb8 100644 --- a/docs/en/cluster-admin/upgrading-kubernetes/upgrading-kubernetes.md +++ b/docs/en/cluster-admin/upgrading-kubernetes/upgrading-kubernetes.md @@ -45,10 +45,12 @@ The restore operation will work on a cluster that is not in a healthy or active # Upgrading the Kubernetes Version -> **Prerequisites:** -> -> - The options below are available only for [Rancher-launched RKE Kubernetes clusters]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) and [Registered K3s Kubernetes clusters.]({{}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-k3s-clusters) -> - Before upgrading Kubernetes, [back up your cluster.]({{}}/rancher/v2.6/en/backups) +:::note Prerequisites: + +- The options below are available only for [Rancher-launched RKE Kubernetes clusters]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) and [Registered K3s Kubernetes clusters.]({{}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-k3s-clusters) +- Before upgrading Kubernetes, [back up your cluster.]({{}}/rancher/v2.6/en/backups) + +::: 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**. @@ -102,7 +104,11 @@ To enable draining each node during a cluster upgrade, **Result:** The cluster is updated to use the new upgrade strategy. -> **Note:** As of Rancher v2.4.0, there is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained. +:::note + +As of Rancher v2.4.0, there is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained. + +::: ### Maintaining Availability for Applications During Upgrades diff --git a/docs/en/cluster-admin/volumes-and-storage/attaching-existing-storage/attaching-existing-storage.md b/docs/en/cluster-admin/volumes-and-storage/attaching-existing-storage/attaching-existing-storage.md index c129077e4dd..01d403cdb8d 100644 --- a/docs/en/cluster-admin/volumes-and-storage/attaching-existing-storage/attaching-existing-storage.md +++ b/docs/en/cluster-admin/volumes-and-storage/attaching-existing-storage/attaching-existing-storage.md @@ -5,7 +5,11 @@ weight: 1 This section describes how to set up existing persistent storage for workloads in Rancher. -> This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works) +:::note + +This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works) + +::: To set up storage, follow these steps: diff --git a/docs/en/cluster-admin/volumes-and-storage/ceph/ceph.md b/docs/en/cluster-admin/volumes-and-storage/ceph/ceph.md index c7b633e5b2f..a3a6dcb0a2b 100644 --- a/docs/en/cluster-admin/volumes-and-storage/ceph/ceph.md +++ b/docs/en/cluster-admin/volumes-and-storage/ceph/ceph.md @@ -47,7 +47,11 @@ For more information about the `extra_binds` directive, refer to [this section.] # Installing the ceph-csi driver on an RKE2 cluster -> **Note:** These steps are needed for dynamic RBD provisioning only. +:::note + +These steps are needed for dynamic RBD provisioning only. + +::: For more information about the `ceph-csi-rbd` chart, refer to [this page.](https://github.com/ceph/ceph-csi/blob/devel/charts/ceph-csi-rbd/README.md) diff --git a/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md b/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md index 65863b93fad..49e0d658658 100644 --- a/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md +++ b/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md @@ -5,13 +5,19 @@ weight: 3054 Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server. ->**Note:** -> ->- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/). -> ->- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation. +:::note ->**Recommended:** To simplify the process of managing firewall rules, use NFSv4. +- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/). + +- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation. + +::: + +:::note Recommended: + +To simplify the process of managing firewall rules, use NFSv4. + +::: 1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage. diff --git a/docs/en/cluster-admin/volumes-and-storage/examples/vsphere/vsphere.md b/docs/en/cluster-admin/volumes-and-storage/examples/vsphere/vsphere.md index 301a5def990..b2734c6624f 100644 --- a/docs/en/cluster-admin/volumes-and-storage/examples/vsphere/vsphere.md +++ b/docs/en/cluster-admin/volumes-and-storage/examples/vsphere/vsphere.md @@ -19,9 +19,11 @@ In order to provision vSphere volumes in a cluster created with the [Rancher Kub ### Creating a StorageClass -> **Note:** -> -> The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details. +:::tip + +The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details. + +::: 1. Click **☰ > Cluster Management**. 1. Go to the cluster where you want to provide vSphere storage. diff --git a/docs/en/cluster-admin/volumes-and-storage/glusterfs-volumes/glusterfs-volumes.md b/docs/en/cluster-admin/volumes-and-storage/glusterfs-volumes/glusterfs-volumes.md index eaf2386d9fa..6d06f06d837 100644 --- a/docs/en/cluster-admin/volumes-and-storage/glusterfs-volumes/glusterfs-volumes.md +++ b/docs/en/cluster-admin/volumes-and-storage/glusterfs-volumes/glusterfs-volumes.md @@ -3,7 +3,11 @@ title: GlusterFS Volumes weight: 5000 --- -> This section only applies to [RKE clusters.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) +:::note + +This section only applies to [RKE clusters.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) + +::: In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. The logging of the `kubelet` will show: `transport endpoint is not connected`. To prevent this from happening, you can configure your cluster to mount the `systemd-run` binary in the `kubelet` container. There are two requirements before you can change the cluster configuration: @@ -14,9 +18,11 @@ In clusters that store data on GlusterFS volumes, you may experience an issue wh docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version ``` ->**Note:** -> ->Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed. +:::caution + +Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed. + +::: ``` services: diff --git a/docs/en/cluster-admin/volumes-and-storage/how-storage-works/how-storage-works.md b/docs/en/cluster-admin/volumes-and-storage/how-storage-works/how-storage-works.md index 4993c0061b3..6f69bfdc83b 100644 --- a/docs/en/cluster-admin/volumes-and-storage/how-storage-works/how-storage-works.md +++ b/docs/en/cluster-admin/volumes-and-storage/how-storage-works/how-storage-works.md @@ -54,7 +54,11 @@ PVs can represent a physical disk or file system that you host on premise, or a Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned. -> **Important:** PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV. +:::note Important: + +PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV. + +::: ### Binding PVs to PVCs @@ -62,7 +66,7 @@ When pods are set up to use persistent storage, they mount a persistent volume c > Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster. -In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PVs that has at least the amount of disk space required by the PVC. +In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PV that has at least the amount of disk space required by the PVC. To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume. diff --git a/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md b/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md index c8a14cb458d..5871cd887f4 100644 --- a/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md +++ b/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md @@ -17,12 +17,14 @@ If you encounter this issue, you can work around it by installing the initiator After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below. ->**Notes:** -> ->- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
->
-> ->- The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes. +:::note Notes + +- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
+
+ +- The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes. + +::: ``` services: From 97e22b9c9a535574c449de87cd1c52bdab8a0afd Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 7 Jul 2022 14:20:49 -0400 Subject: [PATCH 06/18] Updating notes --- .../iscsi-volumes/iscsi-volumes.md | 3 +-- .../hosted-kubernetes-clusters/ack/ack.md | 7 +++++-- .../hosted-kubernetes-clusters/aks/aks.md | 13 ++++++++++--- .../hosted-kubernetes-clusters/cce/cce.md | 7 +++++-- .../hosted-kubernetes-clusters/eks/eks.md | 13 ++++++++++--- .../hosted-kubernetes-clusters/gke/gke.md | 14 ++++++++++---- .../hosted-kubernetes-clusters/tke/tke.md | 7 +++++-- 7 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md b/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md index 5871cd887f4..d48eb80e214 100644 --- a/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md +++ b/docs/en/cluster-admin/volumes-and-storage/iscsi-volumes/iscsi-volumes.md @@ -19,8 +19,7 @@ After installing the initiator tool on your nodes, edit the YAML for your cluste :::note Notes -- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
-
+- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed. - The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes. diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/ack/ack.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/ack/ack.md index 2a701f6a6dc..8c01b435914 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/ack/ack.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/ack/ack.md @@ -8,8 +8,11 @@ You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK) # Prerequisites Outside of Rancher ->**Note** ->Deploying to ACK will incur charges. +:::caution + +Deploying to ACK will incur charges. + +::: 1. In Aliyun, activate the following services in their respective consoles. diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/aks/aks.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/aks/aks.md index f54e1e42bdd..ac4c2a78cc5 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/aks/aks.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/aks/aks.md @@ -19,8 +19,11 @@ You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Ser # Prerequisites in Microsoft Azure ->**Note** ->Deploying to AKS will incur charges. +:::caution + +Deploying to AKS will incur charges. + +::: To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the [AKS documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal). @@ -143,7 +146,11 @@ The first way to ensure that Rancher is running on the same [NAT](https://docs.m The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled. -> **Note:** Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. +:::note + +Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. + +::: For more information about connecting to an AKS private cluster, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md index 1065d360b17..2d0d16ef917 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md @@ -8,8 +8,11 @@ You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine # Prerequisites in Huawei ->**Note** ->Deploying to CCE will incur charges. +:::caution + +Deploying to CCE will incur charges. + +::: 1. Find your project ID in Huawei CCE portal. See the CCE documentation on how to [manage your projects](https://support.huaweicloud.com/en-us/usermanual-iam/en-us_topic_0066738518.html). diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/eks/eks.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/eks/eks.md index 3f55612fbdd..935b58ebdf6 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/eks/eks.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/eks/eks.md @@ -20,8 +20,11 @@ Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon - [Programmatically Creating EKS Clusters](#programmatically-creating-eks-clusters) # Prerequisites in Amazon Web Services ->**Note** ->Deploying to Amazon AWS will incur charges. For more information, refer to the [EKS pricing page](https://aws.amazon.com/eks/pricing/). +:::caution + +Deploying to Amazon AWS will incur charges. For more information, refer to the [EKS pricing page](https://aws.amazon.com/eks/pricing/). + +::: To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate [permissions.](#minimum-eks-permissions) For details, refer to the official guide on [Amazon EKS Prerequisites](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#eks-prereqs). @@ -39,7 +42,11 @@ Rancher needs access to your AWS account in order to provision and administer yo 3. Finally, follow the steps [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) to create an access key and secret key for this user. -> **Note:** It's important to regularly rotate your access and secret keys. See this [documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#rotating_access_keys_console) for more information. +:::note Important: + +It's important to regularly rotate your access and secret keys. See this [documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#rotating_access_keys_console) for more information. + +::: For more detailed information on IAM policies for EKS, refer to the official [documentation on Amazon EKS IAM Policies, Roles, and Permissions](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html). diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/gke/gke.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/gke/gke.md index 95567faa8c9..88232871dce 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/gke/gke.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/gke/gke.md @@ -41,8 +41,11 @@ To get the project ID of an existing project, refer to the Google cloud document # Provisioning a GKE Cluster ->**Note** ->Deploying to GKE will incur charges. +:::caution + +Deploying to GKE will incur charges. + +::: ### 1. Create a Cloud Credential @@ -90,8 +93,11 @@ For details on configuring GKE clusters in Rancher, see [this page.]({{ The Kubernetes version of a cluster can be upgraded to any version available in the region or zone fo the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently. ->**Note** ->GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the [Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#disabling_authentication_with_a_static_password). After this, the Kubernetes version can be updated to 1.19+ via Rancher. +:::note + +GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the [Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#disabling_authentication_with_a_static_password). After this, the Kubernetes version can be updated to 1.19+ via Rancher. + +::: # Syncing diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md index 7b4f92bd0ea..69681f92180 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md @@ -8,8 +8,11 @@ You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE # Prerequisites in Tencent ->**Note** ->Deploying to TKE will incur charges. +:::caution + +Deploying to TKE will incur charges. + +::: 1. Make sure that the account you will be using to create the TKE cluster has the appropriate permissions by referring to the [Cloud Access Management](https://intl.cloud.tencent.com/document/product/598/10600) documentation for details. From cc0a6eb774122f44cc48fcff28eadfae8b3ef103 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 7 Jul 2022 18:33:04 -0400 Subject: [PATCH 07/18] Updating notes --- .../node-requirements/node-requirements.md | 16 ++++-- .../nodes-and-roles/nodes-and-roles.md | 12 ++++- .../registered-clusters.md | 41 +++++++++----- .../cloud-providers/amazon/amazon.md | 6 ++- .../rke-clusters/cloud-providers/gce/gce.md | 6 ++- .../rke-clusters/custom-nodes/custom-nodes.md | 53 +++++++++++++------ .../rke-clusters/node-pools/azure/azure.md | 12 +++-- .../rke-clusters/node-pools/ec2/ec2.md | 13 ++++- .../rke-clusters/node-pools/node-pools.md | 12 ++++- .../vsphere-node-template-config.md | 6 ++- .../node-pools/vsphere/vsphere.md | 6 ++- .../windows-clusters/windows-clusters.md | 34 ++++++++---- docs/en/contributing/contributing.md | 25 +++++++-- .../multi-cluster-apps/multi-cluster-apps.md | 36 ++++++++++--- .../deprecated-features.md | 1 + .../networking/cni-providers/cni-providers.md | 14 +++-- 16 files changed, 223 insertions(+), 70 deletions(-) diff --git a/docs/en/cluster-provisioning/node-requirements/node-requirements.md b/docs/en/cluster-provisioning/node-requirements/node-requirements.md index 519e8c31077..a6d2924de98 100644 --- a/docs/en/cluster-provisioning/node-requirements/node-requirements.md +++ b/docs/en/cluster-provisioning/node-requirements/node-requirements.md @@ -5,7 +5,11 @@ weight: 1 This page describes the requirements for the Rancher managed Kubernetes clusters where your apps and services will be installed. These downstream clusters should be separate from the three-node cluster running Rancher. -> If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the [installation section.]({{}}/rancher/v2.6/en/installation/requirements/) +:::note + +If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the [installation section.]({{}}/rancher/v2.6/en/installation/requirements/) + +::: Make sure the nodes for the Rancher server fulfill the following requirements: @@ -30,13 +34,17 @@ For information on how to install Docker, refer to the official [Docker document Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off. ->**Note:** In RHEL 8.4, two extra services are included on the NetworkManager: `nm-cloud-setup.service` and `nm-cloud-setup.timer`. These services add a routing table that interferes with the CNI plugin's configuration. If these services are enabled, you must disable them using the command below, and then reboot the node to restore connectivity: -> -> ``` +:::note + +In RHEL 8.4, two extra services are included on the NetworkManager: `nm-cloud-setup.service` and `nm-cloud-setup.timer`. These services add a routing table that interferes with the CNI plugin's configuration. If these services are enabled, you must disable them using the command below, and then reboot the node to restore connectivity: + + ``` systemctl disable nm-cloud-setup.service nm-cloud-setup.timer reboot ``` +::: + ### SUSE Linux Nodes SUSE Linux may have a firewall that blocks all ports by default. In that situation, follow [these steps]({{}}/rancher/v2.6/en/installation/requirements/ports/#opening-suse-linux-ports) to open the ports needed for adding a host to a custom cluster. diff --git a/docs/en/cluster-provisioning/production/nodes-and-roles/nodes-and-roles.md b/docs/en/cluster-provisioning/production/nodes-and-roles/nodes-and-roles.md index c073cdb4388..ec7d5bd67d2 100644 --- a/docs/en/cluster-provisioning/production/nodes-and-roles/nodes-and-roles.md +++ b/docs/en/cluster-provisioning/production/nodes-and-roles/nodes-and-roles.md @@ -14,13 +14,21 @@ This diagram is applicable to Kubernetes clusters [launched with Rancher using R Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node. ->**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. +:::note + +Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. + +::: # controlplane Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components. ->**Note:** Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. +:::note + +Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. + +::: ### kube-apiserver diff --git a/docs/en/cluster-provisioning/registered-clusters/registered-clusters.md b/docs/en/cluster-provisioning/registered-clusters/registered-clusters.md index 5bcc0cc73f0..69233513ad0 100644 --- a/docs/en/cluster-provisioning/registered-clusters/registered-clusters.md +++ b/docs/en/cluster-provisioning/registered-clusters/registered-clusters.md @@ -67,8 +67,11 @@ EKS clusters must have at least one managed node group to be imported into Ranch - **Active** clusters are assigned two Projects: `Default` (containing the namespace `default`) and `System` (containing the namespaces `cattle-system`, `ingress-nginx`, `kube-public` and `kube-system`, if present). -> **Note:** -> You can not re-register a cluster that is currently active in a Rancher setup. +:::note + +You can not re-register a cluster that is currently active in a Rancher setup. + +::: ### Configuring a K3s Cluster to Enable Registration in Rancher @@ -90,7 +93,11 @@ $ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s - You should define **only** the minimum fields that Rancher requires when importing an EKS cluster with Terraform. This is important as Rancher will overwrite what was in the EKS cluster with any config that the user has provided. ->**Warning:** Even a small difference between the current EKS cluster and a user-provided config could have unexpected results. +::caution + +Even a small difference between the current EKS cluster and a user-provided config could have unexpected results. + +::: The minimum config fields required by Rancher to import EKS clusters with Terraform using `eks_config_v2` are as follows: @@ -155,7 +162,11 @@ The capabilities for registered clusters are listed in the table on [this page.] # Configuring K3s Cluster Upgrades -> It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider. +:::tip + +It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider. + +::: The **concurrency** is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the **concurrency,** the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed. @@ -194,13 +205,15 @@ _Available as of v2.6.3_ Authorized Cluster Endpoint (ACE) support has been added for registered RKE2 and K3s clusters. This support includes manual steps you will perform on the downstream cluster to enable the ACE. For additional information on the authorized cluster endpoint, click [here]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/ace/). -> **Note:** -> -> - These steps only need to be performed on the control plane nodes of the downstream cluster. You must configure each control plane node individually. -> -> - The following steps will work on both RKE2 and K3s clusters registered in v2.6.x as well as those registered (or imported) from a previous version of Rancher with an upgrade to v2.6.x. -> -> - These steps will alter the configuration of the downstream RKE2 and K3s clusters and deploy the `kube-api-authn-webhook`. If a future implementation of the ACE requires an update to the `kube-api-authn-webhook`, then this would also have to be done manually. For more information on this webhook, click [here]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/ace/#about-the-kube-api-auth-authentication-webhook). +:::note Notes: + +- These steps only need to be performed on the control plane nodes of the downstream cluster. You must configure each control plane node individually. + +- The following steps will work on both RKE2 and K3s clusters registered in v2.6.x as well as those registered (or imported) from a previous version of Rancher with an upgrade to v2.6.x. + +- These steps will alter the configuration of the downstream RKE2 and K3s clusters and deploy the `kube-api-authn-webhook`. If a future implementation of the ACE requires an update to the `kube-api-authn-webhook`, then this would also have to be done manually. For more information on this webhook, click [here]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/ace/#about-the-kube-api-auth-authentication-webhook). + +::: ###### **Manual steps to be taken on the control plane of each downstream cluster to enable ACE:** @@ -236,7 +249,11 @@ Authorized Cluster Endpoint (ACE) support has been added for registered RKE2 and 1. Finally, you **must** go back to the Rancher UI and edit the imported cluster there to complete the ACE enablement. Click on **⋮ > Edit Config**, then click the **Networking** tab under Cluster Configuration. Finally, click the **Enabled** button for **Authorized Endpoint**. Once the ACE is enabled, you then have the option of entering a fully qualified domain name (FQDN) and certificate information. - >**Note:** The FQDN field is optional, and if one is entered, it should point to the downstream cluster. Certificate information is only needed if there is a load balancer in front of the downstream cluster that is using an untrusted certificate. If you have a valid certificate, then nothing needs to be added to the CA Certificates field. + :::note + + The FQDN field is optional, and if one is entered, it should point to the downstream cluster. Certificate information is only needed if there is a load balancer in front of the downstream cluster that is using an untrusted certificate. If you have a valid certificate, then nothing needs to be added to the CA Certificates field. + + ::: # Annotating Registered Clusters diff --git a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md index b8582ef3535..cbbb614615f 100644 --- a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md +++ b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md @@ -131,7 +131,11 @@ The following resources need to tagged with a `ClusterID`: - **Subnet**: The subnet used for your cluster. - **Security Group**: The security group used for your cluster. ->**Note:** Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB). +::note + +Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB). + +::: When you create an [Amazon EC2 Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/ec2/), the `ClusterID` is automatically configured for the created nodes. Other resources still need to be tagged manually. diff --git a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/gce/gce.md b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/gce/gce.md index e1b7c2c3024..e6492ecb295 100644 --- a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/gce/gce.md +++ b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/gce/gce.md @@ -7,7 +7,11 @@ In this section, you'll learn how to enable the Google Compute Engine (GCE) clou The official Kubernetes documentation for the GCE cloud provider is [here.](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#gce) -> **Prerequisites:** The service account of `Identity and API` access on GCE needs the `Computer Admin` permission. +:::note Prerequisites: + +The service account of `Identity and API` access on GCE needs the `Computer Admin` permission. + +::: If you are using Calico, diff --git a/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md b/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md index fcf49838d16..82e3cef778c 100644 --- a/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md +++ b/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md @@ -13,9 +13,11 @@ This section describes how to set up a custom cluster. # Creating a Cluster with Custom Nodes ->**Want to use Windows hosts as Kubernetes workers?** -> ->See [Configuring Custom Clusters for Windows]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/) before you start. +:::note Want to use Windows hosts as Kubernetes workers? + +See [Configuring Custom Clusters for Windows]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/) before you start. + +::: @@ -47,12 +49,18 @@ If you're using Amazon EC2 as your host and want to use the [dual-stack](https:/ 1. Enter a **Cluster Name**. 1. Use **Cluster Configuration** section to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on **Show advanced options**. - >**Using Windows nodes as Kubernetes workers?** - > - >- See [Enable the Windows Support Option]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). - >- The only Network Provider available for clusters with Windows support is Flannel. - > - >**Dual-stack on Amazon EC2:** If you're using Amazon EC2 as your host and want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) when configuring RKE. + :::note Using Windows nodes as Kubernetes workers? + + - See [Enable the Windows Support Option]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). + - The only Network Provider available for clusters with Windows support is Flannel. + + ::: + + :::note Dual-stack on Amazon EC2: + + If you're using Amazon EC2 as your host and want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) when configuring RKE. + + ::: 6. Click **Next**. @@ -60,10 +68,12 @@ If you're using Amazon EC2 as your host and want to use the [dual-stack](https:/ 7. From **Node Role**, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: `etcd`, `worker`, and `control plane`. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see [this section.]({{}}/rancher/v2.6/en/overview/concepts/#roles-for-nodes-in-kubernetes-clusters) - >**Notes:** - > - >- Using Windows nodes as Kubernetes workers? See [this section]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). - >- Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). + :::note Notes: + + - Using Windows nodes as Kubernetes workers? See [this section]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). + - Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). + + ::: 8. **Optional**: Click **[Show advanced options]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/rancher-agents/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node. @@ -71,7 +81,11 @@ If you're using Amazon EC2 as your host and want to use the [dual-stack](https:/ 10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. - >**Note:** Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed. + :::note + + Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed. + + ::: 11. When you finish running the command(s) on your Linux host(s), click **Done**. @@ -93,8 +107,11 @@ If you have configured your cluster to use Amazon as **Cloud Provider**, tag you [Amazon Documentation: Tagging Your Amazon EC2 Resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) ->**Note:** You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see [Kubernetes Cloud Providers](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/) +:::note +You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see [Kubernetes Cloud Providers](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/) + +::: The following resources need to be tagged with a `ClusterID`: @@ -102,7 +119,11 @@ The following resources need to be tagged with a `ClusterID`: - **Subnet**: The subnet used for your cluster - **Security Group**: The security group used for your cluster. - >**Note:** Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer. + :::note + + Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer. + + ::: The tag that should be used is: diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/azure/azure.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/azure/azure.md index 8e7deb9bf62..731dd8c755d 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/azure/azure.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/azure/azure.md @@ -10,12 +10,16 @@ First, you will set up your Azure cloud credentials in Rancher. Then you will us Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. ->**Warning:** When the Rancher RKE cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows: +:::caution -> - Terminate the SSL/TLS on the internal load balancer -> - Use the L7 load balancer +When the Rancher RKE cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows: -> For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations). +- Terminate the SSL/TLS on the internal load balancer +- Use the L7 load balancer + +For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations). + +::: For more information on configuring the Kubernetes cluster that Rancher will install on the Azure nodes, refer to the [RKE cluster configuration reference.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options) diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/ec2/ec2.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/ec2/ec2.md index 26d8d3c4576..5cafd243f31 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/ec2/ec2.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/ec2/ec2.md @@ -53,7 +53,11 @@ Creating a [node template]({{}}/rancher/v2.6/en/cluster-provisioning/rk 1. Fill out a node template for EC2. For help filling out the form, refer to [EC2 Node Template Configuration.](./ec2-node-template-config) 1. Click **Create**. - >**Note:** If you want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) that must be taken into consideration. + :::note + + If you want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) that must be taken into consideration. + + ::: ### 3. Create a cluster with node pools using the node template @@ -66,7 +70,12 @@ Add one or more node pools to your cluster. For more information about node pool 1. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. 1. Use **Cluster Options** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. Refer to [Selecting Cloud Providers]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/) to configure the Kubernetes Cloud Provider. For help configuring the cluster, refer to the [RKE cluster configuration reference.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options) - >**Note:** If you want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) that must be taken into consideration. + :::note + + If you want to use the [dual-stack](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) feature, there are additional [requirements]({{}}/rke//latest/en/config-options/dual-stack#requirements) that must be taken into consideration. + + ::: + 1. Click **Create**. {{% /tab %}} diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/node-pools.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/node-pools.md index 4f5700144d8..a840dec637c 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/node-pools.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/node-pools.md @@ -99,7 +99,11 @@ When there are taints on the node pool and node template, if there is no conflic If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes. -> **Important:** Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. +:::caution + +Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. + +::: Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the `--node-monitor-period` flag of the `kube-controller`). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool. @@ -144,7 +148,11 @@ If you don't find the node driver that you want to use, you can see if it is ava Rancher v2.6 introduces provisioning for [RKE2](https://docs.rke2.io/) clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. -> **Note:** For RKE2 cluster templates, please refer to [this page]({{}}/rancher/v2.6/en/admin-settings/cluster-templates/#rke2-cluster-template) for additional information. +:::note + +For RKE2 cluster templates, please refer to [this page]({{}}/rancher/v2.6/en/admin-settings/cluster-templates/#rke2-cluster-template) for additional information. + +::: ### Node Roles diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/vsphere-node-template-config.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/vsphere-node-template-config.md index 3cc65593540..bd446a50462 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/vsphere-node-template-config.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/vsphere-node-template-config.md @@ -78,7 +78,11 @@ For tags, all your vSphere tags will show up as options to select from in your n In the custom attributes, Rancher will let you select all the custom attributes you have already set up in vSphere. The custom attributes are keys and you can enter values for each one. -> **Note:** Custom attributes are a legacy feature that will eventually be removed from vSphere. +:::note + +Custom attributes are a legacy feature that will eventually be removed from vSphere. + +::: # cloud-init diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere.md index e11d83949fb..85d83075cb5 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere.md @@ -25,7 +25,11 @@ The vSphere node templates have been updated, allowing you to bring cloud operat One of the biggest advantages of provisioning vSphere nodes with Rancher is that it allows you to take advantage of Rancher's self-healing node pools, also called the [node auto-replace feature,]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#about-node-auto-replace) in your on-premises clusters. Self-healing node pools are designed to help you replace worker nodes for stateless applications. When Rancher provisions nodes from a node template, Rancher can automatically replace unreachable nodes. -> **Important:** It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. +:::caution + +It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. + +::: ### Dynamically Populated Options for Instances and Scheduling diff --git a/docs/en/cluster-provisioning/rke-clusters/windows-clusters/windows-clusters.md b/docs/en/cluster-provisioning/rke-clusters/windows-clusters/windows-clusters.md index 5db4add3d41..d79d4d76adc 100644 --- a/docs/en/cluster-provisioning/rke-clusters/windows-clusters/windows-clusters.md +++ b/docs/en/cluster-provisioning/rke-clusters/windows-clusters/windows-clusters.md @@ -43,7 +43,11 @@ The RKE2 provisioning feature also includes installing RKE2 on Windows clusters. Windows Support for RKE2 Custom Clusters requires choosing Calico as the CNI. ->**Important:** Rancher will allow Windows workload pods to deploy on both Windows and Linux worker nodes by default. When creating mixed clusters in RKE2, you must edit the `nodeSelector` in the chart to direct the pods to be placed onto a compatible Windows node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on how to use `nodeSelector` to assign pods to nodes. +:::note + +Rancher will allow Windows workload pods to deploy on both Windows and Linux worker nodes by default. When creating mixed clusters in RKE2, you must edit the `nodeSelector` in the chart to direct the pods to be placed onto a compatible Windows node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on how to use `nodeSelector` to assign pods to nodes. + +::: # Requirements for Windows Clusters @@ -85,7 +89,11 @@ For **VXLAN (Overlay)** networking, the [KB4489899](https://support.microsoft.co If you are configuring DHCP options sets for an AWS virtual private cloud, note that in the `domain-name` option field, only one domain name can be specified. According to the DHCP options [documentation:](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) -> Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name. +:::note + +Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name. + +::: ### Rancher on vSphere with ESXi 6.7u2 and above @@ -196,7 +204,11 @@ The instructions for creating a Windows cluster on existing nodes are very simil 1. Optional: After you enable Windows support, you will be able to choose the Flannel backend. There are two network options: [**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) and [**VXLAN (Overlay)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan). The default option is **VXLAN (Overlay)** mode. 1. Click **Next**. -> **Important:** For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM. +:::note Important: + +For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM. + +::: # 3. Add Nodes to the Cluster @@ -245,13 +257,17 @@ After the initial provisioning of your cluster, your cluster only has a single L **Result:** The **Worker** role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster. -> **Note:** Taints on Linux Worker Nodes -> -> For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads. +:::note -> | Taint Key | Taint Value | Taint Effect | -> | -------------- | ----------- | ------------ | -> | `cattle.io/os` | `linux` | `NoSchedule` | +Taints on Linux Worker Nodes + +For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads. + +| Taint Key | Taint Value | Taint Effect | +| -------------- | ----------- | ------------ | +| `cattle.io/os` | `linux` | `NoSchedule` | + +::: ### Add a Windows Worker Node diff --git a/docs/en/contributing/contributing.md b/docs/en/contributing/contributing.md index cb8d8332c8e..781c277bb30 100644 --- a/docs/en/contributing/contributing.md +++ b/docs/en/contributing/contributing.md @@ -55,8 +55,17 @@ If you can't find anything related to your issue, contact us by [filing an issue Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue. ->**Note:** For large amounts of data, please use [GitHub Gist](https://gist.github.com/) or similar and link the created resource in the issue. ->**Important:** Please remove any sensitive data as it will be publicly viewable. +:::note + +For large amounts of data, please use [GitHub Gist](https://gist.github.com/) or similar and link the created resource in the issue. + +::: + +:::note Important: + +Please remove any sensitive data as it will be publicly viewable. + +::: - **Resources:** Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below: - **Hosts:** What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce @@ -78,7 +87,11 @@ Please follow this checklist when filing an issue which will helps us investigat ``` - Kubernetes install using `kubectl` - > **Note:** Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI. + :::note + + Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI. + + ::: ``` kubectl -n cattle-system \ @@ -95,7 +108,11 @@ Please follow this checklist when filing an issue which will helps us investigat ``` - Kubernetes Install with RKE Add-On - > **Note:** Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI. + :::note + + Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI. + + ::: ``` kubectl -n cattle-system \ diff --git a/docs/en/deploy-across-clusters/multi-cluster-apps/multi-cluster-apps.md b/docs/en/deploy-across-clusters/multi-cluster-apps/multi-cluster-apps.md index 65e1978953d..b6a446453c3 100644 --- a/docs/en/deploy-across-clusters/multi-cluster-apps/multi-cluster-apps.md +++ b/docs/en/deploy-across-clusters/multi-cluster-apps/multi-cluster-apps.md @@ -88,13 +88,21 @@ Rancher will let you select from two options for Roles, **Project** and **Cluste When launching the application, Rancher will confirm if you have these permissions in the target projects before launching the application. -> **Note:** There are some applications like _Grafana_ or _Datadog_ that require access to specific cluster-scoped resources. These applications will require the _Cluster_ role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles. +:::note + +There are some applications like _Grafana_ or _Datadog_ that require access to specific cluster-scoped resources. These applications will require the _Cluster_ role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles. + +::: # Application Configuration Options For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm. -> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``). +:::note Example + +When entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``). + +::: ### Using a questions.yml file @@ -118,7 +126,11 @@ By default, multi-cluster applications can only be managed by the user who creat - **Read-only**: This access type cannot modify any configuration option for the multi-cluster application. Users can only view these applications. - > **Note:** Please ensure only trusted users are given _Owner_ or _Member_ access as they will automatically be able to manage applications created for this multi-cluster application in target projects they might not have direct access to. + :::caution + + Please ensure only trusted users are given _Owner_ or _Member_ access as they will automatically be able to manage applications created for this multi-cluster application in target projects they might not have direct access to. + + ::: ### Overriding Application Configuration Options for Specific Projects @@ -148,7 +160,11 @@ The creator and any users added with the access-type "owner" to a multi-cluster One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back. -> **Prerequisite:** The `legacy` feature flag needs to be enabled. +:::note Prerequisite: + +The `legacy` feature flag needs to be enabled. + +::: 1. In the upper left corner, click **☰ > Multi-cluster Apps**. @@ -160,10 +176,18 @@ One of the benefits of using a multi-cluster application as opposed to multiple # Deleting a Multi-Cluster Application -> **Prerequisite:** The `legacy` feature flag needs to be enabled. +:::note Prerequisite: + +The `legacy` feature flag needs to be enabled. + +::: 1. In the upper left corner, click **☰ > Multi-cluster Apps**. 2. Choose the multi-cluster application you want to delete and click the **⋮ > Delete**. When deleting the multi-cluster application, all applications and namespaces are deleted in all of the target projects. - > **Note:** The applications in the target projects, that are created for a multi-cluster application, cannot be deleted individually. The applications can only be deleted when the multi-cluster application is deleted. + :::note + + The applications in the target projects, that are created for a multi-cluster application, cannot be deleted individually. The applications can only be deleted when the multi-cluster application is deleted. + + ::: \ No newline at end of file diff --git a/docs/en/faq/deprecated-features/deprecated-features.md b/docs/en/faq/deprecated-features/deprecated-features.md index b0eb76250a4..0815fd29044 100644 --- a/docs/en/faq/deprecated-features/deprecated-features.md +++ b/docs/en/faq/deprecated-features/deprecated-features.md @@ -19,6 +19,7 @@ Rancher will publish deprecated features as part of the [release notes](https:// | [2.6.3](https://github.com/rancher/rancher/releases/tag/v2.6.3) | Dec 21, 2021 | | [2.6.4](https://github.com/rancher/rancher/releases/tag/v2.6.4) | Mar 31, 2022 | | [2.6.5](https://github.com/rancher/rancher/releases/tag/v2.6.5) | May 12, 2022 | +| [2.6.6](https://github.com/rancher/rancher/releases/tag/v2.6.6) | Jun 30, 2022 | ### What can I expect when a feature is marked for deprecation? diff --git a/docs/en/faq/networking/cni-providers/cni-providers.md b/docs/en/faq/networking/cni-providers/cni-providers.md index ea4bbde4872..2aba76d51d0 100644 --- a/docs/en/faq/networking/cni-providers/cni-providers.md +++ b/docs/en/faq/networking/cni-providers/cni-providers.md @@ -109,11 +109,15 @@ Calico also provides a stateless IP-in-IP or VXLAN encapsulation mode that can b Kubernetes workers should open TCP port `179` if using BGP or UDP port `4789` if using VXLAN encapsulation. In addition, TCP port `5473` is needed when using Typha. See [the port requirements for user clusters]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/#networking-requirements) for more details. ->**Important:** In Rancher v2.6.3, Calico probes fail on Windows nodes upon RKE2 installation. Note that this issue is resolved in v2.6.4. -> ->- To work around this issue, first navigate to `https:///v3/settings/windows-rke2-install-script`. -> ->- There, change the current setting: `https://raw.githubusercontent.com/rancher/wins/v0.1.3/install.ps1` to this new setting: `https://raw.githubusercontent.com/rancher/rke2/master/windows/rke2-install.ps1`. +:::note Important: + +In Rancher v2.6.3, Calico probes fail on Windows nodes upon RKE2 installation. Note that this issue is resolved in v2.6.4. + +- To work around this issue, first navigate to `https:///v3/settings/windows-rke2-install-script`. + +- There, change the current setting: `https://raw.githubusercontent.com/rancher/wins/v0.1.3/install.ps1` to this new setting: `https://raw.githubusercontent.com/rancher/rke2/master/windows/rke2-install.ps1`. + +::: ![Calico Diagram]({{}}/img/rancher/calico-diagram.svg) From 859854dd930b4b41a0b24538b130bb10b5bc3767 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 8 Jul 2022 09:45:13 -0400 Subject: [PATCH 08/18] Updating notes in Docu format --- docs/en/faq/technical/technical.md | 6 ++++- docs/en/helm-charts/helm-charts.md | 42 ++++++++++++++++++++---------- 2 files changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/en/faq/technical/technical.md b/docs/en/faq/technical/technical.md index ed4d3ec3f02..59630e73b9d 100644 --- a/docs/en/faq/technical/technical.md +++ b/docs/en/faq/technical/technical.md @@ -98,7 +98,11 @@ You can add additional arguments/binds/environment variables via the [Config Fil Use the `openssl verify` command to validate your certificate chain: ->**Note:** Configure `SSL_CERT_DIR` and `SSL_CERT_FILE` to a dummy location to make sure the OS installed certificates are not used when verifying manually. +:::tip + +Configure `SSL_CERT_DIR` and `SSL_CERT_FILE` to a dummy location to make sure the OS-installed certificates are not used when verifying manually. + +::: ``` SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem diff --git a/docs/en/helm-charts/helm-charts.md b/docs/en/helm-charts/helm-charts.md index aab00dd91dd..578cad8c2be 100644 --- a/docs/en/helm-charts/helm-charts.md +++ b/docs/en/helm-charts/helm-charts.md @@ -11,7 +11,11 @@ Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts w **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** charts are also upgraded to the correct release line for the chart. ->**Note:** Any major versions that are less than the ones mentioned in the table below are meant for 2.5 and below only. For example, you are advised to not use <100.x.x versions of Monitoring in 2.6.x+. +:::note + +Any major versions that are less than the ones mentioned in the table below are meant for 2.5 and below only. For example, you are advised to not use <100.x.x versions of Monitoring in 2.6.x+. + +::: **Feature Charts:** @@ -54,7 +58,11 @@ The charts page contains all Rancher, Partner, and Custom Charts. All three types are deployed and managed in the same way. -> 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 & Marketplace in the new UI must be managed only by Apps & Marketplace. +:::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 & Marketplace in the new UI must be managed only by Apps & Marketplace. + +::: ### Repositories @@ -88,19 +96,21 @@ To add a private CA for Helm Chart repositories: ``` -> **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`. -> -> ```yaml +:::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`. + +```yaml [...] spec: disableSameOriginCheck: true [...] ``` +::: + ### Helm Compatibility Only Helm 3 compatible charts are supported. @@ -116,11 +126,15 @@ After installing a chart, you can find it in the _"Installed Apps"_ tab. In this 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. -> 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 +:::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 + +::: #### Changes in Rancher v2.6.3 From 106e84d3c0f25ccdce1a059b6f5389ff0c2d4a09 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 8 Jul 2022 10:07:12 -0400 Subject: [PATCH 09/18] Updating notes in Docu format --- .../creating-apps/creating-apps.md | 18 ++++++++-- .../install-rancher-on-k8s.md | 36 +++++++++++++++---- 2 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/en/helm-charts/creating-apps/creating-apps.md b/docs/en/helm-charts/creating-apps/creating-apps.md index b4376f81ef7..1b4bf548ece 100644 --- a/docs/en/helm-charts/creating-apps/creating-apps.md +++ b/docs/en/helm-charts/creating-apps/creating-apps.md @@ -5,7 +5,11 @@ weight: 400 Rancher's App Marketplace is based on Helm Repositories and Helm Charts. You can add HTTP based standard Helm Repositories as well as any Git Repository which contains charts. -> For a complete walkthrough of developing charts, see the [Chart Template Developer's Guide](https://helm.sh/docs/chart_template_guide/) in the official Helm documentation. +:::tip + +For a complete walkthrough of developing charts, see the [Chart Template Developer's Guide](https://helm.sh/docs/chart_template_guide/) in the official Helm documentation. + +::: - [Chart types](#chart-types) - [Helm charts](#helm-charts) @@ -94,7 +98,11 @@ Inside the `questions.yml`, most of the content will be around the questions to For each chart, you can add the minimum and/or maximum Rancher version, which determines whether or not this chart is available to be deployed from Rancher. -> **Note:** Even though Rancher release versions are prefixed with a `v`, there is *no* prefix for the release version when using this option. +:::note + +Even though Rancher release versions are prefixed with a `v`, there is *no* prefix for the release version when using this option. + +::: ``` rancher_min_version: 2.3.0 @@ -125,4 +133,8 @@ This reference contains variables that you can use in `questions.yml` nested und | show_if | string | false | Show current variable if conditional variable is true. For example `show_if: "serviceType=Nodeport"` | | show\_subquestion_if | string | false | Show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| ->**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. +:::note + +`subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. + +::: diff --git a/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md b/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md index 55522d6caa9..1475548856e 100644 --- a/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md +++ b/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md @@ -53,7 +53,11 @@ To choose a Rancher version to install, refer to [Choosing a Rancher Version.]({ To choose a version of Helm to install Rancher with, refer to the [Helm version requirements]({{}}/rancher/v2.6/en/installation/resources/helm-version) -> **Note:** The installation instructions assume you are using Helm 3. +:::note + +The installation instructions assume you are using Helm 3. + +::: To set up Rancher, @@ -87,7 +91,11 @@ kubectl create namespace cattle-system The Rancher management server is designed to be secure by default and requires SSL/TLS configuration. -> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). +:::note + +If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). + +::: There are three recommended options for the source of the certificate used for TLS termination at the Rancher server: @@ -112,7 +120,11 @@ This step is only required to use certificates issued by Rancher's generated CA {{% accordion id="cert-manager" label="Click to Expand" %}} -> **Important:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). +:::note Important: + +Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + +::: These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm). @@ -152,7 +164,11 @@ The exact command to install Rancher differs depending on the certificate config However, irrespective of the certificate configuration, the name of the Rancher installation in the `cattle-system` namespace should always be `rancher`. -> **Tip for testing and development:** This final command to install Rancher requires a domain name that forwards traffic to Rancher. If you are using the Helm CLI to set up a proof-of-concept, you can use a fake domain name when passing the `hostname` option. An example of a fake domain name would be `.sslip.io`, which would expose Rancher on an IP where it is running. Production installs would require a real domain name. +:::tip Testing and Development: + +This final command to install Rancher requires a domain name that forwards traffic to Rancher. If you are using the Helm CLI to set up a proof-of-concept, you can use a fake domain name when passing the `hostname` option. An example of a fake domain name would be `.sslip.io`, which would expose Rancher on an IP where it is running. Production installs would require a real domain name. + +::: {{% tabs %}} {{% tab "Rancher-generated Certificates" %}} @@ -187,7 +203,11 @@ deployment "rancher" successfully rolled out This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. ->**Note:** You need to have port 80 open as the HTTP-01 challenge can only be done on port 80. +:::note + +You need to have port 80 open as the HTTP-01 challenge can only be done on port 80. + +::: In the following command, @@ -224,7 +244,11 @@ When you run this command, the `hostname` option must match the `Common Name` or Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers and applications. -> If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?]({{}}/rancher/v2.6/en/faq/technical/#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate) +:::note + +If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?]({{}}/rancher/v2.6/en/faq/technical/#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate) + +::: - Set the `hostname`. - Set the `bootstrapPassword` to something unique for the `admin` user. From 6b9095d077611b8e4312474f4f914ad1b2c88c0d Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 8 Jul 2022 11:54:36 -0400 Subject: [PATCH 10/18] Updating notes in Docu format --- .../install-rancher-on-k8s/aks/aks.md | 7 ++- .../amazon-eks/amazon-eks.md | 12 +++--- .../chart-options/chart-options.md | 18 ++++++-- .../install-rancher-on-k8s/gke/gke.md | 2 +- .../rollbacks/rollbacks.md | 17 +++++--- .../air-gap-upgrade/air-gap-upgrade.md | 18 +++++--- .../upgrades/upgrades.md | 34 ++++++++++++--- .../air-gap/air-gap.md | 8 +++- .../docker-install-commands.md | 43 +++++++++++++------ .../install-rancher/install-rancher.md | 19 ++++++-- .../launch-kubernetes/launch-kubernetes.md | 31 ++++++++++--- .../populate-private-registry.md | 24 ++++++++--- .../air-gap/prepare-nodes/prepare-nodes.md | 25 ++++++++--- 13 files changed, 192 insertions(+), 66 deletions(-) diff --git a/docs/en/installation/install-rancher-on-k8s/aks/aks.md b/docs/en/installation/install-rancher-on-k8s/aks/aks.md index b48aca076d9..d74b72b8e35 100644 --- a/docs/en/installation/install-rancher-on-k8s/aks/aks.md +++ b/docs/en/installation/install-rancher-on-k8s/aks/aks.md @@ -12,8 +12,11 @@ If you already have an AKS Kubernetes cluster, skip to the step about [installin # Prerequisites ->**Note** ->Deploying to Microsoft Azure will incur charges. +:::caution + +Deploying to Microsoft Azure will incur charges. + +::: - [Microsoft Azure Account](https://azure.microsoft.com/en-us/free/): A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes. - [Microsoft Azure Subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal): Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet. diff --git a/docs/en/installation/install-rancher-on-k8s/amazon-eks/amazon-eks.md b/docs/en/installation/install-rancher-on-k8s/amazon-eks/amazon-eks.md index 85e2f93bd56..8253a003126 100644 --- a/docs/en/installation/install-rancher-on-k8s/amazon-eks/amazon-eks.md +++ b/docs/en/installation/install-rancher-on-k8s/amazon-eks/amazon-eks.md @@ -45,11 +45,13 @@ Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS. -> **Prerequisites:** -> -> - You should already have an AWS account. -> - It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface. -> - The IAM user needs the minimum IAM policies described in the official [eksctl documentation.](https://eksctl.io/usage/minimum-iam-policies/) +:::note Prerequisites: + +- You should already have an AWS account. +- It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface. +- The IAM user needs the minimum IAM policies described in the official [eksctl documentation.](https://eksctl.io/usage/minimum-iam-policies/) + +::: ### 1. Prepare your Workstation diff --git a/docs/en/installation/install-rancher-on-k8s/chart-options/chart-options.md b/docs/en/installation/install-rancher-on-k8s/chart-options/chart-options.md index 4436fcfe473..65d0288c77a 100644 --- a/docs/en/installation/install-rancher-on-k8s/chart-options/chart-options.md +++ b/docs/en/installation/install-rancher-on-k8s/chart-options/chart-options.md @@ -120,7 +120,11 @@ See [TLS settings]({{}}/rancher/v2.6/en/installation/resources/tls-sett By default Rancher server will detect and import the `local` cluster it's running on. User with access to the `local` cluster will essentially have "root" access to all the clusters managed by Rancher server. -> **Important:** If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner. +:::caution + +If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner. + +::: If this is a concern in your environment you can set this option to "false" on your initial install. @@ -181,7 +185,11 @@ We recommend configuring your load balancer as a Layer 4 balancer, forwarding pl You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the `--set tls=external` option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer. -> **Note:** If you are using a Private CA signed certificate, add `--set privateCA=true` and see [Adding TLS Secrets - Using a Private CA Signed Certificate]({{}}/rancher/v2.6/en/installation/resources/tls-secrets/) to add the CA cert for Rancher. +:::note + +If you are using a Private CA signed certificate, add `--set privateCA=true` and see [Adding TLS Secrets - Using a Private CA Signed Certificate]({{}}/rancher/v2.6/en/installation/resources/tls-secrets/) to add the CA cert for Rancher. + +::: Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly. @@ -217,7 +225,11 @@ Rancher will respond `200` to health checks on the `/healthz` endpoint. This NGINX configuration is tested on NGINX 1.14. -> **Note:** This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). +:::caution + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). + +::: - Replace `IP_NODE1`, `IP_NODE2` and `IP_NODE3` with the IP addresses of the nodes in your cluster. - Replace both occurrences of `FQDN` to the DNS name for Rancher. diff --git a/docs/en/installation/install-rancher-on-k8s/gke/gke.md b/docs/en/installation/install-rancher-on-k8s/gke/gke.md index 1c84eb38083..f830ed263d9 100644 --- a/docs/en/installation/install-rancher-on-k8s/gke/gke.md +++ b/docs/en/installation/install-rancher-on-k8s/gke/gke.md @@ -70,7 +70,7 @@ To install `gcloud` and `kubectl`, perform the following steps: - Using gcloud config, to individually set your project ID, zone, and region. {{% tabs %}} -{{% tab "Using gloud init" %}} +{{% tab "Using gcloud init" %}} 1. Run gcloud init and follow the directions: diff --git a/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md b/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md index fd46576cf20..6d29281ebc1 100644 --- a/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md +++ b/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md @@ -15,10 +15,13 @@ Rancher has to be started with the lower/previous version after a rollback. A restore is performed by creating a Restore custom resource. -> **Important** -> -> * Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.]({{}}/rancher/v2.6/en/backups/migrating-rancher) -> * While restoring Rancher on the same setup, the Rancher deployment is manually scaled down before the restore starts, then the operator will scale it back up once the restore completes. As a result, Rancher and its UI will be unavailable until the restore is complete. While the UI is unavailable, use the original cluster kubeconfig with the restore YAML file: `kubectl create -f restore.yaml`. +:::note Important: + +* Follow the instructions from this page for restoring Rancher on the same cluster where it was backed up from. In order to migrate Rancher to a new cluster, follow the steps to [migrate Rancher.]({{}}/rancher/v2.6/en/backups/migrating-rancher) + +* While restoring Rancher on the same setup, the Rancher deployment is manually scaled down before the restore starts, then the operator will scale it back up once the restore completes. As a result, Rancher and its UI will be unavailable until the restore is complete. While the UI is unavailable, use the original cluster kubeconfig with the restore YAML file: `kubectl create -f restore.yaml`. + +::: ### Scale the Rancher Deployment to 0 @@ -100,7 +103,11 @@ To roll back to Rancher before v2.5, follow the procedure detailed here: [Restor For information on how to roll back Rancher installed with Docker, refer to [this page.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks) -> Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken. +:::note + +Managed clusters are authoritative for their state. This means restoring the Rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken. + +::: # Rolling Back to Rancher v2.0-v2.1 diff --git a/docs/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/air-gap-upgrade.md b/docs/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/air-gap-upgrade.md index 3b0ef16a876..0f334a5a20a 100644 --- a/docs/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/air-gap-upgrade.md +++ b/docs/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/air-gap-upgrade.md @@ -1,10 +1,14 @@ --- -title: Rendering the Helm Template in an Air Gapped Environment +title: Rendering the Helm Template in an Air-Gapped Environment shortTitle: Air Gap Upgrade weight: 1 --- -> These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/) including the prerequisites, up until step 3. Upgrade Rancher. +:::note + +These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/) including the prerequisites, up until step 3. Upgrade Rancher. + +::: ### Rancher Helm Template Options @@ -74,9 +78,13 @@ kubectl -n cattle-system apply -R -f ./rancher Log into Rancher to confirm that the upgrade succeeded. ->**Having network issues following upgrade?** -> -> See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). +:::tip + +Having network issues following upgrade? + +See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). + +::: # Known Upgrade Issues diff --git a/docs/en/installation/install-rancher-on-k8s/upgrades/upgrades.md b/docs/en/installation/install-rancher-on-k8s/upgrades/upgrades.md index cfe481e2b94..6ad04c5c749 100644 --- a/docs/en/installation/install-rancher-on-k8s/upgrades/upgrades.md +++ b/docs/en/installation/install-rancher-on-k8s/upgrades/upgrades.md @@ -84,8 +84,11 @@ You'll use the backup as a restore point if something goes wrong during upgrade. rancher- https://releases.rancher.com/server-charts/ ``` - > **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories]({{}}/rancher/v2.6/en/installation/resources/choosing-version/#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added. + :::note + + If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories]({{}}/rancher/v2.6/en/installation/resources/choosing-version/#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added. + ::: 1. Fetch the latest chart to install Rancher from the Helm chart repository. @@ -104,7 +107,11 @@ You'll use the backup as a restore point if something goes wrong during upgrade. This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm. -> **Air Gap Instructions:** If you are installing Rancher in an air gapped environment, skip the rest of this page and render the Helm template by following the instructions on [this page.](./air-gap-upgrade) +:::note Air Gap Instructions: + +If you are installing Rancher in an air gapped environment, skip the rest of this page and render the Helm template by following the instructions on [this page.](./air-gap-upgrade) + +::: Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed. @@ -115,7 +122,12 @@ helm get values rancher -n cattle-system hostname: rancher.my.org ``` -> **Note:** There will be more values that are listed with this command. This is just an example of one of the values. +:::note + +There will be more values that are listed with this command. This is just an example of one of the values. + +::: + If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow [Option B: Reinstalling Rancher and cert-manager.](#option-b-reinstalling-rancher-and-cert-manager) @@ -133,7 +145,11 @@ helm upgrade rancher rancher-/rancher \ --set hostname=rancher.my.org ``` -> **Note:** The above is an example, there may be more values from the previous step that need to be appended. +:::note + +The above is an example, there may be more values from the previous step that need to be appended. + +::: Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version: @@ -176,9 +192,13 @@ If you are currently running the cert-manager whose version is 1.5 or below, and Log into Rancher to confirm that the upgrade succeeded. ->**Having network issues following upgrade?** -> -> See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). +:::tip + +Having network issues following upgrade? + +See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). + +::: # Known Upgrade Issues diff --git a/docs/en/installation/other-installation-methods/air-gap/air-gap.md b/docs/en/installation/other-installation-methods/air-gap/air-gap.md index 51442964790..17315bb95a2 100644 --- a/docs/en/installation/other-installation-methods/air-gap/air-gap.md +++ b/docs/en/installation/other-installation-methods/air-gap/air-gap.md @@ -1,5 +1,5 @@ --- -title: Air Gapped Helm CLI Install +title: Air-Gapped Helm CLI Install weight: 1 --- @@ -11,7 +11,11 @@ For more information on each installation option, refer to [this page.]({{ **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation. +:::note Important: + +If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation. + +::: # Installation Outline diff --git a/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md b/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md index 97aeffdccaa..8e38a449920 100644 --- a/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md +++ b/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md @@ -16,10 +16,14 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher | `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | | `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | -> **Do you want to..**. -> -> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.6/en/installation/resources/custom-ca-root-certificate/). -> - Record all transactions with the Rancher API? See [API Auditing]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log). +:::note + +**Do you want to..** + +- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.6/en/installation/resources/custom-ca-root-certificate/). +- Record all transactions with the Rancher API? See [API Auditing]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log). + +::: Choose from the following options: @@ -55,11 +59,14 @@ docker run -d --restart=unless-stopped \ In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. -> **Prerequisites:** -> From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. -> -> - The certificate files must be in PEM format. -> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) +:::note Prerequisites: + +From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +::: After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container. @@ -94,7 +101,11 @@ docker run -d --restart=unless-stopped \ In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. -> **Prerequisite:** The certificate files must be in PEM format. +:::note Prerequisite: + +The certificate files must be in PEM format. + +::: After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. @@ -106,7 +117,11 @@ After obtaining your certificate, log into your Linux host, and then run the ins | `` | Your private registry URL and port. | | `` | The release tag of the [Rancher version]({{}}/rancher/v2.6/en/installation/resources/chart-options/) that you want to install. | -> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. +:::note + +Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +::: Privileged access is [required.](#privileged-access-for-rancher) @@ -126,5 +141,9 @@ docker run -d --restart=unless-stopped \ -> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. +:::note + +If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. + +::: diff --git a/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md b/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md index a739fd07987..8c2fceca0ce 100644 --- a/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md +++ b/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md @@ -52,7 +52,11 @@ Rancher Server is designed to be secure by default and requires SSL/TLS configur When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate. -> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). +:::note + +If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). + +::: | Configuration | Chart option | Description | Requires cert-manager | | ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | @@ -78,8 +82,11 @@ Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-yo By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. -> **Note:** -> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). +:::note + +Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + +::: ### 1. Add the cert-manager repo @@ -233,7 +240,11 @@ kubectl -n cattle-system apply -R -f ./rancher ``` The installation is complete. -> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully. +:::caution + +If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully. + +::: # Additional Resources diff --git a/docs/en/installation/other-installation-methods/air-gap/launch-kubernetes/launch-kubernetes.md b/docs/en/installation/other-installation-methods/air-gap/launch-kubernetes/launch-kubernetes.md index 5245f52e95d..8f6baeabc7e 100644 --- a/docs/en/installation/other-installation-methods/air-gap/launch-kubernetes/launch-kubernetes.md +++ b/docs/en/installation/other-installation-methods/air-gap/launch-kubernetes/launch-kubernetes.md @@ -3,7 +3,11 @@ title: '3. Install Kubernetes (Skip for Docker Installs)' weight: 300 --- -> Skip this section if you are installing Rancher on a single node with Docker. +:::note + +Skip this section if you are installing Rancher on a single node with Docker. + +::: This section describes how to install a Kubernetes cluster according to our [best practices for the Rancher server environment.]({{}}/rancher/v2.6/en/overview/architecture-recommendations/#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server. @@ -86,7 +90,11 @@ INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetok Note, take care to ensure you replace `myserver` with the IP or valid DNS of the server and replace `mynodetoken` with the node-token from the server. The node-token is on the server at `/var/lib/rancher/k3s/server/node-token` ->**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks. +:::note + +K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gapped networks. + +::: ### 4. Save and Start Using the kubeconfig File @@ -151,7 +159,11 @@ This file is an RKE configuration file, which is a configuration for the cluster Replace values in the code sample below with help of the _RKE Options_ table. Use the IP address or DNS names of the three nodes you created. -> **Tip:** For more details on the options available, see the RKE [Config Options]({{}}/rke/latest/en/config-options/). +:::tip + +For more details on the options available, see the RKE [Config Options]({{}}/rke/latest/en/config-options/). + +:::
RKE Options
@@ -200,8 +212,11 @@ rke up --config ./rancher-cluster.yml ### 4. Save Your Files -> **Important** -> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. +:::note Important: + +The files mentioned below are needed to maintain, troubleshoot, and upgrade your cluster. + +::: Save a copy of the following files in a secure location: @@ -211,7 +226,11 @@ Save a copy of the following files in a secure location: {{% /tab %}} {{% /tabs %}} -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. +:::note + +The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +::: ### Issues or errors? diff --git a/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md b/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md index 18c8817f76f..52dd83e4af2 100644 --- a/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md +++ b/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md @@ -11,11 +11,13 @@ Populating the private registry with images is the same process for installing R The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/), there are separate instructions to support the images needed. -> **Prerequisites:** -> -> You must have a [private registry](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) available to use. -> -> If the registry has certs, follow [this K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container. +:::note Prerequisites: + +You must have a [private registry](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) available to use. + +If the registry has certs, follow [this K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container. + +::: {{% tabs %}} {{% tab "Linux Only Clusters" %}} @@ -47,7 +49,11 @@ If you will use ARM64 hosts, the registry must support manifests. As of April 20 ### 2. Collect the cert-manager image -> Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer. +:::note + +Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer. + +::: In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. @@ -55,7 +61,11 @@ In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS 1. Fetch the latest `cert-manager` Helm chart and parse the template for image details: - > **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + :::note + + Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + + ::: ```plain helm repo add jetstack https://charts.jetstack.io diff --git a/docs/en/installation/other-installation-methods/air-gap/prepare-nodes/prepare-nodes.md b/docs/en/installation/other-installation-methods/air-gap/prepare-nodes/prepare-nodes.md index 19cc8159774..396d5f8c346 100644 --- a/docs/en/installation/other-installation-methods/air-gap/prepare-nodes/prepare-nodes.md +++ b/docs/en/installation/other-installation-methods/air-gap/prepare-nodes/prepare-nodes.md @@ -62,8 +62,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::note Important: + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 4. Set up the DNS Record @@ -125,8 +128,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 3. Set up the DNS Record @@ -148,9 +154,14 @@ If you need help with creating a private registry, please refer to the [official {{% /tab %}} {{% tab "Docker" %}} -> The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server. -> -> The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.]({{}}/rancher/v2.6/en/backups/migrating-rancher) + +:::note Notes: + +- The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server. + +- The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.]({{}}/rancher/v2.6/en/backups/migrating-rancher) + +::: ### 1. Set up a Linux Node From b6237a5a7fb36fe8acef43613926e339deb62f1d Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 8 Jul 2022 16:18:20 -0400 Subject: [PATCH 11/18] Updating notes --- .../install-rancher/install-rancher.md | 12 +++- .../launch-kubernetes/launch-kubernetes.md | 13 +++- .../prepare-nodes/prepare-nodes.md | 7 +- .../single-node-docker/proxy/proxy.md | 6 +- .../single-node-docker/single-node-docker.md | 62 +++++++++++------- .../single-node-rollbacks.md | 12 +++- .../single-node-upgrades.md | 65 ++++++++++++++----- .../installation/requirements/ports/ports.md | 41 ++++++++---- .../installation/requirements/requirements.md | 12 +++- .../advanced/arm64-platform/arm64-platform.md | 23 ++++--- .../single-node-install-external-lb.md | 45 ++++++++----- .../choosing-version/choosing-version.md | 22 +++++-- .../resources/feature-flags/feature-flags.md | 12 +++- .../resources/k8s-tutorials/ha-RKE/ha-RKE.md | 58 ++++++++++++----- .../ha-with-external-db.md | 15 +++-- .../ec2-node/ec2-node.md | 6 +- .../infra-for-ha-with-external-db.md | 13 +++- .../infra-for-ha/infra-for-ha.md | 13 +++- .../infra-for-rke2-ha/infra-for-rke2-ha.md | 13 +++- .../infrastructure-tutorials/nginx/nginx.md | 12 +++- .../infrastructure-tutorials/nlb/nlb.md | 6 +- docs/en/installation/resources/resources.md | 2 +- .../resources/tls-secrets/tls-secrets.md | 12 +++- .../troubleshooting/troubleshooting.md | 6 +- .../update-rancher-cert.md | 18 ++++- .../upgrading-cert-manager.md | 14 ++-- .../enable-istio-with-psp.md | 14 ++-- .../selectors-and-scrape.md | 6 +- docs/en/istio/resources/resources.md | 6 +- .../deploy-workloads/deploy-workloads.md | 6 +- .../enable-istio-in-cluster.md | 14 ++-- .../enable-istio-in-namespace.md | 12 +++- docs/en/istio/setup/setup.md | 4 +- .../istio/setup/view-traffic/view-traffic.md | 6 +- .../certificates/certificates.md | 6 +- .../k8s-in-rancher/configmaps/configmaps.md | 6 +- .../manage-hpa-with-rancher-ui.md | 12 +++- .../ingress-config/ingress-config.md | 7 +- .../load-balancers-and-ingress.md | 8 ++- .../load-balancers/load-balancers.md | 6 +- .../k8s-in-rancher/registries/registries.md | 30 +++++++-- docs/en/k8s-in-rancher/secrets/secrets.md | 28 ++++++-- .../deploy-workloads/deploy-workloads.md | 17 ++--- 43 files changed, 518 insertions(+), 190 deletions(-) diff --git a/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md b/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md index c147692a558..3f51aa8769f 100644 --- a/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md +++ b/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md @@ -5,7 +5,11 @@ weight: 300 Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through [cert-manager](https://cert-manager.io/). In a real-world use-case you will likely use Let's Encrypt or provide your own certificate. -> **Note:** These installation instructions assume you are using Helm 3. +:::note + +These installation instructions assume you are using Helm 3. + +::: ### Install cert-manager @@ -78,7 +82,11 @@ kubectl rollout status deployment -n cattle-system rancher You can now navigate to `https://rancher.example.com` and start using Rancher. -> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully. +:::caution + +If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully. + +::: ### Additional Resources diff --git a/docs/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/launch-kubernetes.md b/docs/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/launch-kubernetes.md index 41428448b27..71f7c1039d7 100644 --- a/docs/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/launch-kubernetes.md +++ b/docs/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/launch-kubernetes.md @@ -151,8 +151,11 @@ default backend - 404 ### Save Your Files -> **Important** -> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. +:::note Important: + +The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. + +::: Save a copy of the following files in a secure location: @@ -160,7 +163,11 @@ Save a copy of the following files in a secure location: - `kube_config_cluster.yml`: The [Kubeconfig file]({{}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster. - `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains the current state of the cluster including the RKE configuration and the certificates. -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. +:::note + +The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +::: ### Issues or errors? diff --git a/docs/en/installation/other-installation-methods/behind-proxy/prepare-nodes/prepare-nodes.md b/docs/en/installation/other-installation-methods/behind-proxy/prepare-nodes/prepare-nodes.md index 6d8aaf813e3..94095c6c64e 100644 --- a/docs/en/installation/other-installation-methods/behind-proxy/prepare-nodes/prepare-nodes.md +++ b/docs/en/installation/other-installation-methods/behind-proxy/prepare-nodes/prepare-nodes.md @@ -44,8 +44,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::note Important: + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 3. Set up the DNS Record diff --git a/docs/en/installation/other-installation-methods/single-node-docker/proxy/proxy.md b/docs/en/installation/other-installation-methods/single-node-docker/proxy/proxy.md index 37d3d2cfc00..58fb799bcf4 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/proxy/proxy.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/proxy/proxy.md @@ -13,7 +13,11 @@ Make sure `NO_PROXY` contains the network addresses, network address ranges and | HTTPS_PROXY | Proxy address to use when initiating HTTPS connection(s) | | NO_PROXY | Network address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s) | -> **Note** NO_PROXY must be in uppercase to use network range (CIDR) notation. +:::note Important: + +NO_PROXY must be in uppercase to use network range (CIDR) notation. + +::: ## Docker Installation diff --git a/docs/en/installation/other-installation-methods/single-node-docker/single-node-docker.md b/docs/en/installation/other-installation-methods/single-node-docker/single-node-docker.md index a52c192fe83..51196529568 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/single-node-docker.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/single-node-docker.md @@ -8,8 +8,11 @@ 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. -> **Want to use an external load balancer?** -> See [Docker Install with an External Load Balancer]({{}}/rancher/v2.6/en/installation/resources/advanced/single-node-install-external-lb) instead. +:::note Want to use an external load balancer? + +See [Docker Install with an External Load Balancer]({{}}/rancher/v2.6/en/installation/resources/advanced/single-node-install-external-lb) instead. + +::: A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: @@ -31,12 +34,14 @@ Provision a single Linux host according to our [Requirements]({{}}/ranc For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. -> **Do you want to..**. -> -> - Use a proxy? See [HTTP Proxy Configuration]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/proxy/) -> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate/) -> - Complete an Air Gap Installation? See [Air Gap: Docker Install]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/) -> - Record all transactions with the Rancher API? See [API Auditing](./advanced/#api-audit-log) +:::tip Do you want to.. + +- Use a proxy? See [HTTP Proxy Configuration]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/proxy/) +- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate/) +- Complete an Air Gap Installation? See [Air Gap: Docker Install]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/) +- Record all transactions with the Rancher API? See [API Auditing](./advanced/#api-audit-log) + +::: Choose from the following options: @@ -62,11 +67,14 @@ docker run -d --restart=unless-stopped \ ### Option B: Bring Your Own Certificate, Self-signed In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. -> **Prerequisites:** -> Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. -> -> - The certificate files must be in PEM format. -> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) +:::note Prerequisites: + +Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +::: After creating your certificate, run the Docker command below to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container. @@ -95,10 +103,12 @@ In production environments where you're exposing an app publicly, you would use The Docker install is not recommended for production. These instructions are provided for testing and development purposes only. -> **Prerequisites:** -> -> - The certificate files must be in PEM format. -> - In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) +:::note Prerequisites: + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +::: After obtaining your certificate, run the Docker command below. @@ -125,17 +135,23 @@ docker run -d --restart=unless-stopped \ ### Option D: Let's Encrypt Certificate -> **Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). +:::caution + +Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). + +::: For production environments, you also have the option of using [Let's Encrypt](https://letsencrypt.org/) certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS. The Docker install is not recommended for production. These instructions are provided for testing and development purposes only. -> **Prerequisites:** -> -> - Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network. -> - Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). -> - Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. +:::note Prerequisites: + +- Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network. +- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). +- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. + +::: After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command. diff --git a/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md b/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md index 4e27d103300..62161562653 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md @@ -37,7 +37,11 @@ You can obtain `` and `` by loggi If you have issues upgrading Rancher, roll it back to its latest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade. ->**Warning!** Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur. +:::danger + +Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur. + +::: 1. Using a remote Terminal connection, log into the node running your Rancher Server. @@ -78,7 +82,11 @@ If you have issues upgrading Rancher, roll it back to its latest known healthy s ``` Privileged access is [required.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher) - >**Note:** _Do not_ stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades. + :::note Important: + + **_Do not_** stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades. + + ::: 1. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored. diff --git a/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md b/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md index 3b03de02a22..3fd403f8d79 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md @@ -5,7 +5,11 @@ weight: 1010 The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -> **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]({{}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading. +:::note Important: + +**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]({{}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading. + +::: # Prerequisites @@ -112,7 +116,11 @@ docker pull rancher/rancher: Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container. ->**Important:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. +:::note Important: + +**_Do not_** stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. + +::: If you used a proxy, see [HTTP Proxy Configuration.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/proxy/) @@ -158,7 +166,11 @@ Privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. ->**Reminder of the Cert Prerequisite:** The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. + +::: Placeholder | Description ------------|------------- @@ -189,7 +201,11 @@ Privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include `--no-cacerts` as an argument to the container to disable the default CA certificate generated by Rancher. ->**Reminder of the Cert Prerequisite:** The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +::: Placeholder | Description ------------|------------- @@ -216,14 +232,20 @@ Privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe {{% accordion id="option-d" label="Click to expand" %}} ->**Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). +:::caution + +Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). + +::: If you have selected to use [Let's Encrypt](https://letsencrypt.org/) certificates, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher. ->**Reminder of the Cert Prerequisites:** -> ->- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). ->- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. +:::note Reminder of the Cert Prerequisites: + +- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). +- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. + +::: Placeholder | Description ------------|------------- @@ -280,7 +302,11 @@ Privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. ->**Reminder of the Prerequisite:** The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +::: Placeholder | Description ------------|------------- @@ -311,7 +337,11 @@ Privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. - >**Reminder of the Prerequisite:** The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + :::note Reminder of the Cert Prerequisite: + + The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting) + + ::: Placeholder | Description ------------|------------- @@ -321,7 +351,11 @@ Placeholder | Description `` | Your private registry URL and port. `` | The release tag of the [Rancher version]({{}}/rancher/v2.6/en/installation/resources/chart-options/) that you want to upgrade to. -> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. +:::note + +Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +::: ``` docker run -d --volumes-from rancher-data \ @@ -346,10 +380,11 @@ privileged access is [required.]({{}}/rancher/v2.6/en/installation/othe Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window. ->**Having network issues in your user clusters following upgrade?** -> -> See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). +:::note Having network issues in your user clusters following upgrade? +See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). + +::: # 6. Clean up Your Old Rancher Server Container diff --git a/docs/en/installation/requirements/ports/ports.md b/docs/en/installation/requirements/ports/ports.md index a9eaaf1bd81..d1c42d9b8dc 100644 --- a/docs/en/installation/requirements/ports/ports.md +++ b/docs/en/installation/requirements/ports/ports.md @@ -30,12 +30,14 @@ The port requirements differ based on the Rancher server architecture. Rancher can be installed on any Kubernetes cluster. For Rancher installs on a K3s, RKE, or RKE2 Kubernetes cluster, refer to the tabs below. For other Kubernetes distributions, refer to the distribution's documentation for the port requirements for cluster nodes. -> **Notes:** -> -> - Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example). -> - Kubernetes recommends TCP 30000-32767 for node port services. -> - For firewalls, traffic may need to be enabled within the cluster and pod CIDR. -> - Rancher nodes may also need outbound access to an external S3 location which is used for storing cluster backups (Minio for example). +:::note Notes: + +- Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example). +- Kubernetes recommends TCP 30000-32767 for node port services. +- For firewalls, traffic may need to be enabled within the cluster and pod CIDR. +- Rancher nodes may also need outbound access to an external S3 location which is used for storing cluster backups (Minio for example). + +::: ### Ports for Rancher Server Nodes on K3s @@ -47,7 +49,11 @@ The nodes need to be able to reach other nodes over UDP port 8472 when Flannel V If you wish to utilize the metrics server, you will need to open port 10250 on each node. -> **Important:** The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. +:::note Important: + +The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. + +::: The following tables break down the port requirements for inbound and outbound traffic: @@ -127,7 +133,11 @@ All nodes need to be able to reach other nodes over UDP port 8472 when Flannel V If you wish to utilize the metrics server, you will need to open port 10250 on each node. -**Important:** The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. +:::note Important: + +The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. + +:::
Inbound Rules for RKE2 Server Nodes
@@ -183,9 +193,11 @@ The following diagram depicts the ports that are opened for each [cluster type]( ![Basic Port Requirements]({{}}/img/rancher/port-communications.svg) ->**Tip:** -> ->If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in [Commonly Used Ports](#commonly-used-ports) as your port reference instead of the comprehensive tables below. +:::tip + +If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in [Commonly Used Ports](#commonly-used-ports) as your port reference instead of the comprehensive tables below. + +::: ### Ports for Rancher Launched Kubernetes Clusters using Node Pools @@ -193,8 +205,11 @@ The following diagram depicts the ports that are opened for each [cluster type]( The following table depicts the port requirements for [Rancher Launched Kubernetes]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) with nodes created in an [Infrastructure Provider]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/). ->**Note:** ->The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean. +:::note + +The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean. + +::: {{< ports-iaas-nodes >}} diff --git a/docs/en/installation/requirements/requirements.md b/docs/en/installation/requirements/requirements.md index affe086b066..6e8fa28184a 100644 --- a/docs/en/installation/requirements/requirements.md +++ b/docs/en/installation/requirements/requirements.md @@ -6,7 +6,11 @@ weight: 1 This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster. -> It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/) which will run your apps and services. +:::note Important: + +If you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/) which will run your apps and services. + +::: Make sure the node(s) for the Rancher server fulfill the following requirements: @@ -164,7 +168,11 @@ Rancher performance depends on etcd in the cluster performance. To ensure optima This section describes the networking requirements for the node(s) where the Rancher server is installed. -> If a server containing Rancher has the `X-Frame-Options=DENY` header, some pages in the new Rancher UI will not be able to render after upgrading from the legacy UI. This is because some legacy pages are embedded as iFrames in the new UI. +:::caution + +If a server containing Rancher has the `X-Frame-Options=DENY` header, some pages in the new Rancher UI will not be able to render after upgrading from the legacy UI. This is because some legacy pages are embedded as iFrames in the new UI. + +::: ### Node IP Addresses diff --git a/docs/en/installation/resources/advanced/arm64-platform/arm64-platform.md b/docs/en/installation/resources/advanced/arm64-platform/arm64-platform.md index 9bc042f366d..3d7e1462fff 100644 --- a/docs/en/installation/resources/advanced/arm64-platform/arm64-platform.md +++ b/docs/en/installation/resources/advanced/arm64-platform/arm64-platform.md @@ -3,9 +3,11 @@ title: "Running on ARM64 (Experimental)" weight: 3 --- -> **Important:** -> -> Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment. +:::caution: + +Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment. + +::: The following options are available when using an ARM64 platform: @@ -19,12 +21,15 @@ The following options are available when using an ARM64 platform: --privileged \ rancher/rancher:vX.Y.Z ``` -> **Note:** To check if your specific released version is compatible with the ARM64 architecture, you may navigate to your -> version's release notes in the following two ways: -> -> - Manually find your version using https://github.com/rancher/rancher/releases. -> - Go directly to your version using the tag and the specific version number. If you plan to use v2.5.8, for example, you may -> navigate to https://github.com/rancher/rancher/releases/tag/v2.5.8. +:::note + +To check if your specific released version is compatible with the ARM64 architecture, you may navigate to your +version's release notes in the following two ways: + +- Manually find your version using https://github.com/rancher/rancher/releases. +- Go directly to your version using the tag and the specific version number. If you plan to use v2.5.8, for example, you may navigate to https://github.com/rancher/rancher/releases/tag/v2.5.8. + +::: - Create custom cluster and adding ARM64 based node(s) - Kubernetes cluster version must be 1.12 or higher diff --git a/docs/en/installation/resources/advanced/single-node-install-external-lb/single-node-install-external-lb.md b/docs/en/installation/resources/advanced/single-node-install-external-lb/single-node-install-external-lb.md index 91972e9aa5f..49868054ed5 100644 --- a/docs/en/installation/resources/advanced/single-node-install-external-lb/single-node-install-external-lb.md +++ b/docs/en/installation/resources/advanced/single-node-install-external-lb/single-node-install-external-lb.md @@ -31,22 +31,27 @@ Provision a single Linux host according to our [Requirements]({{}}/ranc For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. -> **Do you want to..**. -> -> - Complete an Air Gap Installation? -> - Record all transactions with the Rancher API? -> -> See [Advanced Options](#advanced-options) below before continuing. +:::note Do you want to.. + +- Complete an Air Gap Installation? +- Record all transactions with the Rancher API? + +See [Advanced Options](#advanced-options) below before continuing. + +::: Choose from the following options: {{% accordion id="option-a" label="Option A-Bring Your Own Certificate: Self-Signed" %}} If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate. -> **Prerequisites:** -> Create a self-signed certificate. -> -> - The certificate files must be in PEM format. +:::note Prerequisites: + +Create a self-signed certificate. + +- The certificate files must be in PEM format. + +::: **To Install Rancher Using a Self-Signed Cert:** @@ -63,9 +68,11 @@ If you elect to use a self-signed certificate to encrypt communication, you must {{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Signed by Recognized CA" %}} If your cluster is public facing, it's best to use a certificate signed by a recognized CA. -> **Prerequisites:** -> -> - The certificate files must be in PEM format. +:::note Prerequisites: + +- The certificate files must be in PEM format. + +::: **To Install Rancher Using a Cert Signed by a Recognized CA:** @@ -101,7 +108,11 @@ The load balancer or proxy has to be configured to support the following: This NGINX configuration is tested on NGINX 1.14. -> **Note:** This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). +:::note + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). + +::: - Replace `rancher-server` with the IP address or hostname of the node running the Rancher container. - Replace both occurrences of `FQDN` to the DNS name for Rancher. @@ -205,7 +216,11 @@ As of Rancher v2.5, privileged access is [required.]({{}}/rancher/v2.6/ This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable). -> **Note:** This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/). +:::note + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/). + +::: ``` upstream rancher { diff --git a/docs/en/installation/resources/choosing-version/choosing-version.md b/docs/en/installation/resources/choosing-version/choosing-version.md index db2a8afef31..6186082cd08 100644 --- a/docs/en/installation/resources/choosing-version/choosing-version.md +++ b/docs/en/installation/resources/choosing-version/choosing-version.md @@ -29,7 +29,11 @@ Rancher provides several different Helm chart repositories to choose from. We al
Instructions on when to select these repos are available below in [Switching to a Different Helm Chart Repository](#switching-to-a-different-helm-chart-repository). -> **Note:** All charts in the `rancher-stable` repository will correspond with any Rancher version tagged as `stable`. +:::note + +All charts in the `rancher-stable` repository will correspond with any Rancher version tagged as `stable`. + +::: ### Helm Chart Versions @@ -46,7 +50,11 @@ To fetch a specific version of your chosen repo, define the `--version` paramete After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps. -> **Note:** Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported. +:::note + +Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported. + +::: {{< release-channel >}} @@ -87,10 +95,12 @@ Rancher Server is distributed as a Docker image, which have tags attached to the | `rancher/rancher:stable` | Our newest stable release. This tag is recommended for production. | | `rancher/rancher:` | You can install specific versions of Rancher by using the tag from a previous release. See what's available at DockerHub. | -> **Notes:** -> -> - The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported. -> - Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). Caveat: Alpha releases cannot be upgraded to or from any other release. +:::note + +- The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported. +- Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). Caveat: Alpha releases cannot be upgraded to or from any other release. + +::: {{% /tab %}} {{% /tabs %}} diff --git a/docs/en/installation/resources/feature-flags/feature-flags.md b/docs/en/installation/resources/feature-flags/feature-flags.md index 25baf0c06a2..fdc6dd1bb23 100644 --- a/docs/en/installation/resources/feature-flags/feature-flags.md +++ b/docs/en/installation/resources/feature-flags/feature-flags.md @@ -21,7 +21,11 @@ Because the API sets the actual value and the command line sets the default valu For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. -> **Note:** There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI. +:::note + +There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI. + +::: The following is a list of the feature flags available in Rancher: @@ -59,7 +63,11 @@ When you install Rancher, enable the feature you want with a feature flag. The c ### Enabling Features for Kubernetes Installs -> **Note:** Values set from the Rancher API will override the value passed in through the command line. +:::note + +Values set from the Rancher API will override the value passed in through the command line. + +::: When installing Rancher with a Helm chart, use the `--set` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list: diff --git a/docs/en/installation/resources/k8s-tutorials/ha-RKE/ha-RKE.md b/docs/en/installation/resources/k8s-tutorials/ha-RKE/ha-RKE.md index ce46ab810c0..34c133ea7d5 100644 --- a/docs/en/installation/resources/k8s-tutorials/ha-RKE/ha-RKE.md +++ b/docs/en/installation/resources/k8s-tutorials/ha-RKE/ha-RKE.md @@ -7,16 +7,23 @@ weight: 3 This section describes how to install a Kubernetes cluster. This cluster should be dedicated to run only the Rancher server. -> Rancher can run on any Kubernetes cluster, included hosted Kubernetes solutions such as Amazon EKS. The below instructions represent only one possible way to install Kubernetes. +:::note + +Rancher can run on any Kubernetes cluster, included hosted Kubernetes solutions such as Amazon EKS. The below instructions represent only one possible way to install Kubernetes. + +::: For systems without direct internet access, refer to [Air Gap: Kubernetes install.]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/) -> **Single-node Installation Tip:** -> In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. -> -> To set up a single-node RKE cluster, configure only one node in the `cluster.yml` . The single node should have all three roles: `etcd`, `controlplane`, and `worker`. -> -> In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. +:::tip Single-node Installation Tip: + +In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. + +To set up a single-node RKE cluster, configure only one node in the `cluster.yml` . The single node should have all three roles: `etcd`, `controlplane`, and `worker`. + +In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. + +::: # Installing Kubernetes @@ -75,13 +82,17 @@ ingress: | `internal_address` | no | The private DNS or IP address for internal cluster traffic | | `ssh_key_path` | no | Path to SSH private key used to authenticate to the node (defaults to `~/.ssh/id_rsa`) | -> **Advanced Configurations:** RKE has many configuration options for customizing the install to suit your specific environment. -> -> Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. -> -> For tuning your etcd cluster for larger Rancher installations, see the [etcd settings guide]({{}}/rancher/v2.6/en/installation/resources/advanced/etcd/). -> -> For more information regarding Dockershim support, refer to [this page]({{}}/rancher/v2.6/en/installation/requirements/dockershim/) +:::note Advanced Configurations: + +RKE has many configuration options for customizing the install to suit your specific environment. + +Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. + +For tuning your etcd cluster for larger Rancher installations, see the [etcd settings guide]({{}}/rancher/v2.6/en/installation/resources/advanced/etcd/). + +For more information regarding Dockershim support, refer to [this page]({{}}/rancher/v2.6/en/installation/requirements/dockershim/) + +::: ### 2. Run RKE @@ -99,7 +110,11 @@ Assuming you have installed `kubectl`, you need to place the `kubeconfig` file i When you ran `rke up`, RKE should have created a `kubeconfig` file named `kube_config_cluster.yml`. This file has the credentials for `kubectl` and `helm`. -> **Note:** If you have used a different file name from `rancher-cluster.yml`, then the kube config file will be named `kube_config_.yml`. +:::note + +If you have used a different file name from `rancher-cluster.yml`, then the kube config file will be named `kube_config_.yml`. + +::: Move this file to `$HOME/.kube/config`, or if you are working with multiple Kubernetes clusters, set the `KUBECONFIG` environmental variable to the path of `kube_config_cluster.yml`: @@ -149,8 +164,11 @@ This confirms that you have successfully installed a Kubernetes cluster that the ### 5. Save Your Files -> **Important** -> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. +:::note Important: + +The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. + +::: Save a copy of the following files in a secure location: @@ -158,7 +176,11 @@ Save a copy of the following files in a secure location: - `kube_config_cluster.yml`: The [Kubeconfig file]({{}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster. - `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains credentials for full access to the cluster.

_The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher._ -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. +:::note + +The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +::: ### Issues or errors? diff --git a/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md b/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md index bce53d8b157..68117354ecc 100644 --- a/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md +++ b/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md @@ -8,12 +8,15 @@ This section describes how to install a Kubernetes cluster according to the [bes For systems without direct internet access, refer to the air gap installation instructions. -> **Single-node Installation Tip:** -> In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. -> -> To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes. -> -> In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. +:::tip Single-node Installation Tip: + +In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. + +To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes. + +In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. + +::: # Prerequisites diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md index c4211bae501..1d25958506d 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md @@ -56,7 +56,11 @@ sudo usermod -aG docker ubuntu ``` 1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server. -> To find out whether a script is available for installing a certain Docker version, refer to this [GitHub repository,](https://github.com/rancher/install-docker) which contains all of Rancher’s Docker installation scripts. +:::tip + +To find out whether a script is available for installing a certain Docker version, refer to this [GitHub repository,](https://github.com/rancher/install-docker) which contains all of Rancher’s Docker installation scripts. + +::: **Result:** You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking. diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/infra-for-ha-with-external-db.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/infra-for-ha-with-external-db.md index 4e13afe13a8..ed15d32b80f 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/infra-for-ha-with-external-db.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/infra-for-ha-with-external-db.md @@ -9,7 +9,11 @@ The recommended infrastructure for the Rancher-only Kubernetes cluster differs d For more information about each installation option, refer to [this page.]({{}}/rancher/v2.6/en/installation) -> **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +::: To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure: @@ -53,8 +57,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 4. Set up the DNS Record diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/infra-for-ha.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/infra-for-ha.md index 6c55c72f305..5c3098e9713 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/infra-for-ha.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/infra-for-ha.md @@ -5,7 +5,11 @@ weight: 2 This tutorial is intended to help you create a high-availability RKE cluster that can be used to install a Rancher server. -> **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +::: To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure: @@ -44,8 +48,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 3. Set up the DNS Record diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha/infra-for-rke2-ha.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha/infra-for-rke2-ha.md index e03f8ccc868..a07f1c18f54 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha/infra-for-rke2-ha.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha/infra-for-rke2-ha.md @@ -7,7 +7,11 @@ This tutorial is intended to help you provision the underlying infrastructure fo The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a RKE2 Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. -> **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +:: To install the Rancher management server on a high-availability RKE2 cluster, we recommend setting up the following infrastructure: @@ -38,8 +42,11 @@ For an example showing how to set up an NGINX load balancer, refer to [this page For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/) -> **Important:** -> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: ### 4. Set up the DNS Record diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/nginx.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/nginx.md index e918b1c379b..6486c2d8b1b 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/nginx.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/nginx.md @@ -7,7 +7,11 @@ NGINX will be configured as Layer 4 load balancer (TCP) that forwards connection In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX. -One caveat: do not use one of your Rancher nodes as the load balancer. +:::note + +Do not use one of your Rancher nodes as the load balancer. + +::: > These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required. @@ -25,7 +29,11 @@ After installing NGINX, you need to update the NGINX configuration file, `nginx. 2. From `nginx.conf`, replace both occurrences (port 80 and port 443) of ``, ``, and `` with the IPs of your nodes. - > **Note:** See [NGINX Documentation: TCP and UDP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options. + :::note + + See [NGINX Documentation: TCP and UDP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options. + + :::
Example NGINX config
``` diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/nlb.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/nlb.md index 24eb4b4ca43..9644a16a306 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/nlb.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/nlb.md @@ -36,7 +36,11 @@ Regardless of whether an NGINX Ingress or Traefik Ingress controller is used, th 1. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**. 1. Click **Create target group** to create the first target group, regarding TCP port 443. -> **Note:** Health checks are handled differently based on the Ingress. For details, refer to [this section.](#health-check-paths-for-nginx-ingress-and-traefik-ingresses) +:::note + +Health checks are handled differently based on the Ingress. For details, refer to [this section.](#health-check-paths-for-nginx-ingress-and-traefik-ingresses) + +::: ### Target Group (TCP port 443) diff --git a/docs/en/installation/resources/resources.md b/docs/en/installation/resources/resources.md index 94fe05dda8c..d7c44116e0b 100644 --- a/docs/en/installation/resources/resources.md +++ b/docs/en/installation/resources/resources.md @@ -9,7 +9,7 @@ The [single-node Docker installation]({{}}/rancher/v2.6/en/installation Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. -### Air Gapped Installations +### Air-Gapped Installations Follow [these steps]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap) to install the Rancher server in an air gapped environment. diff --git a/docs/en/installation/resources/tls-secrets/tls-secrets.md b/docs/en/installation/resources/tls-secrets/tls-secrets.md index c5b79f9b37d..f64c6378cdc 100644 --- a/docs/en/installation/resources/tls-secrets/tls-secrets.md +++ b/docs/en/installation/resources/tls-secrets/tls-secrets.md @@ -18,7 +18,11 @@ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --key=tls.key ``` -> **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use. +:::note + +If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use. + +::: # Using a Private CA Signed Certificate @@ -31,7 +35,11 @@ kubectl -n cattle-system create secret generic tls-ca \ --from-file=cacerts.pem=./cacerts.pem ``` -> **Note:** The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started. +:::note + +The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started. + +::: # Updating a Private CA Certificate diff --git a/docs/en/installation/resources/troubleshooting/troubleshooting.md b/docs/en/installation/resources/troubleshooting/troubleshooting.md index 40384c2e4ae..8a2b6a45e92 100644 --- a/docs/en/installation/resources/troubleshooting/troubleshooting.md +++ b/docs/en/installation/resources/troubleshooting/troubleshooting.md @@ -71,7 +71,11 @@ kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert. -> **Note:** if you are using LetsEncrypt to issue certs it can sometimes take a few minutes to issue the cert. +:::note + +If you are using LetsEncrypt to issue certs, it can sometimes take a few minutes to issue the cert. + +::: ### Checking for issues with cert-manager issued certs (Rancher Generated or LetsEncrypt) diff --git a/docs/en/installation/resources/update-rancher-cert/update-rancher-cert.md b/docs/en/installation/resources/update-rancher-cert/update-rancher-cert.md index afb49caa9df..34eb35577d5 100644 --- a/docs/en/installation/resources/update-rancher-cert/update-rancher-cert.md +++ b/docs/en/installation/resources/update-rancher-cert/update-rancher-cert.md @@ -59,7 +59,11 @@ $ kubectl -n cattle-system create secret generic tls-ca \ ## 3. Reconfigure the Rancher deployment -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. +:::note + +Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. + +::: This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`). @@ -157,7 +161,11 @@ Fleet agents in Rancher managed clusters store kubeconfig that is used to connec # Updating from a Private CA Certificate to a Common Certificate ->It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below. +:::note + +It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below. + +::: ## 1. Create/update the certificate secret resource @@ -198,7 +206,11 @@ kubectl -n cattle-system delete secret tls-ca ## 3. Reconfigure the Rancher deployment -> Before proceeding, [generate an API token in the Rancher UI]({{}}/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys). +:::note Important: + +Before proceeding, [generate an API token in the Rancher UI]({{}}/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys). + +::: This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`). diff --git a/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md b/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md index f3b21f8aed0..5534d945794 100644 --- a/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md +++ b/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md @@ -39,8 +39,11 @@ In order to upgrade cert-manager, follow these instructions: issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` - > **Important:** - > If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + :::note Important: + + If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + + ::: 1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm) @@ -182,8 +185,11 @@ Before you can perform the upgrade, you must prepare your air gapped environment kubectl apply -f cert-manager/cert-manager-crd.yaml ``` - > **Note:** - > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + :::note Important: + + If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + + ::: 1. Create the namespace for cert-manager diff --git a/docs/en/istio/configuration-reference/enable-istio-with-psp/enable-istio-with-psp.md b/docs/en/istio/configuration-reference/enable-istio-with-psp/enable-istio-with-psp.md index d0e996a19cd..08d2db68831 100644 --- a/docs/en/istio/configuration-reference/enable-istio-with-psp/enable-istio-with-psp.md +++ b/docs/en/istio/configuration-reference/enable-istio-with-psp/enable-istio-with-psp.md @@ -7,12 +7,14 @@ If you have restrictive Pod Security Policies enabled, then Istio may not be abl The Istio CNI plugin removes the need for each application pod to have a privileged `NET_ADMIN` container. For further information, see the [Istio CNI Plugin docs](https://istio.io/docs/setup/additional-setup/cni). Please note that the [Istio CNI Plugin is in alpha](https://istio.io/about/feature-stages/). -> **Prerequisites:** -> -> - The cluster must be an RKE Kubernetes cluster. -> - The cluster must have been created with a default PodSecurityPolicy. -> -> To enable pod security policy support when creating a Kubernetes cluster in the Rancher UI, go to Advanced Options. In the Pod Security Policy Support section, click Enabled. Then select a default pod security policy. +:::note Prerequisites: + +- The cluster must be an RKE Kubernetes cluster. +- The cluster must have been created with a default PodSecurityPolicy. + +To enable pod security policy support when creating a Kubernetes cluster in the Rancher UI, go to Advanced Options. In the Pod Security Policy Support section, click Enabled. Then select a default pod security policy. + +::: 1. [Set the PodSecurityPolicy to unrestricted](#1-set-the-podsecuritypolicy-to-unrestricted) 2. [Enable the CNI](#2-enable-the-cni) diff --git a/docs/en/istio/configuration-reference/selectors-and-scrape/selectors-and-scrape.md b/docs/en/istio/configuration-reference/selectors-and-scrape/selectors-and-scrape.md index a704bf081fb..da12c344c6b 100644 --- a/docs/en/istio/configuration-reference/selectors-and-scrape/selectors-and-scrape.md +++ b/docs/en/istio/configuration-reference/selectors-and-scrape/selectors-and-scrape.md @@ -36,7 +36,11 @@ This option allows you to define which specific services or pods you would like The usability tradeoff is that you have to create the service monitor or pod monitor per namespace since you cannot monitor across namespaces. -> **Prerequisite:** Define a ServiceMonitor or PodMonitor for ``. An example ServiceMonitor is provided below. +:::note Prerequisite: + +Define a ServiceMonitor or PodMonitor for ``. An example ServiceMonitor is provided below. + +::: 1. Click **☰ > Cluster Management**. 1. Go to the cluster that you created and click **Explore**. diff --git a/docs/en/istio/resources/resources.md b/docs/en/istio/resources/resources.md index bb40d0fc6b5..e45edd50f53 100644 --- a/docs/en/istio/resources/resources.md +++ b/docs/en/istio/resources/resources.md @@ -9,7 +9,11 @@ The CPU and memory allocations for each component are [configurable.](#configuri Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio. -> **Tip:** In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component. +:::tip + +In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component. + +::: The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each core Istio component. diff --git a/docs/en/istio/setup/deploy-workloads/deploy-workloads.md b/docs/en/istio/setup/deploy-workloads/deploy-workloads.md index cf91f928e8c..c2a7d2fbc5b 100644 --- a/docs/en/istio/setup/deploy-workloads/deploy-workloads.md +++ b/docs/en/istio/setup/deploy-workloads/deploy-workloads.md @@ -3,7 +3,11 @@ title: 3. Add Deployments and Services with the Istio Sidecar weight: 4 --- -> **Prerequisite:** To enable Istio for a workload, the cluster and namespace must have the Istio app installed. +:::note Prerequisite: + +To enable Istio for a workload, the cluster and namespace must have the Istio app installed. + +::: Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload. diff --git a/docs/en/istio/setup/enable-istio-in-cluster/enable-istio-in-cluster.md b/docs/en/istio/setup/enable-istio-in-cluster/enable-istio-in-cluster.md index 62ab5e95d28..8d2771b4418 100644 --- a/docs/en/istio/setup/enable-istio-in-cluster/enable-istio-in-cluster.md +++ b/docs/en/istio/setup/enable-istio-in-cluster/enable-istio-in-cluster.md @@ -3,12 +3,14 @@ title: 1. Enable Istio in the Cluster weight: 1 --- ->**Prerequisites:** -> ->- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster. ->- If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/enable-istio-with-psp) ->- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/rke2/) ->- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/canal-and-project-network) +:::note Prerequisites: + +- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster. +- If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/enable-istio-with-psp) +- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/rke2/) +- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.]({{}}/rancher/v2.6/en/istio/configuration-reference/canal-and-project-network) + +::: 1. Click **☰ > Cluster Management**. 1. Go to the where you want to enable Istio and click **Explore**. diff --git a/docs/en/istio/setup/enable-istio-in-namespace/enable-istio-in-namespace.md b/docs/en/istio/setup/enable-istio-in-namespace/enable-istio-in-namespace.md index 1c2b8e46baf..4ebf10ad23b 100644 --- a/docs/en/istio/setup/enable-istio-in-namespace/enable-istio-in-namespace.md +++ b/docs/en/istio/setup/enable-istio-in-namespace/enable-istio-in-namespace.md @@ -7,7 +7,11 @@ You will need to manually enable Istio in each namespace that you want to be tra This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection. -> **Prerequisite:** To enable Istio in a namespace, the cluster must have Istio installed. +:::note Prerequisite: + +To enable Istio in a namespace, the cluster must have Istio installed. + +::: 1. Click **☰ > Cluster Management**. 1. Go to the cluster that you created and click **Explore**. @@ -39,7 +43,11 @@ To add the annotation to a workload, **Result:** The Istio sidecar will not be injected into the workload. -> **NOTE:** If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. +:::note + +If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. + +::: ### [Next: Add Deployments with the Istio Sidecar ]({{}}/rancher/v2.6/en/istio/setup/deploy-workloads) \ No newline at end of file diff --git a/docs/en/istio/setup/setup.md b/docs/en/istio/setup/setup.md index 27c126a8d77..5d4ff8d8e36 100644 --- a/docs/en/istio/setup/setup.md +++ b/docs/en/istio/setup/setup.md @@ -18,7 +18,9 @@ The workloads and services that you want to be controlled by Istio must meet [Is # Install -> **Quick Setup** If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway]({{}}/rancher/v2.6/en/istio/setup/gateway) and [setting up Istio's components for traffic management.]({{}}/rancher/v2.6/en/istio/setup/set-up-traffic-management) +:::tip Quick Setup Tip: If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway]({{}}/rancher/v2.6/en/istio/setup/gateway) and [setting up Istio's components for traffic management.]({{}}/rancher/v2.6/en/istio/setup/set-up-traffic-management) + +::: 1. [Enable Istio in the cluster.]({{}}/rancher/v2.6/en/istio/setup/enable-istio-in-cluster) 1. [Enable Istio in all the namespaces where you want to use it.]({{}}/rancher/v2.6/en/istio/setup/enable-istio-in-namespace) diff --git a/docs/en/istio/setup/view-traffic/view-traffic.md b/docs/en/istio/setup/view-traffic/view-traffic.md index 0c1b5597b15..620e3ef9644 100644 --- a/docs/en/istio/setup/view-traffic/view-traffic.md +++ b/docs/en/istio/setup/view-traffic/view-traffic.md @@ -9,7 +9,11 @@ This section describes how to view the traffic that is being managed by Istio. The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you are able to view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other. ->**Prerequisite:** To enable traffic to show up in the graph, ensure you have prometheus installed in the cluster. Rancher-istio installs Kiali configured by default to work with the rancher-monitoring chart. You can use rancher-monitoring or install your own monitoring solution. Optional: you can change configuration on how data scraping occurs by setting the [Selectors & Scrape Configs]({{}}/rancher/v2.6/en/istio/configuration-reference/selectors-and-scrape) options. +:::note Prerequisites: + +To enable traffic to show up in the graph, ensure you have prometheus installed in the cluster. Rancher-istio installs Kiali configured by default to work with the rancher-monitoring chart. You can use rancher-monitoring or install your own monitoring solution. Optional: you can change configuration on how data scraping occurs by setting the [Selectors & Scrape Configs]({{}}/rancher/v2.6/en/istio/configuration-reference/selectors-and-scrape) options. + +::: To see the traffic graph, diff --git a/docs/en/k8s-in-rancher/certificates/certificates.md b/docs/en/k8s-in-rancher/certificates/certificates.md index ae8ee6911d4..277517b1ca9 100644 --- a/docs/en/k8s-in-rancher/certificates/certificates.md +++ b/docs/en/k8s-in-rancher/certificates/certificates.md @@ -6,7 +6,11 @@ weight: 3060 When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by adding the certificate to the ingress deployment. ->**Prerequisites:** You must have a TLS private key and certificate available to upload. +:::note Prerequisite: + +You must have a TLS private key and certificate available to upload. + +::: ### 1. Create a Secret diff --git a/docs/en/k8s-in-rancher/configmaps/configmaps.md b/docs/en/k8s-in-rancher/configmaps/configmaps.md index 4c4653cd2f1..23811f400ee 100644 --- a/docs/en/k8s-in-rancher/configmaps/configmaps.md +++ b/docs/en/k8s-in-rancher/configmaps/configmaps.md @@ -13,8 +13,12 @@ ConfigMaps accept key value pairs in common string formats, like config files or 1. Click **Create**. 1. Enter a **Name** for the Config Map. - >**Note:** Kubernetes classifies ConfigMaps as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace. + :::note + + Kubernetes classifies ConfigMaps as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace. + ::: + 1. Select the **Namespace** you want to add Config Map to. 1. On the **Data** tab, add a key-value pair to your ConfigMap. Add as many values as you need. You can add multiple key value pairs to the ConfigMap by copying and pasting. Alternatively, use **Read from File** to add the data. Note: If you need to store sensitive data, [use a secret]({{}}/rancher/v2.6/en/k8s-in-rancher/secrets/), not a ConfigMap. diff --git a/docs/en/k8s-in-rancher/horizontal-pod-autoscaler/manage-hpa-with-rancher-ui/manage-hpa-with-rancher-ui.md b/docs/en/k8s-in-rancher/horizontal-pod-autoscaler/manage-hpa-with-rancher-ui/manage-hpa-with-rancher-ui.md index 15514596211..8625afb3421 100644 --- a/docs/en/k8s-in-rancher/horizontal-pod-autoscaler/manage-hpa-with-rancher-ui/manage-hpa-with-rancher-ui.md +++ b/docs/en/k8s-in-rancher/horizontal-pod-autoscaler/manage-hpa-with-rancher-ui/manage-hpa-with-rancher-ui.md @@ -21,7 +21,11 @@ If you want to create HPAs that scale based on other metrics than CPU and memory 1. Click **Create** to create the HPA. -> **Result:** The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view. +:::note Result: + +The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view. + +::: ## Get HPA Metrics and Status @@ -41,4 +45,8 @@ For more detailed metrics and status of a specific HPA, click the name of the HP 1. Find the HPA which you would like to delete and click **⋮ > Delete**. 1. Click **Delete** to confirm. -> **Result:** The HPA is deleted from the current cluster. +:::note Result: + +The HPA is deleted from the current cluster. + +::: \ No newline at end of file diff --git a/docs/en/k8s-in-rancher/load-balancers-and-ingress/ingress-config/ingress-config.md b/docs/en/k8s-in-rancher/load-balancers-and-ingress/ingress-config/ingress-config.md index 7b5f1f48f13..d3655a4090b 100644 --- a/docs/en/k8s-in-rancher/load-balancers-and-ingress/ingress-config/ingress-config.md +++ b/docs/en/k8s-in-rancher/load-balancers-and-ingress/ingress-config/ingress-config.md @@ -31,7 +31,12 @@ If you use this option, ingress routes requests for a hostname to the service or 1. **Optional:** If you want specify a workload or service when a request is sent to a particular hostname path, add a **Path** for the target. For example, if you want requests for `www.mysite.com/contact-us` to be sent to a different service than `www.mysite.com`, enter `/contact-us` in the **Path** field. Typically, the first rule that you create does not include a path. 1. Enter the **Port** number that each target operates on. ### Certificates ->**Note:** You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see [Adding SSL Certificates]({{}}/rancher/v2.6/en/k8s-in-rancher/certificates/). + +:::note + +You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see [Adding SSL Certificates]({{}}/rancher/v2.6/en/k8s-in-rancher/certificates/). + +::: 1. When creating an ingress, click the **Certificates** tab. 1. Click **Add Certificate**. diff --git a/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers-and-ingress.md b/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers-and-ingress.md index 420411de1b7..7cfbbca3982 100644 --- a/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers-and-ingress.md +++ b/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers-and-ingress.md @@ -52,9 +52,11 @@ Your ingress, which creates a port of entry to your cluster similar to a load ba Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more. ->**Using Rancher in a High Availability Configuration?** -> ->Refrain from adding an Ingress to the `local` cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for _all_ clusters managed by Rancher, including the `local` cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher. +:::note Using Rancher in a High Availability Configuration? + +Refrain from adding an Ingress to the `local` cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for _all_ clusters managed by Rancher, including the `local` cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher. + +::: - For more information on how to set up ingress in Rancher, see [Ingress]({{}}/rancher/v2.6/en/k8s-in-rancher/load-balancers-and-ingress/ingress). - For complete information about ingress and ingress controllers, see the [Kubernetes Ingress Documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) diff --git a/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/load-balancers.md b/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/load-balancers.md index 9ee09220401..33046bd2639 100644 --- a/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/load-balancers.md +++ b/docs/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/load-balancers.md @@ -11,7 +11,11 @@ Layer-4 load balancer (or the external load balancer) forwards traffic to Nodepo Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single [globally managed config-map](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) can be used to expose services on NGINX or third-party ingress. -> **Note:** It is possible to deploy a cluster with a non-cloud load balancer, such as [MetalLB.](https://metallb.universe.tf/) However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE. +:::note + +It is possible to deploy a cluster with a non-cloud load balancer, such as [MetalLB.](https://metallb.universe.tf/) However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE. + +::: ### Support for Layer-4 Load Balancing diff --git a/docs/en/k8s-in-rancher/registries/registries.md b/docs/en/k8s-in-rancher/registries/registries.md index 0b075b620d0..66c67de9efe 100644 --- a/docs/en/k8s-in-rancher/registries/registries.md +++ b/docs/en/k8s-in-rancher/registries/registries.md @@ -16,7 +16,11 @@ Currently, deployments pull the private registry credentials automatically only # Creating a Registry in Namespaces ->**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. +:::note Prerequisite: + +You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. + +::: 1. In the upper left corner, click **☰ > Cluster Management**. 1. Go to the cluster where you want to add a registry and click **Explore**. @@ -25,7 +29,11 @@ Currently, deployments pull the private registry credentials automatically only 1. Click **Registry**. 1. Enter a **Name** for the registry. - >**Note:** Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + + ::: 1. Select a namespace for the registry. 1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password. @@ -39,7 +47,11 @@ Currently, deployments pull the private registry credentials automatically only # Creating a Registry in Projects ->**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. +:::note Prerequisites: + +You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. + +::: Before v2.6, secrets were required to be in a project scope. Projects are no longer required, and you may use the namespace scope instead. As a result, the Rancher UI was updated to reflect this new functionality. However, you may still create a project-scoped registry if desired. Use the following steps to do so: @@ -54,7 +66,11 @@ Before v2.6, secrets were required to be in a project scope. Projects are no lon 1. In the top navigation bar, filter to see only one project. 1. Enter a **Name** for the registry. - >**Note:** Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + + ::: 1. Select a namespace for the registry. 1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password. @@ -66,7 +82,11 @@ Before v2.6, secrets were required to be in a project scope. Projects are no lon - You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. - Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. ->**Note:** Project-scoped registries on the local cluster are only visible when a single project is selected. +:::note + +Project-scoped registries on the local cluster are only visible when a single project is selected. + +::: # Using a Private Registry diff --git a/docs/en/k8s-in-rancher/secrets/secrets.md b/docs/en/k8s-in-rancher/secrets/secrets.md index 9c7f74220ea..56bee0cda29 100644 --- a/docs/en/k8s-in-rancher/secrets/secrets.md +++ b/docs/en/k8s-in-rancher/secrets/secrets.md @@ -5,7 +5,11 @@ weight: 3062 [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets) store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs. -> This page is about secrets in general. For details on setting up a private registry, refer to the section on [registries.]({{}}/rancher/v2.6/en/k8s-in-rancher/registries) +:::note + +This page is about secrets in general. For details on setting up a private registry, refer to the section on [registries.]({{}}/rancher/v2.6/en/k8s-in-rancher/registries) + +::: When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount. @@ -21,13 +25,21 @@ Mounted secrets will be updated automatically unless they are mounted as subpath 1. Select a **Namespace** for the secret. 1. Enter a **Name** for the secret. - >**Note:** Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace. + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace. + + ::: 1. From **Data**, click **Add** to add a key-value pair. Add as many values as you need. - >**Tip:** You can add multiple key value pairs to the secret by copying and pasting. - > - > {{< img "/img/rancher/bulk-key-values.gif" "Bulk Key Value Pair Copy/Paste">}} + :::tip + + You can add multiple key value pairs to the secret by copying and pasting. + + ::: + + {{< img "/img/rancher/bulk-key-values.gif" "Bulk Key Value Pair Copy/Paste">}} 1. Click **Save**. @@ -52,7 +64,11 @@ Before v2.6, secrets were required to be in a project scope. Projects are no lon **Result:** Your secret is added to the individual project you chose. You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. ->**Note:** Project-scoped secrets on the local cluster are only visible when a single project is selected. +:::note + +Project-scoped secrets on the local cluster are only visible when a single project is selected. + +::: # What's Next? diff --git a/docs/en/k8s-in-rancher/workloads/deploy-workloads/deploy-workloads.md b/docs/en/k8s-in-rancher/workloads/deploy-workloads/deploy-workloads.md index e6032e069b2..5e04fa91b78 100644 --- a/docs/en/k8s-in-rancher/workloads/deploy-workloads/deploy-workloads.md +++ b/docs/en/k8s-in-rancher/workloads/deploy-workloads/deploy-workloads.md @@ -36,15 +36,16 @@ Deploy a workload to run an application in one or more containers. - **Scaling/Upgrade Policy** - >**Amazon Note for Volumes:** - > - > To mount an Amazon EBS volume: - > - >- In [Amazon AWS](https://aws.amazon.com/), the nodes must be in the same Availability Zone and possess IAM permissions to attach/unattach volumes. - > - >- The cluster must be using the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws) option. For more information on enabling this option see [Creating an Amazon EC2 Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/ec2/) or [Creating a Custom Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes). - + :::note Amazon Note for Volumes: + + To mount an Amazon EBS volume: + + - In [Amazon AWS](https://aws.amazon.com/), the nodes must be in the same Availability Zone and possess IAM permissions to attach/unattach volumes. + + - The cluster must be using the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws) option. For more information on enabling this option see [Creating an Amazon EC2 Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/ec2/) or [Creating a Custom Cluster]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes). + ::: + 1. Click **Show Advanced Options** and configure: - **Command** From e1434d97172d98cd185ffe9e72c3cfc812279387 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 8 Jul 2022 18:00:56 -0400 Subject: [PATCH 12/18] Updating notes --- .../custom-resource-config/outputs/outputs.md | 6 +- .../helm-chart-options/helm-chart-options.md | 24 +++++-- docs/en/logging/migrating/migrating.md | 18 ++++- docs/en/logging/rbac/rbac.md | 6 +- docs/en/longhorn/longhorn.md | 2 +- .../advanced/alertmanager/alertmanager.md | 6 +- .../advanced/prometheus/prometheus.md | 6 +- .../prometheusrules/prometheusrules.md | 11 ++- .../configuration/configuration.md | 6 +- .../configuration/receiver/receiver.md | 16 +++-- .../configuration/route/route.md | 12 +++- .../servicemonitor-podmonitor.md | 6 +- .../dashboards/dashboards.md | 11 ++- .../enable-monitoring/enable-monitoring.md | 6 +- .../guides/persist-grafana/persist-grafana.md | 37 +++++++--- .../guides/uninstall/uninstall.md | 6 +- .../guides/enable-prom-fed/enable-prom-fed.md | 12 +++- .../prometheus-federator.md | 38 ++++++++--- .../prometheus-federator/rbac/rbac.md | 6 +- .../neuvector-integration.md | 6 +- docs/en/opa-gatekeper/opa-gatekeeper.md | 18 ++++- docs/en/overview/architecture/architecture.md | 26 +++++-- docs/en/overview/concepts/concepts.md | 6 +- docs/en/pipelines/pipelines.md | 67 +++++++++++++------ 24 files changed, 277 insertions(+), 81 deletions(-) diff --git a/docs/en/logging/custom-resource-config/outputs/outputs.md b/docs/en/logging/custom-resource-config/outputs/outputs.md index 577af052f16..93cf01c067a 100644 --- a/docs/en/logging/custom-resource-config/outputs/outputs.md +++ b/docs/en/logging/custom-resource-config/outputs/outputs.md @@ -211,7 +211,11 @@ spec: For the final example, we create an `Output` to write logs to a destination that is not supported out of the box: -> **Note on syslog** `syslog` is a supported `Output`. However, this example still provides an overview on using unsupported plugins. +:::note Note on syslog: + +`syslog` is a supported `Output`. However, this example still provides an overview on using unsupported plugins. + +::: ```yaml apiVersion: v1 diff --git a/docs/en/logging/helm-chart-options/helm-chart-options.md b/docs/en/logging/helm-chart-options/helm-chart-options.md index b05c1ff1528..bee19349e81 100644 --- a/docs/en/logging/helm-chart-options/helm-chart-options.md +++ b/docs/en/logging/helm-chart-options/helm-chart-options.md @@ -20,7 +20,11 @@ By default, Windows node logging will be enabled if the Cluster Dashboard UI is In this scenario, setting `global.cattle.windows.enabled` to `false` will disable Windows node logging on the cluster. When disabled, logs will still be collected from Linux nodes within the Windows cluster. -> Note: Currently an [issue](https://github.com/rancher/rancher/issues/32325) exists where Windows nodeAgents are not deleted when performing a `helm upgrade` after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed. +:::note + +Currently an [issue](https://github.com/rancher/rancher/issues/32325) exists where Windows nodeAgents are not deleted when performing a `helm upgrade` after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed. + +::: ### Working with a Custom Docker Root Directory @@ -38,7 +42,11 @@ You can add your own `nodeSelector` settings and add `tolerations` for additiona ### Enabling the Logging Application to Work with SELinux -> **Requirements:** Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. +:::note Requirements: + +Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +::: [Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. @@ -84,8 +92,12 @@ K3s and RKE2 Kubernetes distributions log to journald, which is the subsystem of * If `/var/log/journal` exists, then use `/var/log/journal`. * If `/var/log/journal` does not exist, then use `/run/log/journal`. -> **Note:** If any value not described above is returned, Rancher Logging will not be able to collect control plane logs. To address this issue, you will need to perform the following actions on every control plane node: +:::note Notes: -> * Set `Storage=volatile` in journald.conf. -> * Reboot your machine. -> * Set `systemdLogPath` to `/run/log/journal`. \ No newline at end of file +If any value not described above is returned, Rancher Logging will not be able to collect control plane logs. To address this issue, you will need to perform the following actions on every control plane node: + +* Set `Storage=volatile` in journald.conf. +* Reboot your machine. +* Set `systemdLogPath` to `/run/log/journal`. + +::: \ No newline at end of file diff --git a/docs/en/logging/migrating/migrating.md b/docs/en/logging/migrating/migrating.md index b0c8d2906e8..e039e3bb958 100644 --- a/docs/en/logging/migrating/migrating.md +++ b/docs/en/logging/migrating/migrating.md @@ -27,7 +27,11 @@ To install logging in Rancher v2.5+, refer to the [installation instructions]({{ In v2.5+, logging configuration in the **Cluster Dashboard**. To configure logging custom resources after the Logging application is installed, go to the left navigation bar and click **Logging**. It is from this menu option that logging for both cluster and namespace is configured. -> Note: Logging is installed on a per-cluster basis. You will need to navigate between clusters to configure logging for each cluster. +:::note + +Logging is installed on a per-cluster basis. You will need to navigate between clusters to configure logging for each cluster. + +::: There are four key concepts to understand for v2.5+ logging: @@ -51,7 +55,11 @@ There are four key concepts to understand for v2.5+ logging: To configure cluster-wide logging for v2.5+ logging, one needs to set up a `ClusterFlow`. This object defines the source of logs, any transformations or filters to be applied, and finally the `Output` (or `Outputs`) for the logs. -> Important: `ClusterFlows` must be defined within the `cattle-logging-system` namespace. `ClusterFlows` will not work if defined in any other namespace. +:::note Important: + +`ClusterFlows` must be defined within the `cattle-logging-system` namespace. `ClusterFlows` will not work if defined in any other namespace. + +::: In legacy logging, in order to collect logs from across the entire cluster, one only needed to enable cluster-level logging and define the desired `Output`. This basic approach remains in v2.5+ logging. To replicate legacy cluster-level logging, follow these steps: @@ -77,7 +85,11 @@ To collect logs from a specific namespace, follow these steps: This will result in logs from all sources in the namespace (pods) being collected and sent to the `Output` (or `Outputs`) you defined in your `Flow`. -> To collect logs from a project, repeat the above steps for every namespace within the project. Alternatively, you can label your project workloads with a common label (e.g. `project=my-project`) and use a `ClusterFlow` to collect logs from all pods matching this label. +:::note + +To collect logs from a project, repeat the above steps for every namespace within the project. Alternatively, you can label your project workloads with a common label (e.g. `project=my-project`) and use a `ClusterFlow` to collect logs from all pods matching this label. + +::: # Output Configuration In legacy logging, there are five logging destinations to choose from: Elasticsearch, Splunk, Kafka, Fluentd, and Syslog. With the exception of Syslog, all of these destinations are available in logging v2.5+. diff --git a/docs/en/logging/rbac/rbac.md b/docs/en/logging/rbac/rbac.md index 063d09d6bf0..8065e16d964 100644 --- a/docs/en/logging/rbac/rbac.md +++ b/docs/en/logging/rbac/rbac.md @@ -9,7 +9,11 @@ Rancher logging has two roles, `logging-admin` and `logging-view`. - `logging-admin` gives users full access to namespaced `Flows` and `Outputs` - `logging-view` allows users to *view* namespaced `Flows` and `Outputs`, and `ClusterFlows` and `ClusterOutputs` -> **Why choose one role over the other?** Edit access to `ClusterFlow` and `ClusterOutput` resources is powerful. Any user with it has edit access for all logs in the cluster. +:::note Why choose one role over the other? + +Edit access to `ClusterFlow` and `ClusterOutput` resources is powerful. Any user with it has edit access for all logs in the cluster. + +::: In Rancher, the cluster administrator role is the only role with full access to all `rancher-logging` resources. Cluster members are not able to edit or read any logging resources. Project owners and members have the following privileges: diff --git a/docs/en/longhorn/longhorn.md b/docs/en/longhorn/longhorn.md index fc3d2e2ac91..187bfd5d2a9 100644 --- a/docs/en/longhorn/longhorn.md +++ b/docs/en/longhorn/longhorn.md @@ -4,7 +4,7 @@ shortTitle: Longhorn Storage weight: 19 --- -[Longhorn](https://longhorn.io/) is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes. +[Longhorn](https://longhorn.io/) is a lightweight, reliable, and easy-to-use distributed block storage system for Kubernetes. Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI. You can learn more about its architecture [here.](https://longhorn.io/docs/latest/concepts/) diff --git a/docs/en/monitoring-alerting/configuration/advanced/alertmanager/alertmanager.md b/docs/en/monitoring-alerting/configuration/advanced/alertmanager/alertmanager.md index d149d442eb8..9dd2ca29608 100644 --- a/docs/en/monitoring-alerting/configuration/advanced/alertmanager/alertmanager.md +++ b/docs/en/monitoring-alerting/configuration/advanced/alertmanager/alertmanager.md @@ -7,7 +7,11 @@ It is usually not necessary to directly edit the Alertmanager custom resource. F When Receivers and Routes are updated, the monitoring application will automatically update the Alertmanager custom resource to be consistent with those changes. -> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../../how-monitoring-works/#3-how-alertmanager-works) +:::note + +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../../how-monitoring-works/#3-how-alertmanager-works) + +::: # About the Alertmanager Custom Resource diff --git a/docs/en/monitoring-alerting/configuration/advanced/prometheus/prometheus.md b/docs/en/monitoring-alerting/configuration/advanced/prometheus/prometheus.md index 3a514005498..136d58de064 100644 --- a/docs/en/monitoring-alerting/configuration/advanced/prometheus/prometheus.md +++ b/docs/en/monitoring-alerting/configuration/advanced/prometheus/prometheus.md @@ -5,7 +5,11 @@ weight: 1 It is usually not necessary to directly edit the Prometheus custom resource because the monitoring application automatically updates it based on changes to ServiceMonitors and PodMonitors. -> This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../how-monitoring-works/) +:::note + +This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../how-monitoring-works/) + +::: # About the Prometheus Custom Resource diff --git a/docs/en/monitoring-alerting/configuration/advanced/prometheusrules/prometheusrules.md b/docs/en/monitoring-alerting/configuration/advanced/prometheusrules/prometheusrules.md index a09ebe54d8e..6e4a82344ed 100644 --- a/docs/en/monitoring-alerting/configuration/advanced/prometheusrules/prometheusrules.md +++ b/docs/en/monitoring-alerting/configuration/advanced/prometheusrules/prometheusrules.md @@ -5,12 +5,19 @@ weight: 3 A PrometheusRule defines a group of Prometheus alerting and/or recording rules. -> This section assumes familiarity with how monitoring components work together. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/how-monitoring-works) +:::note +This section assumes familiarity with how monitoring components work together. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/how-monitoring-works) + +::: ### Creating PrometheusRules in the Rancher UI -> **Prerequisite:** The monitoring application needs to be installed. +:::note Prerequisite: + +The monitoring application needs to be installed. + +::: To create rule groups in the Rancher UI, diff --git a/docs/en/monitoring-alerting/configuration/configuration.md b/docs/en/monitoring-alerting/configuration/configuration.md index 876031fb4d7..c1884dc9489 100644 --- a/docs/en/monitoring-alerting/configuration/configuration.md +++ b/docs/en/monitoring-alerting/configuration/configuration.md @@ -11,7 +11,11 @@ For information on configuring custom scrape targets and rules for Prometheus, p The resource requests and limits for the monitoring application can be configured when installing `rancher-monitoring`. For more information about the default limits, see [this page.](./helm-chart-options/#configuring-resource-limits-and-requests) ->**Note:** On an idle cluster, Monitoring V2 has significantly higher CPU usage (up to 70%) as compared to Monitoring V1. To improve performance and achieve similar results as in Monitoring V1, turn off the Prometheus adapter. +:::note + +On an idle cluster, Monitoring V2 has significantly higher CPU usage (up to 70%) as compared to Monitoring V1. To improve performance and achieve similar results as in Monitoring V1, turn off the Prometheus adapter. + +::: # Prometheus Configuration diff --git a/docs/en/monitoring-alerting/configuration/receiver/receiver.md b/docs/en/monitoring-alerting/configuration/receiver/receiver.md index 3a9daaeb6ce..c005fffdb0d 100644 --- a/docs/en/monitoring-alerting/configuration/receiver/receiver.md +++ b/docs/en/monitoring-alerting/configuration/receiver/receiver.md @@ -6,7 +6,11 @@ weight: 1 The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file) Secret contains the configuration of an Alertmanager instance that sends out notifications based on alerts it receives from Prometheus. -> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/#3-how-alertmanager-works) +:::note + +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/#3-how-alertmanager-works) + +::: - [Creating Receivers in the Rancher UI](#creating-receivers-in-the-rancher-ui) - [Receiver Configuration](#receiver-configuration) @@ -25,10 +29,12 @@ The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configurati # Creating Receivers in the Rancher UI -> **Prerequisites:** -> ->- The monitoring application needs to be installed. ->- If you configured monitoring with an existing Alertmanager Secret, it must have a format that is supported by Rancher's UI. Otherwise you will only be able to make changes based on modifying the Alertmanager Secret directly. Note: We are continuing to make enhancements to what kinds of Alertmanager Configurations we can support using the Routes and Receivers UI, so please [file an issue](https://github.com/rancher/rancher/issues/new) if you have a request for a feature enhancement. +:::note Prerequisites: + +- The monitoring application needs to be installed. +- If you configured monitoring with an existing Alertmanager Secret, it must have a format that is supported by Rancher's UI. Otherwise you will only be able to make changes based on modifying the Alertmanager Secret directly. Note: We are continuing to make enhancements to what kinds of Alertmanager Configurations we can support using the Routes and Receivers UI, so please [file an issue](https://github.com/rancher/rancher/issues/new) if you have a request for a feature enhancement. + +::: To create notification receivers in the Rancher UI, diff --git a/docs/en/monitoring-alerting/configuration/route/route.md b/docs/en/monitoring-alerting/configuration/route/route.md index 4366f20a9a5..a80315dddbb 100644 --- a/docs/en/monitoring-alerting/configuration/route/route.md +++ b/docs/en/monitoring-alerting/configuration/route/route.md @@ -10,7 +10,11 @@ When a Route is changed, the Prometheus Operator regenerates the Alertmanager cu For more information about configuring routes, refer to the [official Alertmanager documentation.](https://www.prometheus.io/docs/alerting/latest/configuration/#route) -> This section assumes familiarity with how monitoring components work together. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/how-monitoring-works) +:::note + +This section assumes familiarity with how monitoring components work together. For more information, see [this section.]({{}}/rancher/v2.6/en/monitoring-alerting/how-monitoring-works) + +::: - [Route Restrictions](#route-restrictions) - [Route Configuration](#route-configuration) @@ -45,7 +49,11 @@ The route needs to refer to a [receiver](#receiver-configuration) that has alrea {{% tabs %}} {{% tab "Rancher v2.6.5+" %}} -> **Note** As of Rancher v2.6.5 `Group By` now accepts a list of strings instead of key-value pairs. See the [upstream documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#route) for details. +:::note + +As of Rancher v2.6.5, `Group By` now accepts a list of strings instead of key-value pairs. See the [upstream documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#route) for details. + +::: | Field | Default | Description | |-------|--------------|---------| diff --git a/docs/en/monitoring-alerting/configuration/servicemonitor-podmonitor/servicemonitor-podmonitor.md b/docs/en/monitoring-alerting/configuration/servicemonitor-podmonitor/servicemonitor-podmonitor.md index d2f848b6e67..696574ba6ad 100644 --- a/docs/en/monitoring-alerting/configuration/servicemonitor-podmonitor/servicemonitor-podmonitor.md +++ b/docs/en/monitoring-alerting/configuration/servicemonitor-podmonitor/servicemonitor-podmonitor.md @@ -10,7 +10,11 @@ These configuration objects declaratively specify the endpoints that Prometheus ServiceMonitors are more commonly used than PodMonitors, and we recommend them for most use cases. -> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/) +:::note + +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/) + +::: ### ServiceMonitors diff --git a/docs/en/monitoring-alerting/dashboards/dashboards.md b/docs/en/monitoring-alerting/dashboards/dashboards.md index a6882eaba28..100796b63cf 100644 --- a/docs/en/monitoring-alerting/dashboards/dashboards.md +++ b/docs/en/monitoring-alerting/dashboards/dashboards.md @@ -30,14 +30,21 @@ For information about role-based access control for Grafana, see [this section.] When `rancher-monitoring` is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration. -> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../how-monitoring-works/#how-alertmanager-works) +:::note +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../how-monitoring-works/#how-alertmanager-works) + +::: ### Accessing the Alertmanager UI The Alertmanager UI lets you see the most recently fired alerts. -> **Prerequisite:** The `rancher-monitoring` application must be installed. +:::note Prerequisite: + +The `rancher-monitoring` application must be installed. + +::: To see the Alertmanager UI, diff --git a/docs/en/monitoring-alerting/guides/enable-monitoring/enable-monitoring.md b/docs/en/monitoring-alerting/guides/enable-monitoring/enable-monitoring.md index ec66d77aba5..715a16782f1 100644 --- a/docs/en/monitoring-alerting/guides/enable-monitoring/enable-monitoring.md +++ b/docs/en/monitoring-alerting/guides/enable-monitoring/enable-monitoring.md @@ -22,7 +22,11 @@ rkeEtcd: useLocalhost: true ``` -> **Note:** If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment. +:::note + +If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment. + +::: # Setting Resource Limits and Requests diff --git a/docs/en/monitoring-alerting/guides/persist-grafana/persist-grafana.md b/docs/en/monitoring-alerting/guides/persist-grafana/persist-grafana.md index 4e36acf3341..d9d3fecea3d 100644 --- a/docs/en/monitoring-alerting/guides/persist-grafana/persist-grafana.md +++ b/docs/en/monitoring-alerting/guides/persist-grafana/persist-grafana.md @@ -13,11 +13,13 @@ To allow the Grafana dashboard to persist after the Grafana instance restarts, a {{% tabs %}} {{% tab "Rancher v2.5.8+" %}} -> **Prerequisites:** -> -> - The monitoring application needs to be installed. -> - To create the persistent dashboard, you must have at least the **Manage Config Maps** Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the `monitoring-dashboard-edit` or `monitoring-dashboard-admin` Kubernetes native RBAC Roles exposed by the Monitoring chart. -> - To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.]({{}}/rancher/v2.6/en/monitoring-alerting/rbac/#users-with-rancher-cluster-manager-based-permissions) +:::note Prerequisites: + +- The monitoring application needs to be installed. +- To create the persistent dashboard, you must have at least the **Manage Config Maps** Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the `monitoring-dashboard-edit` or `monitoring-dashboard-admin` Kubernetes native RBAC Roles exposed by the Monitoring chart. +- To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.]({{}}/rancher/v2.6/en/monitoring-alerting/rbac/#users-with-rancher-cluster-manager-based-permissions) + +::: ### 1. Get the JSON model of the dashboard that you want to persist @@ -30,7 +32,12 @@ To use your own dashboard: 1. Click on the link to open Grafana. On the cluster detail page, click **Monitoring**. 1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. - > **Note:** Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart. + :::note + + Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart. + + ::: + 1. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click **JSON Model**. 1. Copy the JSON data structure that appears. @@ -84,10 +91,13 @@ Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboar {{% /tab %}} {{% tab "Rancher before v2.5.8" %}} -> **Prerequisites:** -> -> - The monitoring application needs to be installed. -> - You must have the cluster-admin ClusterRole permission. + +:::note Prerequisites: + +- The monitoring application needs to be installed. +- You must have the cluster-admin ClusterRole permission. + +::: 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you want to configure the Grafana namespace and click **Explore**. @@ -95,7 +105,12 @@ Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboar 1. Click **Grafana**. 1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. - > **Note:** Regardless of who has the password, cluster administrator permission in Rancher is still required to access the Grafana instance. + :::note + + Regardless of who has the password, cluster administrator permission in Rancher is still required to access the Grafana instance. + + ::: + 1. Go to the dashboard that you want to persist. In the top navigation menu, go to the dashboard settings by clicking the gear icon. 1. In the left navigation menu, click **JSON Model**. 1. Copy the JSON data structure that appears. diff --git a/docs/en/monitoring-alerting/guides/uninstall/uninstall.md b/docs/en/monitoring-alerting/guides/uninstall/uninstall.md index b2e8ee0a55d..66da5a42fe5 100644 --- a/docs/en/monitoring-alerting/guides/uninstall/uninstall.md +++ b/docs/en/monitoring-alerting/guides/uninstall/uninstall.md @@ -13,4 +13,8 @@ weight: 2 **Result:** `rancher-monitoring` is uninstalled. -> **Note on Persistent Grafana Dashboards:** For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster. \ No newline at end of file +:::note Persistent Grafana Dashboards: + +For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster. + +::: \ No newline at end of file diff --git a/docs/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/enable-prom-fed.md b/docs/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/enable-prom-fed.md index ae4ff801de2..963c38ea9d3 100644 --- a/docs/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/enable-prom-fed.md +++ b/docs/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/enable-prom-fed.md @@ -40,13 +40,21 @@ The following selector fields are recommended to have this value: Once this setting is turned on, you can always create ServiceMonitors or PodMonitors that are picked up by the Cluster Prometheus by adding the label `release: "rancher-monitoring"` to them, in which case they will be ignored by Project Monitoring Stacks automatically by default, even if the namespace in which those ServiceMonitors or PodMonitors reside in are not system namespaces. -> Note: If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain `cattle-monitoring-system` and `cattle-dashboards`, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the `default` namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true` to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace. +:::note + +If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain `cattle-monitoring-system` and `cattle-dashboards`, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the `default` namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true` to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace. + +::: ## Increase the CPU / memory limits of the Cluster Prometheus Depending on a cluster's setup, it's generally recommended to give a large amount of dedicated memory to the Cluster Prometheus to avoid restarts due to out-of-memory errors (OOMKilled) usually caused by churn created in the cluster that causes a large number of high cardinality metrics to be generated and ingested by Prometheus within one block of time. This is one of the reasons why the default Rancher Monitoring stack expects around 4GB of RAM to be able to operate in a normal-sized cluster. However, when introducing Project Monitoring Stacks that are all sending `/federate` requests to the same Cluster Prometheus and are reliant on the Cluster Prometheus being "up" to federate that system data on their namespaces, it's even more important that the Cluster Prometheus has an ample amount of CPU / memory assigned to it to prevent an outage that can cause data gaps across all Project Prometheis in the cluster. -> Note: There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup. +:::note + +There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup. + +::: # Install the Prometheus Federator Application diff --git a/docs/en/monitoring-alerting/prometheus-federator/prometheus-federator.md b/docs/en/monitoring-alerting/prometheus-federator/prometheus-federator.md index cc88321bee4..59592733ecc 100644 --- a/docs/en/monitoring-alerting/prometheus-federator/prometheus-federator.md +++ b/docs/en/monitoring-alerting/prometheus-federator/prometheus-federator.md @@ -11,7 +11,11 @@ Prometheus Federator, also referred to as Project Monitoring v2, deploys a Helm - Default PrometheusRules and Grafana dashboards based on the collection of community-curated resources from [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus/) - Default ServiceMonitors that watch the deployed resources -> **Important** Prometheus Federator is designed to be deployed alongside an existing Prometheus Operator deployment in a cluster that has already installed the Prometheus Operator CRDs. +:::note Important: + +Prometheus Federator is designed to be deployed alongside an existing Prometheus Operator deployment in a cluster that has already installed the Prometheus Operator CRDs. + +::: ## How does the operator work? @@ -35,18 +39,28 @@ The `spec.values` of this ProjectHelmChart's resources will correspond to the `v As a Project Operator based on [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator), Prometheus Federator has three different classifications of namespaces that the operator looks out for: 1. **Operator / System Namespace**: The namespace that the operator is deployed into (e.g., `cattle-monitoring-system`). This namespace will contain all HelmCharts and HelmReleases for all ProjectHelmCharts watched by this operator. **Only Cluster Admins should have access to this namespace.** + 2. **Project Registration Namespace (`cattle-project-`)**: The set of namespaces that the operator watches for ProjectHelmCharts within. The RoleBindings and ClusterRoleBindings that apply to this namespace will also be the source of truth for the auto-assigned RBAC created in the Project Release Namespace. For details, refer to the [RBAC page](./rbac/). **Project Owners (admin), Project Members (edit), and Read-Only Members (view) should have access to this namespace.** - > **Note:** Project Registration Namespaces will be auto-generated by the operator and imported into the Project it is tied to if `.Values.global.cattle.projectLabel` is provided, which is set to `field.cattle.io/projectId` by default. This indicates that a Project Registration Namespace should be created by the operator if at least one namespace is observed with that label. The operator will not let these namespaces be deleted unless either all namespaces with that label are gone (e.g., this is the last namespace in that project, in which case the namespace will be marked with the label `"helm.cattle.io/helm-project-operator-orphaned": "true"`, which signals that it can be deleted), or it is no longer watching that project because the project ID was provided under `.Values.helmProjectOperator.otherSystemProjectLabelValues`, which serves as a denylist for Projects. These namespaces will also never be auto-deleted to avoid destroying user data; it is recommended that users clean up these namespaces manually if desired on creating or deleting a project. + :::note Notes: + + - Project Registration Namespaces will be auto-generated by the operator and imported into the Project it is tied to if `.Values.global.cattle.projectLabel` is provided, which is set to `field.cattle.io/projectId` by default. This indicates that a Project Registration Namespace should be created by the operator if at least one namespace is observed with that label. The operator will not let these namespaces be deleted unless either all namespaces with that label are gone (e.g., this is the last namespace in that project, in which case the namespace will be marked with the label `"helm.cattle.io/helm-project-operator-orphaned": "true"`, which signals that it can be deleted), or it is no longer watching that project because the project ID was provided under `.Values.helmProjectOperator.otherSystemProjectLabelValues`, which serves as a denylist for Projects. These namespaces will also never be auto-deleted to avoid destroying user data; it is recommended that users clean up these namespaces manually if desired on creating or deleting a project. + + - If `.Values.global.cattle.projectLabel` is not provided, the Operator / System Namespace will also be the Project Registration Namespace. + + ::: - > **Note:** If `.Values.global.cattle.projectLabel` is not provided, the Operator / System Namespace will also be the Project Registration Namespace. 3. **Project Release Namespace (`cattle-project--monitoring`):** The set of namespaces that the operator deploys Project Monitoring Stacks within on behalf of a ProjectHelmChart; the operator will also automatically assign RBAC to Roles created in this namespace by the Project Monitoring Stack based on bindings found in the Project Registration Namespace. **Only Cluster Admins should have access to this namespace; Project Owners (admin), Project Members (edit), and Read-Only Members (view) will be assigned limited access to this namespace by the deployed Helm Chart and Prometheus Federator.** - > **Note:** Project Release Namespaces are automatically deployed and imported into the project whose ID is specified under `.Values.helmProjectOperator.projectReleaseNamespaces.labelValue`, which defaults to the value of `.Values.global.cattle.systemProjectId` if not specified, whenever a ProjectHelmChart is specified in a Project Registration Namespace. + :::note Notes: + + - Project Release Namespaces are automatically deployed and imported into the project whose ID is specified under `.Values.helmProjectOperator.projectReleaseNamespaces.labelValue`, which defaults to the value of `.Values.global.cattle.systemProjectId` if not specified, whenever a ProjectHelmChart is specified in a Project Registration Namespace. - > **Note:** Project Release Namespaces follow the same orphaning conventions as Project Registration Namespaces (see note above). + - Project Release Namespaces follow the same orphaning conventions as Project Registration Namespaces (see note above). - > **Note:** If `.Values.projectReleaseNamespaces.enabled` is false, the Project Release Namespace will be the same as the Project Registration Namespace. + - If `.Values.projectReleaseNamespaces.enabled` is false, the Project Release Namespace will be the same as the Project Registration Namespace. + + ::: ### Helm Resources (HelmChart, HelmRelease) @@ -54,11 +68,19 @@ On deploying a ProjectHelmChart, the Prometheus Federator will automatically cre - A HelmChart CR (managed via an embedded [k3s-io/helm-contoller](https://github.com/k3s-io/helm-controller) in the operator): This custom resource automatically creates a Job in the same namespace that triggers a `helm install`, `helm upgrade`, or `helm uninstall` depending on the change applied to the HelmChart CR. This CR is automatically updated on changes to the ProjectHelmChart (e.g., modifying the values.yaml) or changes to the underlying Project definition (e.g., adding or removing namespaces from a project). -> **Important:** If a ProjectHelmChart is not deploying or updating the underlying Project Monitoring Stack for some reason, the Job created by this resource in the Operator / System namespace should be the first place you check to see if there's something wrong with the Helm operation. However, this is generally only accessible by a **Cluster Admin.** +:::note Important: + +If a ProjectHelmChart is not deploying or updating the underlying Project Monitoring Stack for some reason, the Job created by this resource in the Operator / System namespace should be the first place you check to see if there's something wrong with the Helm operation. However, this is generally only accessible by a **Cluster Admin.** + +::: - A HelmRelease CR (managed via an embedded [rancher/helm-locker](https://github.com/rancher/helm-locker) in the operator): This custom resource automatically locks a deployed Helm release in place and automatically overwrites updates to underlying resources unless the change happens via a Helm operation (`helm install`, `helm upgrade`, or `helm uninstall` performed by the HelmChart CR). -> **Note:** HelmRelease CRs emit Kubernetes Events that detect when an underlying Helm release is being modified and locks it back to place. To view these events, you can use `kubectl describe helmrelease -n `; you can also view the logs on this operator to see when changes are detected and which resources modifications were attempted on. +:::note + +HelmRelease CRs emit Kubernetes Events that detect when an underlying Helm release is being modified and locks it back to place. To view these events, you can use `kubectl describe helmrelease -n `; you can also view the logs on this operator to see when changes are detected and which resources modifications were attempted on. + +::: Both of these resources are created for all Helm charts in the Operator / System namespaces to avoid escalation of privileges to underprivileged users. diff --git a/docs/en/monitoring-alerting/prometheus-federator/rbac/rbac.md b/docs/en/monitoring-alerting/prometheus-federator/rbac/rbac.md index d656246d982..6b1cdf652ad 100644 --- a/docs/en/monitoring-alerting/prometheus-federator/rbac/rbac.md +++ b/docs/en/monitoring-alerting/prometheus-federator/rbac/rbac.md @@ -19,7 +19,11 @@ On observing a change to one of those types of bindings, the Helm Project Operat By default, these roleRefs will correspond to `admin`, `edit`, and `view` respectively, which are the [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles). -> **Note** For Rancher RBAC users, these [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) directly correlate to the `Project Owner`, `Project Member`, and `Read-Only` default Project Role Templates. +:::note + +For Rancher RBAC users, these [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) directly correlate to the `Project Owner`, `Project Member`, and `Read-Only` default Project Role Templates. + +::: If the `roleRef` matches, the Helm Project Operator will filter the `subjects` of the binding for all Users and Groups and use that to automatically construct a RoleBinding for each Role in the Project Release Namespace with the same name as the role and the following labels: diff --git a/docs/en/neuvector-integration/neuvector-integration.md b/docs/en/neuvector-integration/neuvector-integration.md index 1c58d6e200a..534019fabb0 100644 --- a/docs/en/neuvector-integration/neuvector-integration.md +++ b/docs/en/neuvector-integration/neuvector-integration.md @@ -28,8 +28,12 @@ Some examples are as follows: - EKS: `docker` for v1.22 and below; `containerd` for v1.23 and up - GKE: `containerd` (see the [Google docs](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd) for more) - >**Note:** Only one container runtime engine may be selected at a time during installation. + :::note + + Only one container runtime engine may be selected at a time during installation. + ::: + **To navigate to and install the NeuVector chart through Cluster Tools:** 1. Click **☰ > Cluster Management**. diff --git a/docs/en/opa-gatekeper/opa-gatekeeper.md b/docs/en/opa-gatekeper/opa-gatekeeper.md index e9eee7e67c7..d8a23354324 100644 --- a/docs/en/opa-gatekeper/opa-gatekeeper.md +++ b/docs/en/opa-gatekeper/opa-gatekeeper.md @@ -24,9 +24,17 @@ OPA Gatekeeper is made available via Rancher's Helm system chart, and it is inst # Enabling OPA Gatekeeper in a Cluster -> In Rancher v2.5, the OPA Gatekeeper application was improved. The Rancher v2.4 feature can't be upgraded to the new version in Rancher v2.5. If you installed OPA Gatekeeper in Rancher v2.4, you will need to uninstall OPA Gatekeeper and its CRDs from the old UI, then reinstall it in Rancher v2.5. To uninstall the CRDs run the following command in the kubectl console `kubectl delete crd configs.config.gatekeeper.sh constrainttemplates.templates.gatekeeper.sh`. +:::note -> **Prerequisite:** Only administrators and cluster owners can enable OPA Gatekeeper. +In Rancher v2.5, the OPA Gatekeeper application was improved. The Rancher v2.4 feature can't be upgraded to the new version in Rancher v2.5. If you installed OPA Gatekeeper in Rancher v2.4, you will need to uninstall OPA Gatekeeper and its CRDs from the old UI, then reinstall it in Rancher v2.5. To uninstall the CRDs run the following command in the kubectl console `kubectl delete crd configs.config.gatekeeper.sh constrainttemplates.templates.gatekeeper.sh`. + +::: + +:::note Prerequisite: + +Only administrators and cluster owners can enable OPA Gatekeeper. + +::: The OPA Gatekeeper Helm chart can be installed from **Apps & Marketplace**. @@ -54,7 +62,11 @@ Rancher also provides the ability to create your own constraint templates by imp [Constraints](https://github.com/open-policy-agent/gatekeeper#constraints) are Kubernetes custom resources that define the scope of objects to which a specific constraint template applies to. The complete policy is defined by constraint templates and constraints together. -> **Prerequisites:** OPA Gatekeeper must be enabled in the cluster. +:::note Prerequisite: + +OPA Gatekeeper must be enabled in the cluster. + +::: To list the constraints installed, go to the left side menu under OPA Gatekeeper, and click on **Constraints**. diff --git a/docs/en/overview/architecture/architecture.md b/docs/en/overview/architecture/architecture.md index a6c09157de9..4d1e5e1e05d 100644 --- a/docs/en/overview/architecture/architecture.md +++ b/docs/en/overview/architecture/architecture.md @@ -11,7 +11,11 @@ For a list of main features of the Rancher API server, refer to the [overview se For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.6/en/overview/architecture-recommendations) -> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.6/en/overview/concepts) page. +:::note + +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.6/en/overview/concepts) page. + +::: This section covers the following topics: @@ -107,9 +111,13 @@ The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/do An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy. -> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters) to provision the cluster. The ACE is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. +:::note -> The [ACE is available for registered RKE2 and K3s clusters]({{}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#authorized-cluster-endpoint-support-for-rke2-and-k3s-clusters) as of Rancher v2.6.3. +- The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters) to provision the cluster. The ACE is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. + +- The [ACE is available for registered RKE2 and K3s clusters]({{}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#authorized-cluster-endpoint-support-for-rke2-and-k3s-clusters) as of Rancher v2.6.3. + +::: There are two main reasons why a user might need the authorized cluster endpoint: @@ -120,7 +128,11 @@ The `kube-api-auth` microservice is deployed to provide the user authentication Like the authorized cluster endpoint, the `kube-api-auth` authentication service is also only available for Rancher-launched Kubernetes clusters. -> **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint. +:::note Example scenario: + +Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint. + +::: With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`. @@ -134,7 +146,11 @@ The files mentioned below are needed to maintain, troubleshoot and upgrade your - `kube_config_cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down. - `rancher-cluster.rkestate`: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher. -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. +:::note + +The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +::: For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/kubectl/) documentation. diff --git a/docs/en/overview/concepts/concepts.md b/docs/en/overview/concepts/concepts.md index 5cd01b9460c..eab89a4bc67 100644 --- a/docs/en/overview/concepts/concepts.md +++ b/docs/en/overview/concepts/concepts.md @@ -20,7 +20,11 @@ This section covers the following topics: Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. [Docker Hub](https://hub.docker.com) is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes. ->**Note:** Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes. +:::note + +Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes. + +::: # About Kubernetes diff --git a/docs/en/pipelines/pipelines.md b/docs/en/pipelines/pipelines.md index 5c9a2e868d7..90e7dbc3361 100644 --- a/docs/en/pipelines/pipelines.md +++ b/docs/en/pipelines/pipelines.md @@ -3,12 +3,15 @@ title: Pipelines weight: 10 --- -> As of Rancher v2.5, Git-based deployment pipelines are now deprecated. We recommend handling pipelines with Rancher Continuous Delivery powered by [Fleet]({{}}/rancher/v2.6/en/deploy-across-clusters/fleet). To get to Fleet in Rancher, click ☰ > Continuous Delivery. -> ->**Notice:** -> -> - Pipelines in Kubernetes 1.21+ are no longer supported. -> - Fleet does not replace Rancher pipelines; the distinction is that Rancher pipelines are now powered by Fleet. +:::note Notes + +- As of Rancher v2.5, Git-based deployment pipelines are now deprecated. We recommend handling pipelines with Rancher Continuous Delivery powered by [Fleet]({{}}/rancher/v2.6/en/deploy-across-clusters/fleet). To get to Fleet in Rancher, click ☰ > Continuous Delivery. + +- Pipelines in Kubernetes 1.21+ are no longer supported. + +- Fleet does not replace Rancher pipelines; the distinction is that Rancher pipelines are now powered by Fleet. + +::: Rancher's pipeline provides a simple CI/CD experience. Use it to automatically checkout code, run builds or scripts, publish Docker images or catalog applications, and deploy the updated software to users. @@ -22,13 +25,17 @@ After configuring Rancher and GitHub, you can deploy containers running Jenkins - Run unit tests. - Run regression tests. ->**Note:** Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses. +:::note + +Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses. + +::: This section covers the following topics: - [Concepts](#concepts) - [How Pipelines Work](#how-pipelines-work) -- [Roles-based Access Control for Pipelines](#roles-based-access-control-for-pipelines) +[Roles-based Access Control for Pipelines](#role-based-access-control-for-pipelines) - [Setting up Pipelines](#setting-up-pipelines) - [Configure version control providers](#1-configure-version-control-providers) - [Configure repositories](#2-configure-repositories) @@ -56,7 +63,11 @@ When you configure a pipeline in one of your projects, a namespace specifically The pipeline's build engine. Because project users do not directly interact with Jenkins, it's managed and locked. - >**Note:** There is no option to use existing Jenkins deployments as the pipeline engine. + :::note + + There is no option to use existing Jenkins deployments as the pipeline engine. + + ::: - **Docker Registry:** @@ -66,9 +77,13 @@ When you configure a pipeline in one of your projects, a namespace specifically Minio storage is used to store the logs for pipeline executions. - >**Note:** The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in [data persistency for pipeline components]({{}}/rancher/v2.6/en/pipelines/storage). + :::note + + The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in [data persistency for pipeline components]({{}}/rancher/v2.6/en/pipelines/storage). -# Roles-based Access Control for Pipelines + ::: + +# Role-based Access Control for Pipelines If you can access a project, you can enable repositories to start building pipelines. @@ -80,11 +95,15 @@ Project members can only configure repositories and pipelines. ### Prerequisite -> **Prerequisite:** Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported. -> -> 1. In the upper left corner, click **☰ > Global Settings**. -> 1. Click **Feature Flags**. -> 1. Go to the `legacy` feature flag and click **⋮ > Activate**. +:::note Legacy Feature Flag: + +Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported. + +1. In the upper left corner, click **☰ > Global Settings**. +1. Click **Feature Flags**. +1. Go to the `legacy` feature flag and click **⋮ > Activate**. + +::: 1. [Configure version control providers](#1-configure-version-control-providers) 2. [Configure repositories](#2-configure-repositories) @@ -127,9 +146,13 @@ Select your provider's tab below and follow the directions. 1. If you're using GitLab for enterprise setup, select **Use a private gitlab enterprise installation**. Enter the host address of your GitLab installation. 1. Click **Authenticate**. ->**Note:** -> 1. Pipeline uses Gitlab [v4 API](https://docs.gitlab.com/ee/api/v3_to_v4.html) and the supported Gitlab version is 9.0+. -> 2. If you use GitLab 10.7+ and your Rancher setup is in a local network, enable the **Allow requests to the local network from hooks and services** option in GitLab admin settings. +:::note Notes: + +1. Pipeline uses Gitlab [v4 API](https://docs.gitlab.com/ee/api/v3_to_v4.html) and the supported Gitlab version is 9.0+. +2. If you use GitLab 10.7+ and your Rancher setup is in a local network, enable the **Allow requests to the local network from hooks and services** option in GitLab admin settings. + +::: + {{% /tab %}} {{% tab "Bitbucket Cloud" %}} @@ -253,7 +276,11 @@ Available Events: * **Pull Request**: Whenever a pull request is made to the repository, the pipeline is triggered. * **Tag**: When a tag is created in the repository, the pipeline is triggered. -> **Note:** This option doesn't exist for Rancher's [example repositories]({{}}/rancher/v2.6/en/pipelines/example-repos/). +:::note + +This option doesn't exist for Rancher's [example repositories]({{}}/rancher/v2.6/en/pipelines/example-repos/). + +::: ### Modifying the Event Triggers for the Repository From b39bb84a6499c07ecbfc058350d5791aff39a245 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 09:11:45 -0400 Subject: [PATCH 13/18] Updating notes --- docs/en/pipelines/config/config.md | 33 ++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/en/pipelines/config/config.md b/docs/en/pipelines/config/config.md index 86b10606e47..2f469245966 100644 --- a/docs/en/pipelines/config/config.md +++ b/docs/en/pipelines/config/config.md @@ -311,7 +311,11 @@ You can enable notifications to any notifiers based on the build status of a pip 1. If you don't have any existing notifiers, Rancher will provide a warning that no notifiers are set up and provide a link to be able to go to the notifiers page. Follow the [instructions]({{}}/rancher/v2.0-v2.4/en/cluster-admin/tools/notifiers) to add a notifier. If you already have notifiers, you can add them to the notification by clicking the **Add Recipient** button. - > **Note:** Notifiers are configured at a cluster level and require a different level of permissions. + :::note + + Notifiers are configured at a cluster level and require a different level of permissions. + + ::: 1. For each recipient, select which notifier type from the dropdown. Based on the type of notifier, you can use the default recipient or override the recipient with a different one. For example, if you have a notifier for _Slack_, you can update which channel to send the notification to. You can add additional notifiers by clicking **Add Recipient**. @@ -504,7 +508,11 @@ If you need to use security-sensitive information in your pipeline scripts (like Create a secret in the same project as your pipeline, or explicitly in the namespace where pipeline build pods run.
->**Note:** Secret injection is disabled on [pull request events](#triggers-and-trigger-rules). +:::note + +Secret injection is disabled on [pull request events](#triggers-and-trigger-rules). + +::: ### Configuring Secrets by UI @@ -560,11 +568,16 @@ After configuring a version control provider, there are several options that can ### Changing Pipeline Settings -> **Prerequisite:** Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported. -> -> 1. In the upper left corner, click **☰ > Global Settings**. -> 1. Click **Feature Flags**. -> 1. Go to the `legacy` feature flag and click **⋮ > Activate**. +:::note Prerequisite: + +Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy +features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported. + +1. In the upper left corner, click **☰ > Global Settings**. +1. Click **Feature Flags**. +1. Go to the `legacy` feature flag and click **⋮ > Activate**. + +::: To edit these settings: @@ -620,7 +633,11 @@ stages: memoryLimit: 1Gi ``` ->**Note:** Rancher sets default compute resources for pipeline steps except for `Build and Publish Images` and `Run Script` steps. You can override the default value by specifying compute resources in the same way. +:::note + +Rancher sets default compute resources for pipeline steps except for `Build and Publish Images` and `Run Script` steps. You can override the default value by specifying compute resources in the same way. + +::: ### Custom CA From 67499d800bf462358036799fb63582de70c05615 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 10:12:18 -0400 Subject: [PATCH 14/18] Updating notes in docu format --- .../authentication/authentication.md | 6 +++- .../rancher-adfs-setup/rancher-adfs-setup.md | 6 +++- .../authentication/okta/okta.md | 22 +++++++++--- .../authentication/openldap/openldap.md | 16 +++++---- .../ping-federate/ping-federate.md | 6 +++- .../authentication/shibboleth/shibboleth.md | 6 +++- .../authentication/user-groups/user-groups.md | 10 ++++-- .../migrating-rancher/migrating-rancher.md | 30 ++++++++++++---- .../restoring-rancher/restoring-rancher.md | 18 ++++++---- .../rke-config-references.md | 4 ++- .../volumes-and-storage/examples/nfs/nfs.md | 6 +++- .../hosted-kubernetes-clusters/cce/cce.md | 6 +++- .../hosted-kubernetes-clusters/tke/tke.md | 6 +++- .../provisioning-nutanix-clusters.md | 5 ++- .../creating-a-vm-template.md | 11 ++++-- .../install-rancher-on-k8s.md | 6 +++- .../rollbacks/rollbacks.md | 7 +++- .../install-rancher/install-rancher.md | 13 +++++-- .../populate-private-registry.md | 14 ++++++-- .../install-rancher/install-rancher.md | 6 +++- .../installation/requirements/ports/ports.md | 6 +++- .../resources/feature-flags/feature-flags.md | 6 +++- .../ha-with-external-db.md | 7 +++- .../ec2-node/ec2-node.md | 6 +++- .../upgrading-cert-manager.md | 7 ++-- .../istio/disabling-istio/disabling-istio.md | 6 +++- .../windows-clusters/windows-clusters.md | 11 ++++-- .../pipelines/example-repos/example-repos.md | 32 +++++++++++------ docs/en/pipelines/pipelines.md | 15 ++++---- docs/en/pipelines/storage/storage.md | 8 +++-- .../en/project-admin/namespaces/namespaces.md | 21 ++++++++---- .../pod-security-policies.md | 12 +++++-- .../project-members/project-members.md | 34 ++++++++++++------- .../override-namespace-default.md | 10 +++--- .../quota-type-reference.md | 6 +++- .../deployment/amazon-aws-qs/amazon-aws-qs.md | 13 +++++-- .../digital-ocean-qs/digital-ocean-qs.md | 13 +++++-- .../equinix-metal-qs/equinix-metal-qs.md | 18 ++++++---- .../deployment/google-gcp-qs/google-gcp-qs.md | 13 +++++-- .../hetzner-cloud-qs/hetzner-cloud-qs.md | 13 +++++-- .../microsoft-azure-qs/microsoft-azure-qs.md | 13 +++++-- .../quickstart-vagrant/quickstart-vagrant.md | 6 +++- .../en/quick-start-guide/quick-start-guide.md | 8 +++-- .../hardening-guides/hardening-guides.md | 8 +++-- .../rke-1.6-benchmark-2.6.md | 6 +++- .../rke-1.6-hardening-2.6.md | 18 ++++++++-- .../rke2-1.6-benchmark-2.6.md | 6 +++- .../rke2-1.6-hardening-2.6.md | 23 ++++++++++--- docs/en/security/selinux/selinux.md | 12 +++++-- docs/en/troubleshooting/dns/dns.md | 6 +++- .../expired-webhook-certificates.md | 6 +++- .../imported-clusters/imported-clusters.md | 6 +++- .../controlplane/etcd.md | 6 +++- .../troubleshooting/networking/networking.md | 6 +++- docs/en/user-settings/api-keys/api-keys.md | 6 +++- .../node-templates/node-templates.md | 6 +++- 56 files changed, 457 insertions(+), 146 deletions(-) diff --git a/docs/en/admin-settings/authentication/authentication.md b/docs/en/admin-settings/authentication/authentication.md index 66a270b2264..4e11c9f3665 100644 --- a/docs/en/admin-settings/authentication/authentication.md +++ b/docs/en/admin-settings/authentication/authentication.md @@ -35,7 +35,11 @@ In most cases, you should use an external authentication service over local auth Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control]({{}}/rancher/v2.6/en/admin-settings/rbac/). -> **Note:** Local authentication does not support creating or managing groups. +:::note + +Local authentication does not support creating or managing groups. + +::: For more information, see [Users and Groups]({{}}/rancher/v2.6/en/admin-settings/authentication/user-groups/) 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 47ecea1e0a6..1ed5ae53f32 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 @@ -44,8 +44,12 @@ After you complete [Configuring Microsoft AD FS for Rancher]({{}}/ranch -**Tip:** You can generate a certificate using an openssl command. For example: +:::tip + +You can generate a certificate using an openssl command. For example: ``` 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/docs/en/admin-settings/authentication/okta/okta.md b/docs/en/admin-settings/authentication/okta/okta.md index 919bb90cd41..f099f0b8661 100644 --- a/docs/en/admin-settings/authentication/okta/okta.md +++ b/docs/en/admin-settings/authentication/okta/okta.md @@ -5,8 +5,11 @@ weight: 1210 If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. ->**Note:** Okta integration only supports Service Provider initiated logins. +:::note +Okta integration only supports Service Provider initiated logins. + +::: ## Prerequisites In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help. @@ -33,18 +36,27 @@ Setting | Value | Private Key / Certificate | A key/certificate pair used for Assertion Encryption. | | Metadata XML | The `Identity Provider metadata` file that you find in the application `Sign On` section. | - >**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.crt + :::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.crt + ``` + ::: 1. After you complete the **Configure Okta Account** form, click **Enable**. Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration. - >**Note:** If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize. + :::note + + If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize. + ::: + **Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins. {{< saml_caveats >}} diff --git a/docs/en/admin-settings/authentication/openldap/openldap.md b/docs/en/admin-settings/authentication/openldap/openldap.md index dd722903236..ddeb7c2fd52 100644 --- a/docs/en/admin-settings/authentication/openldap/openldap.md +++ b/docs/en/admin-settings/authentication/openldap/openldap.md @@ -28,9 +28,11 @@ Configure the settings for the OpenLDAP server, groups and users. For help filli Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful. -> **Note:** -> -> The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step. +:::note + +The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step. + +::: 1. Enter the **username** and **password** for the OpenLDAP account that should be mapped to the local principal account. 2. Click **Authenticate With OpenLDAP** to test the OpenLDAP connection and finalise the setup. @@ -40,9 +42,11 @@ Once you have completed the configuration, proceed by testing the connection to - OpenLDAP authentication is configured. - The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account. -> **Note:** -> -> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. +:::note + +You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. + +::: ## Annex: Troubleshooting diff --git a/docs/en/admin-settings/authentication/ping-federate/ping-federate.md b/docs/en/admin-settings/authentication/ping-federate/ping-federate.md index 484b0a1610c..f61b55eb786 100644 --- a/docs/en/admin-settings/authentication/ping-federate/ping-federate.md +++ b/docs/en/admin-settings/authentication/ping-federate/ping-federate.md @@ -45,8 +45,12 @@ Note that these URLs will not return valid data until the authentication configu Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity 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 PingIdentity. Your users can now sign into Rancher using their PingIdentity logins. {{< saml_caveats >}} diff --git a/docs/en/admin-settings/authentication/shibboleth/shibboleth.md b/docs/en/admin-settings/authentication/shibboleth/shibboleth.md index f5ff30298e7..914abb72577 100644 --- a/docs/en/admin-settings/authentication/shibboleth/shibboleth.md +++ b/docs/en/admin-settings/authentication/shibboleth/shibboleth.md @@ -65,8 +65,12 @@ If your organization uses Shibboleth for user authentication, you can configure Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth 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 Shibboleth. Your users can now sign into Rancher using their Shibboleth logins. ### SAML Provider Caveats diff --git a/docs/en/admin-settings/authentication/user-groups/user-groups.md b/docs/en/admin-settings/authentication/user-groups/user-groups.md index f82c58a3935..11ed02f1afb 100644 --- a/docs/en/admin-settings/authentication/user-groups/user-groups.md +++ b/docs/en/admin-settings/authentication/user-groups/user-groups.md @@ -40,8 +40,11 @@ To change these settings, 1. In the upper left corner, click **☰ > Global Settings**. 1. Go to the setting you want to configure and click **⋮ > Edit Setting**. -> **Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI. +:::note +Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI. + +::: ### Manually Refreshing User Information If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users. @@ -51,8 +54,11 @@ If you are not sure the last time Rancher performed an automatic refresh of user **Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to. ->**Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI. +:::note +Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI. + +::: ## Session Length diff --git a/docs/en/backups/migrating-rancher/migrating-rancher.md b/docs/en/backups/migrating-rancher/migrating-rancher.md index 5b5e4f3acdd..c2c9d8f6ca7 100644 --- a/docs/en/backups/migrating-rancher/migrating-rancher.md +++ b/docs/en/backups/migrating-rancher/migrating-rancher.md @@ -9,7 +9,11 @@ If you are migrating Rancher to a new Kubernetes cluster, you don't need to inst These instructions assume you have [created a backup](../back-up-rancher) and you have already installed a new Kubernetes cluster where Rancher will be deployed. ->**Warning:** It is required to use the same hostname that was set as the server URL in the first cluster. If not done, downstream clusters will show as unavailable in the cluster management page of the UI, and you won't be able to click inside the cluster or on the cluster's Explore button. +:::caution + +It is required to use the same hostname that was set as the server URL in the first cluster. If not done, downstream clusters will show as unavailable in the cluster management page of the UI, and you won't be able to click inside the cluster or on the cluster's Explore button. + +::: Rancher version must be v2.5.0 and up @@ -34,16 +38,24 @@ For an **air-gapped environment**, use the option below to pull the `backup-rest ### 2. Restore from backup using a Restore custom resource ->**Important:** Kubernetes v1.22, available as an experimental feature of v2.6.3, does not support restoring from backup files containing CRDs with the apiVersion `apiextensions.k8s.io/v1beta1`. In v1.22, the default `resourceSet` in the rancher-backup app is updated to collect only CRDs that use `apiextensions.k8s.io/v1`. There are currently two ways to work around this issue: -> +:::note Important: + +Kubernetes v1.22, available as an experimental feature of v2.6.3, does not support restoring from backup files containing CRDs with the apiVersion `apiextensions.k8s.io/v1beta1`. In v1.22, the default `resourceSet` in the rancher-backup app is updated to collect only CRDs that use `apiextensions.k8s.io/v1`. There are currently two ways to work around this issue: + 1. Update the default `resourceSet` to collect the CRDs with the apiVersion v1. 1. Update the default `resourceSet` and the client to use the new APIs internally, with `apiextensions.k8s.io/v1` as the replacement. -> -> - Note that when making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different. + +- Note that when making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different. + +::: If you are using an S3 store as the backup source and need to use your S3 credentials for restore, create a secret in this cluster using your S3 credentials. The Secret data must have two keys - `accessKey` and `secretKey` - that contain the S3 credentials. -**Warning:** The values `accessKey` and `secretKey` in the example below must be base64-encoded first when creating the object directly. If not encoded first, the pasted values will cause errors when you are attempting to backup or restore. +:::caution + +The values `accessKey` and `secretKey` in the example below must be base64-encoded first when creating the object directly. If not encoded first, the pasted values will cause errors when you are attempting to backup or restore. + +::: ```yaml apiVersion: v1 @@ -82,7 +94,11 @@ spec: endpoint: s3.us-west-2.amazonaws.com ``` ->**Important:** The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the Secret containing the encryption config file. If you only have the encryption config file, but don't have a secret created with it in this cluster, use the following steps to create the secret: +:::note Important: + +The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the Secret containing the encryption config file. If you only have the encryption config file, but don't have a secret created with it in this cluster, use the following steps to create the secret: + +::: 1. The encryption configuration file must be named `encryption-provider-config.yaml`, and the `--from-file` flag must be used to create this secret. So save your `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: ``` diff --git a/docs/en/backups/restoring-rancher/restoring-rancher.md b/docs/en/backups/restoring-rancher/restoring-rancher.md index 2ec7691aa79..b679c5f21c6 100644 --- a/docs/en/backups/restoring-rancher/restoring-rancher.md +++ b/docs/en/backups/restoring-rancher/restoring-rancher.md @@ -5,11 +5,13 @@ weight: 2 This page outlines how to perform a restore with Rancher. -> **Important** -> -> * Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.]({{}}/rancher/v2.6/en/backups/migrating-rancher) -> * While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. -> * If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/rollbacks/) +:::note Important: + +* Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.]({{}}/rancher/v2.6/en/backups/migrating-rancher) +* While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. +* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/rollbacks/) + +::: ### Additional Steps for Rollbacks with Rancher v2.6.4+ @@ -17,7 +19,11 @@ In Rancher v2.6.4, the cluster-api module has been upgraded from v0.4.4 to v1.0. To avoid this, the Rancher resource cleanup scripts should be run **before** the restore or rollback is attempted. Specifically, two scripts have been created to assist you: one to clean up the cluster (`cleanup.sh`), and one to check for any Rancher-related resources in the cluster (`verify.sh`). Details on the cleanup script can be found in the [rancherlabs/support-tools repo](https://github.com/rancherlabs/support-tools/tree/master/rancher-cleanup). -> **Caution** Rancher will be down as the `cleanup` script runs as it deletes the resources created by rancher. +:::caution + +Rancher will be down as the `cleanup` script runs as it deletes the resources created by rancher. + +::: The additional preparations: diff --git a/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md b/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md index 4888de83817..38c1922a15a 100644 --- a/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md +++ b/docs/en/cluster-admin/editing-clusters/rke-config-reference/rke-config-references.md @@ -106,10 +106,12 @@ Out of the box, Rancher is compatible with the following network providers: - [Calico](https://docs.projectcalico.org/v3.11/introduction/) - [Weave](https://github.com/weaveworks/weave) -**Notes on Weave:** +:::note Notes on Weave: When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a [Config File]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#cluster-config-file) and the [Weave Network Plug-in Options]({{}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options). +::: + ### Project Network Isolation If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication. diff --git a/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md b/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md index 49e0d658658..3a22ba0988b 100644 --- a/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md +++ b/docs/en/cluster-admin/volumes-and-storage/examples/nfs/nfs.md @@ -44,8 +44,12 @@ To simplify the process of managing firewall rules, use NFSv4. /nfs (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) ``` - **Tip:** You can replace the IP addresses with a subnet. For example: `10.212.50.12/24` + :::tip + + You can replace the IP addresses with a subnet. For example: `10.212.50.12/24` + ::: + 1. Update the NFS table by entering the following command: ``` diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md index 2d0d16ef917..d5712c41af8 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/cce/cce.md @@ -70,7 +70,11 @@ You can access your cluster after its state is updated to **Active**. | Cluster Label | The labels for the cluster. | | Highway Subnet | This option is only supported in `BareMetal` type. It requires you to select a VPC with high network speed for the bare metal machines. | -**Note:** If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) +:::note + +If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) + +::: # Node Configuration diff --git a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md index 69681f92180..66e68655759 100644 --- a/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md +++ b/docs/en/cluster-provisioning/hosted-kubernetes-clusters/tke/tke.md @@ -59,8 +59,12 @@ When the cluster driver is finished downloading, you will be able to create Tenc | VPC | Select the VPC name that you have created in the Tencent Cloud Console. | | Container Network CIDR | Enter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16. | - **Note:** If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) + :::note + + If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0) + ::: + 7. Click `Next: Select Instance Type` to choose the instance type that will use for your TKE cluster. | Option | Description | diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/nutanix/provisioning-nutanix-clusters/provisioning-nutanix-clusters.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/nutanix/provisioning-nutanix-clusters/provisioning-nutanix-clusters.md index de2647ddced..f333463b38a 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/nutanix/provisioning-nutanix-clusters/provisioning-nutanix-clusters.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/nutanix/provisioning-nutanix-clusters/provisioning-nutanix-clusters.md @@ -22,8 +22,11 @@ For details on configuring RKE Kubernetes clusters in Rancher, refer to the [clu The following sections describe the requirements for setting up Nutanix AOS so that Rancher can provision VMs and clusters. -**Note:** The node templates are documented and tested with Nutanix AOS version 5.20.2 and 6.0.1. +:::note +The node templates are documented and tested with Nutanix AOS version 5.20.2 and 6.0.1. + +::: ### Create Credentials in Nutanix AOS Before proceeding to create a cluster, you must ensure that you have a [Nutanix Prism Central user account](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Security-Guide-v6_0:wc-user-create-wc-t.html) with admin permissions. When you set up a node template, the template will need to use these credentials. diff --git a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/creating-a-vm-template.md b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/creating-a-vm-template.md index 1ed401c2ebd..d718f33253b 100644 --- a/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/creating-a-vm-template.md +++ b/docs/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/creating-a-vm-template.md @@ -18,7 +18,11 @@ In order to leverage the template to create new VMs, Rancher has some [specific There is specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is [cloud-init](https://cloud-init.io/) for Linux and [cloudbase-init](https://cloudbase.it/cloudbase-init/) for Windows. Both of these are used for provisioning the VMs by configuring the hostname and by setting up the SSH access and the default Rancher user. Users can add additional content to these as desired if other configuration is needed. In addition, other requirements are listed below for reference. -**Note:** If you have any specific firewall rules or configuration, you will need to add this to the VM before creating a template. +:::note + +If you have any specific firewall rules or configuration, you will need to add this to the VM before creating a template. + +::: ## Linux Dependencies @@ -48,10 +52,13 @@ The list of packages that need to be installed on the template is as follows: * [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) * [Docker EE](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server#install-docker) - RKE1 Only -**Important to note: The configuration for Windows templates varies between RKE1 and RKE2:** +:::note About the configuration for Windows templates varies between RKE1 and RKE2: + - RKE1 leverages Docker, so any RKE1 templates need to have Docker EE pre-installed as well - RKE2 does not require Docker EE, and thus it does not need to be installed +::: + # Creating a Template You may either manually create your VM or you can utilize [other alternatives](#alternatives-to-manual-creation) to create your VM. diff --git a/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md b/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md index 1475548856e..d1f75d3397e 100644 --- a/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md +++ b/docs/en/installation/install-rancher-on-k8s/install-rancher-on-k8s.md @@ -112,7 +112,11 @@ There are three recommended options for the source of the certificate used for T ### 4. Install cert-manager -**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. +:::note + +New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. + +::: > You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). diff --git a/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md b/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md index 6d29281ebc1..599f5a1c18c 100644 --- a/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md +++ b/docs/en/installation/install-rancher-on-k8s/rollbacks/rollbacks.md @@ -38,7 +38,12 @@ A restore is performed by creating a Restore custom resource. 1. Click **☰ > Cluster Management**. 1. Go to the local cluster and click **Explore**. 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**. Refer [here]({{}}/rancher/v2.6/en/helm-charts/#charts) for more information. + :::note + + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps & Marketplace**. Refer [here]({{}}/rancher/v2.6/en/helm-charts/#charts) for more information. + + ::: + 1. Click **Create**. 1. Create the Restore with the form or with YAML. For help creating the Restore resource using the online form, refer to the [configuration reference]({{}}/rancher/v2.6/en/backups/configuration/restore-config) and to the [examples.]({{}}/rancher/v2.6/en/backups/examples) 1. To use the YAML editor, you can click **Create > Create from YAML.** Enter the Restore YAML. The following is an example Restore custom resource: diff --git a/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md b/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md index 8c2fceca0ce..29cb15c0c34 100644 --- a/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md +++ b/docs/en/installation/other-installation-methods/air-gap/install-rancher/install-rancher.md @@ -101,7 +101,11 @@ helm repo update Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). -**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. +:::note + +New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. + +::: ```plain helm fetch jetstack/cert-manager --version v1.7.1 @@ -222,9 +226,12 @@ kubectl create namespace cert-manager kubectl apply -f cert-manager/cert-manager-crd.yaml ``` - > **Note:** - > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + :::note + If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + + ::: + 1. Launch cert-manager. ```plain kubectl apply -R -f ./cert-manager diff --git a/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md b/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md index 52dd83e4af2..c0c8aa11c0d 100644 --- a/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md +++ b/docs/en/installation/other-installation-methods/air-gap/populate-private-registry/populate-private-registry.md @@ -57,7 +57,11 @@ Skip this step if you are using your own certificates, or if you are terminating In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. -**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. +:::note + +New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. + +::: 1. Fetch the latest `cert-manager` Helm chart and parse the template for image details: @@ -237,7 +241,13 @@ The workstation must have Docker 18.02+ in order to support manifests, which are **For Kubernetes Installs using Rancher Generated Self-Signed Certificate:** In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates. 1. Fetch the latest `cert-manager` Helm chart and parse the template for image details: - > **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + + :::note + + Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/). + + ::: + ```plain helm repo add jetstack https://charts.jetstack.io helm repo update diff --git a/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md b/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md index 3f51aa8769f..c65bbe3902b 100644 --- a/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md +++ b/docs/en/installation/other-installation-methods/behind-proxy/install-rancher/install-rancher.md @@ -27,7 +27,11 @@ kubectl create namespace cert-manager Install the CustomResourceDefinitions of cert-manager: -**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. +:::note + +New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. + +::: ``` kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml diff --git a/docs/en/installation/requirements/ports/ports.md b/docs/en/installation/requirements/ports/ports.md index d1c42d9b8dc..2408997304e 100644 --- a/docs/en/installation/requirements/ports/ports.md +++ b/docs/en/installation/requirements/ports/ports.md @@ -237,7 +237,11 @@ The following table depicts the port requirements for [hosted clusters]({{=true,=true' ``` -Note: If you are installing an alpha version, Helm requires adding the `--devel` option to the command. +:::note + +If you are installing an alpha version, Helm requires adding the `--devel` option to the command. + +::: ### Rendering the Helm Chart for Air Gap Installations diff --git a/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md b/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md index 68117354ecc..1b269fb2697 100644 --- a/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md +++ b/docs/en/installation/resources/k8s-tutorials/ha-with-external-db/ha-with-external-db.md @@ -40,7 +40,12 @@ When running the command to start the K3s Kubernetes API server, you will pass i curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z sh -s - server \ --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name" ``` - Note: The datastore endpoint can also be passed in using the environment variable `$K3S_DATASTORE_ENDPOINT`. + + :::note + + The datastore endpoint can also be passed in using the environment variable `$K3S_DATASTORE_ENDPOINT`. + + ::: 1. Repeat the same command on your second K3s server node. diff --git a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md index 1d25958506d..953e2345f01 100644 --- a/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md +++ b/docs/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/ec2-node.md @@ -36,7 +36,11 @@ If the Rancher server is installed in a single Docker container, you only need o **Result:** You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking. -**Note:** If the nodes are being used for an RKE Kubernetes cluster, install Docker on each node in the next step. For a K3s Kubernetes cluster, the nodes are now ready to install K3s. +:::note + +If the nodes are being used for an RKE Kubernetes cluster, install Docker on each node in the next step. For a K3s Kubernetes cluster, the nodes are now ready to install K3s. + +::: ### 3. Install Docker and Create User for RKE Kubernetes Cluster Nodes diff --git a/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md b/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md index 5534d945794..0ce0a8f5370 100644 --- a/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md +++ b/docs/en/installation/resources/upgrading-cert-manager/upgrading-cert-manager.md @@ -63,9 +63,12 @@ In order to upgrade cert-manager, follow these instructions: kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml ``` - > **Note:** - > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + :::note + If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + + ::: + 1. Create the namespace for cert-manager if needed ```plain diff --git a/docs/en/istio/disabling-istio/disabling-istio.md b/docs/en/istio/disabling-istio/disabling-istio.md index 57018718f62..c7956f35c70 100644 --- a/docs/en/istio/disabling-istio/disabling-istio.md +++ b/docs/en/istio/disabling-istio/disabling-istio.md @@ -17,7 +17,11 @@ To uninstall Istio, **Result:** The `rancher-istio` app in the cluster gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster. -**Note:** You can no longer disable and re-enable your Istio installation. If you would like to save your settings for a future install, view and save individual YAMLs to refer back to / reuse for future installations. +:::note + +You can no longer disable and re-enable your Istio installation. If you would like to save your settings for a future install, view and save individual YAMLs to refer back to / reuse for future installations. + +::: **Troubleshooting Uninstall:** If you didn't follow the uninstall steps, you may encounter a warning during uninstall: diff --git a/docs/en/monitoring-alerting/windows-clusters/windows-clusters.md b/docs/en/monitoring-alerting/windows-clusters/windows-clusters.md index 3a2b0e3deda..593dc3e74b0 100644 --- a/docs/en/monitoring-alerting/windows-clusters/windows-clusters.md +++ b/docs/en/monitoring-alerting/windows-clusters/windows-clusters.md @@ -43,9 +43,14 @@ To facilitate this upgrade, Rancher 2.5.8 has released a brand new Helm chart ca enabled: true as: c:\\etc\wmi-exporter\wmi-exporter.exe ``` - > **Note for Non-Default Windows Prefix Path:** If you set up the RKE cluster with a `cluster.yml` that has a non-default `win_prefix_path`, you will need to update the `masquerade.as` field with your prefix path in place of `c:\\`. - > - > For example, if you have `win_prefix_path: 'c:\host\opt\'`, then you will need to set `as: c:\host\opt\etc\wmi-exporter\wmi-exporter.exe`. + :::note Note for Non-Default Windows Prefix Path: + + - If you set up the RKE cluster with a `cluster.yml` that has a non-default `win_prefix_path`, you will need to update the `masquerade.as` field with your prefix path in place of `c:\\`. + + - For example, if you have `win_prefix_path: 'c:\host\opt\'`, then you will need to set `as: c:\host\opt\etc\wmi-exporter\wmi-exporter.exe`. + + ::: + 2. Once all your hosts have been successfully upgraded, please ensure that you deploy the Helm chart once again with default values to avoid conflicts with the following settings: ```yaml masquerade: diff --git a/docs/en/pipelines/example-repos/example-repos.md b/docs/en/pipelines/example-repos/example-repos.md index 9147e1f751b..4be1264961c 100644 --- a/docs/en/pipelines/example-repos/example-repos.md +++ b/docs/en/pipelines/example-repos/example-repos.md @@ -9,15 +9,17 @@ Rancher ships with several example repositories that you can use to familiarize - Maven - php -> **Prerequisites:** -> -> - The example repositories are only available if you have not [configured a version control provider]({{}}/rancher/v2.6/en/project-admin/pipelines). -> - Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. -> - Note that pipelines in Kubernetes 1.21+ are no longer supported. -> -> 1. In the upper left corner, click **☰ > Global Settings**. -> 1. Click **Feature Flags**. -> 1. Go to the `legacy` feature flag and click **⋮ > Activate**. +:::note Prerequisites: + +- The example repositories are only available if you have not [configured a version control provider]({{}}/rancher/v2.6/en/project-admin/pipelines). +- Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. +- Note that pipelines in Kubernetes 1.21+ are no longer supported. + + 1. In the upper left corner, click **☰ > Global Settings**. + 1. Click **Feature Flags**. + 1. Go to the `legacy` feature flag and click **⋮ > Activate**. + +::: To start using these example repositories, @@ -35,7 +37,11 @@ By default, the example pipeline repositories are disabled. Enable one (or more) 1. In the left navigation bar, click **Legacy > Project > Pipelines**. 1. In the **Pipelines** tab, click **Configure Repositories**. - >**Note:** Example repositories only display if you haven't fetched your own repos. + :::note + + Example repositories only display if you haven't fetched your own repos. + + ::: 1. Click **Enable** for one of the example repos (e.g., `https://github.com/rancher/pipeline-example-go.git`). Then click **Done**. @@ -71,8 +77,12 @@ After enabling an example repository, run the pipeline to see how it works. 1. In the left navigation bar, click **Legacy > Project > Pipelines**. 1. In the **Pipelines** tab, go to the pipeline and select the vertical **⋮ > Run**. - >**Note:** When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components. + :::note + + When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components. + ::: + **Result:** The pipeline runs. You can see the results in the logs. ### What's Next? diff --git a/docs/en/pipelines/pipelines.md b/docs/en/pipelines/pipelines.md index 90e7dbc3361..8252a6bb7fc 100644 --- a/docs/en/pipelines/pipelines.md +++ b/docs/en/pipelines/pipelines.md @@ -179,12 +179,15 @@ Select your provider's tab below and follow the directions. 1. Enter the host address of your Bitbucket server installation. 1. Click **Authenticate**. ->**Note:** -> Bitbucket server needs to do SSL verification when sending webhooks to Rancher. Please ensure that Rancher server's certificate is trusted by the Bitbucket server. There are two options: -> -> 1. Setup Rancher server with a certificate from a trusted CA. -> 1. If you're using self-signed certificates, import Rancher server's certificate to the Bitbucket server. For instructions, see the Bitbucket server documentation for [configuring self-signed certificates](https://confluence.atlassian.com/bitbucketserver/if-you-use-self-signed-certificates-938028692.html). -> +:::note + +Bitbucket server needs to do SSL verification when sending webhooks to Rancher. Please ensure that Rancher server's certificate is trusted by the Bitbucket server. There are two options: + +1. Setup Rancher server with a certificate from a trusted CA. +1. If you're using self-signed certificates, import Rancher server's certificate to the Bitbucket server. For instructions, see the Bitbucket server documentation for [configuring self-signed certificates](https://confluence.atlassian.com/bitbucketserver/if-you-use-self-signed-certificates-938028692.html). + +::: + {{% /tab %}} {{% /tabs %}} diff --git a/docs/en/pipelines/storage/storage.md b/docs/en/pipelines/storage/storage.md index 5e81c0595a2..6e052bb5146 100644 --- a/docs/en/pipelines/storage/storage.md +++ b/docs/en/pipelines/storage/storage.md @@ -7,9 +7,11 @@ The pipelines' internal Docker registry and the Minio workloads use ephemeral vo This section assumes that you understand how persistent storage works in Kubernetes. For more information, refer to the section on [how storage works.]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/how-storage-works/) ->**Prerequisites (for both parts A and B):** -> ->[Persistent volumes]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) must be available for the cluster. +:::note Prerequisites for both parts A and B: + +[Persistent volumes]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) must be available for the cluster. + +::: ### A. Configuring Persistent Data for Docker Registry diff --git a/docs/en/project-admin/namespaces/namespaces.md b/docs/en/project-admin/namespaces/namespaces.md index c7f328842ab..a7d6c18d5c4 100644 --- a/docs/en/project-admin/namespaces/namespaces.md +++ b/docs/en/project-admin/namespaces/namespaces.md @@ -20,14 +20,21 @@ Resources that you can assign directly to namespaces include: To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project. -> **Note:** If you create a namespace with `kubectl`, it may be unusable because `kubectl` doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to [create a namespace through Rancher]({{}}/rancher/v2.6/en/project-admin/namespaces) to ensure that you will have permission to access the namespace. +:::note +If you create a namespace with `kubectl`, it may be unusable because `kubectl` doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to [create a namespace through Rancher]({{}}/rancher/v2.6/en/project-admin/namespaces) to ensure that you will have permission to access the namespace. + +::: ### Creating Namespaces Create a new namespace to isolate apps and resources in a project. ->**Tip:** When working with project resources that you can assign to a namespace (i.e., [workloads]({{}}/rancher/v2.6/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{}}/rancher/v2.6/en/k8s-in-rancher/certificates/), [ConfigMaps]({{}}/rancher/v2.6/en/k8s-in-rancher/configmaps), etc.) you can create a namespace on the fly. +:::tip + +When working with project resources that you can assign to a namespace (i.e., [workloads]({{}}/rancher/v2.6/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{}}/rancher/v2.6/en/k8s-in-rancher/certificates/), [ConfigMaps]({{}}/rancher/v2.6/en/k8s-in-rancher/configmaps), etc.) you can create a namespace on the fly. + +::: 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you want to create a namespace and click **Explore**. @@ -51,11 +58,11 @@ Cluster admins and members may occasionally need to move a namespace to another 1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one. - >**Notes:** - > - >- Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking. - >- You cannot move a namespace into a project that already has a [resource quota]({{}}/rancher/v2.6/en/project-admin/resource-quotas)configured. - >- If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace. + :::note Notes: + + - Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking. + - You cannot move a namespace into a project that already has a [resource quota]({{}}/rancher/v2.6/en/project-admin/resource-quotas)configured. + - If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace. 1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**. diff --git a/docs/en/project-admin/pod-security-policies/pod-security-policies.md b/docs/en/project-admin/pod-security-policies/pod-security-policies.md index d7ce7a74ee3..faf681dbebf 100644 --- a/docs/en/project-admin/pod-security-policies/pod-security-policies.md +++ b/docs/en/project-admin/pod-security-policies/pod-security-policies.md @@ -3,7 +3,11 @@ title: Pod Security Policies weight: 5600 --- -> These cluster options are only available for [clusters in which Rancher has launched Kubernetes]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). +:::note + +These cluster options are only available for [clusters in which Rancher has launched Kubernetes]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). + +::: You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation. @@ -29,4 +33,8 @@ You can always assign a pod security policy (PSP) to an existing project if you **Result:** The PSP is applied to the project and any namespaces added to the project. ->**Note:** Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP. \ No newline at end of file +:::note + +Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP. + +::: \ No newline at end of file diff --git a/docs/en/project-admin/project-members/project-members.md b/docs/en/project-admin/project-members/project-members.md index 32708445e60..a6a639b146c 100644 --- a/docs/en/project-admin/project-members/project-members.md +++ b/docs/en/project-admin/project-members/project-members.md @@ -7,7 +7,11 @@ If you want to provide a user with access and permissions to _specific_ projects You can add members to a project as it is created, or add them to an existing project. ->**Tip:** Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/) instead. +:::tip + +Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/) instead. + +::: ### Adding Members to a New Project @@ -30,23 +34,29 @@ Following project creation, you can add users as project members so that they ca - A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in. - >**Note:** If you are logged in as a local user, external users do not display in your search results. + :::note + + If you are logged in as a local user, external users do not display in your search results. + + ::: 1. Assign the user or group **Project** roles. [What are Project Roles?]({{}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/) - >**Notes:** - > - >- 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 or delete namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. - > - >- 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. - > - >- For `Custom` roles, you can modify the list of individual roles available for assignment. - > - > - To add roles to the list, [Add a Custom Role]({{}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles). - > - To remove roles from the list, [Lock/Unlock Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles/). + :::note Notes: + + - 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 or delete namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + + - 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. + + - For `Custom` roles, you can modify the list of individual roles available for assignment. + + - To add roles to the list, [Add a Custom Role]({{}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles). + - To remove roles from the list, [Lock/Unlock Roles]({{}}/rancher/v2.6/en/admin-settings/rbac/locked-roles/). + ::: + **Result:** The chosen users are added to the project. - To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user. diff --git a/docs/en/project-admin/resource-quotas/override-namespace-default/override-namespace-default.md b/docs/en/project-admin/resource-quotas/override-namespace-default/override-namespace-default.md index cf26b09aa65..208f4788786 100644 --- a/docs/en/project-admin/resource-quotas/override-namespace-default/override-namespace-default.md +++ b/docs/en/project-admin/resource-quotas/override-namespace-default/override-namespace-default.md @@ -24,9 +24,11 @@ If there is a resource quota configured for a project, you can override the name For more information about each **Resource Type**, see [the type reference]({{}}/rancher/v2.6/en/project-admin/resource-quotas/quota-type-reference/). - >**Note:** - > - >- If a resource quota is not configured for the project, these options will not be available. - >- If you enter limits that exceed the configured project limits, Rancher will not let you save your edits. + :::note + + - If a resource quota is not configured for the project, these options will not be available. + - If you enter limits that exceed the configured project limits, Rancher will not let you save your edits. + ::: + **Result:** Your override is applied to the namespace's resource quota. diff --git a/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md b/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md index 7e5f66ed3e9..a3c9a873790 100644 --- a/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md +++ b/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md @@ -21,4 +21,8 @@ When you create a resource quota, you are configuring the pool of resources avai | Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. | | Secrets | The maximum number of secrets that can exist in the project/namespace. | ->***** When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. \ No newline at end of file +:::note Important: + +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. + +::: \ No newline at end of file diff --git a/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md b/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md index f5e80d10091..caa8533219e 100644 --- a/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md +++ b/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md @@ -5,12 +5,19 @@ weight: 100 --- The following steps will quickly deploy a Rancher server on AWS in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites ->**Note** ->Deploying to Amazon AWS will incur charges. +:::caution + +Deploying to Amazon AWS will incur charges. + +::: - [Amazon AWS Account](https://aws.amazon.com/account/): An Amazon AWS Account is required to create resources for deploying Rancher and Kubernetes. - [Amazon AWS Access Key](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html): Use this link to follow a tutorial to create an Amazon AWS Access Key if you don't have one yet. diff --git a/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md b/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md index 8afb42b9d33..6f79c04cd37 100644 --- a/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md +++ b/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md @@ -5,12 +5,19 @@ weight: 120 --- The following steps will quickly deploy a Rancher server on DigitalOcean in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites ->**Note** ->Deploying to DigitalOcean will incur charges. +:::caution + +Deploying to DigitalOcean will incur charges. + +::: - [DigitalOcean Account](https://www.digitalocean.com): You will require an account on DigitalOcean as this is where the server and cluster will run. - [DigitalOcean Access Key](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key): Use this link to create a DigitalOcean Access Key if you don't have one. diff --git a/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md b/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md index ad208bd3bf8..29844d1270a 100644 --- a/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md +++ b/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md @@ -10,7 +10,11 @@ weight: 250 - Creation of your first cluster - Deployment of an application, Nginx ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Quick Start Outline @@ -42,12 +46,14 @@ This Quick Start Guide is divided into different tasks for easier consumption. - [Equinix Metal Server Types](https://metal.equinix.com/developers/docs/servers/about/) - [Equinix Metal Pricing](https://metal.equinix.com/developers/docs/servers/server-specs/) - **Note:** - > When provisioning a new Equinix Metal Server via the CLI or API you will need to be able to provide the following information: project-id, plan, metro, and the operating-system - > When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration. - > For a full list of port requirements, refer to [Docker Installation]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/). - > Provision the host according to our [Requirements]({{}}/rancher/v2.6/en/installation/requirements/). +:::note Notes: +- When provisioning a new Equinix Metal Server via the CLI or API you will need to be able to provide the following information: project-id, plan, metro, and the operating-system +- When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration. +- For a full list of port requirements, refer to [Docker Installation]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/). +- Provision the host according to our [Requirements]({{}}/rancher/v2.6/en/installation/requirements/). + +::: ### 2. Install Rancher To install Rancher on your Equinix Metal host, connect to it and then use a shell to install. diff --git a/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md b/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md index b589f810c46..38fcf14ae7a 100644 --- a/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md +++ b/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md @@ -5,12 +5,19 @@ weight: 130 --- The following steps will quickly deploy a Rancher server on GCP in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites ->**Note** ->Deploying to Google GCP will incur charges. +:::caution + +Deploying to Google GCP will incur charges. + +::: - [Google GCP Account](https://console.cloud.google.com/): A Google GCP Account is required to create resources for deploying Rancher and Kubernetes. - [Google GCP Project](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/creating-project): Use this link to follow a tutorial to create a GCP Project if you don't have one yet. diff --git a/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md b/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md index ea7a2bbf1b8..526221d24c2 100644 --- a/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md +++ b/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md @@ -5,12 +5,19 @@ weight: 140 --- The following steps will quickly deploy a Rancher server on Hetzner Cloud in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites ->**Note** ->Deploying to Hetzner Cloud will incur charges. +:::caution + +Deploying to Hetzner Cloud will incur charges. + +::: - [Hetzner Cloud Account](https://www.hetzner.com): You will require an account on Hetzner as this is where the server and cluster will run. - [Hetzner API Access Key](https://docs.hetzner.cloud/#getting-started): Use these instructions to create a Hetzner Cloud API Key if you don't have one. diff --git a/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md b/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md index ec8d16a475e..2f1b6561362 100644 --- a/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md +++ b/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md @@ -6,12 +6,19 @@ weight: 115 The following steps will quickly deploy a Rancher server on Azure in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites ->**Note** ->Deploying to Microsoft Azure will incur charges. +:::caution + +Deploying to Microsoft Azure will incur charges. + +::: - [Microsoft Azure Account](https://azure.microsoft.com/en-us/free/): A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes. - [Microsoft Azure Subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal): Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet. diff --git a/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md b/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md index 86b3bb420c3..25423322f32 100644 --- a/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md +++ b/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md @@ -4,7 +4,11 @@ weight: 200 --- The following steps quickly deploy a Rancher Server with a single node cluster attached. ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: ## Prerequisites diff --git a/docs/en/quick-start-guide/quick-start-guide.md b/docs/en/quick-start-guide/quick-start-guide.md index b6b0ba33866..7059f429421 100644 --- a/docs/en/quick-start-guide/quick-start-guide.md +++ b/docs/en/quick-start-guide/quick-start-guide.md @@ -6,9 +6,13 @@ weight: 2 aliases: - /rancher/v2.x/en/quick-start-guide/ --- ->**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). +:::note -Howdy buckaroos! Use this section of the docs to jump start your deployment and testing of Rancher 2.x! It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future. +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). + +::: + +Use this section of the docs to jump start your deployment and testing of Rancher 2.x. It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future. We have Quick Start Guides for: diff --git a/docs/en/security/hardening-guides/hardening-guides.md b/docs/en/security/hardening-guides/hardening-guides.md index 24f10ae4b38..461b1eed92c 100644 --- a/docs/en/security/hardening-guides/hardening-guides.md +++ b/docs/en/security/hardening-guides/hardening-guides.md @@ -39,9 +39,11 @@ These guides have been tested along with the Rancher v2.6 release. Each self-ass | ------------------ | --------------------- | --------------------- | ---------------- | | Kubernetes v1.18 up to v1.23 | CIS v1.6 | [Link]({{}}/rancher/v2.6/en/security/hardening-guides/rke-1.6-benchmark-2.6) | [Link]({{}}/rancher/v2.6/en/security/hardening-guides/rke-1.6-hardening-2.6) | -> **Notes** -> -> - CIS v1.20 benchmark version for Kubernetes v1.19 and v1.20 is not yet released as a profile in Rancher's CIS Benchmark chart. +:::note + +- CIS v1.20 benchmark version for Kubernetes v1.19 and v1.20 is not yet released as a profile in Rancher's CIS Benchmark chart. + +::: ### RKE2 Guides diff --git a/docs/en/security/hardening-guides/rke-1.6-benchmark-2.6/rke-1.6-benchmark-2.6.md b/docs/en/security/hardening-guides/rke-1.6-benchmark-2.6/rke-1.6-benchmark-2.6.md index 02b68e4a0e5..2f4f1d724fa 100644 --- a/docs/en/security/hardening-guides/rke-1.6-benchmark-2.6/rke-1.6-benchmark-2.6.md +++ b/docs/en/security/hardening-guides/rke-1.6-benchmark-2.6/rke-1.6-benchmark-2.6.md @@ -31,7 +31,11 @@ Rancher and RKE install Kubernetes services via Docker containers. Configuration Where control audits differ from the original CIS benchmark, the audit commands specific to Rancher are provided for testing. When performing the tests, you will need access to the command line on the hosts of all RKE nodes. The commands also make use of the [kubectl](https://kubernetes.io/docs/tasks/tools/) (with a valid configuration file) and [jq](https://stedolan.github.io/jq/) tools, which are required in the testing and evaluation of test results. -> NOTE: Only `automated` tests (previously called `scored`) are covered in this guide. +:::note + +Only `automated` tests (previously called `scored`) are covered in this guide. + +::: ### Controls ## 1.1 Master Node Configuration Files diff --git a/docs/en/security/hardening-guides/rke-1.6-hardening-2.6/rke-1.6-hardening-2.6.md b/docs/en/security/hardening-guides/rke-1.6-hardening-2.6/rke-1.6-hardening-2.6.md index e12823a88a5..d783ac7bde0 100644 --- a/docs/en/security/hardening-guides/rke-1.6-hardening-2.6/rke-1.6-hardening-2.6.md +++ b/docs/en/security/hardening-guides/rke-1.6-hardening-2.6/rke-1.6-hardening-2.6.md @@ -7,7 +7,11 @@ aliases: This document provides prescriptive guidance for hardening a production installation of a RKE cluster to be used with Rancher v2.6. It outlines the configurations and controls required to address Kubernetes benchmark controls from the Center for Information Security (CIS). -> This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes. +:::note + +This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes. + +::: This hardening guide is intended to be used for RKE clusters and associated with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher: @@ -115,7 +119,11 @@ Network Policies are namespace scoped. When a network policy is introduced to a Once a CNI provider is enabled on a cluster a default network policy can be applied. For reference purposes a **permissive** example is provided below. If you want to allow all traffic to all pods in a namespace (even if policies are added that cause some pods to be treated as “isolated”), you can create a policy that explicitly allows all traffic in that namespace. Save the following configuration as `default-allow-all.yaml`. Additional [documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/) about network policies can be found on the Kubernetes site. -> This `NetworkPolicy` is just an example and is not recommended for production use. +:::note + +This `NetworkPolicy` is just an example and is not recommended for production use. + +::: ```yaml --- @@ -150,7 +158,11 @@ Execute this script to apply the `default-allow-all.yaml` configuration with the The reference `cluster.yml` is used by the RKE CLI that provides the configuration needed to achieve a hardened install of Rancher Kubernetes Engine (RKE). RKE install [documentation]({{}}/rke/latest/en/installation/) is provided with additional details about the configuration items. This reference `cluster.yml` does not include the required **nodes** directive which will vary depending on your environment. Documentation for node configuration in RKE can be found [here]({{}}/rke/latest/en/config-options/nodes/). -> For a Kubernetes v1.18 cluster, the configuration `spec.volumes: 'ephemeral'` should be removed from the `PodSecurityPolicy`, since it's not supported in this Kubernetes release. +:::note Important: + +For a Kubernetes v1.18 cluster, the configuration `spec.volumes: 'ephemeral'` should be removed from the `PodSecurityPolicy`, since it's not supported in this Kubernetes release. + +::: ```yaml # If you intend to deploy Kubernetes in an air-gapped environment, diff --git a/docs/en/security/hardening-guides/rke2-1.6-benchmark-2.6/rke2-1.6-benchmark-2.6.md b/docs/en/security/hardening-guides/rke2-1.6-benchmark-2.6/rke2-1.6-benchmark-2.6.md index 39c4c3409f3..76297744ffa 100644 --- a/docs/en/security/hardening-guides/rke2-1.6-benchmark-2.6/rke2-1.6-benchmark-2.6.md +++ b/docs/en/security/hardening-guides/rke2-1.6-benchmark-2.6/rke2-1.6-benchmark-2.6.md @@ -29,7 +29,11 @@ RKE2 launches control plane components as static pods, managed by the kubelet, a Where control audits differ from the original CIS benchmark, the audit commands specific to Rancher are provided for testing. When performing the tests, you will need access to the command line on the hosts of all RKE2 nodes. The commands also make use of the [kubectl](https://kubernetes.io/docs/tasks/tools/) (with a valid configuration file) and [jq](https://stedolan.github.io/jq/) tools, which are required in the testing and evaluation of test results. -> NOTE: Only `automated` tests (previously called `scored`) are covered in this guide. +:::note + +Only `automated` tests (previously called `scored`) are covered in this guide. + +::: ### Controls diff --git a/docs/en/security/hardening-guides/rke2-1.6-hardening-2.6/rke2-1.6-hardening-2.6.md b/docs/en/security/hardening-guides/rke2-1.6-hardening-2.6/rke2-1.6-hardening-2.6.md index 8ce1fe8f70e..fbc925a9fe5 100644 --- a/docs/en/security/hardening-guides/rke2-1.6-hardening-2.6/rke2-1.6-hardening-2.6.md +++ b/docs/en/security/hardening-guides/rke2-1.6-hardening-2.6/rke2-1.6-hardening-2.6.md @@ -5,7 +5,11 @@ weight: 100 This document provides prescriptive guidance for hardening a production installation of a RKE2 cluster to be provisioned with Rancher v2.6.5. It outlines the configurations and controls required to address Kubernetes benchmark controls from the Center for Information Security (CIS). -> This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes. +:::note + +This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes. + +::: This hardening guide is intended to be used for RKE2 clusters and associated with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher: @@ -40,7 +44,11 @@ To help ensure these above requirements are met, RKE2 can be started with the `p 1. Checks that host-level requirements have been met. If they haven't, RKE2 will exit with a fatal error describing the unmet requirements. 2. Configures runtime pod security policies and network policies that allow the cluster to pass associated controls. -> The profile's flag only valid values are `cis-1.5` or `cis-1.6`. It accepts a string value to allow for other profiles in the future. +:::note + +The profile's flag only valid values are `cis-1.5` or `cis-1.6`. It accepts a string value to allow for other profiles in the future. + +::: The following section outlines the specific actions that are taken when the `profile` flag is set to `cis-1.6`. @@ -54,7 +62,11 @@ This is a kubelet flag that will cause the kubelet to exit if the required kerne When the `profile` flag is set, RKE2 will set the flag to `true`. -> `protect-kernel-defaults` is exposed as a configuration flag for RKE2. If you have set `profile` to "cis-1.x" and `protect-kernel-defaults` to `false` explicitly, RKE2 will exit with an error. +:::caution + +`protect-kernel-defaults` is exposed as a configuration flag for RKE2. If you have set `profile` to "cis-1.x" and `protect-kernel-defaults` to `false` explicitly, RKE2 will exit with an error. + +::: RKE2 will also check the same kernel parameters that the kubelet does and exit with an error following the same rules as the kubelet. This is done as a convenience to help the operator more quickly and easily identify what kernel parameters are violating the kubelet defaults. @@ -122,8 +134,11 @@ When ran with a valid "cis-1.x" profile, RKE2 will put `NetworkPolicies` in plac The `NetworkPolicy` used will only allow pods within the same namespace to talk to each other. The notable exception to this is that it allows DNS requests to be resolved. -> Operators must manage network policies as normal for additional namespaces that are created. +:::note +Operators must manage network policies as normal for additional namespaces that are created. + +::: #### Configure `default` service account **Set `automountServiceAccountToken` to `false` for `default` service accounts** diff --git a/docs/en/security/selinux/selinux.md b/docs/en/security/selinux/selinux.md index f2fa310b3ed..ebb2e915a58 100644 --- a/docs/en/security/selinux/selinux.md +++ b/docs/en/security/selinux/selinux.md @@ -39,7 +39,11 @@ For more information about installing RKE2 on SELinux-enabled hosts, see the [RK # Installing the rancher-selinux RPM -> **Requirements:** The rancher-selinux RPM was tested with CentOS 7 and 8. +:::note Requirement: + +The rancher-selinux RPM was tested with CentOS 7 and 8. + +::: ### 1. Set up the yum repo @@ -80,7 +84,11 @@ yum -y install rancher-selinux # Configuring the Logging Application to Work with SELinux -> **Requirements:** Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. +:::note Requirement: + +Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +::: Applications do not automatically work once the `rancher-selinux` RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM. diff --git a/docs/en/troubleshooting/dns/dns.md b/docs/en/troubleshooting/dns/dns.md index a1292df3e32..1b392ccdf16 100644 --- a/docs/en/troubleshooting/dns/dns.md +++ b/docs/en/troubleshooting/dns/dns.md @@ -194,7 +194,11 @@ services: resolv-conf: "/run/resolvconf/resolv.conf" ``` -> **Note:** As the `kubelet` is running inside a container, the path for files located in `/etc` and `/usr` are in `/host/etc` and `/host/usr` inside the `kubelet` container. +:::note + +As the `kubelet` is running inside a container, the path for files located in `/etc` and `/usr` are in `/host/etc` and `/host/usr` inside the `kubelet` container. + +::: See [Editing Cluster as YAML]({{}}/rancher/v2.6/en/cluster-admin/editing-clusters/#editing-clusters-with-yaml) how to apply this change. When the provisioning of the cluster has finished, you have to remove the kube-dns pod to activate the new setting in the pod: diff --git a/docs/en/troubleshooting/expired-webhook-certificates/expired-webhook-certificates.md b/docs/en/troubleshooting/expired-webhook-certificates/expired-webhook-certificates.md index 59a7bfbcc1f..97cc975e9a5 100644 --- a/docs/en/troubleshooting/expired-webhook-certificates/expired-webhook-certificates.md +++ b/docs/en/troubleshooting/expired-webhook-certificates/expired-webhook-certificates.md @@ -22,4 +22,8 @@ kubectl delete pod -n cattle-system -l app=rancher-webhook 3. Delete the `rancher-webhook` pod in the `cattle-system` namespace in the local cluster. -**Note:** The webhook certificate expiration issue is not specific to `cattle-webhook-tls` as listed in the examples. You will fill in your expired certificate secret accordingly. +:::note + +The webhook certificate expiration issue is not specific to `cattle-webhook-tls` as listed in the examples. You will fill in your expired certificate secret accordingly. + +::: \ No newline at end of file diff --git a/docs/en/troubleshooting/imported-clusters/imported-clusters.md b/docs/en/troubleshooting/imported-clusters/imported-clusters.md index 18d0a0bd062..c40978b36f5 100644 --- a/docs/en/troubleshooting/imported-clusters/imported-clusters.md +++ b/docs/en/troubleshooting/imported-clusters/imported-clusters.md @@ -15,7 +15,11 @@ If the cattle-cluster-agent cannot connect to the configured `server-url`, the c #### cattle-node-agent -> Note: cattle-node-agents are only present in clusters created in Rancher with RKE. +:::note + +cattle-node-agents are only present in clusters created in Rancher with RKE. + +::: Check if the cattle-node-agent pods are present on each node, have status **Running** and don't have a high count of Restarts: diff --git a/docs/en/troubleshooting/kubernetes-components/controlplane/etcd.md b/docs/en/troubleshooting/kubernetes-components/controlplane/etcd.md index e27339cb8b5..6a04373c0a2 100644 --- a/docs/en/troubleshooting/kubernetes-components/controlplane/etcd.md +++ b/docs/en/troubleshooting/kubernetes-components/controlplane/etcd.md @@ -29,7 +29,11 @@ bdf3898b8063 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." # Controlplane Container Logging -> **Note:** If you added multiple nodes with the `controlplane` role, both `kube-controller-manager` and `kube-scheduler` use a leader election process to determine the leader. Only the current leader will log the performed actions. See [Kubernetes leader election]({{}}/rancher/v2.6/en/troubleshooting/kubernetes-resources/#kubernetes-leader-election) how to retrieve the current leader. +:::note + +If you added multiple nodes with the `controlplane` role, both `kube-controller-manager` and `kube-scheduler` use a leader election process to determine the leader. Only the current leader will log the performed actions. See [Kubernetes leader election]({{}}/rancher/v2.6/en/troubleshooting/kubernetes-resources/#kubernetes-leader-election) how to retrieve the current leader. + +::: The logging of the containers can contain information on what the problem could be. diff --git a/docs/en/troubleshooting/networking/networking.md b/docs/en/troubleshooting/networking/networking.md index a184369afe3..c6b55500b8c 100644 --- a/docs/en/troubleshooting/networking/networking.md +++ b/docs/en/troubleshooting/networking/networking.md @@ -16,7 +16,11 @@ The pod can be scheduled to any of the hosts you used for your cluster, but that To test the overlay network, you can launch the following `DaemonSet` definition. This will run a `swiss-army-knife` container on every host (image was developed by Rancher engineers and can be found here: https://github.com/rancherlabs/swiss-army-knife), which we will use to run a `ping` test between containers on all hosts. -> **Note:** This container [does not support ARM nodes](https://github.com/leodotcloud/swiss-army-knife/issues/18), such as a Raspberry Pi. This will be seen in the pod logs as `exec user process caused: exec format error`. +:::note + +This container [does not support ARM nodes](https://github.com/leodotcloud/swiss-army-knife/issues/18), such as a Raspberry Pi. This will be seen in the pod logs as `exec user process caused: exec format error`. + +::: 1. Save the following file as `overlaytest.yml` diff --git a/docs/en/user-settings/api-keys/api-keys.md b/docs/en/user-settings/api-keys/api-keys.md index 7f39b336b55..77e9d2a5fa6 100644 --- a/docs/en/user-settings/api-keys/api-keys.md +++ b/docs/en/user-settings/api-keys/api-keys.md @@ -16,7 +16,11 @@ API Keys are composed of four components: - **Secret Key:** The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together. - **Bearer Token:** The token username and password concatenated together. Use this string for applications that prompt you for one authentication string. ->Note: Users may opt to enable [token hashing]({{}}/rancher/v2.6/en/api/api-tokens). +:::note + +Users may opt to enable [token hashing]({{}}/rancher/v2.6/en/api/api-tokens). + +::: ## Creating an API Key diff --git a/docs/en/user-settings/node-templates/node-templates.md b/docs/en/user-settings/node-templates/node-templates.md index d3b712815e6..62a18b571ad 100644 --- a/docs/en/user-settings/node-templates/node-templates.md +++ b/docs/en/user-settings/node-templates/node-templates.md @@ -25,8 +25,12 @@ When you create a node template, it is bound to your user profile. Node template 1. Click **RKE1 Configuration > Node Templates**. 1. Choose the node template that you want to edit and click the **⋮ > Edit**. - > **Note:** The default `active` [node drivers]({{}}/rancher/v2.6/en/admin-settings/drivers/node-drivers/) and any node driver, that has fields marked as `password`, are required to use [cloud credentials]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#cloud-credentials). + :::note + + The default `active` [node drivers]({{}}/rancher/v2.6/en/admin-settings/drivers/node-drivers/) and any node driver, that has fields marked as `password`, are required to use [cloud credentials]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#cloud-credentials). + ::: + 1. Edit the required information and click **Save**. **Result:** The node template is updated. All node pools using this node template will automatically use the updated information when new nodes are added. From ea9d79eee4cb7dadf2fc610389e6dad30e9e7c8a Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 11:11:14 -0400 Subject: [PATCH 15/18] Updating --- .../rke-clusters/custom-nodes/custom-nodes.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md b/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md index 82e3cef778c..63a50530c4e 100644 --- a/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md +++ b/docs/en/cluster-provisioning/rke-clusters/custom-nodes/custom-nodes.md @@ -68,12 +68,12 @@ If you're using Amazon EC2 as your host and want to use the [dual-stack](https:/ 7. From **Node Role**, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: `etcd`, `worker`, and `control plane`. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see [this section.]({{}}/rancher/v2.6/en/overview/concepts/#roles-for-nodes-in-kubernetes-clusters) - :::note Notes: +:::note Notes: - - Using Windows nodes as Kubernetes workers? See [this section]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). - - Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). +- Using Windows nodes as Kubernetes workers? See [this section]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/). +- Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). - ::: +::: 8. **Optional**: Click **[Show advanced options]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/rancher-agents/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node. @@ -81,11 +81,11 @@ If you're using Amazon EC2 as your host and want to use the [dual-stack](https:/ 10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. - :::note +:::note - Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed. +Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed. - ::: +::: 11. When you finish running the command(s) on your Linux host(s), click **Done**. @@ -119,11 +119,11 @@ The following resources need to be tagged with a `ClusterID`: - **Subnet**: The subnet used for your cluster - **Security Group**: The security group used for your cluster. - :::note +:::note - Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer. +Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer. - ::: +::: The tag that should be used is: From 49bd1b90c50ebf6db4b8a90356b5d4bed27ef32d Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 11:14:49 -0400 Subject: [PATCH 16/18] Fixed typo --- .../rke-clusters/cloud-providers/amazon/amazon.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md index cbbb614615f..79ace942e3f 100644 --- a/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md +++ b/docs/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/amazon.md @@ -131,7 +131,7 @@ The following resources need to tagged with a `ClusterID`: - **Subnet**: The subnet used for your cluster. - **Security Group**: The security group used for your cluster. -::note +:::note Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB). From cbf95664315a2ac2b550a5631b8c6667e369858a Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 14:07:53 -0400 Subject: [PATCH 17/18] Updating per feedback --- .../rbac/cluster-project-roles/cluster-project-roles.md | 2 +- .../gke-config-reference/private-clusters/private-clusters.md | 4 ++-- .../docker-install-commands/docker-install-commands.md | 4 +--- .../single-node-rollbacks/single-node-rollbacks.md | 2 +- .../single-node-upgrades/single-node-upgrades.md | 4 ++-- .../quota-type-reference/quota-type-reference.md | 2 +- .../deployment/amazon-aws-qs/amazon-aws-qs.md | 2 +- .../deployment/digital-ocean-qs/digital-ocean-qs.md | 2 +- .../deployment/equinix-metal-qs/equinix-metal-qs.md | 2 +- .../deployment/google-gcp-qs/google-gcp-qs.md | 2 +- .../deployment/hetzner-cloud-qs/hetzner-cloud-qs.md | 2 +- .../deployment/microsoft-azure-qs/microsoft-azure-qs.md | 2 +- .../deployment/quickstart-vagrant/quickstart-vagrant.md | 2 +- docs/en/quick-start-guide/quick-start-guide.md | 2 +- 14 files changed, 16 insertions(+), 18 deletions(-) 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 f54b0a817b3..a34d1c4653c 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 @@ -140,7 +140,7 @@ _Project roles_ are roles that can be used to grant users access to a project. T These users can view everything in the project but cannot create, update, or delete anything. - :::note Caveat + :::note danger 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. diff --git a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md index 69ea8f16489..aa326ebec32 100644 --- a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md +++ b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md @@ -11,7 +11,7 @@ Because the nodes in a private cluster only have internal IP addresses, they wil #### Cloud NAT -:::note +:::caution Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). @@ -21,7 +21,7 @@ If restricting outgoing internet access is not a concern for your organization, #### Private registry -:::note +:::caution This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient. diff --git a/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md b/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md index 8e38a449920..a0c9309ae20 100644 --- a/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md +++ b/docs/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/docker-install-commands.md @@ -16,9 +16,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher | `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | | `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | -:::note - -**Do you want to..** +:::note Do you want to.. - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.6/en/installation/resources/custom-ca-root-certificate/). - Record all transactions with the Rancher API? See [API Auditing]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log). diff --git a/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md b/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md index 62161562653..d056b93a415 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md @@ -82,7 +82,7 @@ Rolling back to a previous version of Rancher destroys any changes made to Ranch ``` Privileged access is [required.]({{}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher) - :::note Important: + :::danger **_Do not_** stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades. diff --git a/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md b/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md index 3fd403f8d79..bc3cd99c0d9 100644 --- a/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md +++ b/docs/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md @@ -5,7 +5,7 @@ weight: 1010 The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -:::note Important: +:::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]({{}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading. @@ -116,7 +116,7 @@ docker pull rancher/rancher: Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container. -:::note Important: +:::danger **_Do not_** stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. diff --git a/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md b/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md index a3c9a873790..f111346b07c 100644 --- a/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md +++ b/docs/en/project-admin/resource-quotas/quota-type-reference/quota-type-reference.md @@ -21,7 +21,7 @@ When you create a resource quota, you are configuring the pool of resources avai | Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. | | Secrets | The maximum number of secrets that can exist in the project/namespace. | -:::note Important: +:::note ***** When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. diff --git a/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md b/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md index caa8533219e..5c43eb5c1f0 100644 --- a/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md +++ b/docs/en/quick-start-guide/deployment/amazon-aws-qs/amazon-aws-qs.md @@ -5,7 +5,7 @@ weight: 100 --- The following steps will quickly deploy a Rancher server on AWS in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md b/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md index 6f79c04cd37..af37f6677d6 100644 --- a/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md +++ b/docs/en/quick-start-guide/deployment/digital-ocean-qs/digital-ocean-qs.md @@ -5,7 +5,7 @@ weight: 120 --- The following steps will quickly deploy a Rancher server on DigitalOcean in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md b/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md index 29844d1270a..eece16f895f 100644 --- a/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md +++ b/docs/en/quick-start-guide/deployment/equinix-metal-qs/equinix-metal-qs.md @@ -10,7 +10,7 @@ weight: 250 - Creation of your first cluster - Deployment of an application, Nginx -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md b/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md index 38fcf14ae7a..ca5da1892c9 100644 --- a/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md +++ b/docs/en/quick-start-guide/deployment/google-gcp-qs/google-gcp-qs.md @@ -5,7 +5,7 @@ weight: 130 --- The following steps will quickly deploy a Rancher server on GCP in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md b/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md index 526221d24c2..35ca28a143c 100644 --- a/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md +++ b/docs/en/quick-start-guide/deployment/hetzner-cloud-qs/hetzner-cloud-qs.md @@ -5,7 +5,7 @@ weight: 140 --- The following steps will quickly deploy a Rancher server on Hetzner Cloud in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md b/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md index 2f1b6561362..dbc50068525 100644 --- a/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md +++ b/docs/en/quick-start-guide/deployment/microsoft-azure-qs/microsoft-azure-qs.md @@ -6,7 +6,7 @@ weight: 115 The following steps will quickly deploy a Rancher server on Azure in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md b/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md index 25423322f32..987a9dcbdc2 100644 --- a/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md +++ b/docs/en/quick-start-guide/deployment/quickstart-vagrant/quickstart-vagrant.md @@ -4,7 +4,7 @@ weight: 200 --- The following steps quickly deploy a Rancher Server with a single node cluster attached. -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). diff --git a/docs/en/quick-start-guide/quick-start-guide.md b/docs/en/quick-start-guide/quick-start-guide.md index 7059f429421..d04067484fa 100644 --- a/docs/en/quick-start-guide/quick-start-guide.md +++ b/docs/en/quick-start-guide/quick-start-guide.md @@ -6,7 +6,7 @@ weight: 2 aliases: - /rancher/v2.x/en/quick-start-guide/ --- -:::note +:::caution The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). From 1bae586ed9b506267218ea1572972e0174d528f4 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Mon, 11 Jul 2022 14:15:34 -0400 Subject: [PATCH 18/18] Updating per feedback --- .../gke-config-reference/private-clusters/private-clusters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md index aa326ebec32..f3a6d1a869d 100644 --- a/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md +++ b/docs/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/private-clusters.md @@ -35,7 +35,7 @@ If the cluster has a public endpoint exposed, Rancher will be able to reach the #### Cloud NAT -:::note +:::caution Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing).