Skip to content
Search

Rancher

lastmod 2026-06-11created 2016-12-2329 edits

Rancher is a complete, open source platform for deploying and managing containers in production. It includes commercially-supported distributions of Kubernetes, Mesos, and Docker Swarm, making it easy to run containerized applications on any infrastructure.

Categories

Plaforms

Several open-source projects can be used to build this kind of Docker clustering. Docker Swarm is the native clustering tool distributed by Docker. If you set up clustering with Docker Swarm, you can use clustering without much difference from the Docker API you were already using. However, the clustering API is weak, so things like cross-host autoscaling have to be developed on your own.

Rancher is an open-source project that has recently been getting attention in the community. It builds clustering by deploying an Agent container on each host, which communicates with the Management container. So clustering setup is done just by deploying the Manage container and the Agent containers. Compared to Docker Swarm, it also implements cross-host container management, networking, load balancers, and so on, and in particular it provides a web UI, making container creation and management convenient. Since I started using Rancher, I handle almost everything on the web except image builds.

Next is the Volume plugin, where an open-source project called Flocker seems to be almost unrivaled. Because it supports storage from vendors such as Amazon EBS, OpenStack Cinder, EMC, VMware, and Dell, you can additionally use vendor-supported features such as snapshots and backup/restore.

Convoy is a subproject of Rancher. If you use Rancher and only use storage such as EBS, GFS, or NFS/VFS, it seems to be a perfectly good plugin.

Install/Upgrade Rancher on a Kubernetes Cluster

Prerequisites

Install the Rancher Helm Chart

Rancher feels like it is installed entirely with helm. You need to add one of the three repositories.

Latest
Recommended for trying out the newest features
helm repo add rancher-latesthttps://releases.rancher.com/server-charts/latest
Stable
Recommended for production environments
helm repo add rancher-stablehttps://releases.rancher.com/server-charts/stable
Alpha
Experimental preview of upcoming releases.
helm repo add rancher-alphahttps://releases.rancher.com/server-charts/alpha

INFORMATION

With the alpha (rancher-alpha) repository, you must add the --devel option when installing for it to install correctly.

Update the repository if needed: 

helm repo update

Create a Namespace for Rancher

You need to define the Kubernetes namespace where the resources created by the chart should be installed. This should always be cattle-system. 

kubectl create namespace cattle-system

Choose your SSL Configuration

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

INFORMATION

To terminate SSL/TLS for external access, see #TLS termination on an External Load Balancer.

There are three recommended options for the source of the certificate used for TLS termination on the Rancher server.

Rancher-generated TLS certificate
In this case, you need to install cert-manager in the cluster. Rancher uses cert-manager to issue and maintain its certificates. Rancher generates its own CA certificate and signs certificates using that CA. cert-manager is then responsible for managing those certificates.
Let's Encrypt
cert-manager is combined with a special issuer for Let's Encrypt that performs all the actions (including request and validation) needed to obtain a certificate issued by Let's Encrypt.
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 lets you bring your own public or private CA-signed certificate. Rancher uses that certificate to secure websocket and HTTPS traffic.
In this case, use this certificate (and its associated key) as tls.crt and tls.key.
If you use a private CA, you must also upload its certificate. This is because this private CA may not be trusted by your nodes. Rancher takes that CA certificate and generates a checksum from it. This checksum is used by various Rancher components to verify 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

Install cert-manager

Install cert-manager. See that page for details.

Note that the Rancher documentation site installs the CDRs and then adds the jetstack repository, whereas on the cert-manager official site, kubectl apply -f ... installs everything at once.

Check the ~.crds.yaml at the end of the URLs below:

Check that it installed correctly: 

kubectl get pods --namespace cert-manager

The output looks like this: 

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

Install Rancher with Helm and Your Chosen Certificate Option

The exact command to install Rancher depends on your certificate configuration.

INFORMATION

For the Alpha version, you must also add the --devel option.

Rancher-generated TLS certificate 

helm install rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword=admin

Let's Encrypt 

helm install rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword=admin \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=[email protected] \
  --set letsEncrypt.ingress.class=nginx

Bring your own certificate 

helm install rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set bootstrapPassword=admin \
  --set ingress.tls.source=secret

Other

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

My case

See Blackhole#Rancher.

Verify that the Rancher Server is Successfully Deployed

Check that Rancher was rolled out successfully. 

kubectl -n cattle-system rollout status deploy/rancher

A log like the following is printed... 

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

If you wait a while, the replicas come up one by one: 

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

Check the deployment: 

kubectl -n cattle-system get deploy rancher

If the output looks like this, you can more or less relax 

NAME      READY   UP-TO-DATE   AVAILABLE   AGE
rancher   3/3     3            3           15m

Now connect over HTTPS using the hostname you entered during installation. If you followed the input above, go connect to https://rancher.your.com/.

TLS termination on an External Load Balancer

It is recommended to configure the load balancer as an L4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher management cluster nodes. The cluster's ingress controller redirects http traffic on port 80 to https on port 443.

You can terminate SSL/TLS on an L7 load balancer in front of the Rancher cluster's ingress (inbound from outside). Use the --set tls=external option and point the load balancer at port http 80 on all Rancher cluster nodes. This exposes the Rancher interface on http port 80. Clients that can connect directly to the Rancher cluster will not be encrypted. If you choose to do this, it is recommended to restrict direct network-level access to the load balancer only.

If you use a private CA-signed certificate,after adding the private CA-signed certificate,``--set privateCA=true`` must be applied.

The load balancer must support long-lived websocket connections and must insert proxy headers so that Rancher can route links correctly.

Adding TLS Secrets 

kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

How to uninstall

Rancher is usually installed via Helm, so you first need to delete the Helm Release. Deleting the installed Helm chart also deletes the related resources. 

## Rancher는 보통 Helm을 통해 설치되므로, 먼저 Helm Release를 삭제해야 합니다. 설치된 Helm 차트를 삭제하면 관련 리소스도 함께 삭제됩니다.
helm uninstall rancher -n cattle-system

## Rancher 설치 시 사용된 네임스페이스를 삭제합니다. 기본적으로 cattle-system 네임스페이스가 사용됩니다.
kubectl delete namespace cattle-system

## Rancher 설치 시 사용된 Custom Resource Definition(CRD)을 삭제해야 합니다. 다음 명령어를 사용하여 CRD를 삭제합니다.
kubectl get crd | grep rancher | awk '{print $1}' | xargs kubectl delete crd

## Rancher 설치 중 생성된 리소스 중 일부는 Helm 릴리즈 삭제로는 제거되지 않을 수 있습니다. 이러한 리소스를 수동으로 제거해야 합니다.
kubectl get all -n kube-system | grep rancher | awk '{print $1}' | xargs kubectl delete -n kube-system

## 또한, Rancher와 관련된 클러스터 역할 및 바인딩, 서비스 어카운트 등을 삭제할 수 있습니다.
kubectl delete clusterrolebinding rancher
kubectl delete clusterrole rancher
kubectl delete sa rancher -n kube-system

## Rancher의 데이터는 Persistent Volume에 저장될 수 있습니다. 관련 PVC를 삭제합니다.
kubectl get pvc -n cattle-system
kubectl delete pvc <pvc-name> -n cattle-system

Launching Management Server 

$ docker run -d --restart=unless-stopped -p 80:8080 rancher/server

The UI and API are available on the exposed port 80.

How I installed it and in what order

See Blackhole#Rancher.

Troubleshooting

ERROR: DNS Checking loopback IP address

If the Host installation does not proceed normally, checking the logs with docker logs [CONTAINER_ID] shows the following. 

ERROR: DNS Checking loopback IP address 127.0.0.0/8, localhost or ::1 configured as the DNS server on the host file /etc/resolv.conf, can't accept it

In this case, you need to reconfigure the DNS servers of Docker or Diable dnsmasq.

For how to do it with Docker, see here

Container orchestration

Tools

See also

Favorite site

author Zer0 sitemap