# rancher/elemental-operator architecture

> Architecture diagram of the GitHub repository rancher/elemental-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rancher/elemental-operator
- Repository: https://github.com/rancher/elemental-operator

## Overview

Elemental Operator manages OS provisioning and lifecycle for machines joining Rancher-managed Kubernetes. The principal flow is a live-ISO machine running elemental-register, which exchanges registration data with the operator; the operator records machine inventory and reconciles provisioning plans. Separate operator capabilities select/adopt inventories, build seed images, and manage OS images and version channels. The graph distinguishes those domain controllers from the internal registration client/server and installation layer. Several controller interactions are documented only at product level or were not excerpted, so those links are dashed and unverified.

Main entry points: [`cmd/operator/operator/root.go`](https://github.com/rancher/elemental-operator/blob/main/cmd/operator/operator/root.go) (Operator setup), [`cmd/register/main.go`](https://github.com/rancher/elemental-operator/blob/main/cmd/register/main.go) (Register command), [`pkg/server/server.go`](https://github.com/rancher/elemental-operator/blob/main/pkg/server/server.go) (Inventory HTTP server), [`controllers/machineinventory_controller.go`](https://github.com/rancher/elemental-operator/blob/main/controllers/machineinventory_controller.go) (Inventory reconciliation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_operatorcli["Operator command<br/>[main.go]"]
  node_registercli["Register command<br/>[main.go]"]
  node_supportcli["Support collection<br/>[main.go]"]
end

subgraph group_registration["Machine registration"]
  node_registrationclient["Registration client<br/>[register.go]"]
  node_httpserver["Inventory HTTP server<br/>[server.go]"]
  node_registrationapi["Registration API"]
end

subgraph group_lifecycle["Machine lifecycle"]
  node_inventory["Inventory reconciliation"]
  node_registrationcontroller["Registration reconciliation"]
  node_selector["Inventory selection"]
end

subgraph group_osmanagement["OS management"]
  node_seedimage["Seed image builds"]
  node_managedimage["Managed OS images"]
  node_managedversion["Managed OS versions"]
  node_versionchannel["Version channel sync"]
end

subgraph group_internals["Provisioning internals"]
  node_api["Kubernetes API types"]
  node_operator["Operator setup<br/>[root.go]"]
  node_clients["Kubernetes clients<br/>[clients.go]"]
  node_installer["OS installer<br/>[install.go]"]
  node_hostinfo["Host information<br/>[hostinfo.go]"]
  node_supportagent["System agent interface<br/>[api.go]"]
end

node_machine(("Booting machine"))

node_operatorcli -->|"dispatches"| node_operator
node_registercli -->|"registers with"| node_registrationclient
node_machine -.->|"runs"| node_registercli
node_registrationclient -.->|"connects by WebSocket"| node_httpserver
node_httpserver -->|"routes requests"| node_registrationapi
node_httpserver -->|"creates inventory"| node_inventory
node_operator -.->|"creates clients"| node_clients
node_operator -.->|"registers controller"| node_inventory
node_operator -.->|"registers controller"| node_registrationcontroller
node_operator -.->|"registers controller"| node_selector
node_operator -.->|"registers controller"| node_seedimage
node_operator -.->|"registers controller"| node_managedimage
node_operator -.->|"registers controller"| node_managedversion
node_operator -.->|"registers controller"| node_versionchannel
node_registercli -.->|"installs OS"| node_installer
node_registercli -.->|"loads configuration types"| node_api
node_registrationapi -.->|"reads host data"| node_hostinfo
node_inventory -->|"uses plans"| node_supportagent
node_seedimage -->|"references registration"| node_registrationcontroller
node_versionchannel -->|"creates versions"| node_managedversion
node_supportcli -.->|"collects diagnostics"| node_supportagent
node_operator -->|"uses resource types"| node_api

click node_operatorcli "https://github.com/rancher/elemental-operator/blob/main/cmd/operator/main.go"
click node_registercli "https://github.com/rancher/elemental-operator/blob/main/cmd/register/main.go"
click node_supportcli "https://github.com/rancher/elemental-operator/blob/main/cmd/support/main.go"
click node_api "https://github.com/rancher/elemental-operator/blob/main/api/v1beta1/zz_generated.deepcopy.go"
click node_operator "https://github.com/rancher/elemental-operator/blob/main/cmd/operator/operator/root.go"
click node_clients "https://github.com/rancher/elemental-operator/blob/main/pkg/clients/clients.go"
click node_registrationclient "https://github.com/rancher/elemental-operator/blob/main/pkg/register/register.go"
click node_httpserver "https://github.com/rancher/elemental-operator/blob/main/pkg/server/server.go"
click node_registrationapi "https://github.com/rancher/elemental-operator/blob/main/pkg/server/api_registration.go"
click node_inventory "https://github.com/rancher/elemental-operator/blob/main/controllers/machineinventory_controller.go"
click node_registrationcontroller "https://github.com/rancher/elemental-operator/blob/main/controllers/machineregistration_controller.go"
click node_selector "https://github.com/rancher/elemental-operator/blob/main/controllers/machineselector_controller.go"
click node_seedimage "https://github.com/rancher/elemental-operator/blob/main/controllers/seedimage_controller.go"
click node_managedimage "https://github.com/rancher/elemental-operator/blob/main/controllers/managedosimage_controller.go"
click node_managedversion "https://github.com/rancher/elemental-operator/blob/main/controllers/managedosversion_controller.go"
click node_versionchannel "https://github.com/rancher/elemental-operator/blob/main/controllers/managedosversionchannel_controller.go"
click node_installer "https://github.com/rancher/elemental-operator/blob/main/pkg/install/install.go"
click node_hostinfo "https://github.com/rancher/elemental-operator/blob/main/pkg/hostinfo/hostinfo.go"
click node_supportagent "https://github.com/rancher/elemental-operator/blob/main/internal/system-agent/api.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_operatorcli,node_registercli,node_supportcli toneBlue
class node_registrationclient,node_httpserver,node_registrationapi toneAmber
class node_inventory,node_registrationcontroller,node_selector toneMint
class node_seedimage,node_managedimage,node_managedversion,node_versionchannel toneRose
class node_api,node_operator,node_clients,node_installer,node_hostinfo,node_supportagent,node_machine toneIndigo
```

## Components

### Entry points

- [Operator command](https://github.com/rancher/elemental-operator/blob/main/cmd/operator/main.go): `cmd/operator/main.go`
- [Register command](https://github.com/rancher/elemental-operator/blob/main/cmd/register/main.go): `cmd/register/main.go`
- [Support collection](https://github.com/rancher/elemental-operator/blob/main/cmd/support/main.go): `cmd/support/main.go`

### Machine registration

- [Registration client](https://github.com/rancher/elemental-operator/blob/main/pkg/register/register.go): `pkg/register/register.go`
- [Inventory HTTP server](https://github.com/rancher/elemental-operator/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Registration API](https://github.com/rancher/elemental-operator/blob/main/pkg/server/api_registration.go): `pkg/server/api_registration.go`

### Machine lifecycle

- [Inventory reconciliation](https://github.com/rancher/elemental-operator/blob/main/controllers/machineinventory_controller.go): `controllers/machineinventory_controller.go`
- [Registration reconciliation](https://github.com/rancher/elemental-operator/blob/main/controllers/machineregistration_controller.go): `controllers/machineregistration_controller.go`
- [Inventory selection](https://github.com/rancher/elemental-operator/blob/main/controllers/machineselector_controller.go): `controllers/machineselector_controller.go`

### OS management

- [Seed image builds](https://github.com/rancher/elemental-operator/blob/main/controllers/seedimage_controller.go): `controllers/seedimage_controller.go`
- [Managed OS images](https://github.com/rancher/elemental-operator/blob/main/controllers/managedosimage_controller.go): `controllers/managedosimage_controller.go`
- [Managed OS versions](https://github.com/rancher/elemental-operator/blob/main/controllers/managedosversion_controller.go): `controllers/managedosversion_controller.go`
- [Version channel sync](https://github.com/rancher/elemental-operator/blob/main/controllers/managedosversionchannel_controller.go): `controllers/managedosversionchannel_controller.go`

### Provisioning internals

- [Kubernetes API types](https://github.com/rancher/elemental-operator/blob/main/api/v1beta1/zz_generated.deepcopy.go): `api/v1beta1/zz_generated.deepcopy.go`
- [Operator setup](https://github.com/rancher/elemental-operator/blob/main/cmd/operator/operator/root.go): `cmd/operator/operator/root.go`
- [Kubernetes clients](https://github.com/rancher/elemental-operator/blob/main/pkg/clients/clients.go): `pkg/clients/clients.go`
- [OS installer](https://github.com/rancher/elemental-operator/blob/main/pkg/install/install.go): `pkg/install/install.go`
- [Host information](https://github.com/rancher/elemental-operator/blob/main/pkg/hostinfo/hostinfo.go): `pkg/hostinfo/hostinfo.go`
- [System agent interface](https://github.com/rancher/elemental-operator/blob/main/internal/system-agent/api.go): `internal/system-agent/api.go`

### Other components

- **Booting machine**

## Connections

- Operator command → Operator setup: dispatches (evidence: `cmd/operator/main.go`)
- Register command → Registration client: registers with (evidence: `cmd/register/main.go`)
- Booting machine → Register command: runs
- Registration client → Inventory HTTP server: connects by WebSocket
- Inventory HTTP server → Registration API: routes requests (evidence: `pkg/server/server.go`)
- Inventory HTTP server → Inventory reconciliation: creates inventory (evidence: `pkg/server/server.go`)
- Operator setup → Kubernetes clients: creates clients
- Operator setup → Inventory reconciliation: registers controller
- Operator setup → Registration reconciliation: registers controller
- Operator setup → Inventory selection: registers controller
- Operator setup → Seed image builds: registers controller
- Operator setup → Managed OS images: registers controller
- Operator setup → Managed OS versions: registers controller
- Operator setup → Version channel sync: registers controller
- Register command → OS installer: installs OS
- Register command → Kubernetes API types: loads configuration types
- Registration API → Host information: reads host data
- Inventory reconciliation → System agent interface: uses plans (evidence: `controllers/machineinventory_controller.go`)
- Seed image builds → Registration reconciliation: references registration (evidence: `controllers/seedimage_controller.go`)
- Version channel sync → Managed OS versions: creates versions (evidence: `controllers/managedosversionchannel_controller.go`)
- Support collection → System agent interface: collects diagnostics
- Operator setup → Kubernetes API types: uses resource types (evidence: `cmd/operator/operator/root.go`)
