The website uses cookies. By using this site, you agree to our use of cookies as described in the Privacy Policy.
I Agree

Prerequisite

Set up the Rancher server’s local Kubernetes cluster.

The cluster requirements depend on the Rancher version:

  • As of Rancher v2.5, Rancher can be installed on any Kubernetes cluster. This cluster can use upstream Kubernetes, or it can use one of Rancher’s Kubernetes distributions, or it can be a managed Kubernetes cluster from a provider such as Amazon EKS.
  • In Rancher v2.4.x, Rancher needs to be installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.
  • In Rancher prior to v2.4, Rancher needs to be installed on an RKE Kubernetes cluster.

For the tutorial to install an RKE Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE cluster, refer to this page.

For the tutorial to install a K3s Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability K3s cluster, refer to this page.

Install the Rancher Helm Chart

Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents.

With Helm, we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

For systems without direct internet access, see Air Gap: Kubernetes install.

To choose a Rancher version to install, refer to Choosing a Rancher Version.

To choose a version of Helm to install Rancher with, refer to the Helm version requirements

NOTE: The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. This section provides a copy of the older installation instructions for Rancher installed on an RKE Kubernetes cluster with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

To set up Rancher,

1. Install the Required CLI Tools

The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your $PATH.

Refer to the instructions provided by the Helm project for your specific platform.

2. Add the Helm Chart Repository

Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>

3. Create a Namespace for Rancher

We’ll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system:

kubectl create namespace cattle-system

4. Choose your SSL Configuration

The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.

NOTE: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:

  • Rancher-generated TLS certificate: In this case, you will need to install cert-manager into the cluster. Rancher utilizes cert-manager to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. cert-manager is then responsible for managing that certificate.
  • Let’s Encrypt: The Let’s Encrypt option also uses cert-manager. However, in this case, cert-manager is combined with a special Issuer for Let’s Encrypt that performs all actions (including request and validation) necessary for getting a Let’s Encrypt issued cert. This configuration uses HTTP validation (HTTP-01), so the load balancer must have a public DNS record and be accessible from the internet.
  • Bring your own certificate: This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name tls.crt and tls.key. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
Configuration Helm Chart Option Requires cert-manager
Rancher Generated Certificates (Default) ingress.tls.source=rancher yes
Let’s Encrypt ingress.tls.source=letsEncrypt yes
Certificates from Files ingress.tls.source=secret no

5. Install cert-manager

You should skip this step if you are bringing your own certificate files (option ingress.tls.source=secret), or if you use TLS termination on an external load balancer.

This step is only required to use certificates issued by Rancher’s generated CA (ingress.tls.source=rancher) or to request Let’s Encrypt issued certificates (ingress.tls.source=letsEncrypt).

6. Install Rancher with Helm and Your Chosen Certificate Option

The exact command to install Rancher differs depending on the certificate configuration.

The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.

See the Chart Options for the full list of options.

7. Verify that the Rancher Server is Successfully Deployed

After adding the secrets, check if Rancher was rolled out successfully:

kubectl -n cattle-system rollout status deploy/rancher
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
deployment "rancher" successfully rolled out

If you see the following error: error: deployment "rancher" exceeded its progress deadline, you can check the status of the deployment by running the following command:

kubectl -n cattle-system get deploy rancher
NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rancher   3         3         3            3           3m

It should show the same count for DESIRED and AVAILABLE.

8. Save Your Options

Make sure you save the --set options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.

Finishing Up

That’s it. You should have a functional Rancher server.

In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.

Doesn’t work? Take a look at the Troubleshooting Page

Optional Next Steps

Enable the Enterprise Cluster Manager.

Measure
Measure
Summary | 6 Annotations
Rancher can be installed on any Kubernetes cluster.
2020/11/30 11:24
Rancher’s Kubernetes distributions
2020/11/30 11:24
K3s Kubernetes cluster
2020/11/30 11:25
RKE Kubernetes cluster
2020/11/30 11:25
high-availability RKE cluster
2020/11/30 11:25
Helm charts
2020/11/30 11:26