Rancher Architecture Overview

How Rancher manages and communicates with multiple Kubernetes clusters

Able Lv
3 min readMay 14, 2022

This article focuses on the Rancher server architecture, its components, and how Rancher manages and communicates with downstream Kubernetes clusters.

Rancher Server Architecture

Managing Kubernetes Clusters through Rancher’s Authentication Proxy

The figure above illustrates the high-level architecture of Rancher 2.x.

  • Rancher server can manage multiple Kubernetes clusters at the same time (either created by RKE, or Amazon EKS)
  • Users can manage multiple Kubernetes clusters through the Authentication Proxy. The Authentication Proxy forwards all Kubernetes API calls to downstream clusters.
  • For the best performance and security, a dedicated Kubernetes cluster for the Rancher server is recommended. After deploying Rancher, we can create or import clusters.

Communicating with Downstream User Clusters

The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters.

Communicating with Downstream User Clusters

The following descriptions correspond to the numbers in the diagram above:

1. The Authentication Proxy

  • A user named Bob is authenticated through Rancher’s authentication proxy. The authentication proxy forwards all Kubernetes API calls to downstream clusters.
  • The authentication proxy integrates with authentication services like local authentication, Active Directory, and GitHub.
  • On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
  • Rancher communicates with Kubernetes clusters using a service account, which provides an identity for processes that run in a pod.

2. Cluster Controllers and Cluster Agents

There is one cluster controller and one cluster agent for each downstream cluster. The cluster agent opens a tunnel to the cluster controller in the Rancher server.

Each cluster controller:

  • Watches for resource changes in the downstream cluster
  • Brings the current state of the downstream cluster to the desired state
  • Configures access control policies to clusters and projects
  • Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE

The cluster agent, also called cattle-cluster-agent, is a component that runs in a downstream user cluster. It performs the following tasks:

  • Connects to the Kubernetes API
  • Manages workloads, pod creation and deployment within each cluster
  • Applies the roles and bindings defined in each cluster’s global policies
  • Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health

3. Node Agents

  • If the cluster agent (also called cattle-cluster-agent) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.
  • The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster.
  • It is used to interact with the nodes when performing cluster operations, including upgrading the Kubernetes version and creating or restoring etcd snapshots.

4. Authorized Cluster Endpoint (ACE)

Rancher-launched Kubernetes clusters contain an authentication service named kube-api-auth, which allows users to communicate directly with the downstream k8s cluster without using Authentication Proxy. There are two main purposes:

  • To access a downstream user cluster while Rancher is down
  • To reduce latency when the Rancher server and downstream cluster are separated by a long distance



Able Lv

Cloud Infrastructure Engineer @Airwallex: Kubernetes, DevOps, SRE, Go, Terraform, Istio, and Cloud-Native stuff