Prerequisites

Set up the Rancher server’s local Kubernetes cluster.

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.

For help setting up a Kubernetes cluster, we provide these tutorials:

  • RKE: For the tutorial to install an RKE Kubernetes cluster, refer to For help setting up the infrastructure for a high-availability RKE cluster, refer to this page.
  • K3s: For the tutorial to install a K3s Kubernetes cluster, refer to For help setting up the infrastructure for a high-availability K3s cluster, refer to this page.
  • RKE2: For the tutorial to install an RKE2 Kubernetes cluster, refer to For help setting up the infrastructure for a high-availability RKE2 cluster, refer to this page.
  • Amazon EKS: For details on how to install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to
  • GKE: For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to this page.

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 .

  • kubectl - Kubernetes command-line tool.
  • - Package management for Kubernetes. Refer to the Helm version requirements to choose a version of Helm to install Rancher. Refer to the for your specific platform.

Ingress Controller (For Hosted Kubernetes)

To deploy Rancher v2.5 on a hosted Kubernetes cluster such as EKS, GKE, or AKS, you should deploy a compatible Ingress controller first to configure

For an example of how to deploy an ingress on EKS, refer to this section.

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 .

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

To set up Rancher,

  1. Add the Helm chart repository
  3. Choose your SSL configuration
  4. (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
  5. Install Rancher with Helm and your chosen certificate option
  7. Save your options

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

Latest: Recommended for trying out the newest features

Stable: Recommended for production environments

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

  1. kubectl create namespace cattle-system

3. Choose your SSL Configuration

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

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.

4. Install cert-manager

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

Click to Expand

These instructions are adapted from the .

  1. kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
  3. # **Important:**
  4. # If you are running Kubernetes v1.15 or below, you
  5. # will need to add the `--validate=false` flag to your
  6. # kubectl apply command, or else you will receive a
  7. # validation error relating to the
  8. # x-kubernetes-preserve-unknown-fields field in
  9. # cert-manager’s CustomResourceDefinition resources.
  10. # This is a benign error and occurs due to the way kubectl
  11. # performs resource validation.
  13. # Create the namespace for cert-manager
  14. kubectl create namespace cert-manager
  16. # Add the Jetstack Helm repository
  17. helm repo add jetstack https://charts.jetstack.io
  20. helm repo update
  22. # Install the cert-manager Helm chart
  23. helm install \
  24.   cert-manager jetstack/cert-manager \
  25.   --namespace cert-manager \
  26.   --version v1.0.4

Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

  1. kubectl get pods --namespace cert-manager
  3. NAME                                       READY   STATUS    RESTARTS   AGE
  4. cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
  5. cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
  6. cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

5. Install Rancher with Helm and Your Chosen Certificate Option

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

The default is for Rancher to generate a self-signed CA, and uses cert-manager to issue the certificate for access to the Rancher server interface.

Because rancher is the default option for ingress.tls.source, we are not specifying ingress.tls.source when running the helm install command.

  • Set hostname to the DNS record that resolves to your load balancer.
  • Set replicas to the number of replicas to use for the Rancher Deployment. This defaults to 3; if you have less than 3 nodes in your cluster you should reduce it accordingly.
  • To install a specific Rancher version, use the --version flag, example: --version 2.3.6.
  • If you are installing an alpha version, Helm requires adding the --devel option to the command.

Wait for Rancher to be rolled out:

  1. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  2. deployment "rancher" successfully rolled out

This option uses cert-manager to automatically request and renew certificates. This is a free service that provides you with a valid certificate as Let’s Encrypt is a trusted CA.

In the following command,

  • Set hostname to the public DNS record that resolves to your load balancer.
  • Set replicas to the number of replicas to use for the Rancher Deployment. This defaults to 3; if you have less than 3 nodes in your cluster you should reduce it accordingly.
  • Set ingress.tls.source to letsEncrypt.
  • Set letsEncrypt.email to the email address used for communication about your certificate (for example, expiry notices).
  • To install a specific Rancher version, use the --version flag, example: --version 2.3.6.
  • If you are installing an alpha version, Helm requires adding the --devel option to the command.
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set replicas=3 \
  5.   --set ingress.tls.source=letsEncrypt \
  6.   --set letsEncrypt.email=me@example.org
  1. kubectl -n cattle-system rollout status deploy/rancher
  2. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  3. deployment "rancher" successfully rolled out

In this option, Kubernetes secrets are created from your own certificates for Rancher to use.

When you run this command, the hostname option must match the Common Name or a Subject Alternative Names entry in the server certificate, or the Ingress controller will fail to configure correctly.

Although an entry in the Subject Alternative Names is technically required, having a matching Common Name maximizes compatibility with older browsers and applications.

  • Set hostname as appropriate for your certificate, as described above.
  • Set replicas to the number of replicas to use for the Rancher Deployment. This defaults to 3; if you have less than 3 nodes in your cluster you should reduce it accordingly.
  • Set ingress.tls.source to secret.
  • To install a specific Rancher version, use the --version flag, example: --version 2.3.6.
  • If you are installing an alpha version, Helm requires adding the --devel option to the command.

If you are using a Private CA signed certificate , add --set privateCA=true to the command:

  1. helm install rancher rancher-latest/rancher \
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set ingress.tls.source=secret \
  5.   --set privateCA=true

Now that Rancher is deployed, see Adding TLS Secrets to publish the certificate files so Rancher and the Ingress controller can use them.

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.

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

  1. kubectl -n cattle-system rollout status deploy/rancher
  2. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  3. 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:

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

It should show the same count for DESIRED and AVAILABLE.

7. Save Your Options

Make sure you save the 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 Page

Optional Next Steps

Enable the Enterprise Cluster Manager.