# rancher/system-agent architecture

> Architecture diagram of the GitHub repository rancher/system-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rancher/system-agent
- Repository: https://github.com/rancher/system-agent

## Overview

##### Project Type & Purpose
- This is a Go-based system daemon (“rancher-system-agent”) that runs on a host OS.
- It watches for “plans” (locally on disk or remotely via the Kubernetes API), then executes those plans to configure or upgrade the node.
- It integrates tightly with Rancher/CAPI clusters, but remains a standalone agent.

##### Main Components
A. **Configuration Loader** (pkg/config)
- Reads CLI flags, environment variables, config files (Unix/Windows variants).
B. **Plan Watchers**
- **LocalPlanWatcher** (pkg/localplan/watcher.go) watches a filesystem directory for plan files.
- **K8sPlanWatcher** (pkg/k8splan/watcher.go) watches Kubernetes Custom Resources via the API server.
C. **Event Dispatcher / Controller Core**
- Receives plan events from watchers, deduplicates, and schedules them.
D. **Applyinator** (pkg/applyinator)
- Core engine that applies plans—file operations, script execution, state reconciliation (with OS-specific helpers).
E. **Image Utilities** (pkg/image)
- Pulls, unpacks, or loads container images referenced by plans.
F. **Prober** (pkg/prober)
- Executes health-check probes defined in plans to verify success.
G. **Version Info** (pkg/version)
- Embeds build metadata.
H. **Packaging & Delivery**
- Dockerfiles (package/), cross-compile scripts, and install.sh for distribution.

##### External Systems & Dependencies
- **Kubernetes API Server** (for remote plans)
- **Container Registry** (for pulling images)
- **Local File System** (for local plans and storing unpacked artifacts)
- **OS (Unix/Windows)** for applying changes

##### Architectural Patterns
- **Event-Driven**: Watchers emit plan events to a central dispatcher.
- **Plugin-style**: OS-specific code lives side by side (file_unix.go / file_windows.go).
- **Separation of Concerns**: Watching vs. planning vs. executing vs. probing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    Config["Configuration Loader<br/>(pkg/config)"]:::internal
    subgraph "Plan Watchers"
        LocalWatcher["LocalPlanWatcher<br/>(pkg/localplan)"]:::internal
        K8sWatcher["K8sPlanWatcher<br/>(pkg/k8splan)"]:::internal
    end
    Controller["Controller Core<br/>(main.go)"]:::internal
    Applyinator["Applyinator<br/>(pkg/applyinator)"]:::internal
    ImageUtils["Image Utilities<br/>(pkg/image)"]:::internal
    Prober["Prober<br/>(pkg/prober)"]:::internal
    Version["Version Info<br/>(pkg/version)"]:::internal

    %% External Systems
    K8sAPI["Kubernetes API Server"]:::external
    ContainerReg["Container Registry"]:::external
    OSFS["Host OS / File System"]:::os

    %% Packaging & Delivery
    subgraph "Packaging & Delivery"
        DockerfileDapper["Dockerfile.dapper"] 
        DockerfilePkg["package/Dockerfile"]
        DockerfileSUC["package/Dockerfile.suc"]
        RunSUC["package/suc/run.sh"]
        InstallScript["install.sh"]
        ScriptsPkg["scripts/package/"]
        ScriptsPkgSUC["scripts/package-suc/"]
    end

    %% Connections
    Config -->|"startup config"| LocalWatcher
    Config -->|"startup config"| K8sWatcher
    LocalWatcher -->|"PlanCreated/Updated"| Controller
    K8sWatcher -->|"PlanCreated/Updated"| Controller
    Version -->|"build metadata"| Controller
    Controller -->|"execute plan"| Applyinator
    Applyinator -->|"file ops, scripts"| OSFS
    Applyinator -->|"pull/unpack images"| ImageUtils
    ImageUtils -->|"fetch images"| ContainerReg
    Applyinator -->|"invoke probes"| Prober
    Prober -->|"health checks"| OSFS
    Prober -->|"CR status updates"| K8sAPI

    %% Click Events
    click Config "https://github.com/rancher/system-agent/blob/main/pkg/config/config.go"
    click LocalWatcher "https://github.com/rancher/system-agent/blob/main/pkg/localplan/watcher.go"
    click K8sWatcher "https://github.com/rancher/system-agent/blob/main/pkg/k8splan/watcher.go"
    click Controller "https://github.com/rancher/system-agent/blob/main/main.go"
    click Applyinator "https://github.com/rancher/system-agent/blob/main/pkg/applyinator/applyinator.go"
    click ImageUtils "https://github.com/rancher/system-agent/blob/main/pkg/image/util.go"
    click Prober "https://github.com/rancher/system-agent/blob/main/pkg/prober/prober.go"
    click Version "https://github.com/rancher/system-agent/blob/main/pkg/version/version.go"
    click DockerfileDapper "https://github.com/rancher/system-agent/blob/main/Dockerfile.dapper"
    click DockerfilePkg "https://github.com/rancher/system-agent/tree/main/package/Dockerfile"
    click DockerfileSUC "https://github.com/rancher/system-agent/blob/main/package/Dockerfile.suc"
    click RunSUC "https://github.com/rancher/system-agent/blob/main/package/suc/run.sh"
    click InstallScript "https://github.com/rancher/system-agent/blob/main/install.sh"
    click ScriptsPkg "https://github.com/rancher/system-agent/tree/main/scripts/package/"
    click ScriptsPkgSUC "https://github.com/rancher/system-agent/tree/main/scripts/package-suc/"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef external fill:#DFFFD0,stroke:#228B22,color:#228B22,stroke-width:1px
    classDef os fill:#F0F0F0,stroke:#666666,color:#333333,stroke-width:1px
```
