Kapro

A promotion control plane for Kubernetes fleets.
Kapro coordinates when an artifact version should move across clusters while Flux, Argo CD, OCI pull agents, and other delivery systems keep owning the local rollout.

---

Kapro is pre-stable public release software, not GA. The current public preview line is v0.6.x; user-authored APIs live in kapro.io/v1alpha1 and controller-owned runtime records live in runtime.kapro.io/v1alpha1. This is a clean pre-stable break; there is no automatic conversion for older alpha manifests.

Why Kapro

Kapro answers one operational question:

Which clusters are allowed to receive this artifact version now, and why?

It is useful when one application version must move through many clusters, regions, environments, or connectivity models without burying promotion state in CI scripts.

• Fleet-wide promotion intent: model waves, gates, approvals, and target selection as Kubernetes API state.
• Substrate-neutral delivery: keep Flux, Argo CD, OCI pull agents, and custom plugins in charge of local rollout mechanics.
• Auditable attempts: inspect durable Promotion intent, immutable PromotionRun attempts, and per-target runtime records after CI has exited.

Boundaries

Kapro owns:

• cross-cluster promotion intent;
• stage and wave ordering;
• target selection;
• gate and approval state;
• per-target execution records;
• substrate convergence evidence.

Kapro does not build artifacts, render manifests, replace GitOps controllers, or implement in-cluster traffic shifting. Those jobs stay with CI, Helm, Kustomize, Flux, Argo CD, Argo Rollouts, service mesh controllers, or custom platform tooling.

Permanent non-goals: Kapro is not a Helm registry, CI runner, manifest store, cluster provisioner, or secret store.

Public preview product boundaries:

• Kapro does not build artifacts or run CI.
• Kapro does not provision clusters.
• Kapro does not store secrets.
• Kapro does not act as a Helm registry or manifest store.
• Kapro does not replace Flux, Argo CD, OCI agents, Argo Rollouts, Flagger, Sveltos, Terraform, Cluster API, or secret managers.

Core Concepts

Kind	Role
DeliveryUnit	App/workload source mappings, trigger intent, and default fleet/plan.
Fleet	Target set: clusters and delivery defaults.
Source	Controller-derived source mapping object from a DeliveryUnit.
Substrate	Delivery driver configuration for Flux, Argo CD, OCI, direct apply, or plugin-backed execution.
Plan	Stage order, target selection, and gates.
Promotion	Explicit rollout action: "promote this DeliveryUnit version through this Fleet."
PromotionRun	Controller-authored execution attempt and audit record.
Target	Per-cluster, per-stage runtime state.
Cluster	A workload cluster known to the hub.
Approval	Human approval or rejection for a gated target.

See Concepts for the object model and lifecycle.

How It Compares

Kapro is not a replacement for Flux, Argo CD, Argo Rollouts, Flagger, or Sveltos. It sits above delivery and add-on systems as the promotion layer that decides when a version may advance across a fleet. See ADR-0012: Competitive Positioning for the architectural comparison.

Adapt To Your Fleet

Kapro is substrate-neutral. A fleet can mix delivery styles by cluster:

• Existing Flux or Argo CD: discover existing apps first, review the generated mappings, then opt selected objects into managed promotion.
• OCI pull mode: spoke clusters pull artifacts from inside their own network boundary and report status back to the hub.
• Hub push mode: the hub patches a substrate object directly when network and RBAC policy allow it.
• Plugins: custom actuators, gates, and planners can be loaded through Plugin after they pass the conformance harness.

Run First Promotion in 10 Minutes first to see the API lifecycle, or start with the Adoption CLI when you want kapro create, kapro sample, kapro doctor, and kapro explain as the guided path. Use Substrates when deciding how Kapro should connect to existing delivery systems.

For guided repository setup, use the source-built bootstrap CLI from main until the bootstrap command is included in a tagged CLI release:

git clone --branch main https://github.com/Kapro-dev/kapro.git
cd kapro
make build
export PATH="$PWD/bin:$PATH"
kapro bootstrap guide
kapro create direct ./promotion-repo --name checkout
kapro create flux ./promotion-repo --name checkout
kapro create argo ./promotion-repo --name checkout
kapro create oci ./promotion-repo --name checkout
kapro bootstrap generate ./promotion-repo --profile direct --name checkout
kapro import argo . --out ./kapro-connect --name checkout
kapro import flux . --out ./kapro-connect --name checkout

See the Adoption Guide for the new-repo and existing GitOps decision tree.

Local Hello World With Kind

Use this path when you want to try Kapro from a clean laptop before touching a real cluster.

Install these tools first:

• Docker or another container runtime supported by Kind.
• Kind for a disposable local Kubernetes cluster.
• kubectl.
• Helm 3.
• Go 1.25+ only if you want to build the optional kapro CLI from source.
• ORAS only for OCI artifact examples; the hello-world example does not need it.

Run the smallest example:

KAPRO_VERSION=0.6.0

kind create cluster --name kapro-hello
kubectl config use-context kind-kapro-hello

git clone --branch "v${KAPRO_VERSION}" https://github.com/Kapro-dev/kapro.git
cd kapro

helm upgrade --install kapro \
  "https://github.com/Kapro-dev/kapro/releases/download/v${KAPRO_VERSION}/kapro-operator-${KAPRO_VERSION}.tgz" \
  --namespace kapro-system \
  --create-namespace \
  --wait

kubectl -n kapro-system rollout status deployment/kapro-kapro-operator
examples/00-deliveryunit-lessons/00-hello-world/run.sh
examples/00-deliveryunit-lessons/00-hello-world/run.sh apply
kubectl get deliveryunits.kapro.io,sources.kapro.io

Clean up:

kubectl delete -f examples/00-deliveryunit-lessons/00-hello-world --ignore-not-found
helm uninstall kapro --namespace kapro-system
kind delete cluster --name kapro-hello

Every folder under examples/ has the same run.sh entrypoint. Start at examples/README.md for the indexed learning path from hello world to Flux, Argo CD, OCI, plugins, monitoring, and the full Kind demo.

Released Chart Quick Start

Install the released operator, apply the starter fleet from a source clone, and inspect the controller-owned runtime records:

KAPRO_VERSION=0.6.0
git clone --branch "v${KAPRO_VERSION}" https://github.com/Kapro-dev/kapro.git
cd kapro
helm upgrade --install kapro \
  "https://github.com/Kapro-dev/kapro/releases/download/v${KAPRO_VERSION}/kapro-operator-${KAPRO_VERSION}.tgz" \
  --namespace kapro-system \
  --create-namespace \
  --wait
kubectl wait crd/promotions.kapro.io crd/promotionruns.runtime.kapro.io crd/targets.runtime.kapro.io \
  --for=condition=Established \
  --timeout=60s
kubectl -n kapro-system rollout status deployment/kapro-kapro-operator
kubectl apply -f examples/01-quickstarts/00-flux/substrates/flux.yaml
kubectl apply -f examples/01-quickstarts/00-flux/deliveryunit.yaml
kubectl apply -f examples/01-quickstarts/00-flux/plan.yaml
kubectl apply -f examples/01-quickstarts/00-flux/kapro.yaml
kubectl apply -f examples/01-quickstarts/00-flux/promotion.yaml
kubectl get promotions.kapro.io,promotionruns.runtime.kapro.io,targets.runtime.kapro.io

The setup objects are DeliveryUnit, Fleet, and Plan; Promotion is the explicit rollout action. PromotionRun and Target are controller-owned runtime records for inspection in kubectl or k9s. This starter path proves that the hub API stamps PromotionRun and Target records. Real Complete / Converged status requires a wired delivery substrate or the local CI smoke fixture to report workload health.

To run the same local convergence smoke used by CI, use Docker, Kind, Helm, and kubectl:

KAPRO_CI_QUICKSTARTS=direct,flux,argo,oci scripts/ci-kind-smoke.sh

For a step-by-step minimal path, use First Promotion in 10 Minutes. For a complete local walkthrough, use the Kind demo. Install has local-checkout and release-asset variants.

Documentation

Start at kapro.dev or use these repo docs:

• Concepts
• Install
• Adoption Guide
• Adoption CLI
• First Promotion in 10 Minutes
• Kind Demo
• Substrates
• Operations
• Security
• API Stability
• Competitive Positioning
• Changelog

Deeper references:

• Argo CD Existing GitOps Migration
• Flux Existing GitOps Migration
• RBAC and Tenancy
• Monitoring
• Interface Overview
• Extension Model
• Plugin Authoring
• Architecture Decision Records

Contributing

Issues and pull requests are welcome. Keep changes tied to implemented behavior: public docs should describe what users can run today, while larger design decisions belong in ADRs.

• Open issues and feature requests in GitHub Issues.
• Read CONTRIBUTING.md before opening a pull request.
• Report vulnerabilities through SECURITY.md, not public issues.
• Follow the Code of Conduct.

License

Apache 2.0. See LICENSE.