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 your applications. This template deploys the free open-source edition backed by a highly available PostgreSQL cluster by default. The admin UI and the Admin, Client, and Frontend APIs are served on one public HTTPS endpoint, and the server is stateless — every flag, user, and token lives in PostgreSQL — so it scales to multiple replicas with a single value.

Architecture

Unleash — A standard workload (default 1 replica, replicas knob for more) serving the admin UI and all APIs on port 4242. Stateless by design: all state lives in the PostgreSQL database, so Unleash itself has no volume set. The public URL (UNLEASH_URL) is derived from the canonical endpoint at start.
PostgreSQL (HA, default) — The postgres-highly-available template as a subchart: 3× Patroni PostgreSQL, 3× etcd, and a HAProxy leader-routing endpoint Unleash connects through.
PostgreSQL (dev/lightweight, optional) — The single-instance postgres template instead, for lighter non-HA deployments.

What Gets Created

Standard Unleash Workload — One or more stateless replicas serving the admin UI and the Admin, Client, and Frontend APIs on port 4242.
Database Workloads — HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload. Single mode: one stateful PostgreSQL workload.
Volume Sets — The database subchart’s persistent volumes (10 GiB per replica by default). Unleash itself has none.
Secrets — Admin bootstrap credentials, the start script that derives the public URL at runtime, and the database credentials from the subchart.
Identity & Policy — A least-privilege policy granting the Unleash identity reveal on exactly the secrets it uses, including your pre-created API-token secret when one is configured.
Cron Backup Workload (optional) — When database backups are enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

None for a default install — install, log in with admin.username / admin.password, and create SDK API tokens in the admin UI. Optionally, the template can seed a backend and a frontend SDK API token on first boot from a dictionary secret that you create before installing. The token strings are never passed through values.

Generate token strings

An Unleash token has the format <project>:<environment>.<secret>. The open-source edition ships the default project and the development and production environments. For example:

echo "default:production.$(openssl rand -hex 24)"

Generate one token string for backend SDKs and one for frontend SDKs.

Create a dictionary secret

Create a dictionary secret in your org with exactly two keys, backend and frontend, each holding a full token string.

Reference it in values

Set apiTokens.secretName to the secret’s name. Leave it empty to skip seeding and create tokens in the admin UI instead.

For optional database backups, you also need a bucket and access setup for one of the supported providers — see Backing Up. Install the template using your preferred method:

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

Choosing a Database Mode

Exactly one of the two database modes must be enabled — the chart enforces this at render and fails the install with a clear message otherwise.

	`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
Footprint	8 replicas across 3 workloads (3× Patroni, 3× etcd, 2× HAProxy)	1 workload
Best for	Production	Development and lightweight installs

A fresh HA-mode install takes roughly 5–7 minutes to fully converge; transient Failed to migrate db log errors while the database cluster starts are expected and self-heal, at any replica count. Single mode is ready in about a minute.

Configuration

The default values.yaml for this template:

image: unleashorg/unleash-server:8.0.3

resources:
  cpu: 1000m
  memory: 1Gi
  minCpu: 250m
  minMemory: 512Mi

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

admin: # initial admin login, seeded on first boot only
  username: admin
  password: change-me-unleash-admin # change before installing

apiTokens:
  secretName: "" # your pre-created dictionary secret (see Prerequisites); empty = create tokens in the UI

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, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

postgresHA: # default: highly available PostgreSQL
  enabled: true
  postgres:
    username: unleash
    password: change-me-unleash-db-password # change before installing
    database: unleash
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    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
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

postgres: # dev/lightweight: single-instance PostgreSQL (disable postgresHA first)
  enabled: false
  config:
    username: unleash
    password: change-me-unleash-db-password # change before installing
    database: unleash
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    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
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

Unleash Instance

image — The Unleash open-source server image.
resources — CPU and memory for the Unleash container.
replicas — Number of Unleash replicas behind the platform load balancer. The server is stateless, so scaling is a single value change; 2+ is recommended for production. At 2 replicas, rolling redeploys and a killed replica were both verified to serve every request with zero failures.
admin.* — The initial admin login, seeded into the database on first boot only. Change admin.password before installing — the upstream default password is rejected once your own is set. Changing these values later does not modify the existing account; change the password in the admin UI instead.
apiTokens.secretName — Name of your pre-created dictionary secret with keys backend and frontend (see Prerequisites). When set, both tokens are seeded on first boot; when empty (default), create tokens in the admin UI after install. Like the admin account, tokens are seeded on first boot only.

Access

publicAccess.enabled — Serve the admin UI and SDK APIs on the canonical *.cpln.app HTTPS endpoint (default). Every surface is authenticated — the UI and Admin API by login, the Client and Frontend APIs by tokens. Set to false for an internal-only instance (external requests are blocked at the edge; in-GVC callers still reach it per internalAccess). The public URL Unleash embeds in password-reset and invite links (UNLEASH_URL) is derived at startup — from the canonical endpoint when public, or the internal cpln.local address when not — and re-derived on every restart.
internalAccess.type — Internal firewall scope of the Unleash workload:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

Database

Enable exactly one of postgresHA (production, default) or postgres (dev/lightweight) — see Choosing a Database Mode. In both modes, change the database password before installing (postgresHA.postgres.password / postgres.config.password). Unleash is wired to the active database automatically — the HAProxy leader endpoint in HA mode, or the single instance directly in dev mode.

Connecting

What	Value
Admin UI / Admin API (public)	`https://<canonical>.cpln.app` — `status.canonicalEndpoint` of `{release}-unleash`
Client API (backend SDKs)	`https://<canonical>.cpln.app/api/client` — `Authorization: <backend token>`
Frontend API (browser/mobile SDKs)	`https://<canonical>.cpln.app/api/frontend` — `Authorization: <frontend token>`
Internal (same GVC)	`http://{release}-unleash.{gvc}.cpln.local:4242`
Login	`admin.username` / `admin.password`
PostgreSQL (internal, HA mode)	`{release}-postgres-ha-proxy.{gvc}.cpln.local:5432`, credentials in the `{release}-postgres-config` secret
PostgreSQL (internal, single mode)	`{release}-postgres.{gvc}.cpln.local:5432`, credentials in the `{release}-pg-config` secret

API Tokens

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

Backend tokens authenticate server-side SDKs against /api/client. Treat them like passwords — they must stay secret.
Frontend tokens authenticate browser and mobile SDKs against /api/frontend. They are designed to be publishable and safe to embed in client code.

A 401 or 403 from an SDK API usually means the wrong token type for the endpoint, or the wrong environment in the token string. Tokens come either from your prerequisite secret (seeded on first boot) or from the admin UI (Admin → API access) at any time.

Backing Up

Database backups are optional and disabled by default. They cover the PostgreSQL database — every flag, strategy, user, and token in your Unleash instance. Enable them with postgresHA.backup.enabled or postgres.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The values below are shown under backup.* — set them within the enabled database block.

AWS S3
Google Cloud Storage
S3-compatible (MinIO, R2, Wasabi)

Create a bucket

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

Set up a Cloud Account

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

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET), then set 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 backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project. Set backup.gcp.cloudAccountName to its name — access is keyless (no stored credentials).

Grant the Storage Admin role

Grant the Storage Admin role to the GCP service account created for the Cloud Account (roles/storage.objectAdmin scoped to the bucket also works).

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint

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

Set credentials

Set backup.minio.accessKey and backup.minio.secretKey to credentials with access to the bucket.

In HA mode, backup.mode selects logical (scheduled pg_dump via a cron workload) or wal-g (continuous WAL archiving). The single-instance mode takes scheduled logical dumps.

Important Notes

Change admin.password and the database password (postgresHA.postgres.password / postgres.config.password) before installing.
Admin credentials and API tokens are seeded on first boot only — they live in the database afterwards; change the password or manage tokens in the admin UI, not by upgrading values.
Backend tokens must stay secret (server-side SDKs, /api/client); frontend tokens are safe to embed in browsers (/api/frontend). A 401 usually means the wrong token type or environment.
The free edition ships exactly two environments (development, production) — SSO, role-based access control, multiple projects, change requests, and audit logs require an Unleash Enterprise license and are not available in this template.
HA-mode first boot takes ~5–7 minutes — transient Failed to migrate db log errors while the database cluster starts are expected and self-heal, at any replica count.
Uninstall deletes the database volume sets — all flags, users, and tokens. Enable backups if the data matters.

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

Scaling Unleash

Upstream guidance on horizontal scaling

Unleash Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

Choosing a Database Mode

Configuration

Unleash Instance

Access

Database

Connecting

API Tokens

Backing Up

Important Notes

External References

Unleash Documentation

Configuring Unleash

API Tokens and Client Keys

SDK Overview

Scaling Unleash

Unleash Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Choosing a Database Mode

​Configuration

​Unleash Instance

​Access

​Database

​Connecting

​API Tokens

​Backing Up

​Important Notes

​External References

Unleash Documentation

Configuring Unleash

API Tokens and Client Keys

SDK Overview

Scaling Unleash

Unleash Template

Overview

Architecture

What Gets Created

Prerequisites

Choosing a Database Mode

Configuration

Unleash Instance

Access

Database

Connecting

API Tokens

Backing Up

Important Notes

External References