Architecture¶

kardinal-promoter is a Kubernetes-native controller. All state lives in etcd as CRDs. The CLI, UI, and webhook API are convenience layers that create and read CRDs — you can operate the entire system with kubectl.

System Overview¶

graph TD
    CI["CI/CD Pipeline<br/>(GitHub Actions, etc.)"] -->|"POST /api/v1/bundles<br/>or kubectl apply"| Bundle

    subgraph "Kubernetes Cluster"
        Bundle["Bundle CRD<br/>image ref + provenance"]
        Pipeline["Pipeline CRD<br/>environments + update strategy"]
        PolicyGate["PolicyGate CRDs<br/>CEL expressions"]

        Bundle -->|"translates to"| Graph["kro Graph<br/>(per-Bundle DAG)"]
        Pipeline -->|"read by translator"| Graph
        PolicyGate -->|"injected as DAG nodes"| Graph

        Graph -->|"creates"| PS["PromotionStep CRs<br/>(per environment)"]
        Graph -->|"creates"| PGI["PolicyGate instances"]

        PS -->|"executes"| Steps["Steps Engine<br/>image update → PR → health-check"]
        PGI -->|"evaluates CEL"| PGR["status.ready = true/false"]

        PGR -->|"readyWhen"| GraphAdv["Graph advances<br/>to next environment"]
        Steps -->|"Verified"| GraphAdv

        Steps -->|"Failed"| Rollback["Rollback PR<br/>(kardinal/rollback label)"]
    end

    kubectl["kubectl / kardinal CLI / UI"] -->|"reads/writes"| Bundle
    kubectl -->|"reads"| PS
    kubectl -->|"reads"| PGI

Core Components¶

Controller (cmd/kardinal-controller)¶

The controller manager runs these reconcilers:

Translator (pkg/translator)¶

Converts a Pipeline CRD + a Bundle CRD into a kro Graph spec. The Graph encodes the full promotion DAG:

• One node per PromotionStep (environment)
• One node per PolicyGate instance (injected between environments)
• readyWhen expressions wired so the Graph controller advances nodes in dependency order

kro Graph Controller (kro-system)¶

kardinal-promoter does not implement graph coordination itself. It delegates to the krocodile Graph controller (an experimental fork of kro) which manages the DAG lifecycle:

• Creates owned resources (PromotionStep CRs, PolicyGate CRs) in topological order
• Advances to the next node when readyWhen is satisfied
• Stops the DAG on failure, preventing downstream promotions

Dependency note: kardinal-promoter requires krocodile to be installed in the cluster. See Installation for setup.

Steps Engine (pkg/steps)¶

The PromotionStepReconciler runs a sequence of built-in steps for each environment:

kustomize-set-image  →  git-commit  →  open-pr  →  wait-for-merge  →  health-check

Built-in step implementations:

PolicyGate Evaluator (pkg/reconciler/policygate)¶

Evaluates CEL expressions against the promotion context. Uses the kro CEL library, giving gates access to json.*, maps.*, lists.*, random.*, and standard string extension functions.

See CEL Context Reference for the full variable list.

SCM Provider (pkg/scm)¶

Abstracts Git hosting operations. Current implementations:

Health Adapters (pkg/health)¶

Checks whether a promotion is healthy after merging:

Data Flow: Bundle → Verified¶

sequenceDiagram
    participant CI
    participant API as kardinal API
    participant K8s as Kubernetes API Server
    participant Bundle as BundleReconciler
    participant kro as krocodile Graph
    participant PS as PromotionStepReconciler
    participant PG as PolicyGateReconciler

    CI->>API: create Bundle (image + pipeline)
    API->>K8s: create Bundle CR
    K8s->>Bundle: reconcile event
    Bundle->>K8s: create Graph CR (DAG spec)
    kro->>K8s: create PromotionStep[test] + PolicyGate instances
    K8s->>PG: reconcile PolicyGate[test]
    PG->>K8s: status.ready = true (CEL passed)
    kro->>K8s: advance DAG → create PromotionStep[test] steps
    K8s->>PS: reconcile PromotionStep[test]
    PS->>PS: image update → commit → open PR → wait merge → health check
    PS->>K8s: status.phase = Verified
    kro->>kro: readyWhen satisfied → advance to uat
    Note over kro,PS: Repeat for uat → prod
    kro->>K8s: Graph.status.state = Verified
    K8s->>Bundle: status.phase = Verified

How kardinal Relates to ArgoCD and Flux¶

kardinal-promoter is GitOps-agnostic: it does not communicate with ArgoCD or Flux during promotion. Instead:

1. PromotionStepReconciler opens a Git pull request with the updated image reference.
2. A human (or automated process) merges the PR.
3. ArgoCD or Flux detects the Git change and syncs the cluster.
4. kardinal's health check then queries ArgoCD or Flux to confirm sync is complete before advancing the DAG.

This means kardinal works with any GitOps engine — or even without one (raw Kubernetes deployments).

State Management¶

All state is stored in Kubernetes CRDs:

The controller is stateless: it can be restarted at any time without data loss. All state is recovered by re-reading CRDs.

Further Reading¶

• Concepts — Bundles, Pipelines, PolicyGates explained
• Policy Gates — CEL expression reference
• CEL Context Reference — variables available in gate expressions
• Installation — how to install kardinal-promoter