Kohen is a Kubernetes-native operator for one pattern: an application that consumes domain-specific configuration from a dedicated git repository.

Point a ConfigSync at a git path and a workload. Kohen renders a native ConfigMap, mounts it with standard volume mechanics, wires referenced Secrets the same way, and rolls the workload when the config version changes — no sidecars, no private volumes.

Deploy what runs with Argo CD / Flux; keep config in sync with Kohen.

Config repo                     Deploy / GitOps
(domain + env config)           (app manifests)
        │                              │
        │ path                         │ Deployment
        ▼                              ▼
     ┌──────┐                   ┌──────────────┐
     │Kohen │── ConfigMap ─────▶│   Workload   │
     └──────┘── mount+rollout ─▶└──────────────┘

• Install — Helm and plain manifests
• Getting Started & GitOps — Day-1 runbook
• Concepts · Secrets · Operations
• Troubleshooting · Security · Upgrade
• Specification — behavioral contract
• Project site

v1.0 · API kohen.dev/v1alpha1 · see upgrade notes

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.

• A Kubernetes cluster (v1.28+) 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.

# From a published release:
helm install kohen oci://ghcr.io/ozimakov/kohen/charts/kohen \
  --version 1.0.0 \
  --namespace kohen-system --create-namespace \
  --wait

# Or from this checkout:
helm install kohen deploy/helm/kohen \
  --namespace kohen-system --create-namespace \
  --wait

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

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.

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.

Every feature currently shipped.

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).

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 unless rolloutOnRotate: false). Kohen never reads the secret value; the readiness policy fails closed on first resolution and fails safe (last-good) on a transient outage. Rotation is detected on the sync poll interval (≤ sync.interval). 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
        rolloutOnRotate: true   # default; set false to skip rollout on env rotation
    - name: api               # ESO ExternalSecret (committed to git), as a file
      backend: externalSecret
      externalSecret: { name: checkout-api }
      surface: { as: file, mountPath: /etc/checkout/api }

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.

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 (see security hardening).

status exposes observedGeneration, sourceCommit, configVersion, workloadVersion, rolloutInProgress, per-reference secretRefs (including sticky established), and per-step conditions: Fetched, Rendered, ManifestsApplied, SecretsReady, WorkloadWired, RolloutComplete, and the overall Ready. Short name: kubectl get cs. Common failure reasons and the first action to take:

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.