Unleash

Overview

Unleash is an open-source feature-flag server: toggle features on and off, roll them out gradually and run A/B tests without redeploying the applications that use them. This template deploys the free open-source edition as one stateless workload serving the admin UI and the Admin, Client and Frontend APIs on a single port, backed by a bundled PostgreSQL database that holds every flag, user and token — the postgres-highly-available template by default, or the single-instance postgres template with one flag. Because other applications gate their behaviour on it, the highly available database is the default, and the Unleash server itself scales to more replicas with a single value.

This template deploys into an existing GVC that you already have — it does not create or manage a GVC. Every workload below runs in each location of that GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-unleash`	Unleash admin UI and Admin, Client and Frontend APIs (standard, 1 replica by default, HTTP port `4242`, public by default)	—
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL database (stateful, 3 replicas)	Default; `postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader-routing endpoint Unleash connects through (standard, 2 replicas, port `5432`)	Default; `postgresHA.enabled: true`
Workload	`RELEASE_NAME-etcd`	Consensus store for the highly available database (stateful, 3 replicas)	Default; `postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical dump of the highly available database (cron)	`postgresHA.backup.enabled: true` with `mode: logical`
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL database (stateful, 1 replica, port `5432`)	`postgres.enabled: true` with `postgresHA.enabled: false`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled logical dump of the single-instance database (cron)	`postgres.backup.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	Highly available database and consensus-store data (10 GiB per replica by default; a final snapshot is taken on delete and kept 7 days)	Default; `postgresHA.enabled: true`
Volume set	`RELEASE_NAME-pg-vs`	Single-instance database data (10 GiB by default; a final snapshot is taken on delete and kept 7 days)	`postgres.enabled: true`
Secret	The name in `postgresHA.config.credentialsSecretName` or `postgres.config.credentialsSecretName` (default `my-unleash-db-credentials`)	Database credentials, created by this chart from `postgres.credentials.*` and read by whichever database is enabled	—
Secret	`RELEASE_NAME-unleash-start`	Start script that derives the public URL, waits until the database accepts queries, then starts Unleash	—
Secret	`RELEASE_NAME-etcd-startup`, `RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-wal-g-backup-script`	Startup scripts of the highly available database tier	Default; `postgresHA.enabled: true`
Secret	`RELEASE_NAME-postgres-config`	Non-sensitive backup settings of the highly available database (bucket, region)	`postgresHA.backup.enabled: true`
Identity / Policy	`RELEASE_NAME-unleash-identity`, `RELEASE_NAME-unleash-policy`	`reveal` on exactly the secrets the Unleash workload reads: your admin secret, the start script, the database credentials and, when set, your API-token secret	—
Identity / Policy	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	The highly available database tier’s own identities and policies	Default; `postgresHA.enabled: true`
Identity / Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	The single-instance database’s own identity and policy	`postgres.enabled: true`

Unleash itself has no volume set — all of its state lives in the database. The admin login and the optional API-token seed are prerequisite secrets you create yourself; the chart references them by name and never creates, modifies or deletes them.

Prerequisites

One secret must exist before you install, and a second is optional. Secrets are org-level, so no --gvc flag is involved.

Create the admin login secret (required)

A dictionary secret holding exactly the keys username and password. It seeds the initial admin account, whose login form sits on the public endpoint, so it is a prerequisite secret rather than a Helm value:

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -hex 24)"

Set admin.secretName to this name. Read the values back later with cpln secret reveal ADMIN_SECRET_NAME -o yaml — the -o yaml is required; a bare reveal prints only a summary table.

Create the API-token seed secret (optional)

Skip this step to create SDK tokens in the admin UI after install instead. Otherwise create a dictionary secret holding exactly the keys backend and frontend, each a full Unleash token string in the format <project>:<environment>.<secret>. The open-source edition ships the default project and the development and production environments:

cpln secret create-dictionary --name API_TOKENS_SECRET_NAME \
  --entry backend="default:production.$(openssl rand -hex 24)" \
  --entry frontend="default:production.$(openssl rand -hex 24)"

Set apiTokens.secretName to this name. Leaving it empty (the default) turns seeding off entirely.

Choose the database password

The bundled database’s credentials are internal plumbing: this chart writes postgres.credentials.username, postgres.credentials.password and postgres.credentials.database into a dictionary secret it creates, and the database reads that secret. Nothing to create — but the password ships as the placeholder change-me-unleash-db-password, so set postgres.credentials.password to a value of your own before installing. This applies in both database modes, even with postgres.enabled: false.

A missing prerequisite secret wedges the install rather than failing it. cpln helm install reports success and every resource is created, but the Unleash container never starts — so cpln logs returns zero lines. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-unleash --gvc GVC_NAME -o yaml

The message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

It is get-deployments — plain cpln workload get has no versions key. Create the missing secret and the deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-unleash --gvc GVC_NAME to skip the wait.

Optional database backups need a bucket and access setup on AWS S3, Google Cloud Storage or an S3-compatible server, and S3-compatible servers additionally need a dictionary secret with the bucket keys — see Backing Up.

Installation

Once the admin secret exists, install the template into your GVC, naming the secret and replacing the database password placeholder:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/unleash \
  --version 1.4.0 --gvc GVC_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set postgres.credentials.password='YOUR-STRONG-DB-PASSWORD'

Add --set apiTokens.secretName=API_TOKENS_SECRET_NAME if you created the optional token seed. Prefer a values file (--values) over --set for the database password if you do not want it in your shell history. If you run more than one release of this template in the same org, also give each its own postgresHA.config.credentialsSecretName (or postgres.config.credentialsSecretName in single-instance mode) — see Database.

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Unleash Instance

image: unleashorg/unleash-server:8.0.3

resources:
  maxCpu: 1000m
  maxMemory: 1Gi
  minCpu: 250m
  minMemory: 512Mi

replicas: 1 # stateless server — set 2+ for high availability (all state lives in PostgreSQL)

resources.maxCpu and resources.maxMemory are the container limits; resources.minCpu and resources.minMemory are the reservation. replicas sets a fixed replica count behind the load balancer — the server holds no state of its own, so 2 or more keeps flags served through a rolling restart or the loss of one replica. Unleash’s version check against the upstream service is disabled by the template.

Admin Account and API Tokens

admin:
  secretName: my-unleash-admin # name of your pre-created dictionary secret

apiTokens:
  secretName: "" # name of a pre-created dictionary secret with keys `backend` and `frontend` (e.g. my-unleash-api-tokens); empty = create tokens in the admin UI instead

admin.secretName names the required dictionary secret from Prerequisites, with keys username and password. Unleash creates the admin account from it on first boot only; the account then lives in the database. Editing the secret later changes nothing, and an upgrade never resets the password — change it in the admin UI.
apiTokens.secretName names the optional dictionary secret with keys backend and frontend. When set, both tokens are seeded on first boot only; when empty, nothing is seeded and the workload references no extra secret. Create or revoke tokens later in the admin UI.

Access

publicAccess:
  enabled: true # admin UI + SDK APIs on the canonical *.cpln.app HTTPS endpoint

internalAccess: # internal firewall scope (in-GVC SDK callers)
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

Public access is on by default because SDKs running in browsers and in applications outside the GVC call /api/frontend and /api/client directly. Every surface is authenticated — the UI and Admin API by login, the Client and Frontend APIs by tokens. Set publicAccess.enabled: false for an internal-only instance; in-GVC callers still reach it per internalAccess, and you reach the UI through a tunnel (see Connecting). A firewall change can take a few minutes to take effect, so re-test rather than trusting the first response. The URL Unleash embeds in password-reset and invite links is derived at container start: the canonical endpoint when public, the internal RELEASE_NAME-unleash.GVC_NAME.cpln.local:4242 address when not.

`internalAccess.type`	Who can reach Unleash inside Control Plane
`none`	No workload.
`same-gvc`	Every workload in the same GVC (default).
`same-org`	Every workload in the same org.
`workload-list`	Only the workloads listed in `internalAccess.workloads`.

Database

Exactly one of the two database modes must be enabled — the chart enforces this at render and refuses to install otherwise. Unleash is wired to the active database automatically: the HAProxy leader endpoint in HA mode, or the single instance directly.

	`postgresHA` (default)	`postgres`
What runs	3× Patroni PostgreSQL, 3× etcd, HAProxy leader endpoint	One single-replica PostgreSQL workload
Database failover	Automatic (Patroni leader election)	None — a node failure means minutes of downtime, not data loss
Footprint	8 replicas across 3 workloads	1 workload
Best for	Production — the default, because applications depend on the flag server	Development and lightweight installs

postgresHA:
  enabled: true
  config:
    credentialsSecretName: my-unleash-db-credentials # dictionary secret this chart CREATES from postgres.credentials.*; org-wide name — give each release its own
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

postgresHA:
  enabled: false # set postgresHA.enabled: true (the default) for automatic database failover
postgres:
  enabled: true
  credentials:
    username: unleash
    password: change-me-unleash-db-password # change before installing
    database: unleash
  config:
    credentialsSecretName: my-unleash-db-credentials # secret this chart CREATES; org-wide name — give each release its own
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

In both modes the database credentials come from postgres.credentials.* — the chart writes them into the dictionary secret named by postgresHA.config.credentialsSecretName or postgres.config.credentialsSecretName (whichever database is enabled), and the database reads that secret. Change postgres.credentials.password before installing even when postgres.enabled is false. In HA mode the proxy must stay enabled — that endpoint is Unleash’s stable database address, and the chart refuses to render with postgresHA.proxy.enabled: false. Secret names are org-wide, so a second release of this template left on the default credentialsSecretName is refused at install with cannot be updated because it is being managed by a different release and creates nothing — the first release is unaffected. Give each release its own name. Everything else the bundled databases can do — volume autoscaling, PgBouncer pooling, etcd tuning — is documented on the postgres-highly-available and postgres pages and is set under the same postgresHA.* / postgres.* prefixes. Their backup settings are covered under Backing Up.

Connecting

What	Address	Notes
Admin UI and Admin API (public)	`status.canonicalEndpoint` of `RELEASE_NAME-unleash`	`cpln workload get RELEASE_NAME-unleash --gvc GVC_NAME -o yaml`; present while `publicAccess.enabled` is `true`
Client API (backend SDKs)	`/api/client` on either Unleash address	`Authorization` header carries a backend token
Frontend API (browser and mobile SDKs)	`/api/frontend` on either Unleash address	`Authorization` header carries a frontend token
Unleash (internal)	`http://RELEASE_NAME-unleash.GVC_NAME.cpln.local:4242`	Reachable per `internalAccess.type`; point in-GVC SDKs at `http://RELEASE_NAME-unleash.GVC_NAME.cpln.local:4242/api`
Admin login	The `username` and `password` keys of your admin secret	`cpln secret reveal ADMIN_SECRET_NAME -o yaml` — or whatever you have since changed the password to in the UI
Database (HA mode)	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432`	Always the current leader
Database (single mode)	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	—
Database credentials	The secret named by `postgresHA.config.credentialsSecretName` / `postgres.config.credentialsSecretName`	`cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml`; keys `username`, `password`, `database`
Health	`/health` on either Unleash address	Unauthenticated; the same check the template’s own probes use

Read the public address from status.canonicalEndpoint, then confirm the server answers — /health returns HTTP 200 once Unleash has finished its database migrations:

cpln workload get RELEASE_NAME-unleash --gvc GVC_NAME -o yaml
curl -sS https://UNLEASH_ENDPOINT/health

With publicAccess.enabled: false there is no canonical endpoint. Open a tunnel to the UI instead and browse to http://localhost:4242:

cpln port-forward RELEASE_NAME-unleash 4242:4242 --gvc GVC_NAME

First Run

Unleash has no setup wizard: the admin account is created from your admin secret on first boot. A fresh install in HA mode takes several minutes to become ready while the database cluster forms; the start script waits until the database accepts queries before Unleash runs its migrations.

Wait for the workload to report ready

cpln workload get-deployments RELEASE_NAME-unleash --gvc GVC_NAME -o yaml

Open the canonical endpoint (or http://localhost:4242 through the tunnel) and sign in with the username and password from your admin secret. Change the password in the UI if you wish — that is the only place it changes from now on.

Create an SDK token

If you did not seed tokens through apiTokens.secretName, go to Admin → API access and create one: choose Backend for a server-side SDK or Frontend for a browser or mobile SDK, then the project and environment it applies to.

API Tokens

SDKs authenticate with an API token in the Authorization header, and the two token types are not interchangeable:

Backend tokens authenticate server-side SDKs against /api/client. Treat them like passwords.
Frontend tokens authenticate browser and mobile SDKs against /api/frontend. They are designed to be embedded in client code.

A token string names its project and environment (<project>:<environment>.<secret>), so a 401 or 403 from an SDK API usually means the wrong token type for the endpoint or the wrong environment in the token.

Operations

Backing Up

Database backups are optional and disabled by default. They cover the database — every flag, strategy, segment, user and token in your Unleash instance. Enable them on whichever database is active and complete the storage setup for your provider before installing or upgrading with them on.

postgresHA:
  backup: # optional database backups — see README storage setup
    enabled: false
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *"
    walg:
      intervalSeconds: 21600
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: unleash-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: unleash-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: unleash-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: unleash-pg-backup-bucket
      credentialsSecretName: my-unleash-minio-credentials # REQUIRED prerequisite dictionary secret holding accessKey and secretKey
      prefix: postgres/backups

postgres:
  backup: # optional database backups (Postgres 17+) — see README storage setup
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *"
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: unleash-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: unleash-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: unleash-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: unleash-pg-backup-bucket
      credentialsSecretName: my-unleash-minio-credentials # REQUIRED prerequisite dictionary secret holding accessKey and secretKey
      prefix: postgres/backups

In HA mode postgresHA.backup.mode selects logical (a scheduled dump run by the RELEASE_NAME-postgres-ha-backup cron workload through the HAProxy endpoint) or wal-g (continuous WAL archiving from the database workload itself, with no separate backup workload). The single-instance database takes scheduled logical dumps only, through RELEASE_NAME-postgres-backup. Both come from the bundled postgres-highly-available and postgres templates. The steps below name the keys under postgresHA.backup.*; in single-instance mode set the same keys under postgres.backup.*.

AWS S3
Google Cloud Storage
MinIO / S3-compatible

Create a bucket

Create an S3 bucket. Set postgresHA.backup.aws.bucket and postgresHA.backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for the AWS account holding the bucket. Set postgresHA.backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an IAM policy with the JSON below (replace YOUR_BUCKET), then set postgresHA.backup.aws.policyName to the policy’s name:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:ListBucket",
      "s3:GetBucketLocation",
      "s3:GetObject",
      "s3:GetObjectVersion",
      "s3:PutObject",
      "s3:DeleteObject",
      "s3:DeleteObjectVersion",
      "s3:AbortMultipartUpload"
    ],
    "Resource": [
      "arn:aws:s3:::YOUR_BUCKET",
      "arn:aws:s3:::YOUR_BUCKET/*"
    ]
  }]
}

Create a bucket

Create a GCS bucket. Set postgresHA.backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for the GCP project holding the bucket. Set postgresHA.backup.gcp.cloudAccountName to its name — the backup identity reaches the bucket keylessly, with no stored credentials.

Grant access

Grant the Storage Admin role to the GCP service account created for the Cloud Account. The chart additionally binds the backup identity to roles/storage.objectAdmin on exactly the bucket you named.

Create a bucket

Create the bucket on the server. Set postgresHA.backup.minio.bucket to its name. No Cloud Account is needed.

Set the endpoint

Set postgresHA.backup.minio.endpoint to the S3 API address including the port. For the MinIO template deployed in the same GVC, this is http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000.

Create the credentials secret

Both database modes take the bucket credentials as a dictionary secret holding exactly the keys accessKey and secretKey. Create it before enabling the backup and set postgresHA.backup.minio.credentialsSecretName to its name:

cpln secret create-dictionary --name MINIO_CREDENTIALS_SECRET_NAME \
  --entry accessKey=MINIO_ACCESS_KEY \
  --entry secretKey=MINIO_SECRET_KEY

A database backup does not cover your prerequisite secrets; keep a copy of the admin login somewhere safe. The database volume sets also take a final snapshot when they are deleted, kept for seven days.

Restoring a Backup

No restore path has been rehearsed against this template. The outline below follows the bundled database templates’ own restore procedures and this chart’s configuration; rehearse it against a scratch release before you depend on it. Restoring from a volume set snapshot is likewise unverified here.

A restore goes into the database, not into Unleash: everything that makes up your instance lives there, so restoring it brings back flags, strategies, users and tokens together. A logical backup is a gzip-compressed SQL file (.sql.gz under your prefix), replayed with psql from a client that can reach both the bucket and the database — a workload inside the GVC, or your own machine with a tunnel open. The Unleash container is not that client. In HA mode go through the HAProxy endpoint so the writes land on the leader:

cpln port-forward RELEASE_NAME-postgres-ha-proxy 5432:5432 --gvc GVC_NAME

Use RELEASE_NAME-postgres as the workload name in single-instance mode. The full per-provider replay commands, and the WAL-G outline for HA mode — which ends in a manual volume-set swap this chart does not expose — are on the postgres-highly-available and postgres pages. Restore into an empty database and keep Unleash from connecting until the replay has finished. Because the restored database already holds an admin account, the admin secret is not applied again — sign in with the account from the dump.

Upgrading from 1.0.x

Two changes landed between 1.0.0 and 1.1.0; apply both when upgrading from 1.0.0. 1.0.1 — etcd compaction. Version 1.0.0 did not compact the etcd cluster inside the bundled highly available database, so etcd’s backend grows with time alone and eventually goes read-only when it reaches its quota — taking PostgreSQL failover with it. Only installs running the HA database are affected (postgresHA.enabled, the default). See etcd History Compaction for the mechanism and symptoms. Upgrading to 1.0.1 or later turns compaction on; that stops further growth but cannot shrink a backend that has already grown, and a cluster that has already raised a NOSPACE alarm needs operator recovery rather than an upgrade. 1.1.0 — the admin login became a prerequisite secret. Earlier versions shipped admin.username and a working admin.password as values — a published default guarding a login form on the public endpoint. An upgrade that still carries either key is rejected at render, before anything is applied, with a message naming its replacement; there is no compatibility fallback. Version 1.1.0 also made the start script wait for the database before Unleash runs its migrations.

Removed key (1.0.x)	Replacement (1.1.0 and later)
`admin.username`	`username` key in the prerequisite admin secret named by `admin.secretName`
`admin.password`	`password` key in the same secret

Create the admin login secret

Follow Prerequisites. Its contents only matter to a fresh install — the account already exists in your database and is only created on first boot, so your existing admin password does not change on upgrade. An existing apiTokens.secretName secret stays exactly as it is.

Drop the removed keys and upgrade

Remove admin.username and admin.password from your values and set admin.secretName. The Unleash replicas restart; flags, users and tokens are in the database and are untouched.

Change the admin password in the UI

If the install was still using the published 1.0.x default password (change-me-unleash-admin), treat it as compromised and change it now in the Unleash UI — the secret cannot change an existing account. Every later migration note below also applies.

Upgrading from 1.1.0

Version 1.2.0 adopted the postgres 3.4.1 template, which stopped taking database credentials as values. Unleash absorbed that change — the chart now creates the credentials secret itself — so there is no new prerequisite, only a rename of three keys in single-instance mode:

Removed key (1.1.0)	Replacement (1.2.0 and later)
`postgres.config.username`	`postgres.credentials.username`
`postgres.config.password`	`postgres.credentials.password`
`postgres.config.database`	`postgres.credentials.database`
`postgres.backup.minio.accessKey` / `postgres.backup.minio.secretKey`	a dictionary secret named by `postgres.backup.minio.credentialsSecretName`

Move the keys keeping the same values — the database was initialized with them. A values file that still carries an old key fails the render with the postgres template’s message (config.username was REMOVED in postgres 3.4.0), which tells you to create a dictionary secret yourself — ignore that advice here; this template creates it from postgres.credentials.*. If you back up to MinIO, create the dictionary secret described under Backing Up and set postgres.backup.minio.credentialsSecretName. The HA path is unchanged by this step.

Upgrading from 1.2.x

Version 1.3.0 adopted the postgres-highly-available 2.5.0 template, which made the same change on the HA path, and 1.3.1 did the same for its MinIO backup keys. The HA database credentials now come from the same postgres.credentials.* block as the single-instance ones, and the chart creates the secret named by postgresHA.config.credentialsSecretName.

Removed key (1.2.x)	Replacement (1.3.x and later)
`postgresHA.postgres.username`	`postgres.credentials.username`
`postgresHA.postgres.password`	`postgres.credentials.password`
`postgresHA.postgres.database`	`postgres.credentials.database`
`postgresHA.backup.minio.accessKey` / `postgresHA.backup.minio.secretKey`	a dictionary secret named by `postgresHA.backup.minio.credentialsSecretName` (1.3.1)

Move the three credential values unchanged into postgres.credentials.* — the running cluster was initialized with them — and delete the postgresHA.postgres block entirely. Leaving postgres.enabled: false is correct; the postgres.credentials.* values feed both database modes. A values file that still carries the old block stops the upgrade at render:

Error: ... postgres-highly-available: the `postgres` block was REMOVED in 2.5.0. `postgres.username`,
`postgres.password` and `postgres.database` are now a `dictionary` secret you create, named by
`config.credentialsSecretName`, holding the keys `username`, `password` and `database`. Delete the
`postgres:` block from your values. See Prerequisites in the README.

The message’s instruction to create the secret yourself does not apply — this template creates it. If you back up the HA database to an S3-compatible server, create the credentials secret described under Backing Up with the same access key and secret key, set postgresHA.backup.minio.credentialsSecretName, and remove the two old keys; if you are already on 1.3.0, that MinIO change is the only part of this step that applies.

Upgrading from 1.3.x

Version 1.4.0 renamed the Unleash container’s resource limits: a block that exposes both a reservation and a limit now names the limit maxCpu / maxMemory, so it is no longer ambiguous which number is the ceiling. Nothing else changed.

Removed key (1.3.x)	Replacement (1.4.0)
`resources.cpu`	`resources.maxCpu`
`resources.memory`	`resources.maxMemory`

An upgrade that still carries either old key is refused at render with unleash: resources.cpu was RENAMED to resources.maxCpu (or the memory equivalent); rename the two keys and upgrade. resources.minCpu and resources.minMemory keep their names, and the backup resources blocks, which expose only a limit, keep cpu and memory.

Scaling and Availability

The Unleash server is stateless — set replicas to 2 or more so flags keep being served through a rolling restart or the loss of a replica. Every Helm upgrade rolls the Unleash replicas.
Database replicas are set with postgresHA.replicas; the single-instance database must stay at one replica.
The first helm upgrade after an install can restart the bundled database even when no database value changed, so expect a short interruption on that first upgrade.
Seeded secrets apply on first boot only. Editing the admin or API-token secret later does not change the account or the tokens; manage both in the admin UI.
Confirm an upgrade is live from the deployment, not from the Helm output — cpln workload get-deployments RELEASE_NAME-unleash --gvc GVC_NAME -o yaml.
Uninstall deletes every volume set the chart created — the database and, in HA mode, the consensus store — so the data does not survive a reinstall. The GVC is yours and is left alone, and the prerequisite secrets you created survive. Enable backups if the data matters.

Troubleshooting

The Unleash workload never starts after install while helm reported success

Symptom: cpln helm install succeeded, but RELEASE_NAME-unleash shows no running containers and cpln logs returns nothing.Cause: A prerequisite secret named in your values does not exist — the admin secret, or the API-token secret when apiTokens.secretName is set. The deployment pauses on the unresolved reference.Fix: Read the message naming the secret, then create it:

cpln workload get-deployments RELEASE_NAME-unleash --gvc GVC_NAME -o yaml

The message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Once the secret exists the deployment recovers on its own, or run cpln workload force-redeployment RELEASE_NAME-unleash --gvc GVC_NAME to skip the wait.

Failed to migrate db errors on a fresh install in HA mode

Symptom: Several minutes after a fresh install, RELEASE_NAME-unleash is not ready yet and its logs contain Failed to migrate db.Cause: Unleash cannot run its schema migrations until the bundled database cluster has formed and the HAProxy endpoint routes to a leader. Transient migration errors while the cluster starts are expected and self-correcting, at any replica count.Fix: Wait, then re-check cpln workload get-deployments RELEASE_NAME-unleash --gvc GVC_NAME -o yaml. Confirm the database tier is ready first with cpln workload get-deployments RELEASE_NAME-postgres-ha --gvc GVC_NAME -o yaml. Read the errors with a server-side filter:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-unleash"} |= "migrate"' --limit 50 --since 10m

An SDK gets 401 or 403 from the Client or Frontend API

Symptom: An SDK cannot fetch flags and the API answers 401 or 403.Cause: The token type does not match the endpoint — a frontend token sent to /api/client, or a backend token sent to /api/frontend — or the environment in the token string is not the one you meant.Fix: Use a backend token for server-side SDKs and a frontend token for browser and mobile SDKs, and create a new one in Admin → API access if needed. See API Tokens.

Password-reset or invite links point at the wrong address

Symptom: Links in password-reset or invite emails use the internal cpln.local address, or the public address after you made the instance private.Cause: The link base URL is derived when the container starts, from whether publicAccess.enabled is on at that moment.Fix: Restart the workload so the start script derives it again: cpln workload force-redeployment RELEASE_NAME-unleash --gvc GVC_NAME.

Render fails with enable exactly one database

Symptom: The install stops with unleash: enable exactly one database — set either postgresHA.enabled or postgres.enabled to true, not both, or the variant naming postgresHA.enabled (production) or postgres.enabled (dev/lightweight).Cause: Both postgresHA.enabled and postgres.enabled are true, or both are false.Fix: Enable exactly one — see Database. To use the single-instance database, set postgresHA.enabled: false together with postgres.enabled: true.

A second release is refused because a resource is managed by a different release

Symptom: Installing a second release of this template in the same org fails with cannot be updated because it is being managed by a different release, naming the database credentials secret, and creates nothing.Cause: Secret names are org-wide, and both releases are trying to create the same credentialsSecretName (default my-unleash-db-credentials). The first release owns it.Fix: Give the new release its own postgresHA.config.credentialsSecretName (or postgres.config.credentialsSecretName in single-instance mode) and install again. The first release is unaffected.

Upgrade fails with a key that was REMOVED or RENAMED

Symptom: helm upgrade stops at render with admin.password was REMOVED in 1.1.0, config.username was REMOVED in postgres 3.4.0, the postgres block was REMOVED in 2.5.0, backup.minio.accessKey and backup.minio.secretKey were REMOVED, or resources.cpu was RENAMED to resources.maxCpu.Cause: Your values still carry a key that moved in template versions 1.1.0, 1.2.0, 1.3.0, 1.3.1 or 1.4.0. The existing release is left untouched and running.Fix: Follow the matching migration note above — Upgrading from 1.0.x, Upgrading from 1.1.0, Upgrading from 1.2.x or Upgrading from 1.3.x — keeping the credentials the database already uses. Do not create a database credentials secret yourself; this template creates it.

Important Notes

Create the admin secret before installing, and change postgres.credentials.password from its change-me placeholder. A missing prerequisite secret does not fail the install — the workload waits on it with zero log lines.
The admin secret and the API-token seed apply on first boot only. Change the password and manage tokens in the admin UI; editing the secrets later changes nothing, and an upgrade never resets your password.
Backend tokens must stay secret (server-side SDKs, /api/client); frontend tokens are safe to embed in browsers (/api/frontend).
Give each release its own credentialsSecretName — secret names are org-wide, and a second release on the default name is refused at install.
The free edition ships two environments (development, production); SSO, role-based access control, multiple projects, change requests and audit logs need an Unleash Enterprise license and are not available in this template.
Uninstall deletes the database volume sets — all flags, users and tokens. Enable backups if the data matters; the prerequisite secrets you created survive and must be deleted manually.

External References

Unleash Documentation

Official Unleash documentation

Configuring Unleash

Environment variable configuration reference

API Tokens and Client Keys

Token types, formats, and how SDKs authenticate

SDK Overview

Official backend and frontend SDKs

Unleash Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Unleash Instance

Admin Account and API Tokens

Access

Database

Connecting

First Run

API Tokens

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.x

Upgrading from 1.1.0

Upgrading from 1.2.x

Upgrading from 1.3.x

Scaling and Availability

Troubleshooting

Important Notes

External References

Unleash Documentation

Configuring Unleash

API Tokens and Client Keys

SDK Overview

Unleash Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Unleash Instance

​Admin Account and API Tokens

​Access

​Database

​Connecting

​First Run

​API Tokens

​Operations

​Backing Up

​Restoring a Backup

​Upgrading from 1.0.x

​Upgrading from 1.1.0

​Upgrading from 1.2.x

​Upgrading from 1.3.x

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Unleash Documentation

Configuring Unleash

API Tokens and Client Keys

SDK Overview

Unleash Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Unleash Instance

Admin Account and API Tokens

Access

Database

Connecting

First Run

API Tokens

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.x

Upgrading from 1.1.0

Upgrading from 1.2.x

Upgrading from 1.3.x

Scaling and Availability

Troubleshooting

Important Notes

External References