# maeshinshin/ichor architecture

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

- Interactive diagram: https://gitdiagram.com/maeshinshin/ichor
- Repository: https://github.com/maeshinshin/ichor

## Overview

Ichor is a Kubernetes-native manager for Talos Linux clusters. Users initialize a new cluster or adopt an existing one, then manage machines, operations, CNI, storage, and backups through the CLI, web UI, or kubectl; Kubernetes custom resources hold the desired state. Controllers reconcile those resources against Talos nodes and cluster services. The graph preserves documented security, identity, and installation capabilities. Some subsystem links rely on README-level descriptions because their implementation was not sampled.

Main entry points: [`api/v1alpha1/taloscluster_types.go`](https://github.com/maeshinshin/ichor/blob/main/api/v1alpha1/taloscluster_types.go) (Cluster resources), [`cmd/ichor-ui/main.go`](https://github.com/maeshinshin/ichor/blob/main/cmd/ichor-ui/main.go) (Web UI), [`internal/uiapi/server.go`](https://github.com/maeshinshin/ichor/blob/main/internal/uiapi/server.go) (UI API), [`internal/webhook/v1alpha1/taloscluster_webhook.go`](https://github.com/maeshinshin/ichor/blob/main/internal/webhook/v1alpha1/taloscluster_webhook.go) (Admission validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Ichor CLI<br/>[root.go]"]
  node_webui["Web UI<br/>[main.go]"]
  node_kubectl["kubectl"]
  node_uiapi["UI API<br/>[server.go]"]
end

subgraph group_api["Kubernetes API"]
  node_crds[("Cluster resources")]
  node_admission["Admission validation"]
end

subgraph group_reconcile["Cluster reconciliation"]
  node_machine["Machine reconciliation"]
  node_cni["CNI handover"]
  node_storage["Storage coordination"]
end

subgraph group_operations["Operations and services"]
  node_machineops["Operation execution"]
  node_backup["etcd backup and restore<br/>[restore.go]"]
  node_installer["Cluster installation<br/>[install.go]"]
end

subgraph group_identity["Identity and security"]
  node_oidc["OIDC login<br/>[flow.go]"]
  node_users["User management<br/>[user_service.go]"]
  node_override["Operation safeguards"]
end

node_operator(("Cluster operator"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses console"| node_webui
node_operator -->|"applies resources"| node_kubectl
node_cli -->|"manages resources"| node_crds
node_webui -->|"calls API"| node_uiapi
node_uiapi -->|"reads and writes"| node_crds
node_kubectl -->|"manages resources"| node_crds
node_admission -->|"validates changes"| node_crds
node_machine -->|"reconciles machines"| node_crds
node_cni -->|"reconciles CNI"| node_crds
node_storage -->|"reads storage state"| node_crds
node_machineops -->|"reconciles operations"| node_crds
node_crds -.->|"specifies backups"| node_backup
node_operator -->|"installs manager"| node_installer
node_webui -->|"authenticates with"| node_oidc
node_uiapi -.->|"serves user actions"| node_users
node_admission -->|"gates overrides"| node_override

click node_cli "https://github.com/maeshinshin/ichor/blob/main/internal/cli/root.go"
click node_webui "https://github.com/maeshinshin/ichor/blob/main/cmd/ichor-ui/main.go"
click node_uiapi "https://github.com/maeshinshin/ichor/blob/main/internal/uiapi/server.go"
click node_crds "https://github.com/maeshinshin/ichor/blob/main/api/v1alpha1/taloscluster_types.go"
click node_admission "https://github.com/maeshinshin/ichor/blob/main/internal/webhook/v1alpha1/taloscluster_webhook.go"
click node_machine "https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosmachine_controller.go"
click node_cni "https://github.com/maeshinshin/ichor/blob/main/internal/controller/cnihandover_controller.go"
click node_storage "https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosstorage_controller.go"
click node_machineops "https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosoperation_controller.go"
click node_backup "https://github.com/maeshinshin/ichor/blob/main/internal/etcdbackup/restore.go"
click node_installer "https://github.com/maeshinshin/ichor/blob/main/internal/installer/install.go"
click node_oidc "https://github.com/maeshinshin/ichor/blob/main/internal/oidcissuer/flow.go"
click node_users "https://github.com/maeshinshin/ichor/blob/main/internal/uiapi/user_service.go"
click node_override "https://github.com/maeshinshin/ichor/blob/main/internal/webhook/v1alpha1/override_webhook.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_cli,node_webui,node_kubectl,node_uiapi toneBlue
class node_crds,node_admission toneAmber
class node_machine,node_cni,node_storage toneMint
class node_machineops,node_backup,node_installer toneRose
class node_oidc,node_users,node_override,node_operator toneIndigo
```

## Components

### User entry points

- [Ichor CLI](https://github.com/maeshinshin/ichor/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Web UI](https://github.com/maeshinshin/ichor/blob/main/cmd/ichor-ui/main.go): `cmd/ichor-ui/main.go`
- **kubectl**
- [UI API](https://github.com/maeshinshin/ichor/blob/main/internal/uiapi/server.go): `internal/uiapi/server.go`

### Kubernetes API

- [Cluster resources](https://github.com/maeshinshin/ichor/blob/main/api/v1alpha1/taloscluster_types.go): `api/v1alpha1/taloscluster_types.go`
- [Admission validation](https://github.com/maeshinshin/ichor/blob/main/internal/webhook/v1alpha1/taloscluster_webhook.go): `internal/webhook/v1alpha1/taloscluster_webhook.go`

### Cluster reconciliation

- [Machine reconciliation](https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosmachine_controller.go): `internal/controller/talosmachine_controller.go`
- [CNI handover](https://github.com/maeshinshin/ichor/blob/main/internal/controller/cnihandover_controller.go): `internal/controller/cnihandover_controller.go`
- [Storage coordination](https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosstorage_controller.go): `internal/controller/talosstorage_controller.go`

### Operations and services

- [Operation execution](https://github.com/maeshinshin/ichor/blob/main/internal/controller/talosoperation_controller.go): `internal/controller/talosoperation_controller.go`
- [etcd backup and restore](https://github.com/maeshinshin/ichor/blob/main/internal/etcdbackup/restore.go): `internal/etcdbackup/restore.go`
- [Cluster installation](https://github.com/maeshinshin/ichor/blob/main/internal/installer/install.go): `internal/installer/install.go`

### Identity and security

- [OIDC login](https://github.com/maeshinshin/ichor/blob/main/internal/oidcissuer/flow.go): `internal/oidcissuer/flow.go`
- [User management](https://github.com/maeshinshin/ichor/blob/main/internal/uiapi/user_service.go): `internal/uiapi/user_service.go`
- [Operation safeguards](https://github.com/maeshinshin/ichor/blob/main/internal/webhook/v1alpha1/override_webhook.go): `internal/webhook/v1alpha1/override_webhook.go`

### Other components

- **Cluster operator**

## Connections

- Cluster operator → Ichor CLI: runs commands (evidence: `README.md`)
- Cluster operator → Web UI: uses console (evidence: `README.md`)
- Cluster operator → kubectl: applies resources (evidence: `README.md`)
- Ichor CLI → Cluster resources: manages resources (evidence: `README.md`)
- Web UI → UI API: calls API (evidence: `internal/uiapi/server.go`)
- UI API → Cluster resources: reads and writes (evidence: `internal/uiapi/server.go`)
- kubectl → Cluster resources: manages resources (evidence: `README.md`)
- Admission validation → Cluster resources: validates changes (evidence: `internal/webhook/v1alpha1/taloscluster_webhook.go`)
- Machine reconciliation → Cluster resources: reconciles machines (evidence: `internal/controller/talosmachine_controller.go`)
- CNI handover → Cluster resources: reconciles CNI (evidence: `internal/controller/cnihandover_controller.go`)
- Storage coordination → Cluster resources: reads storage state (evidence: `internal/controller/talosstorage_controller.go`)
- Operation execution → Cluster resources: reconciles operations (evidence: `internal/controller/talosoperation_controller.go`)
- Cluster resources → etcd backup and restore: specifies backups (evidence: `README.md`)
- Cluster operator → Cluster installation: installs manager (evidence: `README.md`)
- Web UI → OIDC login: authenticates with (evidence: `cmd/ichor-ui/main.go`)
- UI API → User management: serves user actions
- Admission validation → Operation safeguards: gates overrides (evidence: `internal/webhook/v1alpha1/override_webhook.go`)