Server Components
Rancher’s server architecture is composed of several major subsystems that work together to provide cluster management capabilities.API Layer
Steve API (v1)
Steve is Rancher’s modern API layer providing a Kubernetes-native experience.Steve API is located in
pkg/api/steve/ and provides the /v1 API endpoints.- Dynamic Schema Discovery: Automatically discovers and exposes all Kubernetes resources
- Watch Streams: Real-time WebSocket updates for resource changes
- SQL Cache: Optional caching layer for improved performance
- Aggregation: Combines resources from multiple clusters
- Field Selectors: Advanced filtering capabilities
Steve Configuration
Norman API (v3)
The Norman API provides Rancher-specific resources and operations.Norman API is in
pkg/api/norman/ and serves legacy /v3 endpoints for Rancher-specific resources.- Cluster management resources
- Project and namespace management
- User and token management
- Auth provider configurations
- Legacy cluster operations
API Middleware Stack
The request processing pipeline:Middleware Chain
Authentication System
The authentication system is implemented inpkg/auth/ and provides pluggable authentication.
Auth Server Structure
Auth Server
Authentication Providers
Located inpkg/auth/providers/, Rancher supports:
- Local
- SAML
- OIDC
- LDAP/AD
- External
Local Provider
- Username/password authentication
- PBKDF2 password hashing
- Stored in Kubernetes secrets
- Bootstrap admin user support
Token Management
Token management is handled bypkg/auth/tokens/:
Token Types
Controller System
Controllers are located inpkg/controllers/ and implement reconciliation logic.
Controller Categories
Management Controllers
Management Controllers
Location:
pkg/controllers/management/Core management reconciliation:- Cluster lifecycle management
- Node driver management
- Auth configuration sync
- Secret encryption
- User cleanup and retention
Provisioning V2 Controllers
Provisioning V2 Controllers
Location:
pkg/controllers/provisioningv2/Modern cluster provisioning:- RKE2 cluster provisioning
- K3s cluster provisioning
- Cluster API (CAPI) integration
- Machine management
- Bootstrap configuration
Dashboard Controllers
Dashboard Controllers
Location:
pkg/controllers/dashboard/Dashboard and UI support:- UI extension management
- Plugin lifecycle
- APIService registration
- Dashboard data seeding
Management Agent Controllers
Management Agent Controllers
Location:
pkg/controllers/managementagent/Downstream cluster agents:- Node management
- Workload management
- Monitoring integration
- Logging integration
- App deployment
Controller Registration Pattern
Controller Setup
Cluster Router
The cluster router (pkg/clusterrouter/) handles routing requests to downstream clusters.
Proxy Architecture
Proxy Middleware
- Parse cluster ID from request path
- Look up cluster connection info
- Check RBAC permissions
- Route via tunnel or direct connection
- Impersonate user context
- Proxy request to cluster API
Tunnel Server
The tunnel server (pkg/tunnelserver/) provides WebSocket-based bidirectional communication.
Peer Manager
Peer Management
- Multi-Replica Support: Peers coordinate via endpoints
- Connection Distribution: Agents connect to available replicas
- Automatic Failover: Reconnect on replica failure
- Leader Election: Consistent peer view
Tunnel Authorizer
Located inpkg/tunnelserver/mcmauthorizer/:
Authorization
Agent Components
Agent components run on downstream clusters.Cluster Agent
Location:pkg/agent/cluster/
Agent Bootstrap
- Maintain WebSocket tunnel to Rancher server
- Execute cluster operations
- Report cluster status
- Proxy API requests from server
Node Agent
Runs on each node for:- Node status reporting
- Log collection
- Metrics gathering
Wrangler Context
The Wrangler context (pkg/wrangler/) provides shared controllers and clients.
Wrangler Components
Wrangler provides a unified interface for all Kubernetes resources with automatic caching and indexing.
Data Management
Custom Resource Definitions
Rancher defines CRDs in several API groups:management.cattle.io
Core Rancher resources:
- Cluster
- Project
- User
- Token
- Setting
provisioning.cattle.io
Provisioning resources:
- Cluster (v2)
- Machine
- MachinePool
fleet.cattle.io
GitOps resources:
- GitRepo
- Bundle
- Cluster (Fleet)
catalog.cattle.io
App catalog:
- ClusterRepo
- App
- Operation
CRD Migration
CRD management inpkg/crds/:
CRD Setup
Feature Flags
Feature management inpkg/features/:
Feature Flags
Settings Management
Global settings inpkg/settings/:
Common Settings
- UI: Settings page
- CLI:
kubectl edit setting <name> - API:
/v1/management.cattle.io.setting
System Dependencies
Rancher relies on several external dependencies and automatically installs system charts for core functionality.External Dependencies
Required:- Kubernetes Cluster: Version 1.x < 1.36.0 - Rancher must run on a supported Kubernetes cluster
- cert-manager: Required for TLS certificate management when using Rancher-generated certificates or Let’s Encrypt. Not needed if bringing your own certificates.
System Charts (Auto-installed)
Rancher automatically installs and manages several system charts that provide core functionality: Core System Charts:Fleet (cattle-fleet-system namespace)
Fleet (cattle-fleet-system namespace)
Fleet is Rancher’s GitOps continuous delivery engine that enables cluster-wide and multi-cluster application deployment.
- Manages GitRepo resources for application deployment
- Handles bundle distribution across clusters
- Provides drift detection and reconciliation
Rancher Webhook (cattle-system)
Rancher Webhook (cattle-system)
Provides validation and mutation webhooks for Rancher resources.
- Validates resource specifications before admission
- Enforces security policies
- Mutates resources with default values
- aks-operator: Azure Kubernetes Service integration (rancher-operator-system)
- eks-operator: Amazon Elastic Kubernetes Service integration (rancher-operator-system)
- gke-operator: Google Kubernetes Engine integration (rancher-operator-system)
- ali-operator: Alibaba Cloud integration (rancher-operator-system)
- System Upgrade Controller: Automates Kubernetes cluster upgrades (cattle-system)
- Rancher Turtles: Cluster API (CAPI) lifecycle management integration (rancher-turtles-system)
System charts are managed by Rancher and should not be modified directly. Configuration should be done through Rancher’s UI or API.
System Namespaces
Rancher creates and manages several namespaces for organizing system components:| Namespace | Purpose |
|---|---|
cattle-system | Core Rancher server components and webhooks |
cattle-fleet-system | Fleet GitOps controller and resources |
cattle-impersonation-system | Impersonation tokens for cluster access |
cattle-telemetry-system | Telemetry collection and reporting |
rancher-operator-system | Cloud provider operators (AKS, EKS, GKE, Alibaba) |
cattle-csp-adapter-system | CSP (Cloud Service Provider) adapter for Rancher Prime |
cattle-scc-system | Support and connectivity check for Rancher Prime |
Service Account Management
Service account token handling inpkg/serviceaccounttoken/:
Token Lifecycle
Extension API Server
Optional extension API server for imperative operations:Extension Server
Component Dependencies
Next Steps
Security Architecture
Learn about authentication, RBAC, and security features
Architecture Overview
Review high-level architecture concepts