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 release is v0.5.7; all Kubernetes APIs are now kapro.io/v1alpha2. If you have legacy kapro.io/v1alpha1 manifests, follow the v1alpha1 to v1alpha2 migration guide; this release does not provide automatic legacy conversion.

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.
• Backend-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;
• backend 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.

Core Concepts

Kind	Role
Fleet	Fleet setup root: source, delivery defaults, clusters, and embedded stage plan.
Source	Reusable catalog of deployable units and backend write targets.
Backend	Delivery driver configuration for Flux, Argo CD, OCI, or plugin-backed execution.
Plan	Stage order, target selection, and gates generated from or referenced by a Fleet.
Promotion	User-authored rollout intent: "promote this 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 backend-neutral. A fleet can mix delivery styles by cluster:

• Flux or Argo CD brownfield: 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 backend 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, then use Backends 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 bootstrap greenfield ./promotion-repo --backend flux --mode pull --name checkout
kapro bootstrap brownfield argo . --out ./kapro-connect --name checkout
kapro bootstrap brownfield flux . --out ./kapro-connect --name checkout

See the Adoption Guide for the greenfield and brownfield decision tree.

Quick Start

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

KAPRO_VERSION=0.5.7
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.kapro.io crd/targets.kapro.io \
  --for=condition=Established \
  --timeout=60s
kubectl -n kapro-system rollout status deployment/kapro-kapro-operator
kubectl apply -f examples/quickstart/backend-flux.yaml
kubectl apply -f examples/quickstart/kapro.yaml
kubectl apply -f examples/quickstart/promotion.yaml
kubectl get promotions,promotionruns,targets

The user-authored object is Promotion. 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 backend 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=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
• First Promotion in 10 Minutes
• Kind Demo
• Backends
• Operations
• Security
• API Stability
• Competitive Positioning
• v1alpha1 to v1alpha2 Migration
• Changelog

Deeper references:

• Argo Brownfield Migration
• Flux Brownfield Migration
• RBAC and Tenancy
• Monitoring
• 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.