Start here · v0.0.1

Install with Helm

Deploy ClusterPilot on Kubernetes with explicit secrets, external PostgreSQL, durable artifacts, and fail-closed production settings.

AudienceKubernetes administrators, platform SREReading time16 minCommands in context11 guided stepsReviewed sourcefcc5871 · 30 July 2026

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

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.

Prepare production values

values.production.yaml

image:
  repository: registry.example.com/clusterpilot/clusterpilot-api
  digest: "sha256:<verified-digest>"

replicaCount: 2

leaderElection:
  enabled: true

artifactStorage:
  provider: filesystem
  filesystem:
    shared: true
    size: 100Gi
    accessModes: [ReadWriteMany]

ingress:
  enabled: true
  className: nginx
  host: clusterpilot.example.com
  tlsSecretName: clusterpilot-tls

secrets:
  database:
    existingSecret: clusterpilot-database
  protection:
    existingSecret: clusterpilot-secrets-protection

Key names may vary by chart revision. Render the exact chart included in your signed release bundle and compare its values.yaml and README before promotion.

Commands for this step

Create the supported unattended install input

Use the schema-versioned configuration file for a repeatable installation. It references approved values and never contains secret values.

Run in orderComplete each step successfully before continuing.

01
Changes statePowerShell
Create a non-interactive Helm install config
Create the schema-versioned input used by every supported Helm entrypoint mode.
Before you run it
- Extracted signed release bundle
- PowerShell 7
- A production values file with Secret references only
PowerShell · helm-config
```
Copy-Item examples/install/clusterpilot-install.config.sample.json clusterpilot-install.json
# Edit chart.path, chart.valuesFiles and kubernetes.context.
Get-Content clusterpilot-install.json | ConvertFrom-Json | Out-Null
```
Expected result
The JSON parses and points to the exact chart, values files, namespace and kube context.
Stop conditions and operator notes
- Do not place secret values in this JSON file.
- Non-interactive mode rejects additional release/chart flags to prevent ambiguous input precedence.
Reviewed sourceexamples/install/clusterpilot-install.config.sample.json

Preflight, render, inspect and install

✓
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

Optional Helm preflight invocation styles

The config-file sequence below is the repeatable enterprise default. Use one of these preflight-only alternatives only when you deliberately need prompts or explicit overrides.

Use when neededDo not run these commands unless the described condition applies.

01
Read-onlyPowerShell
Run an interactive Helm preflight
Use this when
Use for a guided first evaluation on an interactive terminal.
Prompt for any missing release, namespace, chart, values, context and verification inputs while keeping the operation non-mutating.
Before you run it
- PowerShell 7
- Helm
- kubectl
- Interactive terminal on the approved installer host
PowerShell · helm-interactive-preflight
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 `
  -InputMode interactive `
  -ExecutionMode preflight-only
```
Expected result
All required prompts are answered, chart lint and deterministic rendering pass, and no release is changed.
Stop conditions and operator notes
- Use the schema-versioned ConfigPath workflow for repeatable unattended installation.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1
02
Read-onlyPowerShell
Preflight every explicit Helm override
Use this when
Use when a change review requires every override to be visible on the command line.
Exercise the complete interactive-mode override surface without prompts or cluster mutation.
Before you run it
- PowerShell 7
- Exact chart and approved values file
- Approved kube context
PowerShell · helm-explicit-preflight
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 `
  -InputMode interactive `
  -ExecutionMode preflight-only `
  -ReleaseName clusterpilot `
  -Namespace clusterpilot `
  -ChartPath ./charts/clusterpilot `
  -ValuesFilePaths ./values.production.yaml `
  -KubeContext <approved-kube-context> `
  -VerifyTimeoutSeconds 600 `
  -HelmCommand helm `
  -KubectlCommand kubectl
```
Expected result
Every explicit input resolves, lint and render checks pass, and the cluster remains unchanged.
Stop conditions and operator notes
- ConfigPath is valid only with non-interactive mode.
- Non-interactive mode accepts ConfigPath-only release/chart/verify inputs.
- Add -Quiet only in automation that retains the generated JSON result.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1

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 orderComplete each step successfully before continuing.

01
Read-onlyPowerShell
Run the official Helm preflight
Run schema validation, Helm lint and deterministic template rendering without changing the cluster.
Before you run it
- PowerShell 7
- Helm
- Valid install config
PowerShell · helm-preflight
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 \
  -InputMode non-interactive \
  -ExecutionMode preflight-only \
  -ConfigPath ./clusterpilot-install.json
```
Expected result
Exit 0 with lint and template preflight marked successful.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1
02
Read-onlyPowerShell
Run the official Helm dry-run
Exercise the exact atomic install command with Helm dry-run semantics.
Before you run it
- A clean official preflight
- Kube context and values approved for the target environment
PowerShell · helm-dry-run
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 \
  -InputMode non-interactive \
  -ExecutionMode dry-run \
  -ConfigPath ./clusterpilot-install.json
```
Expected result
Exit 0; mutation is reported as dry-run and no release is installed.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1
03
Changes statePowerShell
Install or converge with the official entrypoint
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
PowerShell · helm-install
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 \
  -InputMode non-interactive \
  -ExecutionMode install \
  -ConfigPath ./clusterpilot-install.json
```
Expected result
Exit 0; Helm status succeeds and every matching API deployment completes rollout.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1

Commands for this step

Inspect or bypass the installer only by approved exception

These commands expose the rendered resources and the underlying Helm mutation. They are not the normal customer installation path.

Use when neededDo not run these commands unless the described condition applies.

01
Read-onlyKubernetes
Lint and render the exact chart manually
Use this when
Use when security or change management must review the exact rendered manifest.
Review generated resources when a security or change board requires the rendered manifest.
Before you run it
- Staged or packaged official chart
- Approved values file
Kubernetes · helm-direct-review
```
helm lint ./charts/clusterpilot --namespace clusterpilot -f values.production.yaml
helm template clusterpilot ./charts/clusterpilot \
  --namespace clusterpilot \
  -f values.production.yaml \
  > clusterpilot.rendered.yaml
```
Expected result
Lint succeeds and the rendered manifest contains only approved images, Secret references, storage and ingress objects.
Reviewed sourcecharts/clusterpilot/README.md
02
Changes stateKubernetes
Run the underlying atomic Helm command
Use this when
Use only when the official entrypoint cannot be used and the exception is approved.
Document the exact Helm mutation performed by the official entrypoint.
Before you run it
- Use only when the official entrypoint cannot be used and the exception is approved
- Release, chart and values verified
Kubernetes · helm-direct-install
```
helm upgrade --install clusterpilot ./charts/clusterpilot \
  --namespace clusterpilot \
  --create-namespace \
  --atomic \
  --wait \
  --timeout 600s \
  -f values.production.yaml
```
Expected result
The release becomes deployed; a failed rollout is rolled back atomically.
Stop conditions and operator notes
- The supported customer path is the official entrypoint because it normalizes preflight and verification.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1

Verify 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

Run the supported verifier first, then retain the detailed release, workload, readiness, and clock evidence.

Run in orderComplete each step successfully before continuing.

01
Read-onlyPowerShell
Verify an existing Helm release
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
PowerShell · helm-verify-only
```
pwsh -NoProfile -File ./scripts/clusterpilot-install-entrypoint.ps1 \
  -InputMode non-interactive \
  -ExecutionMode verify-only \
  -ConfigPath ./clusterpilot-install.json
```
Expected result
Exit 0 with release status and API rollout checks successful.
Reviewed sourcescripts/clusterpilot-install-entrypoint.ps1
02
Read-onlyKubernetes
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
```
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 sourcecharts/clusterpilot/README.md
03
Read-onlyKubernetes
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
```
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 sourcedocs/agent/self-hosted-install.md

Security 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