Overview
Contributing to the docs

Guides

Getting started
Adopt a running Talos cluster and reclaim a machine
Hardening the clusters Ichor creates
Install Ichor with Helm
Rotating the service-account and secretbox keys
Settings
Users and login

Concepts

Clusters and machines
Operations
CNI and Cilium
Security model
CA and key rotation

Design

Ichor architecture

Development

Build from source

Decision records
0137. An operation parked for an even control-plane count does not block its own cure
0136. An orphan of a managed cluster is wiped with the cluster's own credentials
0135. Remove and reset are one action that wipes the node and deletes its Kubernetes Node
0134. ichor init --merge-kubeconfig merges the new cluster into the user's kubeconfig
0133. An Ichor upgrade records the version it upgrades to in its status
0132. The docs site renders docs/ in place with Astro, preactcn and Pagefind, and deploys to GitHub Pages
0131. Changing the Cilium values needs an admin-only verb, and the Cilium Secrets namespaces are pinned
0130. No free-text reason is asked for anywhere
0129. Admission enforces the checks the UI backend makes, so a hand-written CR gets no shortcut
0128. Adopting installed Talos machines and clusters: what is covered, the gaps, and what closes them
0127. The local secrets bundle is encrypted with an age passphrase
0126. FQDN rules for ichor-ui's external endpoint and no metrics scraping unless a namespace is named
0125. Kubelet serving certificates are requested by the kubelets and approved by the controller
0124. An os:reader talosconfig role
0123. SecureBoot, UKI and kernel lockdown are typed options that pick the installer, check each node and never change one in place
0122. The installer image runs by digest and its signature is verified before the installer Job
0121. The service-account key and the secretbox key rotate in a dual-key period, and the backup key is versioned
0120. The CA rotation also replaces the etcd CA and the Kubernetes aggregator CA
0119. A daily CI run turns a new Cilium patch into a pull request
0118. Human output by default; YAML and JSON on request
0117. ichor init reads a structured config file
0116. Patch upgrades can be applied automatically when a setting allows it
0115. The release set decides a first install only; each component upgrades on its own
0114. Ichor tells the cluster when a newer release is published
0113. The cluster follows the release set of its Ichor
0112. Approval picks the install disk and NIC from what discovery recorded
0111. An upgrade prunes what the previous run installed and the new manifest drops
0110. The safety-check override is a flag, and its reason is optional
0109. The safety-check override (formerly ADR 0065's mechanism) is named override
0108. Security hardening
0107. Reset and add replaces the override reclaim switch
0106. HA findings: a patch is dry-rendered at admission, a restore refuses an in-cluster backup store, an unreachable node says so, and a dead control plane can be removed
0105. ichor-ui is TLS-only with an Ichor-made serving certificate and a CA the edge can verify, and Ichor's own runtime settings live in IchorInstallation, editable from a Settings tab
0104. A cluster with no CNI gets Ichor's Cilium before Ichor, and Ichor is installable with Helm
0103. Deploy onto machines that already run Talos
0102. The e2e harness clones a cached Talos ISO and still installs from it
0101. Argo CD and Kokumi are no longer part of Ichor
0100. Ichor ships CiliumNetworkPolicies for its own namespace, applied after Cilium is Ready
0099. Argo CD and Kokumi become Ichor's standard stack; Cilium is the only CNI and Ichor's own Helm release
0098. The Cilium bootstrap manifest is the embedded chart rendered with Helm
0097. The UI is built for one cluster
0096. A Secret reference is set or changed only with update on the resource's secret-references
0095. A failed operation step is retried by an annotation the controller acts on once
0094. Ichor users, its own OIDC issuer, roles and per-user kubeconfigs
0093. The UI hands over a CA rotation's new credentials to administrators who hold the download verb
0092. Approval sets the primary NIC, its addressing and extra disk roles as typed spec fields
0091. A CA rotation waits for the operator's new credentials before anything they hold stops working
0090. Air-gapped installs are out of scope
0089. A live etcd restore is a controller-run operation whose progress outlives the API in a marker next to the backups
0088. A renderer change is a desired-state change, not drift
0087. The Kubernetes upgrade runs in three stages: control-plane components, then kube-proxy, then kubelets
0086. A moved node is followed through status, not spec
0085. Node actions are controller-run operations of kind node
0084. Admin-gated support bundle, etcd snapshot and packet capture downloads
0083. Add a node from the cluster page; toasts; alert-dialog confirms; logs in a code block
0082. The machine page shows live Talos and Kubernetes state, read-only
0081. The UI demo cluster is built by ichor init, pulling Ichor's images from a throwaway in-namespace registry
0080. Reboot-requiring configuration changes roll out through an explicit config operation
0079. Node logs start from the tail and the viewer is bounded
0078. UI app shell: sidebar, breadcrumb bar, and "On this page" section navigation
0077. Pod and service subnets, the CNI Talos runs and the install disk are spec fields rendered per contract
0076. Approved machines in maintenance mode are provisioned over the insecure API and followed to running
0075. adopt skips unapproved machines and names the v1.14 documents it cannot capture
0074. UI mobile layout: wrapping header, and a scrollbar gutter instead of scroll-lock padding
0073. A read-only Talos details view on the machine page
0072. The patch screens explain themselves; documents are cards, and the preview nudges without blocking
0071. The machine list shows the Ready condition, not Talos's stage
0070. The UI is English only, with a light/dark switch
0069. Control-plane metrics are exposed by spec.controlPlaneMetrics and fenced by one source-restricting firewall rule
0068. The UI and CLI start, follow, pause and delete TalosOperations through one OperationService, and write the spec first
0067. Whole-cluster shutdown is a TalosOperation kind the controller runs, with a derived mark that refuses other disruptive work
0066. The kube-proxy switch is a TalosOperation of kind cni; Ichor changes the Talos side and removes kube-proxy, and the CNI's owner changes the CNI
0065. Override: a direct write that also opens the matching PR
0064. The UI is localised in English and Japanese with a typed dictionary and no library
0063. CA expiry is read from the secrets bundle and published; CA rotation is decided here and built as the ca-rotation operation
0062. GitOps page and external tool links
0061. A TalosMachine re-reconciles when a render input's spec changes
0060. A TalosMachine requeues a failure that time can fix, and only that
0059. IchorInstallation holds the target version; a TalosOperation of kind ichor runs an installer Job that carries its own manifests, snapshots, and rolls back
0058. OIDC login and Kubernetes impersonation for ichor-ui
0057. The Kubernetes upgrade applies the rendered configuration node by node; talosctl's upgrade-k8s is not reused whole
0056. TalosCluster.spec.gitops: a repository connection, strict mode, and the UI/CLI opening PRs
0055. Cilium stays Synced under Argo CD with ignoreDifferences on CiliumIdentity and ServerSideApply
0054. Approving control planes is capped at count+1, and schedulable false needs a worker
0053. ichor restore --recover-cluster: full-loss etcd recovery from the bundle and a snapshot
0052. TalosMachine.spec.nodeLabels is rendered, wins over the TalosStorage preset, and a kubelet-forbidden label is a render error
0051. UI and CLI writes refuse a CR that Argo CD or Flux tracks
0050. TalosStorage layer 1 renders as the system layer, selected by one shared rule, with a status controller
0049. The CLI calls the Connect API through ichor ui's tunnel and falls back to the same handlers in-process
0048. Kokumi is an option of ichor init's Argo CD hand-off, designed now and built later
0047. TalosEtcdBackup: verified, bundle-keyed age snapshots in S3
0046. Argo CD health checks ship as an opt-in ConfigMap shaped like argocd-cm keys
0045. UI behaviour that can hurt a cluster is tested as pure functions in ui/src/lib, not through rendered pages
0044. Tracking detection moves to pkg/gitopstracking; pkg/prmode.Decide turns it into a write-vs-PR gate
0043. The Talos upgrade executor is one per-node function behind ADR 0026's seam
0042. Reset is opt-in per removal, named partitions only, and idempotent by recording after the ack
0041. Four fixes from the phase 3-6 security review
0040. The UI backend gets one metric, the controller gets zero, and monitoring stays optional in the chart
0039. Config editing UI: PatchService screens, opaque-JSON editing, no generic schema-driven renderer
0038. PR mode: clone, push and open a PR with net/http and the git binary, never a host SDK
0037. PR mode's file-finding and byte-preserving YAML edit, as pkg/prmode
0036. ichor images list cannot resolve catalogs or schematics, and says so
0035. PatchService: the config-editing backend
0034. Config editing UI: the layer-grouped effective-config view, and why the rest waits on proto
0033. strongIdentity and loadBundle: two call sites, one rule each
0032. Etcd member removal completes the removal sequence; Reset stays a separate unit
0031. Fixing two kubebuilder scaffold remnants that actually ship
0030. ichor ui: find the pod through its Service, reforward on failure
0029. The ADR index is generated from each file's own header, not hand-maintained
0028. ichor gitops export/handoff: an allow-list, two tracking checks, a one-field patch
0027. Private registry auth through a Secret reference on TalosCluster
0026. TalosOperation: the backbone every upgrade kind shares, with none of their execution
0025. The storage-system side of the node-operation evacuation hook
0024. CNI hand-over: no registry, render-time removal, a separate controller
0023. TalosStorage and the longhorn-v1 disk preset
0022. pkg/upgrade: version checks machinery already answers, and the ones it doesn't
0021. UI: read and approval screens on the generated TS client
0020. Giving ichor-ui a shipping path
0019. ichor init: scope, the namespace decision, and the gaps it leaves open
0018. UI backend: the read and approval server implementation
0017. UI skeleton: ui/, ichor-ui as a separate binary, building without it
0016. Connect API: phase 5 read and approval surface
0015. GitOps: a hand-rolled Application type, and a policy-free repo skeleton
0014. CLI skeleton under cmd/ichor, and how ichor adopt guarantees zero drift
0013. CNI presets: the interface, custom's contract, Hubble's certificates, and where the guards live
0012. Mirroring the volume config document kinds for disk roles
0011. Discovery does not choose its own candidates, and never auto-registers a weak identity
0010. The quorum and last-control-plane delete guards are stronger than allow-delete
0009. Reboot necessity is predicted, because Talos will not answer it
0008. controlPlane.schedulable drops auto
0007. e2e runs Talos nodes on a real cluster
0006. Webhook serving certificates without cert-manager, failing closed
0005. controller-gen, kustomize, setup-envtest and golangci-lint come from the Makefile
0004. Phase 1 creates three kinds, not seven
0003. Typed configuration through generated mirror types
0002. Nix devShell and Go pin
0001. Use ADRs
NNNN. Title

GitHub

Unreleased (main)

These are the development docs; they can describe changes no release has yet.

Docs
0001. Use ADRs

0001. Use ADRs

Status: Accepted · Date: 2026-10-24 · Design section: —

Decided: Record decisions as one-file-per-decision ADRs, linked from the PR that makes them

Context

The design document leaves defaults, naming and library choices to whoever implements each part. Those choices need to be findable later.

Decision

Record them here, one file each, and link them from the PR that makes them.

Consequences

The design document stays about architecture. Reviewers can see why something is the way it is without digging through PR threads.

Edit this page on GitHub

0002. Nix devShell and Go pin

On this page

Context
Decision
Consequences

Search the docs

Search pages and headings