kohen

KOHEN

Kohen is a Kubernetes-native configuration management tool that lets applications consume configuration from a dedicated git repository and consistently roll out after any change.

Kohen is not an alternative to GitOps solutions. It adds capabilities for applications that prefer running against a dedicated configuration repository covering multiple environments, and is engineered to coexist with Argo CD / Flux rather than replace them (see GitOps coexistence and the "when to use Kohen — and when not" decision table in SPEC.md §2.4).

In one ConfigSync you point at a git repo + path and a workload; Kohen renders the path into a ConfigMap, mounts it into the workload, and rolls the workload whenever the config changes — version-matched across the fleet.

Documentation

• SPEC.md — full technical/non-technical requirements, architecture, consistency model, threat model, and acceptance criteria.
• PLAN.md — the implementation sequence toward v1.0.
• Concepts — architecture, reconcile flow, consistency model.
• Install — Helm and plain manifests, both RBAC scopes.
• Getting Started & GitOps runbook — verified Day-1 walkthrough (install → sync → rollout → auth → rollback → GitOps coexistence), exercised in CI on kind.
• Secret integration guide (ESO + native) — reference secrets safely; readiness, rotation, guard rails, Vault-via-ESO tree.
• Operations — kubectl status, force-sync, rollback.
• Troubleshooting — symptom → condition → action.
• Security hardening — threat model, RBAC, allow-lists.
• Upgrade & uninstall — SemVer, CRD policy, A12.

Status: Phases 0–2 and Phase 3 (ship readiness) are implemented. The U3 acceptance gate automates criteria A1–A12 on kind (two Kubernetes minors, Helm + plain manifests). spec.secretRefs supports externalSecret and nativeSecret backends.

Getting started

Minimal config, maximum value out of the box: with three fields Kohen renders your config, wires it into the workload, and gives you version-matched rollouts.

Prerequisites

• A Kubernetes cluster (v1.29+) and kubectl.
• helm v3.13+.
• A git repository containing your config files under some path, reachable from the cluster.
• The target workload (a Deployment or StatefulSet) already running in the namespace where you'll create the ConfigSync.

1. Install Kohen (Helm)

helm install kohen deploy/helm/kohen \
  --namespace kohen-system --create-namespace \
  --wait

2. Create a ConfigSync (minimal)

Prerequisite for this example: a Deployment named checkout in namespace checkout.

apiVersion: kohen.dev/v1alpha1
kind: ConfigSync
metadata:
  name: checkout-prod
  namespace: checkout
spec:
  source:
    url: https://github.com/acme/platform-config.git
    ref: main
  path: services/checkout/prod
  workloadRef:
    kind: Deployment
    name: checkout

kubectl apply -f checkout-prod.yaml

3. What you get out of the box

With only the fields above, Kohen applies these defaults and does the rest automatically:

Concretely, Kohen: (1) renders services/checkout/prod@main into the checkout-config ConfigMap; (2) merges a volume + mount at /etc/kohen/config into the first container via Server-Side Apply (Kohen-owned fields only); (3) stamps the config version on the pod template; and (4) on every future change, updates the ConfigMap and triggers exactly one rolling update.

4. Verify

kubectl -n checkout get configsync checkout-prod   # READY, CONFIG VERSION
kubectl -n checkout get configmap checkout-config
kubectl -n checkout get deploy checkout \
  -o jsonpath='{.spec.template.metadata.annotations.kohen\.dev/config-sha}'

For the full walkthrough — including private-repo auth, rollback, outage behavior, troubleshooting, and GitOps coexistence — follow the runbook.

Advanced configuration reference

Every feature currently shipped.

ConfigSync spec

The rendered file tree maps to ConfigMap keys; / in a nested file name maps to __ in the key. Rendering fails closed if the result exceeds the ~1 MiB ConfigMap limit (Rendered=False/Oversize).

Secret references

spec.secretRefs[] lets a workload consume secrets alongside its config. Two backends are supported: externalSecret (an External Secrets Operator ExternalSecret, applied from git and awaited) and nativeSecret (a pre-existing Secret). Each is surfaced as a file (mounted volume, live in-place updates) or env (a valueFrom.secretKeyRef entry, rotation rolls the workload). Kohen never reads the secret value; the readiness policy fails closed on first resolution and fails safe (last-good) on a transient outage. See the full secret integration guide for schema, rotation, guard rails, and the Vault-via-ESO decision tree.

spec:
  secretRefs:
    - name: db                # native Secret, as an env var
      backend: nativeSecret
      nativeSecret: { name: checkout-db }
      surface: { as: env, envVar: DB_PASSWORD, key: password }
    - name: api               # ESO ExternalSecret (committed to git), as a file
      backend: externalSecret
      externalSecret: { name: checkout-api }
      surface: { as: file, mountPath: /etc/checkout/api }

Rollout modes

Private repository authentication

Create a Secret in the same namespace as the ConfigSync, labeled kohen.dev/git-credential=true (enforced at reconcile time), and reference it from spec.source.authSecretRef. Recognized keys:

Credentials are never written to logs, events, or status; on failure the ConfigSync goes Degraded with a redacted AuthFailed event.

Operator / Helm configuration

Install-time values (see deploy/helm/kohen/values.yaml):

Regardless of the allow-list, Kohen always blocks source hosts that resolve to loopback, link-local (incl. the 169.254.169.254 metadata endpoint), unspecified, or multicast addresses, and re-screens every HTTP redirect hop (SPEC.md R-AUTH.7).

Annotations

Status & conditions

status exposes sourceCommit, configVersion, workloadVersion, rolloutInProgress, per-reference secretRefs, and per-step conditions: Fetched, Rendered, ManifestsApplied, SecretsReady, WorkloadWired, RolloutComplete, and the overall Ready. Common failure reasons and the first action to take:

GitOps coexistence

Kohen merges only its owned fields (the kohen-config volume/mount and the kohen.dev/config-sha annotation) via Server-Side Apply. Coexistence with Argo CD / Flux is guaranteed when the other controller uses SSA and applies the documented ignore rules; client-side / whole-object appliers will strip Kohen's fields. Copy-paste Argo CD ignoreDifferences and Flux Merge SSA snippets are in the runbook.

When to use Kohen — and when not

Use GitOps to deploy what runs; use Kohen to keep a running workload's config in sync with a dedicated config repo and roll it out consistently. See the decision table in SPEC.md §2.4 before adopting.