Merge pull request #2401 from rancher/staging

2.4 feature docs
2026-09-25 12:38:05 +00:00 · 2020-03-30 16:45:51 -07:00
parent 9967c9b1c2 5fa56f9e7d
commit 6cadd82811
280 changed files with 3468 additions and 1460 deletions
@@ -69,7 +69,7 @@
        </div>

        <div class="buttons-container">
-          <a href="{{< baseurl >}}/rancher/v2.x/en/v1.6-migration/">
+          <a href="{{<baseurl>}}/rancher/v2.x/en/v1.6-migration/">
            <button class="button text">
                <span>Read More</span>
            </button>
@@ -110,7 +110,7 @@
                            <p class="description-label">Rancher manages all of your Kubernetes clusters everywhere, unifies them under centralized RBAC, monitors them and lets you easily deploy and manage workloads through an intuitive user interface.</p>

                            <div class="buttons-container">
-                              <a href="{{< baseurl >}}/rancher/v2.x/en/">
+                              <a href="{{<baseurl>}}/rancher/v2.x/en/">
                                <button class="button text">
                                    <span>Read the docs</span>
                                </button>
@@ -164,7 +164,7 @@
                            <p class="description-label">RancherOS is the lightest, easiest way to run Docker in production. Engineered from the ground up for security and speed, it runs all system services and user workloads within Docker containers.</p>

                            <div class="buttons-container">
-                                <a href="{{< baseurl >}}/os/v1.x/en/">
+                                <a href="{{<baseurl>}}/os/v1.x/en/">
                                <button class="button text">
                                    <span>Read the docs</span>
                                </button>
@@ -191,7 +191,7 @@
                            <p class="description-label">Rancher Kubernetes Engine (RKE) is an extremely simple, lightning fast Kubernetes installer that works everywhere.</p>

                            <div class="buttons-container">
-                              <a href="{{< baseurl >}}/rke/v0.1.x/en/">
+                              <a href="{{<baseurl>}}/rke/v0.1.x/en/">
                                <button class="button text">
                                    <span>Read the docs</span>
                                </button>
@@ -215,10 +215,10 @@

                            <hr/>

-                            <p class="description-label">Lightweight Kubernetes.  Easy to install, half the memory, all in a binary less than 40mb.</p>
+                            <p class="description-label">Lightweight Kubernetes.  Easy to install, half the memory, all in a binary less than 50mb.</p>

                            <div class="buttons-container">
-                              <a href="{{< baseurl >}}/k3s/latest/en/">
+                              <a href="{{<baseurl>}}/k3s/latest/en/">
                                <button class="button text">
                                    <span>Read the docs</span>
                                </button>
@@ -4,7 +4,7 @@ shortTitle: K3s
 name: "menu"
 ---

-Lightweight Kubernetes.  Easy to install, half the memory, all in a binary less than 50mb.
+Lightweight Kubernetes. Easy to install, half the memory, all in a binary of less than 50mb.

 Great for:

@@ -12,7 +12,7 @@ Great for:
 * IoT
 * CI
 * ARM
-* Situations where a PhD in k8s clusterology is infeasible
+* Situations where a PhD in K8s clusterology is infeasible

 # What is K3s?

@@ -33,7 +33,7 @@ Single server clusters can meet a variety of use cases, but for environments whe
 * An **external datastore** (as opposed to the embedded SQLite datastore used in single-server setups)

 <figcaption>K3s Architecture with a High-availability Server</figcaption>
-![Architecture]({{< baseurl >}}/img/rancher/k3s-architecture-ha-server.png)
+![Architecture]({{<baseurl>}}/img/rancher/k3s-architecture-ha-server.png)

 ### Fixed Registration Address for Agent Nodes

@@ -41,7 +41,7 @@ In the high-availability server configuration, each node must also register with

 After registration, the agent nodes establish a connection directly to one of the server nodes.

-![k3s HA]({{< baseurl >}}/img/k3s/k3s-production-setup.svg)
+![k3s HA]({{<baseurl>}}/img/k3s/k3s-production-setup.svg)

 # How Agent Node Registration Works

@@ -5,13 +5,13 @@ weight: 20

 This section contains instructions for installing K3s in various environments. Please ensure you have met the [Installation Requirements]({{< baseurl >}}/k3s/latest/en/installation/installation-requirements/) before you begin installing K3s.

-[Installation and Configuration Options]({{< baseurl >}}/k3s/latest/en/installation/install-options/) provides guidance on the options available to you when installing K3s.
+[Installation and Configuration Options]({{<baseurl>}}/k3s/latest/en/installation/install-options/) provides guidance on the options available to you when installing K3s.

-[High Availability with an External DB]({{< baseurl >}}/k3s/latest/en/installation/ha/) details how to set up an HA K3s cluster backed by an external datastore such as MySQL, PostgreSQL, or etcd.
+[High Availability with an External DB]({{<baseurl>}}/k3s/latest/en/installation/ha/) details how to set up an HA K3s cluster backed by an external datastore such as MySQL, PostgreSQL, or etcd.

-[High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded/) details how to set up an HA K3s cluster that leverages a built-in distributed database.
+[High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) details how to set up an HA K3s cluster that leverages a built-in distributed database.

-[Air-Gap Installation]({{< baseurl >}}/k3s/latest/en/installation/airgap/) details how to set up K3s in environments that do not have direct access to the Internet.
+[Air-Gap Installation]({{<baseurl>}}/k3s/latest/en/installation/airgap/) details how to set up K3s in environments that do not have direct access to the Internet.

 ### Uninstalling

@@ -95,4 +95,4 @@ k3s server
 ```

 ### Embedded DQLite for HA (Experimental)
-K3s's use of DQLite is similar to its use of SQLite. It is simple to set up and manage. As such, there is no external configuration or additional steps to take in order to use this option. Please see [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded/) for instructions on how to run with this option.
+K3s's use of DQLite is similar to its use of SQLite. It is simple to set up and manage. As such, there is no external configuration or additional steps to take in order to use this option. Please see [High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) for instructions on how to run with this option.
@@ -28,12 +28,10 @@ Setting up an HA cluster requires the following steps:
 4. [Join agent nodes](#4-optional-join-agent-nodes)

 ### 1. Create an External Datastore
-
-You will first need to create an external datastore for the cluster. See the [Cluster Datastore Options]({{< baseurl >}}/k3s/latest/en/installation/datastore/) documentation for more details.
+You will first need to create an external datastore for the cluster. See the [Cluster Datastore Options]({{<baseurl>}}/k3s/latest/en/installation/datastore/) documentation for more details.

 ### 2. Launch Server Nodes
-
-K3s requires two or more server nodes for this HA configuration. See the [Installation Requirements]({{< baseurl >}}/k3s/latest/en/installation/installation-requirements/) for minimum machine requirements.
+K3s requires two or more server nodes for this HA configuration. See the [Installation Requirements]({{<baseurl>}}/k3s/latest/en/installation/node-requirements/) guide for minimum machine requirements.

 When running the `k3s server` command on these nodes, you must set the `datastore-endpoint` parameter so that K3s knows how to connect to the external datastore.

@@ -14,7 +14,7 @@ For more advanced options, refer to [this page.]({{<baseurl>}}/k3s/latest/en/adv

 # Installation Script Options

-As mentioned in the [Quick-Start Guide]({{< baseurl >}}/k3s/latest/en/quick-start/), you can use the installation script available at https://get.k3s.io to install K3s as a service on systemd and openrc based systems.
+As mentioned in the [Quick-Start Guide]({{<baseurl>}}/k3s/latest/en/quick-start/), you can use the installation script available at https://get.k3s.io to install K3s as a service on systemd and openrc based systems.

 The simplest form of this command is as follows:
 ```sh
@@ -3,7 +3,7 @@ title: "Network Options"
 weight: 25
 ---

-> **Note:** Please reference the [Networking]({{< baseurl >}}/k3s/latest/en/networking) page for information about CoreDNS, Traefik, and the Service LB.
+> **Note:** Please reference the [Networking]({{<baseurl>}}/k3s/latest/en/networking) page for information about CoreDNS, Traefik, and the Service LB.

 By default, K3s will run with flannel as the CNI, using VXLAN as the default backend. To change the CNI, refer to the section on configuring a [custom CNI](#custom-cni). To change the flannel backend, refer to the flannel options section.

@@ -3,12 +3,11 @@ title: "Networking"
 weight: 35
 ---

-> **Note:** CNI options are covered in detail on the [Installation Network Options]({{< baseurl >}}/k3s/latest/en/installation/network-options/) page. Please reference that page for details on Flannel and the various flannel backend options or how to set up your own CNI.
+>**Note:** CNI options are covered in detail on the [Installation Network Options]({{<baseurl>}}/k3s/latest/en/installation/network-options/) page. Please reference that page for details on Flannel and the various flannel backend options or how to set up your own CNI.

 Open Ports
 ----------
-
-Please reference the [Installation Requirements]({{< baseurl >}}/k3s/latest/en/installation/installation-requirements/#networking) page for port information.
+Please reference the [Installation Requirements]({{<baseurl>}}/k3s/latest/en/installation/node-requirements/#networking) page for port information.

 CoreDNS
 -------
@@ -22,7 +21,7 @@ Traefik Ingress Controller

 [Traefik](https://traefik.io/) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. It simplifies networking complexity while designing, deploying, and running applications.

-Traefik is deployed by default when starting the server. For more information see [Auto Deploying Manifests]({{< baseurl >}}/k3s/latest/en/advanced/#auto-deploying-manifests). The default config file is found in `/var/lib/rancher/k3s/server/manifests/traefik.yaml` and any changes made to this file will automatically be deployed to Kubernetes in a manner similar to `kubectl apply`.
+Traefik is deployed by default when starting the server. For more information see [Auto Deploying Manifests]({{<baseurl>}}/k3s/latest/en/advanced/#auto-deploying-manifests). The default config file is found in `/var/lib/rancher/k3s/server/manifests/traefik.yaml` and any changes made to this file will automatically be deployed to Kubernetes in a manner similar to `kubectl apply`.

 The Traefik ingress controller will use ports 80, 443, and 8080 on the host (i.e. these will not be usable for HostPort or NodePort).

@@ -25,7 +25,7 @@ VMWare     | 1GB                       | 1280MB (rancheros.iso) <br> 2048MB (ran
 GCE        | 1GB                       | 1280MB
 AWS        | 1GB                       | 1.7GB

-You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)
+You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)

 ### How RancherOS Works

@@ -59,7 +59,7 @@ All of repositories are located within our main GitHub [page](https://github.com

 [RancherOS Repo](https://github.com/rancher/os): This repo contains the bulk of the RancherOS code.

-[RancherOS Services Repo](https://github.com/rancher/os-services): This repo is where any [system-services]({{< baseurl >}}/os/v1.x/en//installation/system-services/adding-system-services/) can be contributed.
+[RancherOS Services Repo](https://github.com/rancher/os-services): This repo is where any [system-services]({{<baseurl>}}/os/v1.x/en//installation/system-services/adding-system-services/) can be contributed.

 [RancherOS Images Repo](https://github.com/rancher/os-images): This repo is for the corresponding service images.

@@ -7,7 +7,7 @@ RancherOS can be used to launch [Rancher](/rancher/) and be used as the OS to ad

 ### Launching Agents using Cloud-Config

-You can easily add hosts into Rancher by using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) to launch the rancher/agent container.
+You can easily add hosts into Rancher by using [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) to launch the rancher/agent container.

 After Rancher is launched and host registration has been saved, you will be able to find use the custom option to add Rancher OS nodes.

@@ -37,7 +37,7 @@ rancher:
 ```
 <br>

-> **Note:** You can not name the service `rancher-agent` as this will not allow the rancher/agent container to be launched correctly. Please read more about why [you can't name your container as `rancher-agent`]({{< baseurl >}}/rancher/v1.6/en/faqs/agents/#adding-in-name-rancher-agent).
+> **Note:** You can not name the service `rancher-agent` as this will not allow the rancher/agent container to be launched correctly. Please read more about why [you can't name your container as `rancher-agent`]({{<baseurl>}}/rancher/v1.6/en/faqs/agents/#adding-in-name-rancher-agent).

 ### Adding in Host Labels

@@ -11,13 +11,13 @@ Prior to launching RancherOS EC2 instances, the [ECS Container Instance IAM Role

 ### Launching an instance with ECS

-RancherOS makes it easy to join your ECS cluster. The ECS agent is a [system service]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) that is enabled in the ECS enabled AMI. There may be other RancherOS AMIs that don't have the ECS agent enabled by default, but it can easily be added in the user data on any RancherOS AMI.
+RancherOS makes it easy to join your ECS cluster. The ECS agent is a [system service]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) that is enabled in the ECS enabled AMI. There may be other RancherOS AMIs that don't have the ECS agent enabled by default, but it can easily be added in the user data on any RancherOS AMI.

 When launching the RancherOS AMI, you'll need to specify the **IAM Role** and **Advanced Details** -> **User Data** in the **Configure Instance Details** step.

 For the **IAM Role**, you'll need to be sure to select the ECS Container Instance IAM role.

-For the **User Data**, you'll need to pass in the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file.
+For the **User Data**, you'll need to pass in the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file.

 ```yaml
 #cloud-config
@@ -37,7 +37,7 @@ rancher:

 By default, the ECS agent will be using the `latest` tag for the `amazon-ecs-agent` image. In v0.5.0, we introduced the ability to select which version of the `amazon-ecs-agent`.

-To select the version, you can update your [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file.
+To select the version, you can update your [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file.

 ```yaml
 #cloud-config
@@ -3,17 +3,17 @@ title: Built-in System Services
 weight: 150
 ---

-To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) or override services in the cloud-config.
+To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) or override services in the cloud-config.

 ### preload-user-images

-Read more about [image preloading]({{< baseurl >}}/os/v1.x/en/installation/boot-process/image-preloading/).
+Read more about [image preloading]({{<baseurl>}}/os/v1.x/en/installation/boot-process/image-preloading/).

 ### network

 During this service, networking is set up, e.g. hostname, interfaces, and DNS.

-It is configured by `hostname` and `rancher.network`settings in [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+It is configured by `hostname` and `rancher.network`settings in [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 ### ntp

@@ -24,13 +24,13 @@ Runs `ntpd` in a System Docker container.
 This service provides the RancherOS user interface by running `sshd` and `getty`. It completes the RancherOS configuration on start up:

 1. If the `rancher.password=<password>` kernel parameter exists, it sets `<password>` as the password for the `rancher` user.
-2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).
 3. Runs `cloud-init -execute`, which does the following:
-   * Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/ssh-keys/) and metadata.
-   * Writes files specified by the `write_files` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/write-files/) setting.
-   * Resizes the device specified by the `rancher.resize_device` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/resizing-device-partition/) setting.
-   * Mount devices specified in the `mounts` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/storage/additional-mounts/) setting.
-   * Set sysctl parameters specified in  the`rancher.sysctl` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/sysctl/) setting.
+   * Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/ssh-keys/) and metadata.
+   * Writes files specified by the `write_files` [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/write-files/) setting.
+   * Resizes the device specified by the `rancher.resize_device` [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/resizing-device-partition/) setting.
+   * Mount devices specified in the `mounts` [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/storage/additional-mounts/) setting.
+   * Set sysctl parameters specified in  the`rancher.sysctl` [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/sysctl/) setting.
 4. If user-data contained a file that started with `#!`, then a file would be saved at `/var/lib/rancher/conf/cloud-config-script` during cloud-init and then executed. Any errors are ignored.
 5. Runs `/opt/rancher/bin/start.sh` if it exists and is executable. Any errors are ignored.
 6. Runs `/etc/rc.local` if it exists and is executable. Any errors are ignored.
@@ -7,7 +7,7 @@ Userdata and metadata can be fetched from a cloud provider, VM runtime, or manag

 ### Userdata

-Userdata is a file given by users when launching RancherOS hosts. It is stored in different locations depending on its format. If the userdata is a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file, indicated by beginning with `#cloud-config` and being in YAML format, it is stored in `/var/lib/rancher/conf/cloud-config.d/boot.yml`. If the userdata is a script, indicated by beginning with `#!`, it is stored in `/var/lib/rancher/conf/cloud-config-script`.
+Userdata is a file given by users when launching RancherOS hosts. It is stored in different locations depending on its format. If the userdata is a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, indicated by beginning with `#cloud-config` and being in YAML format, it is stored in `/var/lib/rancher/conf/cloud-config.d/boot.yml`. If the userdata is a script, indicated by beginning with `#!`, it is stored in `/var/lib/rancher/conf/cloud-config-script`.

 ### Metadata

@@ -15,7 +15,7 @@ Although the specifics vary based on provider, a metadata file will typically co

 ## Configuration Load Order

-[Cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file.
+[Cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file.

 1. `/usr/share/ros/os-config.yml` - This is the system default configuration, which should **not** be modified by users.
 2. `/usr/share/ros/oem/oem-config.yml` - This will typically exist by OEM, which should **not** be modified by users.
@@ -34,7 +34,7 @@ In our example above, we have our `#cloud-config` line to indicate it's a cloud-
 ### Manually Changing Configuration

 To update RancherOS configuration after booting, the `ros config set <key> <value>` command can be used.
-For more complicated settings, like the [sysctl settings]({{< baseurl >}}/os/v1.x/en/installation/configuration/sysctl/), you can also create a small YAML file and then run `sudo ros config merge -i <your yaml file>`.
+For more complicated settings, like the [sysctl settings]({{<baseurl>}}/os/v1.x/en/installation/configuration/sysctl/), you can also create a small YAML file and then run `sudo ros config merge -i <your yaml file>`.

 #### Getting Values

@@ -27,7 +27,7 @@ $ sudo system-docker run --rm -it -v /:/host alpine vi /host/boot/global.cfg

 ### During installation

-If you want to set the extra kernel parameters when you are [Installing RancherOS to Disk]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) please use the `--append` parameter.
+If you want to set the extra kernel parameters when you are [Installing RancherOS to Disk]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) please use the `--append` parameter.

 ```bash
 $ sudo ros install -d /dev/sda --append "rancheros.autologin=tty1"
@@ -10,10 +10,10 @@ In the air gap environment, the Docker registry, RancherOS repositories URL, and

 You should use a private Docker registry so that `user-docker` and `system-docker` can pull images.

-1. Add the private Docker registry domain to the [images prefix]({{< baseurl >}}/os/v1.x/en/installation/configuration/images-prefix/).
-2. Set the private registry certificates for `user-docker`. For details, refer to [Certificates for Private Registries]({{< baseurl >}}/os/v1.x/en/installation/configuration/private-registries/#certificates-for-private-registries)
+1. Add the private Docker registry domain to the [images prefix]({{<baseurl>}}/os/v1.x/en/installation/configuration/images-prefix/).
+2. Set the private registry certificates for `user-docker`. For details, refer to [Certificates for Private Registries]({{<baseurl>}}/os/v1.x/en/installation/configuration/private-registries/#certificates-for-private-registries)
 3. Set the private registry certificates for `system-docker`. There are two ways to set the certificates:
-  - To set the private registry certificates before RancherOS starts, you can run a script included with RancherOS. For details, refer to [Set Custom Certs in ISO]({{< baseurl >}}/os/v1.x/en/installation/configuration/airgap-configuration/#set-custom-certs-in-iso).
+  - To set the private registry certificates before RancherOS starts, you can run a script included with RancherOS. For details, refer to [Set Custom Certs in ISO]({{<baseurl>}}/os/v1.x/en/installation/configuration/airgap-configuration/#set-custom-certs-in-iso).
  - To set the private registry certificates after RancherOS starts, append your private registry certs to the `/etc/ssl/certs/ca-certificates.crt.rancher` file. Then reboot to make the certs fully take effect.
 4. The images used by RancherOS should be pushed to your private registry.

@@ -84,7 +84,7 @@ $ sudo ros config set rancher.upgrade.url https://foo.bar.com/os/releases.yml

 Here is a total cloud-config example for using RancherOS in an air gap environment.

-For `system-docker`, see [Configuring Private Docker Registry]({{< baseurl >}}/os/v1.x/en/installation/configuration/airgap-configuration/#configuring-private-docker-registry).
+For `system-docker`, see [Configuring Private Docker Registry]({{<baseurl>}}/os/v1.x/en/installation/configuration/airgap-configuration/#configuring-private-docker-registry).

 ```yaml
 #cloud-config
@@ -5,7 +5,7 @@ weight: 121

 The default console keeps time in the Coordinated Universal Time (UTC) zone and synchronizes clocks with the Network Time Protocol (NTP). The Network Time Protocol daemon (ntpd) is an operating system program that maintains the system time in synchronization with time servers using the NTP. 

-RancherOS can run ntpd in the System Docker container. You can update its configurations by updating `/etc/ntp.conf`. For an example of how to update a file such as `/etc/ntp.conf` within a container, refer to [this page.]({{< baseurl >}}/os/v1.x/en/installation/configuration/write-files/#writing-files-in-specific-system-services)
+RancherOS can run ntpd in the System Docker container. You can update its configurations by updating `/etc/ntp.conf`. For an example of how to update a file such as `/etc/ntp.conf` within a container, refer to [this page.]({{<baseurl>}}/os/v1.x/en/installation/configuration/write-files/#writing-files-in-specific-system-services)

 The default console cannot support changing the time zone because including `tzdata` (time zone data) will increase the ISO size. However, you can change the time zone in the container by passing a flag to specify the time zone when you run the container:

@@ -3,7 +3,7 @@ title: Configuring Docker or System Docker
 weight: 126
 ---

-In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 ### Configuring Docker

@@ -61,7 +61,7 @@ Key | Value | Default | Description
 ---|---|---| ---
 `extra_args` | List of Strings | `[]` | Arbitrary daemon arguments, appended to the generated command
 `environment` | List of Strings | `[]` |
-`tls` | Boolean | `false` | When [setting up TLS]({{< baseurl >}}/os/v1.x/en/installation/configuration/setting-up-docker-tls/), this key needs to be set to true.
+`tls` | Boolean | `false` | When [setting up TLS]({{<baseurl>}}/os/v1.x/en/installation/configuration/setting-up-docker-tls/), this key needs to be set to true.
 `tls_args` | List of Strings (used only if `tls: true`) | `[]` |
 `server_key` | String (used only if `tls: true`)| `""` | PEM encoded server TLS key.
 `server_cert` | String (used only if `tls: true`) | `""` | PEM encoded server TLS certificate.
@@ -120,7 +120,7 @@ $ ros config set rancher.system_docker.bip 172.19.0.0/16
 _Available as of v1.4.x_

 The default path of system-docker logs is `/var/log/system-docker.log`. If you want to write the system-docker logs to a separate partition,
-e.g. [RANCHER_OEM partition]({{< baseurl >}}/os/v1.x/en/about/custom-partition-layout/#use-rancher-oem-partition), you can try `rancher.defaults.system_docker_logs`:
+e.g. [RANCHER_OEM partition]({{<baseurl>}}/os/v1.x/en/about/custom-partition-layout/#use-rancher-oem-partition), you can try `rancher.defaults.system_docker_logs`:

 ```
 #cloud-config
@@ -3,7 +3,7 @@ title: Setting the Hostname
 weight: 124
 ---

-You can set the hostname of the host using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). The example below shows how to configure it.
+You can set the hostname of the host using [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). The example below shows how to configure it.

 ```yaml
 #cloud-config
@@ -3,7 +3,7 @@ title: Private Registries
 weight: 128
 ---

-When launching services through a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), it is sometimes necessary to pull a private image from DockerHub or from a private registry. Authentication for these can be embedded in your cloud-config.
+When launching services through a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config), it is sometimes necessary to pull a private image from DockerHub or from a private registry. Authentication for these can be embedded in your cloud-config.

 For example, to add authentication for DockerHub:

@@ -61,7 +61,7 @@ write_files:

 ### Certificates for Private Registries

-Certificates can be stored in the standard locations (i.e. `/etc/docker/certs.d`) following the [Docker documentation](https://docs.docker.com/registry/insecure). By using the `write_files` directive of the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), the certificates can be written directly into `/etc/docker/certs.d`.
+Certificates can be stored in the standard locations (i.e. `/etc/docker/certs.d`) following the [Docker documentation](https://docs.docker.com/registry/insecure). By using the `write_files` directive of the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config), the certificates can be written directly into `/etc/docker/certs.d`.

 ```yaml
 #cloud-config
@@ -31,4 +31,4 @@ write_files:
      docker run -d nginx
 ```

-Running Docker commands in this manner is useful when pieces of the `docker run` command are dynamically generated. For services whose configuration is static, [adding a system service]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) is recommended.
+Running Docker commands in this manner is useful when pieces of the `docker run` command are dynamically generated. For services whose configuration is static, [adding a system service]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) is recommended.
@@ -3,7 +3,7 @@ title: SSH Settings
 weight: 121
 ---

-RancherOS supports adding SSH keys through the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file. Within the cloud-config file, you simply add the ssh keys within the `ssh_authorized_keys` key.
+RancherOS supports adding SSH keys through the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file. Within the cloud-config file, you simply add the ssh keys within the `ssh_authorized_keys` key.

 ```yaml
 #cloud-config
@@ -3,13 +3,13 @@ title: Switching Consoles
 weight: 125
 ---

-When [booting from the ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
+When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.

-You can select which console you want RancherOS to start with using the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 ### Enabling Consoles using Cloud-Config

-When launching RancherOS with a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.
+When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.

 Currently, the list of available consoles are:

@@ -102,7 +102,7 @@ All consoles except the default (busybox) console are persistent. Persistent con

 <br>

-> **Note:** When using a persistent console and in the current version's console, [rolling back]({{< baseurl >}}/os/v1.x/en/upgrading/#rolling-back-an-upgrade) is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.
+> **Note:** When using a persistent console and in the current version's console, [rolling back]({{<baseurl>}}/os/v1.x/en/upgrading/#rolling-back-an-upgrade) is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.

 ### Enabling Consoles

@@ -3,7 +3,7 @@ title: Switching Docker Versions
 weight: 129
 ---

-The version of User Docker used in RancherOS can be configured using a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file or by using the `ros engine` command.
+The version of User Docker used in RancherOS can be configured using a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file or by using the `ros engine` command.

 > **Note:** There are known issues in Docker when switching between versions. For production systems, we recommend setting the Docker engine only once [using a cloud-config](#setting-the-docker-engine-using-cloud-config).

@@ -83,7 +83,7 @@ FROM scratch
 COPY engine /engine
 ```

-Once the image is built a [system service]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-18.06.3-ce.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built.
+Once the image is built a [system service]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-18.06.3-ce.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built.

 All of the previously mentioned methods of switching Docker engines are now available. For example, if your service file is located at `https://myservicefile` then the following cloud-config file could be used to use your custom Docker engine.

@@ -5,7 +5,7 @@ weight: 130

 Currently, we don't support adding other users besides `rancher`.

-You _can_ add users in the console container, but these users will only exist as long as the console container exists. It only makes sense to add users in a [persistent consoles]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence).
+You _can_ add users in the console container, but these users will only exist as long as the console container exists. It only makes sense to add users in a [persistent consoles]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence).

 If you want the console user to be able to ssh into RancherOS, you need to add them
 to the `docker` group.
@@ -3,13 +3,13 @@ title: Custom Console
 weight: 180
 ---

-When [booting from the ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
+When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.

-You can select which console you want RancherOS to start with using the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 ### Enabling Consoles using Cloud-Config

-When launching RancherOS with a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.
+When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.

 Currently, the list of available consoles are:

@@ -102,7 +102,7 @@ All consoles except the default (busybox) console are persistent. Persistent con

 <br>

-> **Note:** When using a persistent console and in the current version's console, [rolling back]({{< baseurl >}}/os/v1.x/en/upgrading/#rolling-back-an-upgrade) is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.
+> **Note:** When using a persistent console and in the current version's console, [rolling back]({{<baseurl>}}/os/v1.x/en/upgrading/#rolling-back-an-upgrade) is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.

 ### Enabling Consoles

@@ -59,7 +59,7 @@ Your kernel should be packaged and published as a set of files of the following

 ### Building a RancherOS release using the Packaged kernel files.

-By default, RancherOS ships with the kernel provided by the [os-kernel repository](https://github.com/rancher/os-kernel). Swapping out the default kernel can by done by [building your own custom RancherOS ISO]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).
+By default, RancherOS ships with the kernel provided by the [os-kernel repository](https://github.com/rancher/os-kernel). Swapping out the default kernel can by done by [building your own custom RancherOS ISO]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).

 Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.

@@ -75,6 +75,6 @@ ARG KERNEL_VERSION_amd64=4.14.63-rancher
 ARG KERNEL_URL_amd64=https://link/xxxx
 ```

-After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).
+After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).

 > **Note:** `KERNEL_URL` settings should point to a Linux kernel, compiled and packaged in a specific way. You can fork [os-kernel repository](https://github.com/rancher/os-kernel) to package your own kernel.
@@ -11,7 +11,7 @@ Create a clone of the main [RancherOS repository](https://github.com/rancher/os)
 $ git clone https://github.com/rancher/os.git
 ```

-In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` can be updated to use [custom kernels]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-kernels). 
+In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` can be updated to use [custom kernels]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-kernels). 
 After you've saved your edits, run `make` in the root directory. After the build has completed, a `./dist/artifacts` directory will be created with the custom built RancherOS release files. 
 Build Requirements: `bash`, `make`, `docker` (Docker version >= 1.10.3)

@@ -29,7 +29,7 @@ If you need a compressed ISO, you can run this command:
 $ make release
 ```

-The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine).
+The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine).

 ## Creating a GCE Image Archive

@@ -50,7 +50,7 @@ RANCHEROS_VERSION=v1.4.0 make build-gce

 #### Reduce Memory Requirements

-With changes to the kernel and built Docker, RancherOS booting requires more memory. For details, please refer to the [memory requirements]({{< baseurl >}}/os/v1.x/en/#hardware-requirements).
+With changes to the kernel and built Docker, RancherOS booting requires more memory. For details, please refer to the [memory requirements]({{<baseurl>}}/os/v1.x/en/#hardware-requirements).

 By customizing the ISO, you can reduce the memory usage on boot. The easiest way is to downgrade the built-in Docker version, because Docker takes up a lot of space. 
 This can effectively reduce the memory required to decompress the `initrd` on boot. Using docker 17.03 is a good choice:
@@ -3,37 +3,37 @@ title: Running RancherOS
 weight: 100
 ---

-RancherOS runs on virtualization platforms, cloud providers and bare metal servers. We also support running a local VM on your laptop. To start running RancherOS as quickly as possible, follow our [Quick Start Guide]({{< baseurl >}}/os/v1.x/en/quick-start-guide/).
+RancherOS runs on virtualization platforms, cloud providers and bare metal servers. We also support running a local VM on your laptop. To start running RancherOS as quickly as possible, follow our [Quick Start Guide]({{<baseurl>}}/os/v1.x/en/quick-start-guide/).

 ### Platforms

 #### Workstation

-[Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine)
+[Docker Machine]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine)

-[Boot from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso)
+[Boot from ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso)


 #### Cloud

-[Amazon EC2]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/aws)
+[Amazon EC2]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/aws)

-[Google Compute Engine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/gce)
+[Google Compute Engine]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/gce)

-[DigitalOcean]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/do)
+[DigitalOcean]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/do)

-[Azure]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/azure)
+[Azure]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/azure)

-[OpenStack]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/openstack)
+[OpenStack]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/openstack)

-[VMware ESXi]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi)
+[VMware ESXi]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi)

-[Aliyun]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/aliyun)
+[Aliyun]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/aliyun)

 #### Bare Metal & Virtual Servers

-[PXE]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/pxe)
+[PXE]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/pxe)

-[Install to Hard Disk]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk)
+[Install to Hard Disk]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk)

-[Raspberry Pi]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/raspberry-pi)
+[Raspberry Pi]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/raspberry-pi)
@@ -13,7 +13,7 @@ RancherOS is available as an image in Aliyun, and can be easily run in Elastic C

 Example: 

-![RancherOS on Aliyun 1]({{< baseurl >}}/img/os/RancherOS_aliyun1.jpg)
+![RancherOS on Aliyun 1]({{<baseurl>}}/img/os/RancherOS_aliyun1.jpg)

 ## Options

@@ -29,6 +29,6 @@ After the image is uploaded, we can use the `Aliyun Console` to start a new inst

 Since the image is private, we need to use the `Custom Images`.

-![RancherOS on Aliyun 2]({{< baseurl >}}/img/os/RancherOS_aliyun2.jpg)
+![RancherOS on Aliyun 2]({{<baseurl>}}/img/os/RancherOS_aliyun2.jpg)

 After the instance is successfully started, we can login with the `rancher` user via SSH.
@@ -28,7 +28,7 @@ Let’s walk through how to import and create a RancherOS on EC2 machine using t
    {{< img "/img/os/Rancher_aws1.png" "RancherOS on AWS 1">}}
 2. Select the **Community AMIs** on the sidebar and search for **RancherOS**. Pick the latest version and click **Select**.
    {{< img "/img/os/Rancher_aws2.png" "RancherOS on AWS 2">}}
-3. Go through the steps of creating the instance type through the AWS console. If you want to pass in a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file during boot of RancherOS, you'd pass in the file as **User data** by expanding the **Advanced Details** in **Step 3: Configure Instance Details**. You can pass in the data as text or as a file.
+3. Go through the steps of creating the instance type through the AWS console. If you want to pass in a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file during boot of RancherOS, you'd pass in the file as **User data** by expanding the **Advanced Details** in **Step 3: Configure Instance Details**. You can pass in the data as text or as a file.
    {{< img "/img/os/Rancher_aws6.png" "RancherOS on AWS 6">}}
     After going through all the steps, you finally click on **Launch**, and either create a new key pair or choose an existing key pair to be used with the EC2 instance. If you have created a new key pair, download the key pair. If you have chosen an existing key pair, make sure you have the key pair accessible. Click on **Launch Instances**.
     {{< img "/img/os/Rancher_aws3.png" "RancherOS on AWS 3">}}
@@ -15,7 +15,7 @@ To start a RancherOS Droplet on Digital Ocean:
 1. Click **Create Droplet.**
 1. Click the **Container distributions** tab.
 1. Click **RancherOS.**
-1. Choose a plan. Make sure your Droplet has the [minimum hardware requirements for RancherOS]({{< baseurl >}}os/v1.x/en/overview/#hardware-requirements).
+1. Choose a plan. Make sure your Droplet has the [minimum hardware requirements for RancherOS]({{<baseurl>}}os/v1.x/en/overview/#hardware-requirements).
 1. Choose any options for backups, block storage, and datacenter region.
 1. Optional: In the **Select additional options** section, you can check the **User data** box and enter a `cloud-config` file in the text box that appears. The `cloud-config` file is used to provide a script to be run on the first boot. An example is below.
 1. Choose an SSH key that you have access to, or generate a new SSH key.
@@ -3,7 +3,7 @@ title: Google Compute Engine (GCE)
 weight: 106
 ---

-> **Note:** Due to the maximum transmission unit (MTU) of [1460 bytes on GCE](https://cloud.google.com/compute/docs/troubleshooting#packetfragmentation), you will need to configure your [network interfaces]({{< baseurl >}}/os/v1.x/en/installation/networking/interfaces/) and both the [Docker and System Docker]({{< baseurl >}}/os/v1.x/en/installation/configuration/docker/) to use a MTU of 1460 bytes or you will encounter weird networking related errors.
+> **Note:** Due to the maximum transmission unit (MTU) of [1460 bytes on GCE](https://cloud.google.com/compute/docs/troubleshooting#packetfragmentation), you will need to configure your [network interfaces]({{<baseurl>}}/os/v1.x/en/installation/networking/interfaces/) and both the [Docker and System Docker]({{<baseurl>}}/os/v1.x/en/installation/configuration/docker/) to use a MTU of 1460 bytes or you will encounter weird networking related errors.

 ### Adding the RancherOS Image into GCE

@@ -26,7 +26,7 @@ $ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_

 ### Using a Cloud Config File with GCE

-If you want to pass in your own cloud config file that will be processed by [cloud init]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), you can pass it as metadata upon creation of the instance during the `gcloud compute` command. The file will need to be stored locally before running the command. The key of the metadata will be `user-data` and the value is the location of the file. If any SSH keys are added in the cloud config file, it will also be added to the **rancher** user.
+If you want to pass in your own cloud config file that will be processed by [cloud init]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config), you can pass it as metadata upon creation of the instance during the `gcloud compute` command. The file will need to be stored locally before running the command. The key of the metadata will be `user-data` and the value is the location of the file. If any SSH keys are added in the cloud config file, it will also be added to the **rancher** user.

 ```
 $ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_INSTANCE> <INSTANCE_NAME> --image <PRIVATE_IMAGE_NAME> --metadata-from-file user-data=/Directory/of/Cloud_Config.yml
@@ -74,11 +74,11 @@ Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF
 After the image is uploaded, it's easy to use the console to create new instances. You will **not** be able to upload your own cloud config file when creating instances through the console. You can add it after the instance is created using `gcloud compute` commands and resetting the instance.

 1. Make sure you are in the project that the image was created in.
-    ![RancherOS on GCE 4]({{< baseurl >}}/img/os/Rancher_gce4.png)
+    ![RancherOS on GCE 4]({{<baseurl>}}/img/os/Rancher_gce4.png)
 2. In the navigation bar, click on the **VM instances**, which is located at Compute -> Compute Engine -> Metadata.  Click on **Create instance**.
-    ![RancherOS on GCE 5]({{< baseurl >}}/img/os/Rancher_gce5.png)
+    ![RancherOS on GCE 5]({{<baseurl>}}/img/os/Rancher_gce5.png)
 2.  Fill out the information for your instance. In the **Image** dropdown, your private image will be listed among the public images provided by Google. Select the private image for RancherOS. Click **Create**.
-    ![RancherOS on GCE 6]({{< baseurl >}}/img/os/Rancher_gce6.png)
+    ![RancherOS on GCE 6]({{<baseurl>}}/img/os/Rancher_gce6.png)
 3. Your instance is being created and will be up and running shortly!

 #### Adding SSH keys
@@ -89,7 +89,7 @@ In order to SSH into the GCE instance, you will need to have SSH keys set up in

 In your project, click on **Metadata**, which is located within Compute -> Compute Engine -> Metadata. Click on **SSH Keys**.

-![RancherOS on GCE 7]({{< baseurl >}}/img/os/Rancher_gce7.png)
+![RancherOS on GCE 7]({{<baseurl>}}/img/os/Rancher_gce7.png)

 Add the SSH keys that you want to have access to any instances within your project.

@@ -99,11 +99,11 @@ Note: If you do this after any RancherOS instance is created, you will need to r

 After your instance is created, click on the instance name. Scroll down to the **SSH Keys** section and click on **Add SSH key**. This key will only be applicable to the instance.

-![RancherOS on GCE 8]({{< baseurl >}}/img/os/Rancher_gce8.png)
+![RancherOS on GCE 8]({{<baseurl>}}/img/os/Rancher_gce8.png)

 After the SSH keys have been added, you'll need to reset the machine, by clicking **Reset**.

-![RancherOS on GCE 9]({{< baseurl >}}/img/os/Rancher_gce9.png)
+![RancherOS on GCE 9]({{<baseurl>}}/img/os/Rancher_gce9.png)

 After a little bit, you will be able to SSH into the box using the **rancher** user.

@@ -5,4 +5,4 @@ weight: 109

 As of v0.5.0, RancherOS releases include an Openstack image that can be found on our [releases page](https://github.com/rancher/os/releases). The image format is [QCOW3](https://wiki.qemu.org/Features/Qcow3#Fully_QCOW2_backwards-compatible_feature_set) that is backward compatible with QCOW2.

-When launching an instance using the image, you must enable **Advanced Options** -> **Configuration Drive** and in order to use a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file.
+When launching an instance using the image, you must enable **Advanced Options** -> **Configuration Drive** and in order to use a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file.
@@ -3,7 +3,7 @@ title: Installing to Disk
 weight: 111
 ---

-RancherOS comes with a simple installer that will install RancherOS on a given target disk. To install RancherOS on a new disk, you can use the `ros install` command. Before installing, you'll need to have already [booted RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso). Please be sure to pick the `rancheros.iso` from our release [page](https://github.com/rancher/os/releases).
+RancherOS comes with a simple installer that will install RancherOS on a given target disk. To install RancherOS on a new disk, you can use the `ros install` command. Before installing, you'll need to have already [booted RancherOS from ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso). Please be sure to pick the `rancheros.iso` from our release [page](https://github.com/rancher/os/releases).

 ### Using `ros install` to Install RancherOS

@@ -11,7 +11,7 @@ The `ros install` command orchestrates the installation from the `rancher/os` co

 #### Cloud-Config

-The easiest way to log in is to pass a `cloud-config.yml` file containing your public SSH keys. To learn more about what's supported in our cloud-config, please read our [documentation]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+The easiest way to log in is to pass a `cloud-config.yml` file containing your public SSH keys. To learn more about what's supported in our cloud-config, please read our [documentation]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 The `ros install` command will process your `cloud-config.yml` file specified with the `-c` flag. This file will also be placed onto the disk and installed to `/var/lib/rancher/conf/`. It will be evaluated on every boot.

@@ -61,7 +61,7 @@ Status: Downloaded newer image for rancher/os:v0.5.0
 Continue with reboot [y/N]:
 ```

-After installing RancherOS to disk, you will no longer be automatically logged in as the `rancher` user. You'll need to have added in SSH keys within your [cloud-config file]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+After installing RancherOS to disk, you will no longer be automatically logged in as the `rancher` user. You'll need to have added in SSH keys within your [cloud-config file]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).

 #### Installing a Different Version

@@ -63,11 +63,11 @@ Valid cloud-init datasources for RancherOS.
 | cmdline | Kernel command line: `cloud-config-url=http://link/user_data` |
 | configdrive | /media/config-2 |
 | url | URL address |
-| vmware| Set `guestinfo` cloud-init or interface data as per [VMware ESXi]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi) |
+| vmware| Set `guestinfo` cloud-init or interface data as per [VMware ESXi]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi) |
 | * | This will add ["configdrive", "vmware", "ec2", "digitalocean", "packet", "gce"] into the list of datasources to try |

 The vmware datasource was added as of v1.1.

 ### Cloud-Config

-When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config).
+When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).
@@ -5,7 +5,7 @@ weight: 113

 As of v0.5.0, RancherOS releases include a Raspberry Pi image that can be found on our [releases page](https://github.com/rancher/os/releases). The official Raspberry Pi documentation contains instructions on how to [install operating system images](https://www.raspberrypi.org/documentation/installation/installing-images/).

-When installing, there is no ability to pass in a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes.
+When installing, there is no ability to pass in a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes.

 Currently, only Raspberry Pi 3 is tested and known to work.

@@ -13,8 +13,8 @@ VMware     | [rancheros-vmware.iso](https://releases.rancher.com/os/latest/vmwar
 Hyper-V    | [rancheros-hyperv.iso](https://releases.rancher.com/os/latest/hyperv/rancheros.iso)
 Proxmox VE | [rancheros-proxmoxve.iso](https://releases.rancher.com/os/latest/proxmoxve/rancheros.iso)

-You must boot with enough memory which you can refer to [here]({{< baseurl >}}/os/v1.x/en/overview/#hardware-requirements). If you boot with the ISO, you will automatically be logged in as the `rancher` user. Only the ISO is set to use autologin by default. If you run from a cloud or install to disk, SSH keys or a password of your choice is expected to be used.
+You must boot with enough memory which you can refer to [here]({{<baseurl>}}/os/v1.x/en/overview/#hardware-requirements). If you boot with the ISO, you will automatically be logged in as the `rancher` user. Only the ISO is set to use autologin by default. If you run from a cloud or install to disk, SSH keys or a password of your choice is expected to be used.

 ### Install to Disk

-After you boot RancherOS from ISO, you can follow the instructions [here]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) to install RancherOS to a hard disk.
+After you boot RancherOS from ISO, you can follow the instructions [here]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) to install RancherOS to a hard disk.
@@ -4,7 +4,7 @@ weight: 101
 ---

 Before we get started, you'll need to make sure that you have docker machine installed. Download it directly from the docker machine [releases](https://github.com/docker/machine/releases). 
-You also need to know the [memory requirements]({{< baseurl >}}/os/v1.x/en/#hardware-requirements).
+You also need to know the [memory requirements]({{<baseurl>}}/os/v1.x/en/#hardware-requirements).

 > **Note:** If you create a RancherOS instance using Docker Machine, you will not be able to upgrade your version of RancherOS.

@@ -116,7 +116,7 @@ Logging into RancherOS follows the standard Docker Machine commands. To login in
 $ docker-machine ssh <MACHINE-NAME>
 ```

-You'll be logged into RancherOS and can start exploring the OS, This will log you into the RancherOS VM. You'll then be able to explore the OS by [adding system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/), [customizing the configuration]({{< baseurl >}}/os/v1.x/en/installation/configuration/), and launching containers.
+You'll be logged into RancherOS and can start exploring the OS, This will log you into the RancherOS VM. You'll then be able to explore the OS by [adding system services]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/), [customizing the configuration]({{<baseurl>}}/os/v1.x/en/installation/configuration/), and launching containers.

 If you want to exit out of RancherOS, you can exit by pressing `Ctrl+D`.

@@ -3,7 +3,7 @@ title: Additional Mounts
 weight: 161
 ---

-Additional mounts can be specified as part of your [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`.
+Additional mounts can be specified as part of your [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`.

 ```yaml
 #cloud-config
@@ -13,7 +13,7 @@ rancher:
    dev: LABEL=RANCHER_STATE
 ```

-For other labels such as `RANCHER_BOOT` and `RANCHER_OEM` and `RANCHER_SWAP`, please refer to [Custom partition layout]({{< baseurl >}}/os/v1.x/en/about/custom-partition-layout/).
+For other labels such as `RANCHER_BOOT` and `RANCHER_OEM` and `RANCHER_SWAP`, please refer to [Custom partition layout]({{<baseurl>}}/os/v1.x/en/about/custom-partition-layout/).

 ### Autoformat

@@ -3,7 +3,7 @@ title: Custom System Services
 weight: 141
 ---

-You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS.
+You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS.

 ### Launching Services through Cloud-Config

@@ -25,11 +25,11 @@ VMWare     | 1GB                       | 1280MB (rancheros.iso) <br> 2048MB (ran
 GCE        | 1GB                       | 1280MB
 AWS        | 1GB                       | 1.7GB

-You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)
+You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)

 ### How RancherOS Works

-Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/).
+Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/).

 System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers and ensures that normal user commands don’t impact system services.

@@ -39,7 +39,7 @@ System Docker runs a special container called **Docker**, which is another Docke

 ### Running RancherOS

-To get started with RancherOS, head over to our [Quick Start Guide]({{< baseurl >}}/os/v1.x/en/quick-start-guide/).
+To get started with RancherOS, head over to our [Quick Start Guide]({{<baseurl>}}/os/v1.x/en/quick-start-guide/).

 ### Latest Release

@@ -3,7 +3,7 @@ title: Quick Start
 weight: 1
 ---

-If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) and show you some of what RancherOS can do.
+If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) and show you some of what RancherOS can do.

 ### Launching RancherOS using Docker Machine

@@ -120,7 +120,7 @@ $ sudo ros config get rancher.network.dns.nameservers
 ```


-When using the native Busybox console, any changes to the console will be lost after reboots, only changes to `/home` or `/opt` will be persistent. You can use the `ros console switch` command to switch to a [persistent console]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence) and replace the native Busybox console. For example, to switch to the Ubuntu console:
+When using the native Busybox console, any changes to the console will be lost after reboots, only changes to `/home` or `/opt` will be persistent. You can use the `ros console switch` command to switch to a [persistent console]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence) and replace the native Busybox console. For example, to switch to the Ubuntu console:

 ```
 $ sudo ros console switch ubuntu
@@ -9,7 +9,7 @@ Since RancherOS is a kernel and initrd, the upgrade process is downloading a new

 Before upgrading to any version, please review the release notes on our [releases page](https://github.com/rancher/os/releases) in GitHub to review any updates in the release.

-> **Note:** If you are using [`docker-machine`]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) then you will not be able to upgrade your RancherOS version. You need to delete and re-create the machine.
+> **Note:** If you are using [`docker-machine`]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) then you will not be able to upgrade your RancherOS version. You need to delete and re-create the machine.


 ### Version Control
@@ -64,7 +64,7 @@ $ sudo ros -v
 ros version v0.5.0
 ```

-> **Note:** If you are booting from ISO and have not installed to disk, your upgrade will not be saved. You can view our guide to [installing to disk]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/).
+> **Note:** If you are booting from ISO and have not installed to disk, your upgrade will not be saved. You can view our guide to [installing to disk]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/).

 #### Upgrading to a Specific Version

@@ -114,7 +114,7 @@ ros version 0.4.4

 <br>

-> **Note:** If you are using a [persistent console]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence) and in the current version's console, rolling back is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.
+> **Note:** If you are using a [persistent console]({{<baseurl>}}/os/v1.x/en/installation/custom-builds/custom-console/#console-persistence) and in the current version's console, rolling back is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.

 ### Staging an Upgrade

@@ -8,13 +8,14 @@ insertOneSix: true
 weight: 1
 ctaBanner: intro-k8s-rancher-online-training
 ---
+Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2.x exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.

-# What's New?
+Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.

-Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher now exclusively deploys and manages multiple Kubernetes clusters running anywhere, on any provider. It can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or inherit existing Kubernetes clusters running anywhere.
+One Rancher server installation can manage hundreds of Kubernetes clusters and thousands of nodes from the same user interface.

-One Rancher server installation can manage hundreds of Kubernetes clusters from the same interface.
+Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.

-Rancher adds significant value on top of Kubernetes, first by centralizing role-based access control (RBAC) for all of the clusters and giving global admins the ability to control cluster access from one location. It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes a pipeline engine to help you automatically deploy and upgrade workloads.
+It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes a pipeline engine to help you automatically deploy and upgrade workloads.

-Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.
+Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.
@@ -9,7 +9,7 @@ aliases:
  - /rancher/v2.x/en/admin-settings/log-in/
 ---

-After installation, the [system administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.
+After installation, the [system administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.

 ## First Log In

@@ -21,7 +21,7 @@ After you log into Rancher for the first time, Rancher will prompt you for a **R

 One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.

-For more information how authentication works and how to configure each provider, see [Authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/).
+For more information how authentication works and how to configure each provider, see [Authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/).

 ## Authorization

@@ -33,13 +33,13 @@ For more information how authorization works and how to customize roles, see [Ro

 _Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.

-For more information how to create and use PSPs, see [Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
+For more information how to create and use PSPs, see [Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/).

 ## Provisioning Drivers

-Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
+Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.

-For more information, see [Provisioning Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/).
+For more information, see [Provisioning Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/).

 ## Adding Kubernetes Versions into Rancher

@@ -47,9 +47,9 @@ _Available as of v2.3.0_

 With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions.

-The information that Rancher uses to provision [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata/)
+The information that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata/)

-Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
+Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).

 For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata/).

@@ -7,11 +7,11 @@ aliases:

 If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.

-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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/openldap) integration.
+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]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap) integration.

 > **Note:**
 >
-> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).

 ## Prerequisites

@@ -196,4 +196,4 @@ In the same way, we can observe that the value in the **memberOf** attribute in

 ## Annex: Troubleshooting

-If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
+If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
@@ -41,13 +41,11 @@ Before enabling Azure AD within Rancher, you must register Rancher with Azure.

 1. Use search to open the **App registrations** service.

-    ![Open App Registrations]({{< baseurl >}}/img/rancher/search-app-registrations.png)
+    ![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)

 1. Click **New registrations** and complete the **Create** form.

-    ![New App Registration]({{< baseurl >}}/img/rancher/new-app-registration-1.png)
-
-    ![New App Registration Register]({{< baseurl >}}/img/rancher/new-app-registration-2.png)
+    ![New App Registration]({{<baseurl>}}/img/rancher/new-app-registration.png)

    1. Enter a **Name** (something like `Rancher`).

@@ -67,7 +65,7 @@ From the Azure portal, create a client secret. Rancher will use this key to auth

 1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure.

-     ![Open Rancher Registration]({{< baseurl >}}/img/rancher/open-rancher-app.png)
+     ![Open Rancher Registration]({{<baseurl>}}/img/rancher/open-rancher-app.png)

 1. From the navigation pane on left, click **Certificates and Secrets**.

@@ -94,7 +92,7 @@ Next, set API permissions for Rancher within Azure.

 1. From the navigation pane on left, select **API permissions**.

-    ![Open API Permissions]({{< baseurl >}}/img/rancher/select-required-permissions-1.png)
+    ![Open Required Permissions]({{<baseurl>}}/img/rancher/select-required-permissions.png)

 1. Click **Add a permission**.

@@ -117,13 +115,35 @@ Next, set API permissions for Rancher within Azure.

    >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings.

-### 4. Copy Azure Application Data
+
+### 4. Add a Reply URL
+
+To use Azure AD with Rancher you must whitelist Rancher with Azure. You can complete this whitelisting by providing Azure with a reply URL for Rancher, which is your Rancher Server URL followed with a verification path.
+
+
+1. From the **Setting** blade, select **Reply URLs**.
+
+    ![Azure: Enter Reply URL]({{<baseurl>}}/img/rancher/enter-azure-reply-url.png)
+
+1. From the **Reply URLs** blade, enter the URL of your Rancher Server, appended with the verification path: `<MY_RANCHER_URL>/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).
+
+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.
+
+### 5. Copy Azure Application Data

 As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.

 1. Obtain your Rancher **Tenant ID**.

-    1. From **App registrations** select the app configured above.
+    1. Use search to open the **Azure Active Directory** service.
+
+         ![Open Azure Active Directory]({{<baseurl>}}/img/rancher/search-azure-ad.png)

    1. From the left navigation pane, open **Overview**.

@@ -135,7 +155,7 @@ As your final step in Azure, copy the data that you'll use to configure Rancher

    1. Use search to open **App registrations**.

-         ![Open App Registrations]({{< baseurl >}}/img/rancher/search-app-registrations.png)
+         ![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)

    1. Find the entry you created for Rancher.

@@ -145,7 +165,7 @@ As your final step in Azure, copy the data that you'll use to configure Rancher

    1. From **App registrations**, click **Endpoints**.

-        ![Click Endpoints]({{< baseurl >}}/img/rancher/click-endpoints.png)
+        ![Click Endpoints]({{<baseurl>}}/img/rancher/click-endpoints.png)

    2. Copy the following endpoints to your clipboard and paste them into your [text file](#tip) (these values will be your Rancher endpoint values).
    
@@ -13,7 +13,7 @@ If your organization uses FreeIPA for user authentication, you can configure Ran
 >
 >- 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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+>- Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/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_).

@@ -7,7 +7,7 @@ aliases:

 In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.

->**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+>**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/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_).

@@ -65,7 +65,7 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati

 ## Annex: Troubleshooting

-If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
+If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.

 ### You are not redirected to Keycloak

@@ -27,10 +27,10 @@ If your organization uses Microsoft Active Directory Federation Services (AD FS)

 Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.

- [1 — Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
- [2 — Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)
+- [1 — Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
+- [2 — Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)

 {{< saml_caveats >}}


-### [Next: Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
+### [Next: Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
@@ -79,4 +79,4 @@ https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

 **Result:** You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.

-### [Next: Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
+### [Next: Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
@@ -4,7 +4,7 @@ weight: 1205
 ---
 _Available as of v2.0.7_

-After you complete [Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/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.
+After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/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 AD FS Server:**
 > 
@@ -8,17 +8,6 @@ aliases:
 _Available as of v2.0.5_

 If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI. 
- 
-## OpenLDAP Authentication Flow 
- 
-1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes. 
-2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings. 
-3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password. 
-4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.
-
-> **Note:**
-> 
-> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).

 ## Prerequisites

@@ -28,81 +17,16 @@ Rancher must be configured with a LDAP bind account (aka service account) to sea
 >
 > If the certificate used by the OpenLDAP server is self-signed or not from a recognised 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.

-## Configuration Steps
-### Open OpenLDAP Configuration
+## Configure OpenLDAP in Rancher
+
+Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](../openldap-config)
+
+> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).

 1. Log into the Rancher UI using the initial local `admin` account.
 2. From the **Global** view, navigate to **Security** > **Authentication**
 3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.

-### Configure OpenLDAP Server Settings
-
-In the section titled `1. Configure an OpenLDAP server`,   complete the fields with the information specific to your server. Please refer to the following table for detailed information on the required values for each parameter.
-
-> **Note:**
->
-> If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
-
-**Table 1: OpenLDAP server parameters**
-
-| Parameter | Description |
-|:--|:--|
-| Hostname | Specify the hostname or IP address of the OpenLDAP server |
-| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
-| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
-| Server Connection Timeout | 	The duration in number of seconds that Rancher waits before considering the server unreachable. |
-| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). |
-| Service Account Password | The password for the service account.  |
-| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
-| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|
-
---
-
-### Configure User/Group Schema
-
-If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
-Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
-
-> **Note:**
->
-> If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
-
-#### User Schema
-
-The table below details the parameters for the user schema configuration.
-
-**Table 2: User schema configuration parameters**
-
-| Parameter | Description |
-|:--|:--|
-| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
-| Username Attribute | The user attribute whose value is suitable as a display name. |
-| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. |
-| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. |
-| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. |
-| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
-| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
-
---
-
-#### Group Schema
-
-The table below details the parameters for the group schema configuration.
-
-**Table 3: Group schema configuration parameters**
-
-| Parameter | Description |
-|:--|:--|
-| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
-| Name Attribute | The group attribute whose value is suitable for a display name. |
-| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
-| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
-| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
-| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See  `User Member Attribute`. |
-| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). |
-
---
-
 ### Test Authentication

 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.
@@ -125,4 +49,4 @@ Once you have completed the configuration, proceed by testing  the connection to

 ## Annex: Troubleshooting

-If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
+If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
@@ -0,0 +1,86 @@
+---
+title: OpenLDAP Configuration Reference
+weight: 2
+---
+
+This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.
+
+For further details on configuring OpenLDAP, refer to the [official documentation.](https://www.openldap.org/doc/)
+
+> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+
+- [Background: OpenLDAP Authentication Flow](#background-openldap-authentication-flow)
+- [OpenLDAP server configuration](#openldap-server-configuration)
+- [User/group schema configuration](#user-group-schema-configuration)
+  - [User schema configuration](#user-schema-configuration)
+  - [Group schema configuration](#group-schema-configuration)
+
+## Background: OpenLDAP Authentication Flow 
+ 
+1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes. 
+2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings. 
+3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password. 
+4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.
+
+# OpenLDAP Server Configuration
+
+You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic.
+
+> **Using TLS?**
+>
+> If the certificate used by the OpenLDAP 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.
+
+If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
+
+<figcaption>OpenLDAP Server Parameters</figcaption>
+
+| Parameter | Description |
+|:--|:--|
+| Hostname | Specify the hostname or IP address of the OpenLDAP server |
+| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
+| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
+| Server Connection Timeout | 	The duration in number of seconds that Rancher waits before considering the server unreachable. |
+| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). |
+| Service Account Password | The password for the service account.  |
+| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
+| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|
+
+# User/Group Schema Configuration
+
+If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
+
+Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
+
+If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
+
+### User Schema Configuration
+
+The table below details the parameters for the user schema configuration.
+
+<figcaption>User Schema Configuration Parameters</figcaption>
+
+| Parameter | Description |
+|:--|:--|
+| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
+| Username Attribute | The user attribute whose value is suitable as a display name. |
+| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. |
+| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. |
+| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. |
+| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
+| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
+
+### Group Schema Configuration
+
+The table below details the parameters for the group schema configuration.
+
+<figcaption>Group Schema Configuration Parameters<figcaption>
+
+| Parameter | Description |
+|:--|:--|
+| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
+| Name Attribute | The group attribute whose value is suitable for a display name. |
+| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
+| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
+| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
+| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See  `User Member Attribute`. |
+| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth. |
@@ -0,0 +1,109 @@
+---
+title: Configuring Shibboleth (SAML)
+weight: 1210
+---
+
+_Available as of v2.4.0_
+
+If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.
+
+In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.
+
+If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.
+
+> The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](./about)
+
+This section covers the following topics:
+
+- [Setting up Shibboleth in Rancher](#setting-up-shibboleth-in-rancher)
+  - [Shibboleth Prerequisites](#shibboleth-prerequisites)
+  - [Configure Shibboleth in Rancher](#configure-shibboleth-in-rancher)
+  - [SAML Provider Caveats](#saml-provider-caveats)
+- [Setting up OpenLDAP in Rancher](#setting-up-openldap-in-rancher)
+  - [OpenLDAP Prerequisites](#openldap-prerequisites)
+  - [Configure OpenLDAP in Rancher](#configure-openldap-in-rancher)
+  - [Troubleshooting](#troubleshooting)
+
+# Setting up Shibboleth in Rancher
+
+### Shibboleth Prerequisites
+>
+>- You must have a Shibboleth IdP Server configured.
+>- Following are the Rancher Service Provider URLs needed for configuration:
+Metadata URL: `https://<rancher-server>/v1-saml/shibboleth/saml/metadata`
+Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/shibboleth/saml/acs`
+>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home)
+
+### Configure Shibboleth in Rancher
+If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
+
+1.	From the **Global** view, select **Security > Authentication** from the main menu.
+
+1.	Select **Shibboleth**.
+
+1.	Complete the **Configure Shibboleth Account** form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
+
+    1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
+
+	1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
+
+    1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
+
+    1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
+
+    1. **Rancher API Host**: Enter the URL for your Rancher Server.
+
+	1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
+
+        You can generate one 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"
+        ```
+    1. **IDP-metadata**: The `metadata.xml` file that you exported from your IdP server.
+
+
+1. After you complete the **Configure Shibboleth Account** form, click **Authenticate with Shibboleth**, which is at the bottom of the page.
+
+    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.
+
+**Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.
+
+### SAML Provider Caveats
+
+If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.
+
+- There is no validation on users or groups when assigning permissions to them in Rancher.
+- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
+- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
+- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
+
+To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.
+
+# Setting up OpenLDAP in Rancher
+
+If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.
+
+### OpenLDAP Prerequisites
+
+Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
+
+> **Using TLS?**
+>
+> If the certificate used by the OpenLDAP 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.
+
+### Configure OpenLDAP in Rancher
+
+Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config) Note that nested group membership is not available for Shibboleth.
+
+> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+
+1. Log into the Rancher UI using the initial local `admin` account.
+2. From the **Global** view, navigate to **Security** > **Authentication**
+3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
+
+# Troubleshooting
+
+If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
@@ -0,0 +1,34 @@
+---
+title: Group Permissions with Shibboleth and OpenLDAP
+weight: 1
+---
+
+_Available as of Rancher v2.4_
+
+This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher. 
+
+Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.
+
+One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.
+
+### Terminology
+
+- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
+- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
+- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
+- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider.
+
+### Adding OpenLDAP Group Permissions to Rancher Resources
+
+The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.
+
+For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.
+
+In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.
+
+When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.
+
+Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.
+
+![Adding OpenLDAP Group Permissions to Rancher Resources]({{<baseurl>}}/img/rancher/shibboleth-with-openldap-groups.svg)
+ 
@@ -5,11 +5,11 @@ weight: 1

 Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.

-Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).
+Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/).

 ## Managing Members

-When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/local/) user account, you will not be able to search for GitHub users or groups.
+When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/local/) user account, you will not be able to search for GitHub users or groups.

 All users, whether they are local users or from an authentication provider, can be viewed and managed. From the **Global** view, click on **Users**.

@@ -3,7 +3,7 @@ title: Provisioning Drivers
 weight: 1140
 ---

-Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
+Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.

 ###  Rancher Drivers

@@ -18,19 +18,19 @@ There are two types of drivers within Rancher:

 _Available as of v2.2.0_

-Cluster drivers are used to provision [hosted Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.
+Cluster drivers are used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.

 By default, Rancher has activated several hosted Kubernetes cloud providers including:

-*  [Amazon EKS]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/)
-*  [Google GKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/)
-*  [Azure AKS]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/)
+*  [Amazon EKS]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/)
+*  [Google GKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/)
+*  [Azure AKS]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/)

 There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:

-* [Alibaba ACK]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/)
-* [Huawei CCE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/)
-* [Tencent]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/)
+* [Alibaba ACK]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/)
+* [Huawei CCE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/)
+* [Tencent]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/)

 ## Node Drivers

@@ -40,7 +40,7 @@ If there are specific node drivers that you don't want to show to your users, yo

 Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:

-*   [Amazon EC2]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/)
-*   [Azure]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/)
-*   [Digital Ocean]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/)
-*   [vSphere]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/)
+*   [Amazon EC2]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/)
+*   [Azure]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/)
+*   [Digital Ocean]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/)
+*   [vSphere]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/)
@@ -5,7 +5,7 @@ weight: 1

 _Available as of v2.2.0_

-Cluster drivers are used to create clusters in a [hosted Kubernetes provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.
+Cluster drivers are used to create clusters in a [hosted Kubernetes provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.

 If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.

@@ -13,8 +13,8 @@ If there are specific cluster drivers that you do not want to show your users, y

 >**Prerequisites:** To create, edit, or delete cluster drivers, you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.

 ## Activating/Deactivating Cluster Drivers

@@ -14,8 +14,8 @@ If there are specific node drivers that you don't want to show to your users, yo

 >**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.

 ## Activating/Deactivating Node Drivers

@@ -73,10 +73,10 @@ Rancher ships with two default Pod Security Policies (PSPs): the `restricted` an

 You can add a Pod Security Policy (PSPs hereafter) in the following contexts:

- [When creating a cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/)
- [When editing an existing cluster]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/)
- [When creating a project]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#creating-a-project/)
- [When editing an existing project]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/)
+- [When creating a cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/)
+- [When editing an existing cluster]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/)
+- [When creating a project]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#creating-a-project/)
+- [When editing an existing project]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/)

 > **Note:** We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.

@@ -5,7 +5,7 @@ aliases:
    - /rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/
 ---

-Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/), users can either be local or external.
+Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/), users can either be local or external.

 After you configure external authentication, the users that display on the **Users** page changes.

@@ -17,11 +17,11 @@ After you configure external authentication, the users that display on the **Use

 Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by _global permissions_, and _cluster and project roles_.  

- [Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/):
+- [Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/):

    Define user authorization outside the scope of any particular cluster.

- [Cluster and Project Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/):
+- [Cluster and Project Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/):

    Define user authorization inside the specific cluster or project where they are assigned the role.

@@ -140,7 +140,7 @@ By default, when a standard user creates a new cluster or project, they are auto

 There are two methods for changing default cluster/project roles:

- **Assign Custom Roles**: Create a [custom role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles) for either your [cluster](#custom-cluster-roles) or [project](#custom-project-roles), and then set the custom role as default.
+- **Assign Custom Roles**: Create a [custom role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles) for either your [cluster](#custom-cluster-roles) or [project](#custom-project-roles), and then set the custom role as default.

 - **Assign Individual Roles**: Configure multiple [cluster](#cluster-role-reference)/[project](#project-role-reference) roles as default for assignment to the creating user.

@@ -148,7 +148,7 @@ There are two methods for changing default cluster/project roles:

 >**Note:**
 >
->- Although you can [lock]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/) a default role, the system still assigns the role to users who create a cluster/project.
+>- Although you can [lock]({{<baseurl>}}/rancher/v2.x/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
@@ -22,8 +22,8 @@ This section covers the following topics:

 To complete the tasks on this page, one of the following permissions are required:

- - [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/).
- - [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
+ - [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/).
+ - [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.

 ## Creating A Custom Role for a Cluster or Project

@@ -68,7 +68,7 @@ The steps to add custom roles differ depending on the version of Rancher.

 1.  **Name** the role.

-1.  Choose whether to set the role to a status of [locked]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/).
+1.  Choose whether to set the role to a status of [locked]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/).

    > **Note:** Locked roles cannot be assigned to users.

@@ -95,7 +95,7 @@ The steps to add custom roles differ depending on the version of Rancher.

 ## Creating a Custom Global Role that Copies Rules from an Existing Role

-_Available as of v2.4.0-alpha1_
+_Available as of v2.4.0_

 If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.

@@ -112,7 +112,7 @@ To create a custom global role based on an existing role,

 ## Creating a Custom Global Role that Does Not Copy Rules from Another Role

-_Available as of v2.4.0-alpha1_
+_Available as of v2.4.0_

 Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:

@@ -125,7 +125,7 @@ Custom global roles don't have to be based on existing roles. To create a custom

 ## Deleting a Custom Global Role

-_Available as of v2.4.0-alpha1_
+_Available as of v2.4.0_

 When deleting a custom global role, all global role bindings with this custom role are deleted.

@@ -141,7 +141,7 @@ To delete a custom global role,

 ## Assigning a Custom Global Role to a Group

-_Available as of v2.4.0-alpha1_
+_Available as of v2.4.0_

 If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.

@@ -43,7 +43,7 @@ To see the default permissions for new users, go to the **Global** view and clic

 Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users)

-As of Rancher v2.4.0-alpha1, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups.
+As of Rancher v2.4.0, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups.

 # Custom Global Permissions

@@ -128,7 +128,7 @@ To configure permission for a user,

 ### Configuring Global Permissions for Groups

-_Available as of v2.4.0-alpha1_
+_Available as of v2.4.0_

 If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.

@@ -27,7 +27,7 @@ If you want to prevent a role from being assigned to users, you can set it to a

 You can lock roles in two contexts:

- When you're [adding a custom role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
+- When you're [adding a custom role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
 - When you editing an existing role (see below).

 1. From the **Global** view, select **Security** > **Roles**.
@@ -5,11 +5,11 @@ weight: 7500

 ## How to use the API

-The API has its own user interface accessible from a web browser.  This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response.  To access it, click on your user avatar in the upper right corner. Under **API & Keys**, you can find the URL endpoint as well as create [API keys]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys/).
+The API has its own user interface accessible from a web browser.  This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response.  To access it, click on your user avatar in the upper right corner. Under **API & Keys**, you can find the URL endpoint as well as create [API keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/).

 ## Authentication

-API requests must include authentication information.  Authentication is done with HTTP basic authentication using [API Keys]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys/). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
+API requests must include authentication information.  Authentication is done with HTTP basic authentication using [API Keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.

 By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page]({{<baseurl>}}/rancher/v2.x/en/api/api-tokens).

@@ -5,14 +5,15 @@ weight: 1000

 This section is devoted to protecting your data in a disaster scenario.

-
 To protect yourself from a disaster scenario, you should create backups on a regular basis.

-  - [Rancher Server Backups]({{< baseurl >}}/rancher/v2.x/en/backups/backups)
-  - [Backing up Rancher Launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/)
-
+  - Rancher server backups:
+    - [Rancher installed on a K3s Kubernetes cluster](./backups/k3s-backups)
+    - [Rancher installed on an RKE Kubernetes cluster](./backups/ha-backups)
+    - Rancher installed with Docker
+  - [Backing up Rancher Launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/)

 In a disaster scenario, you can restore your `etcd` database by restoring a backup.

-   - [Rancher Server Restorations]({{< baseurl >}}/rancher/v2.x/en/backups/restorations)
-   - [Restoring Rancher Launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/restoring-etcd/)
+   - [Rancher Server Restorations]({{<baseurl>}}/rancher/v2.x/en/backups/restorations)
+   - [Restoring Rancher Launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/)
@@ -7,7 +7,8 @@ aliases:
 ---
 This section contains information about how to create backups of your Rancher data and how to restore them in a disaster scenario.

- [Docker Install Backups](./single-node-backups/)
- [Kubernetes Install Backups](./ha-backups/)
+- [Backing up Rancher installed on a K3s Kubernetes cluster](./k3s-backups)
+- [Backing up Rancher installed on an RKE Kubernetes cluster](./ha-backups/)
+- [Backing up Rancher installed with Docker](./single-node-backups/)

-If you are looking to back up your [Rancher launched Kubernetes cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/).
+If you are looking to back up your [Rancher launched Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/).
@@ -1,6 +1,6 @@
 ---
-title: Creating Backups for Rancher Installed on Kubernetes
-weight: 50
+title: Backing up Rancher Installed on an RKE Kubernetes Cluster
+weight: 2
 aliases:
  - /rancher/v2.x/en/installation/after-installation/k8s-install-backup-and-restoration/
  - /rancher/v2.x/en/installation/backups-and-restoration/ha-backup-and-restoration/
@@ -9,6 +9,13 @@ This section describes how to create backups of your high-availability Rancher i

 >**Prerequisites:** {{< requirements_rollback >}}

+## RKE Kubernetes Cluster Data
+
+In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.
+
+<figcaption>Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server</figcaption>
+![Architecture of an RKE Kubernetes cluster running the Rancher management server]({{<baseurl>}}/img/rancher/rke-server-storage.svg)
+
 ## Backup Outline

 Backing up your high-availability Rancher cluster is process that involves completing multiple tasks.
@@ -0,0 +1,25 @@
+---
+title: Backing up Rancher Installed on a K3s Kubernetes Cluster
+weight: 1
+---
+
+When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.
+
+The database administrator will need to back up the external database, or restore it from a snapshot or dump.
+
+We recommend configuring the database to take recurring snapshots.
+
+### K3s Kubernetes Cluster Data
+
+One main advantage of this K3s architecture is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.
+
+<figcaption>Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server</figcaption>
+![Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server]({{<baseurl>}}/img/rancher/k3s-server-storage.svg)
+
+### Creating Snapshots and Restoring Databases from Snapshots
+
+For details on taking database snapshots and restoring your database from them, refer to the official database documentation:
+
+- [Official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/replication-snapshot-method.html)
+- [Official PostgreSQL documentation](https://www.postgresql.org/docs/8.3/backup-dump.html)
+- [Official etcd documentation](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/recovery.md)
@@ -1,6 +1,6 @@
 ---
-title: Creating Backups for Rancher Installed with Docker
-weight: 25
+title: Backing up Rancher Installed with Docker
+weight: 3
 aliases:
  - /rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/
 ---
@@ -20,7 +20,7 @@ In this command, `<DATE>` is a placeholder for the date that the data container
 Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup).

 <sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
-![Placeholder Reference]({{< baseurl >}}/img/rancher/placeholder-ref.png)
+![Placeholder Reference]({{<baseurl>}}/img/rancher/placeholder-ref.png)

 | Placeholder                | Example                    | Description                                               |
 | -------------------------- | -------------------------- | --------------------------------------------------------- |
@@ -68,4 +68,4 @@ This procedure creates a backup that you can restore if Rancher encounters a dis
    docker start <RANCHER_CONTAINER_NAME>
    ```

-**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Docker Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/single-node-restoration) if you need to restore backup data.
+**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Docker Installs]({{<baseurl>}}/rancher/v2.x/en/backups/restorations/single-node-restoration) if you need to restore backup data.
@@ -4,7 +4,7 @@ weight: 1010
 ---
 If you lose the data on your Rancher Server, you can restore it if you have backups stored in a safe location.

- [Restoring Backups—Docker Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/single-node-restoration/)
- [Restoring Backups—Kubernetes installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/ha-restoration/)
+- [Restoring Backups—Docker Installs]({{<baseurl>}}/rancher/v2.x/en/backups/restorations/single-node-restoration/)
+- [Restoring Backups—Kubernetes installs]({{<baseurl>}}/rancher/v2.x/en/backups/restorations/ha-restoration/)

-If you are looking to restore your [Rancher launched Kubernetes cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
+If you are looking to restore your [Rancher launched Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
@@ -8,7 +8,7 @@ aliases:

 This procedure describes how to use RKE to restore a snapshot of the Rancher Kubernetes cluster. The cluster snapshot will include Kubernetes configuration and the Rancher database and state.

-Additionally, the `pki.bundle.tar.gz` file usage is no longer required as v0.2.0 has changed how the [Kubernetes cluster state is stored]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state).
+Additionally, the `pki.bundle.tar.gz` file usage is no longer required as v0.2.0 has changed how the [Kubernetes cluster state is stored]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state).

 ## Restore Outline

@@ -24,11 +24,11 @@ Additionally, the `pki.bundle.tar.gz` file usage is no longer required as v0.2.0

 ### 1. Preparation

-You will need [RKE]({{< baseurl >}}/rke/latest/en/installation/) and [kubectl]({{< baseurl >}}/rancher/v2.x/en/faq/kubectl/) CLI utilities installed.
+You will need [RKE]({{<baseurl>}}/rke/latest/en/installation/) and [kubectl]({{<baseurl>}}/rancher/v2.x/en/faq/kubectl/) CLI utilities installed.

-Prepare by creating 3 new nodes to be the target for the restored Rancher instance.  See [Kubernetes Install]({{< baseurl >}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/) for node requirements.
+Prepare by creating 3 new nodes to be the target for the restored Rancher instance.  See [Kubernetes Install]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/) for node requirements.

-We recommend that you start with fresh nodes and a clean state. Alternatively you can clear Kubernetes and Rancher configurations from the existing nodes. This will destroy the data on these nodes. See [Node Cleanup]({{< baseurl >}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) for the procedure.
+We recommend that you start with fresh nodes and a clean state. Alternatively you can clear Kubernetes and Rancher configurations from the existing nodes. This will destroy the data on these nodes. See [Node Cleanup]({{<baseurl>}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) for the procedure.

 > **IMPORTANT:** Before starting the restore make sure all the Kubernetes services on the old cluster nodes are stopped. We recommend powering off the nodes to be sure.

@@ -135,8 +135,8 @@ S3 specific options are only available for RKE v0.2.0+.
 | `--bucket-name` value     |  Specify s3 bucket name | *|
 | `--folder` value |  Specify s3 folder in the bucket name _Available as of v2.3.0_ | *|
 | `--region` value          |  Specify the s3 bucket location (optional) | *|
-| `--ssh-agent-auth`      |   [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{< baseurl >}}/rke/latest/en/config-options/#ssh-agent) | |
-| `--ignore-docker-version`  | [Disable Docker version check]({{< baseurl >}}/rke/latest/en/config-options/#supported-docker-versions) |
+| `--ssh-agent-auth`      |   [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{<baseurl>}}/rke/latest/en/config-options/#ssh-agent) | |
+| `--ignore-docker-version`  | [Disable Docker version check]({{<baseurl>}}/rke/latest/en/config-options/#supported-docker-versions) |

 ### 5. Bring Up the Cluster

@@ -150,7 +150,7 @@ rke up --config ./rancher-cluster-restore.yml

 #### Testing the Cluster

-Once RKE completes it will have created a credentials file in the local directory.  Configure `kubectl` to use the `kube_config_rancher-cluster-restore.yml` credentials file and check on the state of the cluster. See [Installing and Configuring kubectl]({{< baseurl >}}/rancher/v2.x/en/faq/kubectl/#configuration) for details.
+Once RKE completes it will have created a credentials file in the local directory.  Configure `kubectl` to use the `kube_config_rancher-cluster-restore.yml` credentials file and check on the state of the cluster. See [Installing and Configuring kubectl]({{<baseurl>}}/rancher/v2.x/en/faq/kubectl/#configuration) for details.

 Your new cluster will take a few minutes to stabilize. Once you see the new "target node" transition to `Ready` and three old nodes in `NotReady` you are ready to continue.

@@ -232,6 +232,6 @@ rke up --config ./rancher-cluster-restore.yml

 #### Finishing Up

-Rancher should now be running and available to manage your Kubernetes clusters. Review the [recommended architecture]({{< baseurl >}}/rancher/v2.x/en/installation/k8s-install/#recommended-architecture) for Kubernetes installations and update the endpoints for Rancher DNS or the Load Balancer that you built during Step 1 of the Kubernetes install ([1. Create Nodes and Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/#load-balancer)) to target the new cluster. Once the endpoints are updated, the agents on your managed clusters should automatically reconnect. This may take 10-15 minutes due to reconnect back off timeouts.
+Rancher should now be running and available to manage your Kubernetes clusters. Review the [recommended architecture]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/#recommended-architecture) for Kubernetes installations and update the endpoints for Rancher DNS or the Load Balancer that you built during Step 1 of the Kubernetes install ([1. Create Nodes and Load Balancer]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/#load-balancer)) to target the new cluster. Once the endpoints are updated, the agents on your managed clusters should automatically reconnect. This may take 10-15 minutes due to reconnect back off timeouts.

 > **IMPORTANT:** Remember to save your new RKE config (`rancher-cluster-restore.yml`) and `kubectl` credentials (`kube_config_rancher-cluster-restore.yml`) files in a safe place for future maintenance.
@@ -0,0 +1,18 @@
+---
+title: Restoring Rancher Installed on a K3s Kubernetes Cluster
+weight: 1
+---
+
+When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.
+
+The database administrator will need to back up the external database, or restore it from a snapshot or dump.
+
+We recommend configuring the database to take recurring snapshots.
+
+### Creating Snapshots and Restoring Databases from Snapshots
+
+For details on taking database snapshots and restoring your database from them, refer to the official database documentation:
+
+- [Official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/replication-snapshot-method.html)
+- [Official PostgreSQL documentation](https://www.postgresql.org/docs/8.3/backup-dump.html)
+- [Official etcd documentation](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/recovery.md)
@@ -23,7 +23,7 @@ In this command, `<RANCHER_CONTAINER_NAME>` and `<RANCHER_VERSION>-<DATE>` are e
 Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup).

 <sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
-![Placeholder Reference]({{< baseurl >}}/img/rancher/placeholder-ref.png)
+![Placeholder Reference]({{<baseurl>}}/img/rancher/placeholder-ref.png)

 | Placeholder                | Example                    | Description                                               |
 | -------------------------- | -------------------------- | --------------------------------------------------------- |
@@ -37,7 +37,7 @@ You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by loggi

 ## Restoring Backups

-Using a [backup]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/) that you created earlier, restore Rancher to its last known healthy state.
+Using a [backup]({{<baseurl>}}/rancher/v2.x/en/backups/backups/single-node-backups/) that you created earlier, restore Rancher to its last known healthy state.

 1. Using a remote Terminal connection, log into the node running your Rancher Server.

@@ -46,9 +46,9 @@ Using a [backup]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-bac
    ```
    docker stop <RANCHER_CONTAINER_NAME>
    ```
-1. Move the backup tarball that you created during completion of [Creating Backups—Docker Installs]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there.
+1. Move the backup tarball that you created during completion of [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.x/en/backups/backups/single-node-backups/) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there.

-    If you followed the naming convention we suggested in [Creating Backups—Docker Installs]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/), it will have a name similar to  `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
+    If you followed the naming convention we suggested in [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.x/en/backups/backups/single-node-backups/), it will have a name similar to  `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.

 1. Enter the following command to delete your current state data and replace it with your backup data, replacing the [placeholders](#before-you-start). Don't forget to close the quotes.

@@ -11,10 +11,10 @@ Use the navigation bar on the left to find the current best practices for managi

 For more guidance on best practices, you can consult these resources:

- [Rancher Docs]({{< baseurl >}})
-    - [Monitoring]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/)
-    - [Backups and Disaster Recovery]({{< baseurl >}}/rancher/v2.x/en/backups/)
-    - [Security]({{< baseurl >}}/rancher/v2.x/en/security/)
+- [Rancher Docs]({{<baseurl>}})
+    - [Monitoring]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring/)
+    - [Backups and Disaster Recovery]({{<baseurl>}}/rancher/v2.x/en/backups/)
+    - [Security]({{<baseurl>}}/rancher/v2.x/en/security/)
 - [Rancher Blog](https://rancher.com/blog/)
    - [Articles about best practices on the Rancher blog](https://rancher.com/tags/best-practices/)
    - [101 More Security Best Practices for Kubernetes](https://rancher.com/blog/2019/2019-01-17-101-more-kubernetes-security-best-practices/)
@@ -28,11 +28,11 @@ For best performance, run all three of your nodes in the same geographic datacen
 It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration.

 ### Monitor Your Clusters to Plan Capacity
-The Rancher server's Kubernetes cluster should run within the [system and hardware requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements/) as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.
+The Rancher server's Kubernetes cluster should run within the [system and hardware requirements]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/) as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.

 However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types.

 Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus. 

-After you [enable monitoring]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) in the cluster, you can set up [a notification channel]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/notifiers/) and [cluster alerts]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/) to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.
+After you [enable monitoring]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) in the cluster, you can set up [a notification channel]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/notifiers/) and [cluster alerts]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/alerts/) to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.

@@ -10,7 +10,7 @@ Rancher allows you to set up numerous combinations of configurations. Some confi
 These tips can help you solve problems before they happen.

 ### Run Rancher on a Supported OS and Supported Docker Version
-Rancher is container-based and can potentially run on any Linux-based operating system. However, only operating systems listed in the [requirements documentation]({{< baseurl >}}/rancher/v2.x/en/installation/requirements/) should be used for running Rancher, along with a supported version of Docker. These versions have been most thoroughly tested and can be properly supported by the Rancher Support team.
+Rancher is container-based and can potentially run on any Linux-based operating system. However, only operating systems listed in the [requirements documentation]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/) should be used for running Rancher, along with a supported version of Docker. These versions have been most thoroughly tested and can be properly supported by the Rancher Support team.

 ### Upgrade Your Kubernetes Version
 Keep your Kubernetes cluster up to date with a recent and supported version. Typically the Kubernetes community will support the current version and previous three minor releases (for example, 1.14.x, 1.13.x, 1.12.x, and 1.11.x). After a new version is released, the third-oldest supported version reaches EOL (End of Life) status. Running on an EOL release can be a risk if a security issues are found and patches are not available. The community typically makes minor releases every quarter (every three months).
@@ -29,11 +29,11 @@ Rancher [maintains a Terraform provider](https://rancher.com/blog/2019/rancher-2
 All upgrades, both patch and feature upgrades, should be first tested on a staging environment before production is upgraded. The more closely the staging environment mirrors production, the higher chance your production upgrade will be successful.

 ### Renew Certificates Before they Expire
-Multiple people in your organization should set up calendar reminders for certificate renewal. Consider renewing the certificate two weeks to one month in advance. If you have multiple certificates to track, consider using [monitoring and alerting mechanisms]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/) to track certificate expiration.
+Multiple people in your organization should set up calendar reminders for certificate renewal. Consider renewing the certificate two weeks to one month in advance. If you have multiple certificates to track, consider using [monitoring and alerting mechanisms]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/) to track certificate expiration.

 Rancher-provisioned Kubernetes clusters will use certificates that expire in one year. Clusters provisioned by other means may have a longer or shorter expiration.

-Certificates can be renewed for Rancher-provisioned clusters [through the Rancher user interface]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/certificate-rotation/).
+Certificates can be renewed for Rancher-provisioned clusters [through the Rancher user interface]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/certificate-rotation/).

 ### Enable Recurring Snapshots for Backing up and Restoring the Cluster
 Make sure etcd recurring snapshots are enabled. Extend the snapshot retention to a period of time that meets your business needs. In the event of a catastrophic failure or deletion of data, this may be your only recourse for recovery. For details about configuring snapshots, refer to the [RKE documentation]({{<baseurl>}}/rke/latest/en/etcd-snapshots/) or the [Rancher documentation on backups]({{<baseurl>}}/rancher/v2.x/en/backups/).
@@ -78,13 +78,13 @@ Provision 3 or 5 etcd nodes. Etcd requires a quorum to determine a leader by the
 Provision two or more control plane nodes. Some control plane components, such as the `kube-apiserver`, run in [active-active](https://www.jscape.com/blog/active-active-vs-active-passive-high-availability-cluster) mode and will give you more scalability. Other components such as kube-scheduler and kube-controller run in active-passive mode (leader elect) and give you more fault tolerance.

 ### Monitor Your Cluster
-Closely monitor and scale your nodes as needed. You should [enable cluster monitoring]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) and use the Prometheus metrics and Grafana visualization options as a starting point.
+Closely monitor and scale your nodes as needed. You should [enable cluster monitoring]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) and use the Prometheus metrics and Grafana visualization options as a starting point.


 # Tips for Security
 Below are some basic tips for increasing security in Rancher. For more detailed information about securing your cluster, you can refer to these resources:

- Rancher's [security documentation and Kubernetes cluster hardening guide]({{< baseurl >}}/rancher/v2.x/en/security/)
+- Rancher's [security documentation and Kubernetes cluster hardening guide]({{<baseurl>}}/rancher/v2.x/en/security/)
 - [101 More Security Best Practices for Kubernetes](https://rancher.com/blog/2019/2019-01-17-101-more-kubernetes-security-best-practices/)

 ### Update Rancher with Security Patches
@@ -19,6 +19,7 @@ This section covers the following topics:

 - [Prerequisites](#prerequisites)
 - [Catalog scopes](#catalog-scopes)
+- [Catalog Helm Deployment Versions](#catalog-helm-deployment-versions)
 - [Enabling built-in global catalogs](#enabling-built-in-global-catalogs)
 - [Adding custom global catalogs](#adding-custom-global-catalogs)
  - [Add custom Git repositories](#add-custom-git-repositories)
@@ -41,7 +42,7 @@ To launch a catalog app or a multi-cluster app, you should have at least one of

 # Catalog Scopes

-Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs across between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects.
+Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects.

 Scope |  Description | Available As of |
 --- |  --- | --- |
@@ -49,6 +50,20 @@ Global | All clusters and all projects can access the Helm charts in this catalo
 Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 |
 Project | This specific cluster can access the Helm charts in this catalog |  v2.2.0 |

+# Catalog Helm Deployment Versions
+
+_Applicable as of v2.4.0_
+
+In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully backwards compatible with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version.
+
+When you create a custom catalog, you will have to configure the catalog to use either Helm 2 or Helm 3. This version cannot be changed later. If the catalog is added with the wrong Helm version, it will need to be deleted and re-added.
+
+When you launch a new app from a catalog, the app will be managed by the catalog's Helm version. A Helm 2 catalog will use Helm 2 to manage all of the apps, and a Helm 3 catalog will use Helm 3 to manage all apps.
+
+By default, catalogs are assumed to be deployed using Helm 2. If you run an app in Rancher prior to v2.4.0, then upgrade to Rancher v2.4.0+, the app will still be managed by Helm 2.
+
+Charts that are specific to Helm 2 should only be added to a Helm 2 catalog, and Helm 3 specific charts should only be added to a Helm 3 catalog.
+
 # Enabling Built-in Global Catalogs

 Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.
@@ -57,19 +72,9 @@ Within Rancher, there are default catalogs packaged as part of Rancher. These ca

 2. Toggle the default catalogs that you want use to a setting of **Enabled**.

-    - **Library**
-
-    	The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. 
-
-    	This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
-
-    - **Helm Stable**
-
-    	This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps.
-
-    - **Helm Incubator**
-
-    	Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
+    - **Library:**	The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
+    - **Helm Stable:** This catalog, which is maintained by the Kubernetes community, includes native [Helm charts](https://helm.sh/docs/chart_template_guide/). This catalog features the largest pool of apps.
+    - **Helm Incubator:** Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.

 **Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, you can select **Catalog Apps** from the main navigation bar.

@@ -77,6 +82,8 @@ Within Rancher, there are default catalogs packaged as part of Rancher. These ca

 Adding a catalog is as simple as adding a catalog name, a URL and a branch name.

+**Prerequisite:** An [admin]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) of Rancher has the ability to add or remove catalogs globally in Rancher.
+
 ### Add Custom Git Repositories
 The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately.

@@ -91,23 +98,15 @@ In Rancher, you can add the custom Helm chart repository with only a catalog nam
 ### Add Private Git/Helm Chart Repositories
 _Available as of v2.2.0_

-In Rancher v2.2.0, you can add private catalog repositories using credentials like Username and Password. You may also want to use the
-OAuth token if your Git or Helm repository server support that.
+Private catalog repositories can be added using credentials like Username and Password. You may also want to use the OAuth token if your Git or Helm repository server supports that.

-[Read More About Adding Private Git/Helm Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#private-repositories)
-
-<!--There are two types of catalogs that can be added into Rancher. There are global catalogs and project catalogs. In a global catalog, the catalog templates are available in *all* projects. In a project catalog, the catalog charts are only available in the project that the catalog is added to.
-
-An [admin]({{< baseurl >}}/rancher/v2.x/en/admin-settings/#global-Permissions) of Rancher has the ability to add or remove catalogs globally in Rancher.
-
-NEEDS TO BE FIXED FOR 2.0: Any [users]({{site.baseurl}}/rancher/{{page.version}}/{{page.lang}}/configuration/accounts/#account-types) of a Rancher environment has the ability to add or remove environment catalogs in their respective Rancher environment in **Catalog** -> **Manage**.
- -->
+[Read More About Adding Private Git/Helm Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#private-repositories)

 1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
 2. Click **Add Catalog**.
 3. Complete the form and click **Create**.

- **Result**: Your catalog is added to Rancher.
+ **Result:** Your catalog is added to Rancher.

 # Launching Catalog Applications

@@ -130,7 +129,7 @@ After you've either enabled the built-in catalogs or added your own custom catal

    * For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section.
    * Keys and values are available within **Detailed Descriptions**.
-    * 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.  
+    * 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`), wrap the values with double quotes (i.e., `"abc, bcd"`).

@@ -144,15 +143,15 @@ By creating a customized repository with added files, Rancher improves on Helm r

 There are two types of catalogs in Rancher. Learn more about each type:

-* [Built-in Global Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/)
-* [Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/)
+* [Built-in Global Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/)
+* [Custom Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/)

 ### Apps

 In Rancher, applications are deployed from the templates in a catalog. Rancher supports two types of applications:

-* [Multi-cluster applications]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/)
-* [Applications deployed in a specific Project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps)
+* [Multi-cluster applications]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/)
+* [Applications deployed in a specific Project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps)

 ### Global DNS

@@ -160,7 +159,7 @@ _Available as v2.2.0_

 When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS.

-For more information on how to use this feature, see [Global DNS]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/).
+For more information on how to use this feature, see [Global DNS]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).

 ### Chart Compatibility with Rancher

@@ -3,9 +3,9 @@ title: Apps in a Project
 weight: 5005
 ---

-Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope).
+Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope).

-If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a [Global DNS entry]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/).
+If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a [Global DNS entry]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).

 ## Prerequisites

@@ -16,7 +16,7 @@ To create a multi-cluster app in Rancher, you must have at least one of the foll

 ## Launching Catalog Applications

-After you've either enabled the [built-in global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or [added your own custom catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding), you can start launching catalog applications.
+After you've either enabled the [built-in global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) or [added your own custom catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding), you can start launching catalog applications.

 1. From the **Global** view, navigate to your project that you want to start deploying applications.

@@ -57,7 +57,7 @@ If the Helm chart that you are deploying contains a `questions.yml` file, Ranche

 #### Key Value Pairs for Native Helm Charts

-For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
+For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.

 {{% /tab %}}
 {{% tab "Editing YAML Files" %}}
@@ -5,14 +5,14 @@ aliases:
  - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/
 ---

-There are default [global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#global-catalogs) packaged as part of Rancher.
+There are default [global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/#global-catalogs) packaged as part of Rancher.

 ## Managing Built-in Global Catalogs

->**Prerequisites:** In order to manage the built-in catalogs or [manage global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding/#adding-global-catalogs), you need _one_ of the following permissions:
+>**Prerequisites:** In order to manage the built-in catalogs or [manage global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/#adding-global-catalogs), you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.

 1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.

@@ -22,7 +22,7 @@ There are default [global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#glo

    	The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.x, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future.

-    	This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
+    	This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.

    - **Helm Stable**

@@ -5,7 +5,7 @@ aliases:

 ---

-Any user can [create custom catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/creating/) to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.
+Any user can [create custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/creating/) to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.

 ## Types of Repositories

@@ -28,7 +28,7 @@ In Rancher, you can add the custom Helm chart repository with only a catalog nam

 ## Catalog Fields

-When [adding your catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding/) to Rancher, you'll provide the following information:
+When [adding your catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/) to Rancher, you'll provide the following information:


 | Variable              |  Description  |
@@ -48,7 +48,7 @@ Private Git or Helm chart repositories can be added into Rancher using either cr

 ### Using Username and Password

-1. When [adding the catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding/), select the **Use private catalog** checkbox.
+1. When [adding the catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/), select the **Use private catalog** checkbox.

 2. Provide the `Username` and `Password` for your Git or Helm repository.

@@ -59,6 +59,6 @@ Read [using Git over HTTPS and OAuth](https://github.blog/2012-09-21-easier-buil
 1. Create an [OAuth token](https://github.com/settings/tokens)
 with `repo` permission selected, and click **Generate token**.

-2. When [adding the catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding/), select the **Use private catalog** checkbox.
+2. When [adding the catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/), select the **Use private catalog** checkbox.

 3. For `Username`, provide the Git generated OAuth token. For `Password`, enter `x-oauth-basic`.  
@@ -5,20 +5,22 @@ aliases:
  - /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/
 ---

-[Custom catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/) can be added into Rancher at any [scope of Rancher]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope).
+[Custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/) can be added into Rancher at any [scope of Rancher]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope).

 ## Adding Global Catalogs

->**Prerequisites:** In order to manage the [built-in catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or manage global catalogs, you need _one_ of the following permissions:
+>**Prerequisites:** In order to manage the [built-in catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) or manage global catalogs, you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.

 1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
 2. Click **Add Catalog**.
- 3. Complete the form and click **Create**.
+ 3. Complete the form. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
+{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
+4. Click **Create**.

- **Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog.
+ **Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.

 ## Adding Cluster Catalogs

@@ -26,17 +28,18 @@ _Available as of v2.2.0_

 >**Prerequisites:** In order to manage cluster scoped catalogs, you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Cluster Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
->- [Custom Cluster Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Cluster Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-role-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
+>- [Custom Cluster Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Cluster Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-role-reference) role assigned.

 1. From the **Global** view, navigate to your cluster that you want to start adding custom catalogs.
 2. Choose the **Tools > Catalogs** in the navigation bar.
 2. Click **Add Catalog**.
-3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Cluster** scope, it is defaulted to `Cluster`.
+3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Cluster** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
+{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
 5. Click **Create**.

-**Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying  [applications in any project in that cluster]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog.
+**Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying  [applications in any project in that cluster]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.

 ## Adding Project Level Catalogs

@@ -44,15 +47,16 @@ _Available as of v2.2.0_

 >**Prerequisites:** In order to manage project scoped catalogs, you need _one_ of the following permissions:
 >
->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
->- [Cluster Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
->- [Project Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles)
->- [Custom Project Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Project Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) role assigned.
+>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
+>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
+>- [Project Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles)
+>- [Custom Project Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Project Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) role assigned.

 1. From the **Global** view, navigate to your project that you want to start adding custom catalogs.
 2. Choose the **Tools > Catalogs** in the navigation bar.
 2. Click **Add Catalog**.
-3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Project** scope, it is defaulted to `Cluster`.
+3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Project** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
+{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
 5. Click **Create**.

-**Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying  [applications in that project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog.
+**Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying  [applications in that project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
@@ -61,7 +61,7 @@ Before you create your own custom catalog, you should have a basic understanding

 	<figcaption>Rancher Chart with <code>app-readme.md</code> (left) vs. Helm Chart without (right)</figcaption>

-	![app-readme.md]({{< baseurl >}}/img/rancher/app-readme.png)
+	![app-readme.md]({{<baseurl>}}/img/rancher/app-readme.png)

 - `questions.yml`

@@ -70,7 +70,7 @@ Before you create your own custom catalog, you should have a basic understanding

 	<figcaption>Rancher Chart with <code>questions.yml</code> (left) vs. Helm Chart without (right)</figcaption>

-	![questions.yml]({{< baseurl >}}/img/rancher/questions.png)
+	![questions.yml]({{<baseurl>}}/img/rancher/questions.png)


 ### Questions.yml
@@ -23,11 +23,11 @@ The following table lists the first version of Rancher each provider debuted.

 ## Global DNS Entries

-For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single [multi-cluster application]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or to specific projects. You must [add specific annotation labels](#adding-annotations-to-ingresses-to-program-the-external-dns) to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work.
+For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or to specific projects. You must [add specific annotation labels](#adding-annotations-to-ingresses-to-program-the-external-dns) to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work.

 ## Permissions for Global DNS Providers/Entries

-By default, only [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get `Owner` role to manage them.
+By default, only [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get `Owner` role to manage them.

 ## Setting up Global DNS for Applications

@@ -63,7 +63,7 @@ By default, only [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-s

 >**Notes:**
 >
->- Alibaba Cloud SDK uses TZ data. It needs to be present on `/usr/share/zoneinfo` path of the nodes running [`local` cluster]({{< baseurl >}}/rancher/v2.x/en/installation/options/chart-options/#import-local-cluster), and it is mounted to the external DNS pods. If it is not available on the nodes, please follow the [instruction](https://www.ietf.org/timezones/tzdb-2018f/tz-link.html) to prepare it.
+>- Alibaba Cloud SDK uses TZ data. It needs to be present on `/usr/share/zoneinfo` path of the nodes running [`local` cluster]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/#import-local-cluster), and it is mounted to the external DNS pods. If it is not available on the nodes, please follow the [instruction](https://www.ietf.org/timezones/tzdb-2018f/tz-link.html) to prepare it.
 >- Different versions of AliDNS have different allowable TTL range, where the default TTL for a global DNS entry may not be valid. Please see the [reference](https://www.alibabacloud.com/help/doc-detail/34338.htm) before adding an AliDNS entry.
 {{% /accordion %}}

@@ -73,7 +73,7 @@ By default, only [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-s
 1. Click on **Add DNS Entry**.
 1. Enter the **FQDN** you wish to program on the external DNS.
 1. Select a Global DNS **Provider** from the list.
-1. Select if this DNS entry will be for a [multi-cluster application]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or for workloads in different [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).  You will need to ensure that [annotations are added to any ingresses](#adding-annotations-to-ingresses-to-program-the-external-dns) for the applications that you want to target.
+1. Select if this DNS entry will be for a [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or for workloads in different [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).  You will need to ensure that [annotations are added to any ingresses](#adding-annotations-to-ingresses-to-program-the-external-dns) for the applications that you want to target.
 1. Configure the **DNS TTL** value in seconds. By default, it will be 300 seconds.
 1. Under **Member Access**, search for any users that you want to have the ability to manage this Global DNS entry.

@@ -85,11 +85,11 @@ In order for Global DNS entries to be programmed, you will need to add a specifi
 1. In order for the DNS to be programmed, the following requirements must be met:
   * The ingress routing rule must be set to use a `hostname` that matches the FQDN of the Global DNS entry.
   * The ingress must have an annotation (`rancher.io/globalDNS.hostname`) and the value of this annotation should match the FQDN of the Global DNS entry.
-1. Once the ingress in your [multi-cluster application]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or in your target projects are in `active` state, the FQDN will be programmed on the external DNS against the Ingress IP addresses.
+1. Once the ingress in your [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or in your target projects are in `active` state, the FQDN will be programmed on the external DNS against the Ingress IP addresses.

 ## Editing a Global DNS Provider

-The [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS provider and any users added as `members` to a Global DNS provider, have _owner_ access to that provider. Any members can edit the following fields:
+The [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS provider and any users added as `members` to a Global DNS provider, have _owner_ access to that provider. Any members can edit the following fields:

 - Root Domain
 - Access Key & Secret Key
@@ -101,7 +101,7 @@ The [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/

 ## Editing a Global DNS Entry

-The [global administrators]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS entry and any users added as `members` to a Global DNS entry, have _owner_ access to that DNS entry. Any members can edit the following fields:
+The [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS entry and any users added as `members` to a Global DNS entry, have _owner_ access to that DNS entry. Any members can edit the following fields:

 - FQDN
 - Global DNS Provider
@@ -6,9 +6,9 @@ _Available as of v2.2.0_

 Typically, most applications are deployed on a single Kubernetes cluster, but there will be times you might want to deploy multiple copies of the same application across different clusters and/or projects. In Rancher, a _multi-cluster application_,  is an application deployed using a Helm chart across multiple clusters. With the ability to deploy the same application across multiple clusters, it avoids the repetition of the same action on each cluster, which could introduce user error during application configuration. With multi-cluster applications, you can customize to have the same configuration across all projects/clusters as well as have the ability to change the configuration based on your target project. Since multi-cluster application is considered a single application, it's easy to manage and maintain this application.

-Any Helm charts from a [global catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope) can be used to deploy and manage multi-cluster applications.
+Any Helm charts from a [global catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope) can be used to deploy and manage multi-cluster applications.

-After creating a multi-cluster application, you can program a [Global DNS entry]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/) to make it easier to access the application.
+After creating a multi-cluster application, you can program a [Global DNS entry]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/) to make it easier to access the application.

 # Prerequisites

@@ -45,7 +45,7 @@ Rancher has divided the configuration option for the multi-cluster application i

 #### Targets

-In the **Targets** section, select the [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#projects) that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on **-**.
+In the **Targets** section, select the [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#projects) that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on **-**.

 #### Upgrades

@@ -57,15 +57,15 @@ In the **Upgrades** section, select the upgrade strategy to use, when you decide

 #### Roles

-In the **Roles** section, you define the role of the multi-cluster application. Typically, when a user [launches catalog applications]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/#launching-catalog-applications), that specific user's permissions are used for creation of all workloads/resources that is required by the app.
+In the **Roles** section, you define the role of the multi-cluster application. Typically, when a user [launches catalog applications]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/#launching-catalog-applications), that specific user's permissions are used for creation of all workloads/resources that is required by the app.

 For multi-cluster applications, the application is deployed by a _system user_ and is assigned as the creator of all underlying resources. A _system user_ is used instead of the actual user due to the fact that the actual user could be removed from one of the target projects. If the actual user was removed from one of the projects, then that user would no longer be able to manage the application for the other projects.

 Rancher will let you select from two options for Roles, **Project** and **Cluster**. Rancher will allow creation using any of these roles based on the user's permissions.

- **Project** - This is the equivalent of a [project member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles). If you select this role, Rancher will check that in all the target projects, the user has minimally the [project member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) role. While the user might not be explicitly granted the _project member_ role, if the user is an [administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), a [cluster owner]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), or a [project owner]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles), then the user is considered to have the appropriate level of permissions.
+- **Project** - This is the equivalent of a [project member]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles). If you select this role, Rancher will check that in all the target projects, the user has minimally the [project member]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) role. While the user might not be explicitly granted the _project member_ role, if the user is an [administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), a [cluster owner]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), or a [project owner]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles), then the user is considered to have the appropriate level of permissions.

- **Cluster** - This is the equivalent of a [cluster owner]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles). If you select this role, Rancher will check that in all the target projects, the user has minimally the [cluster owner]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) role. While the user might not be explicitly granted the _cluster owner_ role, if the user is an [administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), then the user is considered to have the appropriate level of permissions.
+- **Cluster** - This is the equivalent of a [cluster owner]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles). If you select this role, Rancher will check that in all the target projects, the user has minimally the [cluster owner]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) role. While the user might not be explicitly granted the _cluster owner_ role, if the user is an [administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), then the user is considered to have the appropriate level of permissions.

 When launching the application, Rancher will confirm if you have these permissions in the target projects before launching the application.

@@ -83,7 +83,7 @@ If the Helm chart that you are deploying contains a `questions.yml` file, Ranche

 #### Key Value Pairs for Native Helm Charts

-For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
+For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.

 ### Members

@@ -16,8 +16,8 @@ The binary can be downloaded directly from the UI. The link can be found in the

 After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:

- Your [Rancher Server URL]({{< baseurl >}}/rancher/v2.x/en/admin-settings/server-url), which is used to connect to Rancher Server.
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys/).
+- Your [Rancher Server URL]({{<baseurl>}}/rancher/v2.x/en/admin-settings/server-url), which is used to connect to Rancher Server.
+- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/).

 ### CLI Authentication

@@ -31,7 +31,7 @@ If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to con

 ### Project Selection

-Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
+Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.

 **Example: `./rancher context switch` Output**
 ```
@@ -57,17 +57,17 @@ The following commands are available for use in Rancher CLI.

 | Command  | Result  |
 |---|---|
-| `apps, [app]`  | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or [Rancher charts]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-directory-structure)).  |
-| `catalog`  | Performs operations on [catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/).  |
-| `clusters, [cluster]`  | Performs operations on your [clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/).  |
-| `context`  | Switches between Rancher [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). For an example, see [Project Selection](#project-selection).  |
-| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]`  | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/) and [workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/)). Specify resources by name or ID.  |
+| `apps, [app]`  | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or [Rancher charts]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#chart-directory-structure)).  |
+| `catalog`  | Performs operations on [catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/).  |
+| `clusters, [cluster]`  | Performs operations on your [clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/).  |
+| `context`  | Switches between Rancher [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). For an example, see [Project Selection](#project-selection).  |
+| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]`  | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/) and [workloads]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/workloads/)). Specify resources by name or ID.  |
 | `kubectl`  |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations).   |
 | `login, [l]`  | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication).  |
-| `namespaces, [namespace]`  |Performs operations on [namespaces]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces).   |
-| `nodes, [node]`  |Performs operations on [nodes]({{< baseurl >}}/rancher/v2.x/en/overview/architecture/#kubernetes).   |
-| `projects, [project]`  | Performs operations on [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).  |
-| `ps`  | Displays [workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads) in a project.  |
+| `namespaces, [namespace]`  |Performs operations on [namespaces]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces).   |
+| `nodes, [node]`  |Performs operations on [nodes]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#kubernetes).   |
+| `projects, [project]`  | Performs operations on [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).  |
+| `ps`  | Displays [workloads]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/workloads) in a project.  |
 | `settings, [setting]`  | Shows the current settings for your Rancher Server.  |
 | `ssh`  | Connects to one of your cluster nodes using the SSH protocol.  |
 | `help, [h]`  | Shows a list of commands or help for one command.  |
@@ -21,22 +21,22 @@ Alternatively, you can switch between projects and clusters directly in the navi

 ## Managing Clusters in Rancher

-After clusters have been [provisioned into Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/), [cluster owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) will need to manage these clusters. There are many different options of how to manage your cluster. 
+After clusters have been [provisioned into Rancher]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/), [cluster owners]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) will need to manage these clusters. There are many different options of how to manage your cluster. 

-| Action | [Rancher launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) | [Hosted Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) | [Imported Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters) |
+| Action | [Rancher launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) | [Hosted Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) | [Imported Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters) |
 | --- | --- | ---| ---|
-| [Using kubectl and a kubeconfig file to Access a Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/) | * | * | * |
-| [Adding Cluster Members]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cluster-access/cluster-members/) | * | * | * |
-| [Editing Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/editing-clusters/) | * | * | * |
-| [Managing Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/nodes) | * | * | * |
-| [Managing Persistent Volumes and Storage Classes]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) | * | * | * |
-| [Managing Projects and Namespaces]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/projects-and-namespaces/) | * | * | * |
+| [Using kubectl and a kubeconfig file to Access a Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/) | * | * | * |
+| [Adding Cluster Members]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/cluster-members/) | * | * | * |
+| [Editing Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/) | * | * | * |
+| [Managing Nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/nodes) | * | * | * |
+| [Managing Persistent Volumes and Storage Classes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) | * | * | * |
+| [Managing Projects and Namespaces]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/projects-and-namespaces/) | * | * | * |
 | [Configuring Tools](#configuring-tools) | * | * | * |
-| [Cloning Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cloning-clusters/)| | * | * |
-| [Ability to rotate certificates]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/certificate-rotation/) | * |  | |
-| [Ability to back up your Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/) | * | | |
-| [Ability to recover and restore etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/restoring-etcd/) | * | | |
-| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/) | * | | |
+| [Cloning Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cloning-clusters/)| | * | * |
+| [Ability to rotate certificates]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/certificate-rotation/) | * |  | |
+| [Ability to back up your Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/) | * | | |
+| [Ability to recover and restore etcd]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/) | * | | |
+| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/) | * | | |

 ## Configuring Tools

@@ -47,4 +47,4 @@ Rancher contains a variety of tools that aren't included in Kubernetes to assist
 - Logging
 - Monitoring

-For more information, see [Tools]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/)
+For more information, see [Tools]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/)
@@ -1,23 +1,64 @@
 ---
-title: Backing up etcd
+title: Backing up a Cluster
 weight: 2045
 ---

 _Available as of v2.2.0_

-In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) can be easily performed. Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.
+In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) can be easily performed.

 Rancher recommends configuring recurrent `etcd` snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.

->**Note:** If you have any Rancher launched Kubernetes clusters that were created prior to v2.2.0, after upgrading Rancher, you must [edit the cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots prior to v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
+Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

-# Snapshot Creation Period and Retention Count
+This section covers the following topics:
+
+- [How snapshots work](#how-snapshots-work)
+- [Configuring recurring snapshots](#configuring-recurring-snapshots)
+- [One-time snapshots](#one-time-snapshots)
+- [Snapshot backup targets](#snapshot-backup-targets)
+  - [Local backup target](#local-backup-target)
+  - [S3 backup target](#s3-backup-target)
+  - [Using a custom CA certificate for S3](#using-a-custom-ca-certificate-for-s3)
+  - [IAM Support for storing snapshots in S3](#iam-support-for-storing-snapshots-in-s3)
+- [Viewing available snapshots](#viewing-available-snapshots)
+- [Safe timestamps](#safe-timestamps)
+- [Enabling snapshot features for clusters created before Rancher v2.2.0](#enabling-snapshot-features-for-clusters-created-before-rancher-v2-2-0)
+
+# How Snapshots Work
+
+{{% tabs %}}
+{{% tab "Rancher v2.4.0+" %}}
+When Rancher creates a snapshot, it includes three components: 
+
+- The cluster data in etcd
+- The Kubernetes version
+- The cluster configuration in the form of the `cluster.yml`
+
+Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version.
+
+The multiple components of the snapshot allow you to select from the following options if you need to a cluster from a snapshot:
+
+- **Restore just the etcd contents:** This restoration is similar to restoring to snapshots in Rancher prior to v2.4.0.
+- **Restore etcd and Kubernetes version:** This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
+- **Restore etcd, Kubernetes versions and cluster configuration:** This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.
+
+It's always recommended to take a new snapshot before any upgrades.
+{{% /tab %}}
+{{% tab "Rancher prior to v2.4.0" %}}
+When Rancher creates a snapshot, only the etcd data is included in the snapshot.
+
+Because the Kubernetes version is not included in the snapshot, there is no option to restore a cluster to a different Kubernetes version.
+
+It's always recommended to take a new snapshot before any upgrades.
+{{% /tab %}}
+{{% /tabs %}}
+
+# Configuring Recurring Snapshots

 Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.

-### Configuring Recurring Snapshots for the Cluster
-
-By default, [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the [S3 Target](#s3-backup-target) or replicating the path on disk is advised.
+By default, [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the [S3 Target](#s3-backup-target) or replicating the path on disk is advised.

 During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for **Cluster Options**. Click on **Show advanced options**.

@@ -30,7 +71,7 @@ In the **Advanced Cluster Options** section, there are several options available
 |[Recurring etcd Snapshot Creation Period](#snapshot-creation-period-and-retention-count) | Time in hours between recurring snapshots| 12 hours |
 |[Recurring etcd Snapshot Retention Count](#snapshot-creation-period-and-retention-count)| Number of snapshots to retain| 6 |

-### One-Time Snapshots
+# One-Time Snapshots

 In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure.

@@ -49,15 +90,7 @@ Rancher supports two different backup targets:

 ### Local Backup Target

-By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) in `/opt/rke/etcd-snapshots`. All recurring snapshots are taken at configured intervals. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster.
-
-#### Safe Timestamps
-
-_Available as of v2.3.0_
-
-As of v2.2.6, snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. As of Rancher v2.3.0, the option `safe_timestamp` is added to support compatible file names. When this flag is set to `true`, all special characters in the snapshot filename timestamp are replaced.
-
->>**Note:** This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface.
+By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) in `/opt/rke/etcd-snapshots`. All recurring snapshots are taken at configured intervals. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster.

 ### S3 Backup Target

@@ -72,13 +105,14 @@ The `S3` backup target allows users to configure a S3 compatible backend to stor
 |S3 Secret Key|S3 secret key with permission to access the backup bucket|*|
 | Custom CA Certificate | A custom certificate used to access private S3 backends _Available as of v2.2.5_ ||

-#### Using a custom CA certificate for S3
+### Using a custom CA certificate for S3

 _Available as of v2.2.5_

 The backup snapshot can be stored on a custom `S3` backup like [minio](https://min.io/). If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the `Custom CA Certificate` option to connect to the S3 backend.

-# IAM Support for Storing Snapshots in S3
+### IAM Support for Storing Snapshots in S3
+
 The `S3` backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:

 - The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.
@@ -90,8 +124,20 @@ The `S3` backup target supports using IAM authentication to AWS API in addition

 # Viewing Available Snapshots

-The list of all available snapshots for the cluster is available.
+The list of all available snapshots for the cluster is available in the Rancher UI.

 1. In the **Global** view, navigate to the cluster that you want to view snapshots.

 2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
+
+# Safe Timestamps
+
+_Available as of v2.3.0_
+
+As of v2.2.6, snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. As of Rancher v2.3.0, the option `safe_timestamp` is added to support compatible file names. When this flag is set to `true`, all special characters in the snapshot filename timestamp are replaced.
+
+This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface.
+
+# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0
+
+If you have any Rancher launched Kubernetes clusters that were created prior to v2.2.0, after upgrading Rancher, you must [edit the cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots prior to v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
@@ -6,7 +6,7 @@ weight: 2055

 This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes.

-When you use Rancher to [launch nodes for a cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher), resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.
+When you use Rancher to [launch nodes for a cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher), resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.

 When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in `Active` state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again.

@@ -24,10 +24,10 @@ When cleaning nodes provisioned using Rancher, the following components are dele
 | All resources create under the `management.cattle.io` API Group                | ✓               | ✓                 | ✓                   |                     |
 | All CRDs created by Rancher v2.x                                               | ✓               | ✓                 | ✓                   |                     |

-[1]: {{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/
-[2]: {{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/
-[3]: {{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/
-[4]: {{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/
+[1]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/
+[2]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/
+[3]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/
+[4]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/

 ## Removing a Node from a Cluster by Rancher UI

@@ -59,7 +59,7 @@ After the imported cluster is detached from Rancher, the cluster's workloads wil
 {{% 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.

-After you initiate the removal of an [imported cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) using the Rancher UI (or API), the following events occur.
+After you initiate the removal of an [imported cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) using the Rancher UI (or API), the following events occur.

 1. Rancher creates a `serviceAccount` that it uses to remove the Rancher components from the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the Rancher components.

@@ -13,16 +13,16 @@ Duplication of imported clusters, clusters in hosted Kubernetes providers, and c

 | Cluster Type                     | Cloneable?    |
 |----------------------------------|---------------|
-| [Nodes Hosted by Infrastructure Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) | ✓ |
-| [Hosted Kubernetes Providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) |               |
-| [Custom Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/)              |               |
-| [Imported Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/)            |               |
+| [Nodes Hosted by Infrastructure Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) | ✓ |
+| [Hosted Kubernetes Providers]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) |               |
+| [Custom Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/)              |               |
+| [Imported Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-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.

 ## Prerequisites

-Download and install [Rancher CLI]({{< baseurl >}}/rancher/v2.x/en/cli). Remember to [create an API bearer token]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys) if necessary.
+Download and install [Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli). Remember to [create an API bearer token]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys) if necessary.


 ## 1. Export Cluster Config
@@ -17,18 +17,18 @@ There are many ways you can interact with Kubernetes clusters that are managed b

        Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part.

-        For more information, see [Accessing Clusters with kubectl Shell]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-shell).
+        For more information, see [Accessing Clusters with kubectl Shell]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-shell).

    - **Terminal remote connection**

        You can also interact with your clusters by installing [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your local desktop and then copying the cluster's kubeconfig file to your local `~/.kube/config` directory.

-        For more information, see [Accessing Clusters with kubectl and a kubeconfig File]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-and-a-kubeconfig-file).
+        For more information, see [Accessing Clusters with kubectl and a kubeconfig File]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-and-a-kubeconfig-file).

 - **Rancher CLI**

-    You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI]({{< baseurl >}}/rancher/v2.x/en/cli/). This CLI tool can interact directly with different clusters and projects or pass them `kubectl` commands.
+    You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli/). This CLI tool can interact directly with different clusters and projects or pass them `kubectl` commands.

 - **Rancher API**

-    Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an [API key]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys/). To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on **View in API** for any Rancher UI object.
+    Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an [API key]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/). To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on **View in API** for any Rancher UI object.
@@ -9,7 +9,7 @@ aliases:

 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]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/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]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/) instead.

 There are two contexts where you can add cluster members:

@@ -33,23 +33,23 @@ Cluster administrators can edit the membership for a cluster, controlling which

 	If external authentication is configured:

-	-  Rancher returns users from your [external authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) source as you type.
+	-  Rancher returns users from your [external authentication]({{<baseurl>}}/rancher/v2.x/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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/).
+		>There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{<baseurl>}}/rancher/v2.x/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]({{< baseurl >}}/rancher/v2.x/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]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).

 4. Assign the user or group **Cluster** roles.  

-	[What are Cluster Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/)
+	[What are Cluster Roles?]({{<baseurl>}}/rancher/v2.x/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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
-	> - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles).
+	> - To add roles to the list, [Add a Custom Role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
+	> - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles).

 **Result:** The chosen users are added to the cluster.

@@ -8,7 +8,7 @@ After you provision a Kubernetes cluster using Rancher, you can still edit optio
 <sup>To Edit an Existing Cluster</sup>
 ![Edit Cluster]({{<baseurl>}}/img/rancher/edit-cluster.png)

-The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) have **Cluster Options** available for editing.
+The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) have **Cluster Options** available for editing.

 The following table summarizes the options and settings available for each cluster type:

@@ -24,7 +24,7 @@ Cluster administrators can [edit the membership for a cluster,]({{<baseurl>}}/ra

 ## Cluster Options

-When editing clusters, clusters that are [launched using RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) feature more options than clusters that are imported or hosted by a Kubernetes provider. The headings that follow document options available only for RKE clusters.
+When editing clusters, clusters that are [launched using RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) feature more options than clusters that are imported or hosted by a Kubernetes provider. The headings that follow document options available only for RKE clusters.

 ### Updating ingress-nginx

@@ -34,26 +34,26 @@ If the `updateStrategy` of `ingress-nginx` is `OnDelete`, you will need to delet

 # Editing Other Cluster Options

-In [clusters launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can edit any of the remaining options that follow.
+In [clusters launched by RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can edit any of the remaining options that follow.

 >**Note:** These options are not available for imported clusters or hosted Kubernetes clusters.

 <sup>Options for RKE Clusters</sup>
-![Cluster Options]({{< baseurl >}}/img/rancher/cluster-options.png)
+![Cluster Options]({{<baseurl>}}/img/rancher/cluster-options.png)


 Option | Description |
 ---------|----------|
 Kubernetes Version | The version of Kubernetes installed on each cluster node. For more detail, see [Upgrading Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/upgrading-kubernetes). |
- Network Provider | The [container networking interface]({{< baseurl >}}/rancher/v2.x/en/faq/networking/#cni-providers) that powers networking for your cluster.<br/><br/>**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. |
+ Network Provider | The [container networking interface]({{<baseurl>}}/rancher/v2.x/en/faq/networking/#cni-providers) that powers networking for your cluster.<br/><br/>**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. |
 Project Network Isolation | As of Rancher v2.0.7, if you're using the Canal network provider, you can choose whether to enable or disable inter-project communication. |
 Nginx Ingress | If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster. |
 Metrics Server Monitoring | Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal. |
- Pod Security Policy Support | Enables [pod security policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down. |
- Docker version on nodes | Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a [supported Docker version]({{< baseurl >}}/rancher/v2.x/en/installation/options/rke-add-on/layer-7-lb/), Rancher will stop pods from running on nodes that don't have a supported Docker version installed. |
+ Pod Security Policy Support | Enables [pod security policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down. |
+ Docker version on nodes | Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a [supported Docker version]({{<baseurl>}}/rancher/v2.x/en/installation/options/rke-add-on/layer-7-lb/), Rancher will stop pods from running on nodes that don't have a supported Docker version installed. |
 Docker Root Directory | The directory on your cluster nodes where you've installed Docker. If you install Docker on your nodes to a non-default directory, update this path. |
 Default Pod Security Policy | If you enable **Pod Security Policy Support**, use this drop-down to choose the pod security policy that's applied to the cluster. |
- Cloud Provider | If you're using a cloud provider to host cluster nodes launched by RKE, enable [this option]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required.  |
+ Cloud Provider | If you're using a cloud provider to host cluster nodes launched by RKE, enable [this option]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required.  |
 <br/>

 # Editing Cluster as YAML
@@ -67,6 +67,6 @@ Instead of using the Rancher UI to choose Kubernetes options for the cluster, ad

 In Rancher v2.0.0-v2.2.x, the config file is identical to the  [cluster config file for the Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. For more information, see the [cluster configuration reference.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options)

-![image]({{< baseurl >}}/img/rancher/cluster-options-yaml.png)
+![image]({{<baseurl>}}/img/rancher/cluster-options-yaml.png)

-For an example of RKE config file syntax, see the [RKE documentation]({{< baseurl >}}/rke/latest/en/example-yamls/).  
+For an example of RKE config file syntax, see the [RKE documentation]({{<baseurl>}}/rke/latest/en/example-yamls/).  
--- a/Show More
+++ b/Show More