Configure the Helm deployment

The chart's complete values reference is the released values.yaml:

helm show values oci://ghcr.io/usenorn/charts/norn

Use the shared Norn configuration reference for application settings. This page covers only how the Helm chart maps that configuration onto Kubernetes resources.

Application configuration

Value	Use for
norn.configEnv	Non-secret NORN_* settings
norn.existingSecret	A Secret containing credentials and connection strings
norn.extraEnv	Kubernetes valueFrom references
norn.extraEnvFrom	Additional ConfigMaps or Secrets

The chart owns the public URL, listeners, session security, and data-service connections. Configure those through their dedicated values rather than norn.configEnv.

Values passed to Helm are stored in Helm release state. Do not put production credentials in a values file, --set, or norn.secretEnv.

Secrets

With the default configuration, the chart creates a retained Secret and reuses its values on upgrade. Set norn.existingSecret to use a Secret managed outside Helm:

values.yaml

norn:
  existingSecret: norn-production

The Secret requires keys according to the enabled services:

Key	Required when
NORN_SECURITY_ENCRYPTION_KEY	Always
NORN_POSTGRES_DSN	Always
NORN_STORAGE_ACCESS_KEY_ID, NORN_STORAGE_SECRET_ACCESS_KEY	Always
NORN_VALKEY_PASSWORD, NORN_ASYNQ_PASSWORD	External Valkey uses authentication
POSTGRES_PASSWORD	Bundled PostgreSQL is enabled
VALKEY_PASSWORD, valkey.conf	Bundled Valkey is enabled
GARAGE_DEFAULT_ACCESS_KEY, GARAGE_DEFAULT_SECRET_KEY	Bundled Garage is enabled
GARAGE_RPC_SECRET, GARAGE_ADMIN_TOKEN, GARAGE_METRICS_TOKEN	Bundled Garage is enabled

For bundled Valkey, valkey.conf must include appendonly yes, maxmemory-policy noeviction, and a requirepass value matching VALKEY_PASSWORD.

Secret changes do not restart pods. After rotating a credential, restart the affected Norn Deployments. For bundled data services, changing the Secret alone does not change credentials already stored by the service; rotate the service-side credential as part of the same operation.

External PostgreSQL

values.yaml

norn:
  existingSecret: norn-production

postgresql:
  enabled: false

Store the connection string in NORN_POSTGRES_DSN. Use a dedicated database and role with permission to apply Norn's embedded migrations. Require TLS when supported. Do not connect two Norn instances to the same database.

External Valkey

values.yaml

valkey:
  enabled: false
  external:
    address: valkey.database.svc.cluster.local:6379
    username: norn

Store authenticated credentials in NORN_VALKEY_PASSWORD and NORN_ASYNQ_PASSWORD. The external service must satisfy Norn's Valkey requirements.

External object storage

values.yaml

garage:
  enabled: false
  external:
    endpoint: https://s3.eu-west-1.amazonaws.com
    region: eu-west-1
    bucket: norn-production
    usePathStyle: false

Store the credentials in NORN_STORAGE_ACCESS_KEY_ID and NORN_STORAGE_SECRET_ACCESS_KEY. Restrict them to the selected bucket.

The chart configures the required browser CORS policy automatically only for bundled Garage. Configure the object-storage CORS policy yourself for an external bucket.

Public routing

The chart Ingress implements Norn's public routing contract. Bundled Garage uses a separate hostname.

If another system owns routing, disable the chart Ingress and set both public origins:

values.yaml

ingress:
  enabled: false
  tls:
    enabled: false

norn:
  baseUrl: https://norn.example.com

garage:
  publicEndpoint: https://storage.norn.example.com
  service:
    type: LoadBalancer

Put non-secret application settings in norn.configEnv. Reference credentials such as NORN_SMTP_PASSWORD through norn.extraEnv or the existing Secret.

Scaling

API and web can scale horizontally. CPU autoscaling requires CPU requests and a Kubernetes resource metrics API:

values.yaml

api:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 8

web:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 8

The worker intentionally remains a single replica. Bundled PostgreSQL, Valkey, and Garage are also single replicas; application autoscaling does not make the data layer highly available.

Private registries

Set global.imagePullSecrets and override the relevant image repositories or digests. Mirror the API, web, migration wait, and test images plus PostgreSQL, Valkey, Garage, and AWS CLI when those components are enabled. Every chart image supports an immutable digest.