Documentation / Start here
Start here Install with Helm Deploy ClusterPilot on Kubernetes with explicit secrets, external PostgreSQL, durable artifacts, and fail-closed production settings.
Audience Kubernetes administrators, platform SREReading time 16 minCommands in context 6 guided stepsReviewed source 9552586 · 1 August 2026
What the chart installs The ClusterPilot chart installs the API with embedded frontend, background workers, Service, optional Ingress, PodDisruptionBudget, optional filesystem PVC, release metadata, and an optional in-cluster agent. It intentionally does not install PostgreSQL or pull secrets from an external secret manager.
Unsupported shortcuts Do not use tag-only images, rename the required image subjects, add a chart-managed PostgreSQL database, enable the agent without a bootstrap token, or weaken the non-root/read-only runtime baseline.
Prepare production values values.production.yaml Copy
global:
registry:
host: ghcr.io
repositoryPrefix: clusterpilot-system
imagePullSecrets: []
api:
replicaCount: 1
image:
digest: sha256:b961ca54c4058d79cf535ab7718732351e70da4a97f82bed7971389c5a381c81
ingress:
enabled: true
className: nginx
hosts:
- host: clusterpilot.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: clusterpilot-edge-tls
hosts:
- clusterpilot.example.com
runtime:
leaderElection:
enabled: true
retryIntervalSeconds: 30
database:
secretRef:
name: clusterpilot-api-runtime
key: connection-string
artifactStorage:
provider: filesystem
filesystem:
createPersistentVolumeClaim: false
existingClaim: clusterpilot-artifacts
shared: true
featureFlags:
controlPlaneEnabled: true
clusterInfrastructureEnabled: true
clustersEnabled: true
clusterScaleEnabled: true
customAddonsEnabled: true
cloudProviders:
enabled: true
ionosEnabled: true
hetznerEnabled: true
releaseMetadata:
backendVersion: "1.1.0"
frontendVersion: "0.1.0"
conformanceRelease:
allowPreSupportedCatalogSelection: false
secrets:
masterKeySecretRef:
name: clusterpilot-api-runtime
key: master-key
keyId: self-hosted-prod
agent:
enabled: false
image:
digest: sha256:82dd9e6bf51eb2e7c06c58bcb8b597a7a38dd5851b08ee1c388b0183f41b8929This example uses only paths present in the published v0.0.5 chart. Create the referenced Kubernetes Secrets separately; do not put connection strings, keys, or tokens in the values file.
Preflight, render, inspect and install Published v0.0.5 path The v0.0.5 self-hosted bundle contains the packaged chart at charts/clusterpilot-0.0.5.tgz. It does not contain a separate Helm installer script. Use Helm lint, template, atomic install, status, rollout, health and readiness commands against that exact chart.
✓ Confirm the exact kube context, namespace, chart archive, release identity, and values files.
✓ Inspect generated image references, Secret references, storage classes, network policy, Ingress, Service, PodDisruptionBudget, security context, and replica counts.
✓ Require preflight and dry-run to succeed before the state-changing installation step.
✓ Retain the rendered manifest and installer result with the change record.
Commands for this step Run the supported Helm installation sequence Do not skip a successful preflight or dry-run. The final step is the only command in this sequence that mutates the target cluster.
Run in order Complete each step successfully before continuing.
01
Read-only Kubernetes
Lint the published Helm chart Lint the exact v0.0.5 chart archive without changing the cluster.
Before you run it Helm 3 Extracted and checksum-verified v0.0.5 self-hosted bundle Validated values.production.yaml Kubernetes · helm-preflight Copy
helm lint ./charts/clusterpilot-0.0.5.tgz \
--namespace clusterpilot \
-f ./values.production.yaml✓ Expected result Helm reports one chart linted and zero failed.
Reviewed source charts/clusterpilot/values.yaml02
Read-only Kubernetes
Render the published Helm chart Render the exact v0.0.5 chart and values without changing the cluster.
Before you run it A clean Helm lint Validated values.production.yaml Kubernetes · helm-dry-run Copy
helm template clusterpilot ./charts/clusterpilot-0.0.5.tgz \
--namespace clusterpilot \
-f ./values.production.yaml \
> ./clusterpilot.rendered.yaml✓ Expected result Exit 0 and a rendered manifest containing only the approved digests and Secret references.
Reviewed source charts/clusterpilot/values.yaml03
Changes state Kubernetes
Install or converge the published chart Install ClusterPilot atomically, wait for the API deployment and verify rollout state.
Before you run it Release verification complete Preflight and dry-run pass PostgreSQL, artifact storage, secrets, TLS and backup target ready Kubernetes · helm-install Copy
helm upgrade --install clusterpilot ./charts/clusterpilot-0.0.5.tgz \
--namespace clusterpilot \
--create-namespace \
--atomic --wait --timeout 600s \
-f ./values.production.yaml✓ Expected result Exit 0; Helm status succeeds and every matching API deployment completes rollout.
Reviewed source charts/clusterpilot/README.mdVerify the deployment ✓ Every API and worker replica is Ready and reports the expected build metadata.
✓ Leader election is active whenever API or worker replica count is greater than one.
✓ Every replica can read and write the same durable artifact store.
✓ Database migrations are complete and startup auto-migration matches your approved policy.
✓ Ingress TLS, client address handling, DNS, and health probes work from the actual operator network.
Commands for this step Prove the Helm deployment is healthy Check Helm status and rollout first, then retain the detailed workload, health, readiness, and clock evidence.
Run in order Complete each step successfully before continuing.
01
Read-only Kubernetes
Verify an existing Helm deployment Check Helm release status and API deployment rollout without chart mutation.
Before you run it Existing ClusterPilot Helm release kubectl and Helm access to the configured context Kubernetes · helm-verify-only Copy
helm status clusterpilot --namespace clusterpilot
kubectl -n clusterpilot rollout status deployment/clusterpilot --timeout=300s✓ Expected result Exit 0 with release status and API rollout checks successful.
Reviewed source charts/clusterpilot/README.md02
Read-only Kubernetes
Inspect Helm and Kubernetes rollout state Confirm release identity, workload state and the effective manifest after installation.
Before you run it Read access to the ClusterPilot namespace Kubernetes · helm-status Copy
helm status clusterpilot --namespace clusterpilot
helm history clusterpilot --namespace clusterpilot
helm get values clusterpilot --namespace clusterpilot --all
kubectl -n clusterpilot get deploy,pod,svc,ingress,pdb,pvc
kubectl -n clusterpilot rollout status deployment/clusterpilot --timeout=300s✓ Expected result The release is deployed, expected resources exist and the API rollout completes.
Reviewed source charts/clusterpilot/README.md03
Read-only Kubernetes
Verify ClusterPilot health through port-forward Test liveness, readiness and clock posture from an operator workstation without exposing the Service.
Before you run it kubectl port-forward permission No local listener on port 8080 Kubernetes · helm-health Copy
kubectl -n clusterpilot port-forward svc/clusterpilot 8080:80
# Run in a second terminal:
curl --fail http://127.0.0.1:8080/health
curl --fail http://127.0.0.1:8080/ready
curl --fail http://127.0.0.1:8080/health/clock✓ Expected result All three requests return success; readiness and clock posture are healthy.
Reviewed source docs/agent/self-hosted-install.mdSecurity defaults to preserve Control Chart baseline Runtime identity Non-root user Root filesystem Read-only Linux capabilities Drop ALL Seccomp RuntimeDefault Images Digest-pinned release subjects Secrets Existing Kubernetes Secret references Multi-replica safety Fail closed without leader election and shared artifacts
