Continental Innovates with Rancher and Kubernetes
Set up the Rancher server’s local Kubernetes cluster.
The cluster requirements depend on the Rancher version:
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.
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,
The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your $PATH.
$PATH
Refer to the instructions provided by the Helm project for your specific platform.
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
Latest: Recommended for trying out the newest features
Stable: Recommended for production environments
Alpha: Experimental preview of upcoming releases. Note: Upgrades are not supported to, from, or between Alphas.
helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
We’ll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system:
cattle-system
kubectl create namespace cattle-system
The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.
Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.
There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:
cert-manager
HTTP-01
tls.crt
tls.key
ingress.tls.source=rancher
ingress.tls.source=letsEncrypt
ingress.tls.source=secret
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).
Important: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade documentation.
These instructions are adapted from the official cert-manager documentation.
# Install the CustomResourceDefinition resources separately kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml # **Important:** # If you are running Kubernetes v1.15 or below, you # will need to add the `--validate=false` flag to your # kubectl apply command, or else you will receive a # validation error relating to the # x-kubernetes-preserve-unknown-fields field in # cert-manager’s CustomResourceDefinition resources. # This is a benign error and occurs due to the way kubectl # performs resource validation. # Create the namespace for cert-manager kubectl create namespace cert-manager # Add the Jetstack Helm repository helm repo add jetstack https://charts.jetstack.io # Update your local Helm chart repository cache helm repo update # Install the cert-manager Helm chart helm install \ cert-manager jetstack/cert-manager \ --namespace cert-manager \ --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:
kubectl get pods --namespace cert-manager NAME READY STATUS RESTARTS AGE cert-manager-5c6866597-zw7kh 1/1 Running 0 2m cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m
The exact command to install Rancher differs depending on the certificate configuration.
The default is for Rancher to generate a 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.
rancher
ingress.tls.source
helm install
hostname
--devel
--version
--version 2.3.6
helm install rancher rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org
Wait for Rancher to be rolled out:
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
This option uses cert-manager to automatically request and renew Let’s Encrypt 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,
letsEncrypt
letsEncrypt.email
helm install rancher rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=letsEncrypt \ --set letsEncrypt.email=me@example.org
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.
Common Name
Subject Alternative Names
Although an entry in the Subject Alternative Names is technically required, having a matching Common Name maximizes compatibility with older browsers and applications.
If you want to check if your certificates are correct, see How do I check Common Name and Subject Alternative Names in my server certificate?
secret
helm install rancher rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=secret
If you are using a Private CA signed certificate , add --set privateCA=true to the command:
--set privateCA=true
helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=secret \ --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:
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:
error: deployment "rancher" exceeded its progress deadline
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.
DESIRED
AVAILABLE
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.
--set
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
Enable the Enterprise Cluster Manager.