DETalk to us →
ClusterPilot Docs
v0.0.1 RC · fcc5871
Start with:EvaluateInstallCreate a clusterOperateRecoverAutomate
Documentation/Operate
Operate · v0.0.1

Architecture

See how ClusterPilot separates intent, control, execution, persistence, and evidence.

AudienceArchitects, security reviewers, platform SREReading time12 minCommands in contextNo terminal requiredReviewed sourcefcc5871 · 30 July 2026
RC

Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.

System boundary

Operator planeWeb UI / API clientIntent, approval, read models
Control planeAPI + workersAuth, plans, gates, orchestration
Execution planeLifecycle agentProvider and host work
Target planeCloud + clustersInfrastructure and Kubernetes

PostgreSQL stores durable control-plane state. The configured artifact provider stores logs, command evidence, reports, and downloadable bundles. Secret values cross only the approved materialization boundary and should never appear in DTOs, events, logs, URLs, or support output.

Component responsibilities

ComponentOwnsDoes not own
APIAuthentication, authorization, validation, idempotency, read models, admission, audit.Long-running provider or host commands.
WorkersScheduling, state projection, recovery, retention, background verification.Unbounded command execution on target nodes.
Lifecycle agentCompatible assigned work, isolated command execution, event/evidence upload, cleanup.Policy approval or broad autonomous discovery.
Provider adapterProvider-specific validation, discovery, plans, and API calls.Kubernetes bootstrap semantics.
Cluster lifecycleNode preparation, kubeadm, CNI, scale, upgrade, replace, delete.Provider credential storage outside the secret boundary.
Artifact storeDurable evidence blobs and integrity metadata.Primary relational state.

Request-to-evidence flow

  1. 01

    Admit

    Authenticate, authorize, validate schema, resolve tenant/workspace scope, and require idempotency where applicable.

  2. 02

    Plan

    Create stable resource intent, step order, inputs, compatibility decisions, and a reviewable diff.

  3. 03

    Gate

    Apply feature flags, maturity policy, quota, provider, agent, destructive-action, and approval checks.

  4. 04

    Assign

    Match the run contract to an active compatible agent and deliver bounded work.

  5. 05

    Project

    Ingest ordered events, logs, command and step results; update the durable run read model idempotently.

  6. 06

    Retain

    Store redacted evidence, checksums, audit records, and cleanup/recovery state under explicit retention.

Failure and recovery boundaries

Read paths do not trigger hidden mutation. A failed operation remains inspectable and is never rewritten as successful. Retry creates or resumes work only where the run contract permits it; cancellation is a request that remains non-terminal until owned cleanup completes.

Trust model

  • ✓
    Every customer deployment defines its own operator, control, execution, target, registry, and persistence trust zones.
  • ✓
    TLS validates endpoints and identities; private CA and mTLS modes require explicit trust material.
  • ✓
    RBAC and feature gates are independent. A permitted role cannot call a disabled or unapproved capability.
  • ✓
    Release signatures, digests, SBOM, provenance, and compatibility metadata identify what is allowed to run.
  • ✓
    Audit and evidence support review; they do not automatically certify regulatory compliance.