Rancher

---
name: rancher
description: "Expert coverage of SUSE Rancher multi-cluster Kubernetes management: RKE2, K3s, Fleet GitOps, Harvester HCI, multi-cluster RBAC, and Provisioning v2. Use for \"Rancher\", \"RKE2\", \"K3s\", \"Fleet GitOps\", \"Harvester\", \"multi-cluster management\", \"cattle.io\", \"SUSE Kubernetes\"."
license: MIT
---

# SUSE Rancher

This skill covers SUSE Rancher, the multi-cluster Kubernetes management platform, including:

- Rancher server architecture (management cluster, downstream clusters)
- RKE2 (enterprise-grade Kubernetes distribution, CIS hardened)
- K3s (lightweight Kubernetes for edge and IoT)
- Fleet GitOps (multi-cluster continuous delivery)
- Harvester HCI (hyperconverged infrastructure on Kubernetes)
- Provisioning v2 (CAPI-based cluster lifecycle management)
- Multi-cluster RBAC and project-based multi-tenancy
- Authentication integration (AD, LDAP, SAML, OIDC)
- Monitoring and alerting (per-cluster Prometheus/Grafana stacks)
- CIS Benchmark scanning

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture** -- Load `references/architecture.md` for management cluster, RKE2, K3s, Fleet, Harvester
   - **Cluster provisioning** -- RKE2/K3s provisioning via Rancher, imported clusters, cloud-hosted clusters
   - **GitOps** -- Fleet configuration, GitRepo, BundleDeployment, multi-cluster targeting
   - **Multi-cluster** -- RBAC, Projects, cluster grouping, centralized monitoring
   - **Troubleshooting** -- Agent connectivity, cluster import issues, Fleet sync failures

2. **Identify context** -- Which distribution (RKE2, K3s, imported EKS/AKS/GKE)? On-prem or cloud? How many clusters? Ask if unclear.

3. **Load context** -- Read the reference file for deep technical detail.

4. **Apply** -- Provide Rancher UI paths, kubectl/Fleet YAML, RKE2/K3s CLI commands as appropriate.

5. **Validate** -- Suggest Rancher UI cluster status, `kubectl get clusters.management.cattle.io`, Fleet bundle status.

## Rancher Architecture Overview

```
Rancher Management Cluster (RKE2 or K3s)
  ├── Rancher Server (Helm chart deployment)
  │     ├── Authentication (AD, LDAP, SAML, GitHub, Google, Keycloak)
  │     ├── RBAC (global roles, cluster roles, project roles)
  │     ├── Cluster management (provision, import, monitor)
  │     └── App catalog (Helm charts, Fleet GitOps)
  ├── Fleet Controller
  │     ├── GitRepo watchers
  │     └── BundleDeployment reconcilers
  └── Rancher Agent (deployed to each managed cluster)
        ├── Cluster agent (deployment in cattle-system)
        └── Node agent (DaemonSet for node operations)
```

**Communication model**: downstream clusters run a Rancher agent that connects outbound to the Rancher server via WebSocket. No inbound firewall rules needed on downstream clusters.

## Kubernetes Distributions

### RKE2

Enterprise-grade Kubernetes distribution, FIPS 140-2 compliant, CIS hardened by default:

```bash
# Install RKE2 server (control plane)
curl -sfL https://get.rke2.io | sh -
systemctl enable rke2-server
systemctl start rke2-server

# Get kubeconfig
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml

# Install RKE2 agent (worker)
curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -
# Configure /etc/rancher/rke2/config.yaml:
# server: https://<server-ip>:9345
# token: <node-token>
systemctl enable rke2-agent
systemctl start rke2-agent
```

**RKE2 features**:
- Built-in etcd (embedded, no external dependency)
- CIS Kubernetes Benchmark hardened by default
- FIPS 140-2 validated cryptographic modules
- Canal CNI (Calico for policy + Flannel for networking) by default; Cilium and Calico also supported
- containerd runtime
- Integrated audit logging
- Automatic certificate rotation

**Configuration** (`/etc/rancher/rke2/config.yaml`):
```yaml
token: my-shared-secret
tls-san:
  - my-cluster.example.com
  - 10.0.0.10
cni: cilium                          # canal (default), calico, cilium
profile: cis                         # CIS hardening profile
etcd-snapshot-schedule-cron: "0 */6 * * *"
etcd-snapshot-retention: 10
node-taint:
  - "CriticalAddonsOnly=true:NoExecute"   # for control plane nodes
```

### K3s

Lightweight Kubernetes for edge, IoT, and development:

```bash
# Install K3s server
curl -sfL https://get.k3s.io | sh -

# Install K3s agent
curl -sfL https://get.k3s.io | K3S_URL=https://<server>:6443 K3S_TOKEN=<token> sh -

# Get kubeconfig
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
```

**K3s features**:
- Single binary (<100MB), runs on ARM and x86_64
- Embedded SQLite (single server) or embedded etcd (HA)
- External datastore support: MySQL, PostgreSQL, etcd
- Built-in: containerd, Flannel, CoreDNS, Traefik ingress, local-path-provisioner, metrics-server
- Fully CNCF conformant
- Suitable for Raspberry Pi to production edge

**HA K3s** (embedded etcd):
```bash
# First server
curl -sfL https://get.k3s.io | K3S_TOKEN=mysecret sh -s - server --cluster-init

# Additional servers
curl -sfL https://get.k3s.io | K3S_TOKEN=mysecret sh -s - server \
  --server https://<first-server>:6443
```

**K3s vs RKE2**:

| Aspect | K3s | RKE2 |
|--------|-----|------|
| Target | Edge, IoT, dev | Enterprise production |
| Size | <100MB | ~220MB |
| Default CNI | Flannel | Canal |
| CIS hardening | Manual | Built-in |
| FIPS compliance | No | Yes |
| Default storage | SQLite | etcd |
| Ingress | Traefik | NGINX |

## Fleet GitOps

Fleet is Rancher's built-in GitOps engine for deploying to multiple clusters simultaneously:

### GitRepo

```yaml
apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: myapp-config
  namespace: fleet-default
spec:
  repo: https://github.com/myorg/fleet-config
  branch: main
  paths:
  - apps/myapp
  targets:
  - name: production
    clusterSelector:
      matchLabels:
        env: production
  - name: staging
    clusterSelector:
      matchLabels:
        env: staging
  pollingInterval: 30s
```

### fleet.yaml

Per-directory configuration for Fleet:

```yaml
# fleet.yaml in the Git repository
defaultNamespace: production
helm:
  chart: ./charts/myapp
  releaseName: myapp
  values:
    replicaCount: 3
    image:
      tag: v2.0
  valuesFiles:
  - values-common.yaml
targetCustomizations:
- name: production
  clusterSelector:
    matchLabels:
      env: production
  helm:
    values:
      replicaCount: 5
      resources:
        requests:
          cpu: "500m"
          memory: "512Mi"
- name: staging
  clusterSelector:
    matchLabels:
      env: staging
  helm:
    values:
      replicaCount: 1
```

### Fleet Concepts

| Resource | Purpose |
|----------|---------|
| GitRepo | Defines a Git repository Fleet monitors |
| Bundle | Generated by Fleet from GitRepo content |
| BundleDeployment | Bundle applied to a specific cluster |
| Cluster | Represents a managed cluster (auto-created by Rancher) |
| ClusterGroup | Logical grouping of clusters for targeting |

### Fleet at Scale

Fleet is designed for hundreds to thousands of clusters:
- Batch deployments with configurable parallelism
- Drift detection and auto-remediation
- Per-cluster customization via `targetCustomizations`
- Support for Helm charts, Kustomize, and raw YAML
- OCI registry support for chart sources

## Cluster Provisioning (v2)

Provisioning v2 uses Cluster API (CAPI) under the hood:

```yaml
apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
  name: prod-rke2
  namespace: fleet-default
spec:
  kubernetesVersion: v1.35.x+rke2r1
  rkeConfig:
    machineGlobalConfig:
      cni: cilium
      profile: cis
    machinePools:
    - name: control-plane
      controlPlaneRole: true
      etcdRole: true
      quantity: 3
      machineConfigRef:
        kind: VmwarevsphereConfig
        name: cp-config
    - name: workers
      workerRole: true
      quantity: 5
      machineConfigRef:
        kind: VmwarevsphereConfig
        name: worker-config
```

**Supported infrastructure providers**: vSphere, AWS, Azure, GCP, DigitalOcean, Linode, Harvester.

## Multi-Cluster RBAC

### Role Hierarchy

```
Global Roles (cluster-independent)
  ├── Admin (full access to everything)
  ├── Restricted Admin (manage all clusters but not Rancher settings)
  └── Standard User (create clusters, manage own resources)

Cluster Roles (per-cluster)
  ├── Cluster Owner
  ├── Cluster Member
  └── Custom roles

Project Roles (per-project within a cluster)
  ├── Project Owner
  ├── Project Member
  ├── Read Only
  └── Custom roles
```

**Projects**: Rancher's concept for grouping namespaces within a cluster. Projects provide:
- Shared RBAC (one role binding applies to all namespaces in the project)
- Resource quotas (project-level resource limits)
- Network isolation (project-level NetworkPolicy)

## Monitoring

Rancher deploys per-cluster monitoring stacks via the Monitoring app (Helm chart):

```bash
# Install monitoring on a cluster via Rancher UI or CLI
helm install rancher-monitoring rancher-monitoring \
  --namespace cattle-monitoring-system \
  --create-namespace \
  --version <version>
```

Components deployed:
- Prometheus (metrics collection)
- Grafana (dashboards)
- Alertmanager (alert routing)
- Node Exporter (node metrics)
- kube-state-metrics (K8s object metrics)

Pre-built dashboards for: cluster overview, node metrics, workload metrics, etcd, API server.

## Harvester HCI

Hyperconverged infrastructure built on Kubernetes:

```
Harvester Cluster (RKE2-based)
  ├── KubeVirt (VM management as K8s resources)
  ├── Longhorn (distributed block storage)
  ├── Multus (multi-network support for VMs)
  └── Rancher integration (provision K8s clusters on Harvester VMs)
```

**Use case**: replace VMware vSphere with an open-source HCI platform that manages both VMs and containers from a single Kubernetes-based control plane.

```yaml
# VM in Harvester
apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: ubuntu-vm
spec:
  running: true
  template:
    spec:
      domain:
        resources:
          requests:
            memory: 4Gi
            cpu: "2"
        devices:
          disks:
          - name: rootdisk
            disk:
              bus: virtio
          interfaces:
          - name: default
            masquerade: {}
      networks:
      - name: default
        pod: {}
      volumes:
      - name: rootdisk
        persistentVolumeClaim:
          claimName: ubuntu-rootdisk
```

## Common Patterns

### Management Cluster Sizing

| Managed Clusters | Rancher Server Resources |
|-----------------|-------------------------|
| 1-10 | 4 vCPU, 8 GB RAM |
| 10-50 | 8 vCPU, 16 GB RAM |
| 50-100 | 16 vCPU, 32 GB RAM |
| 100+ | 32 vCPU, 64 GB RAM |

**Recommendation**: run Rancher server on a dedicated RKE2 cluster with 3 control plane nodes for HA.

### Edge Deployment Pattern

```
Central Rancher Server
    ↓ (Fleet GitOps)
Edge K3s clusters (100s-1000s)
    ├── Connected mode: agent maintains WebSocket connection
    └── Disconnected mode: Fleet pre-stages configs, periodic sync
```

## Reference Files

- `references/architecture.md` -- Multi-cluster management internals, RKE2/K3s architecture, Fleet engine details, Harvester deep dive, authentication integration, CIS scanning. Read for architecture and design questions.