How Konduit works

Konduit follows Konstruct's standard pattern: the API writes custom resources, an operator reconciles them, and the CR status is the source of truth. Nothing deploys by direct cluster access — every workload lands through a GitOps commit.

The custom resources

Three CRDs in group konstruct.civo.com/beta1 (namespaced per organization):

CRD	Purpose
ForemanApp	One deployable app. Spec: app_name, environment, repo_url/repo_name/branch/sub_path, target_cluster, port, replicas, env[], public_url_enabled. Status: phase (Building → Pushing → Deploying → Live, or Failed), digest-pinned image, build_sha, public url.
ForemanEnvironment	A per-org environment record (production, staging, …). Apps in one environment share a workload namespace, foreman-<org>-<env>.
Subscription	Billing state for the org. When status.state is suspended, every app in the org scales to 0 replicas; the gate fails open when the resource is absent.

The pipeline

sequenceDiagram
    participant UI as Konduit UI
    participant API as konstruct-api
    participant CR as ForemanApp CR
    participant OP as foreman-operator
    participant GIT as Git provider
    participant KP as kpack
    participant HB as Harbor
    participant REPO as GitOps repo
    participant CD as Argo CD

    UI->>API: Register app
    API->>CR: create ForemanApp
    OP->>CR: reconcile
    OP->>GIT: resolve org GitAccount (auth)
    OP->>HB: ensure project + robot accounts
    OP->>KP: create kpack Image (ClusterBuilder "default")
    KP->>GIT: clone repo
    KP->>HB: push digest-pinned image
    OP->>REPO: commit Argo CD Application<br/>(konstruct-web-service chart values)
    CD->>REPO: sync
    CD->>CD: deploy to target cluster
    OP->>CR: status.phase = Live, status.url

Step by step:

1. Register — konstruct-api creates the ForemanApp CR from the UI form (or API call)
2. Credentials — the operator resolves the organization's GitAccount for Git auth, and mints Harbor robot accounts: a push robot for kpack and a pull robot distributed to the workload namespace as an imagePullSecret
3. Build — a kpack Image builds the repository with Cloud Native Buildpacks (the default ClusterBuilder) and pushes a digest-pinned image to Harbor
4. Ship — the operator renders an Argo CD Application over the generic konstruct-web-service chart (Deployment + Service + Gateway HTTPRoute) and commits it to the org's GitOps repository at registry/clusters/<target_cluster>/foreman/<org>/<app>/application.yaml
5. Sync — Argo CD applies the Application to the target cluster; when public_url_enabled is set, the app's HTTPRoute attaches to the platform gateway's apps wildcard listener and status.url is published

Continuous deployment

• kpack polls the repository — new commits on the tracked branch rebuild and redeploy automatically
• Git push webhooks and the Redeploy button stamp a rebuild-revision annotation on the ForemanApp, forcing an immediate rebuild
• The operator watches the kpack Image: when the digest changes, it re-commits the manifest with the new image

Suspension

The operator watches Subscription resources. A suspended org has every app's manifest re-committed with replicaCount: 0; reactivation restores the desired count. Missing billing data never scales an app down.