0048. Kokumi is an option of ichor init's Argo CD hand-off, designed now and built later

Status: Accepted (implemented 2026-10-27); superseded in part by ADR 0090 (ichor images list --kokumi removed) and in part by ADR 0099 · Date: 2026-10-26 · Design section: GitOps and Argo CD

Decided: ichor init --argocd --kokumi prepares the OCI repo-creds Secret, installs neither Kokumi nor Argo CD, and leaves the repository skeleton (including the Cilium Application) unchanged; ichor images list --kokumi names Kokumi 0.17.0's images

Context

A user asked for Kokumi to be usable with Ichor, specifically "as an option when installing Argo CD", not as an ichor gitops export target, a PR-mode destination or a third kind of tracking detection.

Verified from Kokumi's own docs (kokumi.dev, github.com/kokumi-dev/kokumi, read 2026-10-26): an OCI-first delivery operator, Apache-2.0, "currently experimental". Renders become immutable content-addressed OCI artifacts (Preparations); a Serving creates or updates an Argo CD Application in the argocd namespace with spec.source.repoURL set to the Preparation's OCI artifact and targetRevision to its digest. It requires Argo CD >= 3.3 installed first and Kubernetes >= 1.26. It installs by kubectl apply -f of a release install.yaml. Argo CD needs a repo-creds Secret (argocd.argoproj.io/secret-type: repo-creds, type: oci, url: oci://kokumi-registry.kokumi.svc.cluster.local:5000, insecureOCIForceHttp: "true" because the bundled registry serves plain HTTP). Kokumi's Applications have no resources-finalizer.

Decision

Design only (architecture.md, "Kokumi as the delivery layer in front of Argo CD"):

• init offers Kokumi as a choice of the Argo CD hand-off. It prepares the repo-creds Secret from the CLI (never into Git) and installs neither Argo CD nor Kokumi, consistent with ADR 0019: fetching and trusting a third-party release during a privileged bootstrap is not init's call.
• Ichor's tracking detection, Flux handling and argocd-cm reading are unchanged.
• Flag name (--delivery kokumi is a placeholder) is left to implementation.

Why the first cut left implementation out

Reconciling the design against the code turned up gaps that matter more than a new option, and they should be filled first so Kokumi is not built on top of them. Adding a delivery layer before those are closed would widen the surface that has to be re-verified.

Unknowns (what to check before building)

• (Partly answered, ADR 0055: in Kokumi's source at commit 4126144 the Application is hard-coded with prune, selfHeal and ServerSideApply=true, has no ignoreDifferences, and edits to it are reverted. No sync-wave or other options are passed. Still to confirm on a test cluster.)
• Whether Kokumi's Application can be given a ref/path or only a bare artifact, and whether its Applications can carry Ichor's sync-wave and sync options. Check: Kokumi's Serving CRD reference and a generated Application on a test cluster.
• How the root Application (source: a repository) coexists with Kokumi-created Applications, and which Ichor CRs would be delivered as Products/Orders. Check: Kokumi's Product/Order schema and "Producing Base Artifacts" guide. Not in the pages read.
• Air gap: the images Kokumi itself and its scanner need, and how to mirror its artifacts. Check: Kokumi's Container Images (operator guide) and Registries guides; the pages read only listed these topics.
• The Argo CD version range: Kokumi says >= 3.3; ADR 0019 verified shapes against v3.5.x. Likely compatible, not tested.
• Kokumi's project status is "experimental"; its API is v1alpha1.

Consequences

• Without --kokumi, init --argocd behaves as ADR 0019 describes.
• ichor images list --kokumi prints Kokumi's images (see Implementation); it needed a section only if Kokumi's images are shown to be mirrorable through the existing path.

Implementation (2026-10-27)

Accepted and built, in the narrow form the Decision above describes.

• Source confirmed: github.com/kokumi-dev/kokumi, release 0.17.0 (2026-10-11, latest at the time), one asset install.yaml (sha256 345223726800ca3f08f633c76c91a38265bc0c131551b24dc49c69ee0cd7b840). Its CRDs are in delivery.kokumi.dev (Approval, Kitchen, Menu, Order, Pantry, Preparation, Recipe, Serving); everything runs in namespace kokumi. The pinned version lives in internal/cli/kokumi.go (kokumiVersion).
• Flag: ichor init --argocd --kokumi (--kokumi without --argocd is refused before anything happens). The old --delivery kokumi placeholder was not used: this is a boolean refinement of --argocd, not a choice among delivery kinds.
• What it does: creates the Secret kokumi-registry-repo-creds in --argocd-namespace (argocd.argoproj.io/secret-type: repo-creds, type: oci, url: oci://kokumi-registry.kokumi.svc.cluster.local:5000, insecureOCIForceHttp: "true"; the service name and port 5000 were checked in 0.17.0's install.yaml). Soft-fail like the repository Secret. It prints that Kokumi was not installed.
• What it does not do: the repository skeleton is byte-identical with and without --kokumi (tested). Ichor writes no Kokumi CRs (Kitchen, Menu, Order, Serving...) and moves none of its own CRs behind Kokumi. This is the conservative answer to the root-Application coexistence unknown: the root Application keeps delivering everything Ichor generates.
• Cilium: the Cilium Application stays a plain Argo CD Application in the repository (apps/cni/application.yaml, delivered by the root Application), so it keeps ignoreDifferences and ServerSideApply=true (ADR 0055). Kokumi never delivers Cilium, which removes the open question rather than answering the argocd-cm route. A user who delivers other things through Kokumi is unaffected.
• Air gap: Kokumi 0.17.0's install.yaml runs two images, listed by ichor images list --kokumi under kokumiImages with their upstream registries (not rewritten by --image-registry): ghcr.io/kokumi-dev/kokumi:0.17.0 (operator and server) and docker.io/library/registry:3.1.2@sha256:ddf75434.... Images referenced in Orders/Recipes at runtime are the user's and not listed.
• gitops export and gitops handoff are unchanged: Kokumi-created Applications are ordinary Argo CD Applications and tracking detection is untouched.

Deferred: delivering any Ichor CR through Kokumi; the Argo CD >= 3.3 check and Kubernetes >= 1.26 check; testing against a real cluster (not done, no cluster was touched); a TLS or authenticated Kokumi registry (the Secret assumes the bundled plain-HTTP one); tracking Kokumi upgrades past 0.17.0 (v1alpha1, experimental).