Helm reference

The canette Helm chart deploys the API, UI, builder, controller, logstreamer, and BuildKit daemon to your cluster. PostgreSQL and an in-cluster image registry are included and enabled by default.

PrerequisitesCopy Anchor Link

• Helm 3.8+
• Kubernetes 1.27+ with Gateway API CRDs installed
• A Gateway API implementation (Traefik, Cilium, etc.)
• A pre-existing Gateway resource — see Installation for the full setup checklist

InstallCopy Anchor Link

The chart is published to GitHub Container Registry. Create a values.yaml and install:

helm install canette oci://ghcr.io/canette/canette \
  -n canette-system --create-namespace \
  -f values.yaml

Omitting --version installs the latest release. To pin a specific version:

helm install canette oci://ghcr.io/canette/canette \
  --version 1.2.3 \
  -n canette-system --create-namespace \
  -f values.yaml

Available versions are listed on the canette package page.

The -n flag controls the system namespace. canette always creates a second namespace for build jobs named {system}-build — with the default above that becomes canette-system-build.

Install from sourceCopy Anchor Link

If you have the repository cloned, you can install directly from the chart directory:

helm install canette charts/canette \
  -n canette-system --create-namespace \
  -f values.yaml

Multiple instancesCopy Anchor Link

Because all namespaces are derived from -n, you can run isolated installations side by side:

# Production — apps at {app}-{project}.apps.example.com
helm install canette oci://ghcr.io/canette/canette \
  -n canette-system --create-namespace -f prod-values.yaml

# Staging — apps at {app}-{project}.staging.example.com
helm install canette-staging oci://ghcr.io/canette/canette \
  -n canette-staging --create-namespace -f staging-values.yaml

This creates canette-system + canette-system-build for production, and canette-staging + canette-staging-build for staging — no resource conflicts.

Key valuesCopy Anchor Link

The sections below cover the most commonly used values. For the full list with descriptions, see charts/canette/values.yaml in the repository.

RequiredCopy Anchor Link

Authentication (optional)Copy Anchor Link

Email and password login is enabled by default — no OAuth app required. To add GitHub or Google OAuth:

Images (optional)Copy Anchor Link

All service images default to {image.repo}/{serviceName}:{image.tag}, where image.tag defaults to the chart's appVersion. Installing or upgrading the chart automatically uses the matching image versions — no image overrides needed for a standard install.

API configuration (optional)Copy Anchor Link

Resource values use standard Kubernetes quantity notation: 100m (millicores), 256Mi (mebibytes), 1 (full core or gigabyte).

These values are snapshotted into each deployment at trigger time. Changing them takes effect on the next deployment — existing live apps are not affected until redeployed.

Infrastructure (optional)Copy Anchor Link

GatewayCopy Anchor Link

BuildKitCopy Anchor Link

Registry authenticationCopy Anchor Link

In-cluster registryCopy Anchor Link

Registry authentication is always enabled and auto-generated on first install. canette generates a random username and password, stores them in the canette-registry-credentials Secret, and reuses them on every helm upgrade — no configuration required.

Build jobs are automatically given a matching docker config Secret; no extra setup needed.

To use your own credentials instead (e.g. for disaster recovery or cluster migration):

registry:
  username: myuser
  password: mysecret

External registryCopy Anchor Link

When registry.enabled=false, provide credentials for the external registry and set controller.pullRepo explicitly:

registry:
  enabled: false
externalRegistry:
  username: myuser
  password: mytoken
builder:
  imageRepo: ghcr.io/myorg/
controller:
  pullRepo: ghcr.io/myorg/

The host for the docker config is derived automatically from builder.imageRepo.

Amazon ECR with IRSACopy Anchor Link

For ECR on EKS, use IRSA (IAM Roles for Service Accounts) instead of static credentials. ECR repositories are automatically created on first build:

registry:
  enabled: false

builder:
  imageRepo: "123456.dkr.ecr.us-east-1.amazonaws.com/canette/"
  registryAuthType: "irsa"  # or omit to auto-detect from URL
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456:role/canette-builder

controller:
  pullRepo: "123456.dkr.ecr.us-east-1.amazonaws.com/canette/"

The registryAuthType value controls authentication:

• irsa — Use ServiceAccount IAM role (EKS IRSA / GKE Workload Identity)
• static — Use username/password from externalRegistry values
• Empty — Auto-detect: irsa for ECR URLs, static otherwise

See AWS (EKS) for IAM role setup.

Image scanningCopy Anchor Link

Scanning is configured under security.scan and is applied at build time by the builder.

security:
  scan:
    provider: "auto"     # "auto" | "trivy" | "ecr" | "none"
    enabled: ""          # "" = provider-aware default; use "true"/"false" (quoted strings)
    mandatory: false     # true blocks deployments when findings exceed failSeverity
    failSeverity: "HIGH" # CRITICAL | HIGH | MEDIUM | LOW
    sbomEnabled: false   # true generates a CycloneDX SBOM (second Trivy pass, ~30–60 s extra)

Provider selectionCopy Anchor Link

provider: "auto" (the default) picks the backend based on the builder.imageRepo URL:

Override by setting provider explicitly, or flip the default with enabled: "true" or "false".

ECR scanningCopy Anchor Link

The builder calls StartImageScan after each image push, then polls DescribeImageScanFindings until the scan completes (up to 10 minutes). No extra K8s Job is created. Results are stored as vulnerability counts — no CycloneDX SBOM is produced.

The builder's IAM role needs two additional permissions. See AWS (EKS) — ECR image scanning for the IAM policy.

Trivy scanningCopy Anchor Link

When provider: "trivy" (or auto-selected for non-ECR registries), the builder creates a short-lived K8s Job in the build namespace that runs trivy image against the pushed image. The job produces vulnerability counts and, optionally, a CycloneDX SBOM available for download on the deployment detail page.

SBOM generation requires a second trivy image pass and adds roughly 30–60 seconds to scan time. It is disabled by default:

security:
  scan:
    sbomEnabled: true

Override the Trivy image version:

builder:
  trivyImage: "aquasec/trivy:0.58.0"

Secret referencesCopy Anchor Link

Several sensitive values can be sourced from existing Kubernetes Secrets rather than plain Helm values. Create the secret in the system namespace before running helm install or helm upgrade.

External database passwordCopy Anchor Link

Put $(DB_PASSWORD) in the URL where the password goes, then point passwordSecretRef at your secret:

externalDatabase:
  url: "postgresql://myuser:$(DB_PASSWORD)@myhost:5432/mydb?sslmode=require"
  passwordSecretRef:
    name: my-db-secret
    key: password

Kubernetes substitutes $(DB_PASSWORD) at pod startup. Create the secret before running helm install or helm upgrade:

kubectl create secret generic my-db-secret \
  --namespace canette-system \
  --from-literal=password=<your-db-password>

See Production setup for a full walkthrough of using an external database.

External database SSLCopy Anchor Link

Managed databases (AWS RDS, Cloud SQL, Azure Database) use a certificate authority that is not in the default system trust store. Provide the CA certificate so canette can verify the server's TLS certificate.

Option 1 — reference an existing Secret (recommended):

Create a Secret containing the PEM-encoded CA bundle, then point caCertSecretRef at it:

kubectl create secret generic my-db-ca \
  --namespace canette-system \
  --from-file=ca.crt=rds-ca-bundle.pem

externalDatabase:
  url: "postgresql://myuser:$(DB_PASSWORD)@mydb.abc123.us-east-1.rds.amazonaws.com:5432/mydb?sslmode=verify-full"
  ssl:
    caCertSecretRef:
      name: my-db-ca
      key: ca.crt

Option 2 — inline PEM in values:

externalDatabase:
  ssl:
    caCert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

externalDatabase:
  ssl:
    rejectUnauthorized: false

externalDatabase:
  url: "postgresql://myuser:mypassword@myhost:5432/mydb?sslmode=disable"

External registry passwordCopy Anchor Link

externalRegistry:
  username: myuser
  passwordSecretRef:
    name: my-registry-secret
    key: password

The chart looks up the secret at render time to construct the docker config — the secret must exist before helm install.

GitHub client secretCopy Anchor Link

api:
  githubClientId: "my-client-id"
  githubClientSecretRef:
    name: my-github-secret
    key: client-secret

Backup S3 credentialsCopy Anchor Link

backup:
  s3:
    secretRef:
      name: canette-backup-s3-credentials
      accessKeyKey: access-key
      secretKeyKey: secret-key

See Backups for the full setup, including the IAM policy.

Encryption keyCopy Anchor Link

The encryption key used to protect git credentials and app secrets at rest is auto-generated on first install and stored as a Kubernetes Secret. Every helm upgrade reuses the existing key automatically — no action required.

To provide your own key (disaster recovery, cluster migration):

encryptionKey: "your-32-character-key-here"

UpgradingCopy Anchor Link

helm upgrade canette oci://ghcr.io/canette/canette --reuse-values

To upgrade to a specific version:

helm upgrade canette oci://ghcr.io/canette/canette --version 1.2.3 --reuse-values

Migrations run automatically at API startup after the upgrade.

UninstallingCopy Anchor Link

helm uninstall canette -n canette-system
kubectl delete namespace canette-system canette-system-build

OperationsCopy Anchor Link

Rotating registry credentialsCopy Anchor Link

To rotate credentials without changing other values, use a gitignored secrets file:

# secrets.yaml  (add to .gitignore)
externalRegistry:
  username: myuser
  password: mytoken

helm upgrade canette oci://ghcr.io/canette/canette --reuse-values -f secrets.yaml

After upgrading, restart the builder to pick up the new credentials:

kubectl rollout restart deployment/canette-builder -n canette-system

Updating resource defaultsCopy Anchor Link

# values.yaml
api:
  defaultResources:
    cpuRequest: "250m"
    memoryRequest: "256Mi"
    cpuLimit: "1"
    memoryLimit: "1Gi"

helm upgrade canette oci://ghcr.io/canette/canette --reuse-values -f values.yaml

The new values take effect on the next deployment for each app. Existing live apps continue to use the resource values from when they were last deployed.

Restarting a serviceCopy Anchor Link

Rolling restart with zero downtime — the old pod stays up until the new one is ready:

kubectl rollout restart deployment/canette-builder -n canette-system
kubectl rollout restart deployment/canette-controller -n canette-system