Updating notes in docu format

2026-09-25 20:48:11 +00:00 · 2022-07-11 10:12:18 -04:00
parent b39bb84a64
commit 67499d800b
56 changed files with 457 additions and 146 deletions
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/user-groups/)

@@ -44,8 +44,12 @@ After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/ranch

 <a id="cert-command"></a> 

-**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"
 ```
+
+:::
@@ -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 >}}
@@ -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

@@ -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 >}}
@@ -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
@@ -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

@@ -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 <b>Explore</b> 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 <b>Explore</b> 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:   
 ```
@@ -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.]({{<baseurl>}}/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.]({{<baseurl>}}/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.]({{<baseurl>}}/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.]({{<baseurl>}}/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:

@@ -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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#cluster-config-file) and the [Weave Network Plug-in Options]({{<baseurl>}}/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. 
@@ -44,8 +44,12 @@ To simplify the process of managing firewall rules, use NFSv4.
        /nfs <IP_ADDRESS1>(rw,sync,no_subtree_check) <IP_ADDRESS2>(rw,sync,no_subtree_check) <IP_ADDRESS3>(rw,sync,no_subtree_check)
        ```

-        **Tip:**  You can replace the IP addresses with a subnet. For example: `10.212.50.12&#47;24`
+        :::tip
+        
+        You can replace the IP addresses with a subnet. For example: `10.212.50.12&#47;24`

+        :::
+        
    1. Update the NFS table by entering the following command:

        ```
@@ -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.]({{<baseurl>}}/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.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
+
+:::

 # Node Configuration

@@ -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+.]({{<baseurl>}}/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+.]({{<baseurl>}}/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                                                                                                          |
@@ -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.
@@ -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.
@@ -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]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). 

@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/backups/configuration/restore-config) and to the [examples.]({{<baseurl>}}/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:
@@ -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
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/).
+
+   :::
+
   ```plain
   helm repo add jetstack https://charts.jetstack.io
   helm repo update
@@ -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
@@ -237,7 +237,11 @@ The following table depicts the port requirements for [hosted clusters]({{<baseu

 ### Ports for Registered Clusters

-Note: Registered clusters were called imported clusters before Rancher v2.5.
+:::note
+
+Registered clusters were called imported clusters before Rancher v2.5.
+
+:::

 {{% accordion label="Click to expand" %}}

@@ -79,7 +79,11 @@ helm install rancher rancher-latest/rancher \
  --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=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

@@ -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.

@@ -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

@@ -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
@@ -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:

@@ -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:
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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?
@@ -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 %}}

@@ -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.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/how-storage-works/)

->**Prerequisites (for both parts A and B):**
->
->[Persistent volumes]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) must be available for the cluster.
+
+:::

 ### A. Configuring Persistent Data for Docker Registry

@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/certificates/), [ConfigMaps]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/certificates/), [ConfigMaps]({{<baseurl>}}/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]({{<baseurl>}}/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]({{<baseurl>}}/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**.

@@ -3,7 +3,11 @@ title: Pod Security Policies
 weight: 5600
 ---

-> These cluster options are only available for [clusters in which Rancher has launched Kubernetes]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/).  
+:::note
+
+These cluster options are only available for [clusters in which Rancher has launched Kubernetes]({{<baseurl>}}/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.
+:::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.
+
+:::
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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?]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles).
-    >    - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles).
+        - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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.
@@ -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.                                                                                                                            |

->**<sup>*</sup>** 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.
+:::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.
+
+:::
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/node-requirements/).
-  > Provision the host according to our [Requirements]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/node-requirements/).
+- Provision the host according to our [Requirements]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/installation/).
+
+:::

 ## Prerequisites

@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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:

@@ -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]({{<baseurl>}}/rancher/v2.6/en/security/hardening-guides/rke-1.6-benchmark-2.6) | [Link]({{<baseurl>}}/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

@@ -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
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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,
@@ -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

@@ -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**
@@ -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. 

@@ -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]({{<baseurl>}}/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:

@@ -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.
+
+:::
@@ -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:

@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/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.

@@ -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`

@@ -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]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens).
+:::note
+
+Users may opt to enable [token hashing]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens).
+
+:::

 ## Creating an API Key

@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#cloud-credentials).
+	   :::note
+	   
+	   The default `active` [node drivers]({{<baseurl>}}/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]({{<baseurl>}}/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.