CPLN Advisor

Overview

CPLN Advisor watches the workloads in the org it runs in, tracks CPU, memory, replica counts, error rates and billed cost, and turns what it finds into concrete tuning suggestions — memory limits, autoscaling thresholds, replica counts — generated by an LLM. Suggestions appear in a dashboard, and Autopilot can apply the qualifying ones for you, each with a one-click revert. It reports on the org it runs in: Control Plane injects CPLN_ORG into every container, so the advisor knows where it lives without being told. No credential passes through this chart. It creates no credential secret and takes none as a value — it reads two dictionary secrets you create first, and the advisor’s own Control Plane token is entered in the dashboard after install.

What Gets Created

Dashboard Workload (RELEASE_NAME-web) — The Next.js UI on port 3000, a serverless workload scaling 1–3. The only public workload, and the only one holding a session key.
API Workload (RELEASE_NAME-api) — FastAPI backend on port 8000, standard, pinned to one replica. Verifies the login, runs the database migration at startup, and is reachable only by the dashboard.
Worker Workload (RELEASE_NAME-worker) — Runs the scans, applies Autopilot changes, sends the Slack digest. One replica, no inbound traffic.
Scheduler Workload (RELEASE_NAME-scheduler) — Fires the crons that create the scans. One replica, no inbound traffic.
Redis Workload (RELEASE_NAME-redis) — Task broker and cache on port 6379. Not persistent and not authenticated; its firewall admits exactly the API, worker and scheduler.
Bundled Postgres (RELEASE_NAME-postgres plus -pg-vs, -pg-identity, -pg-policy) — The database, from the catalog’s Postgres template pinned at 3.4.1: a stateful workload on its own volume set, with a pg_isready probe and scheduled backups behind a switch. It creates no secret — it reads your database credentials secret.
Identity & Policies (RELEASE_NAME-identity, -policy) — reveal on the secret (the advisor credentials you created).

This template does not create a GVC. It deploys into a GVC you already have — every resource lands in the GVC you install into, so cpln workload exec, cpln logs and uninstalling all work against that GVC, and uninstalling can never delete it. The location you configure must already be a location of that GVC, and a GVC location this release did not ask for starts nothing.

The Single Location Requirement

Install the advisor into a GVC with exactly one location. One location is not a simplification: scale bounds are per-location, so a second location would mean a second scheduler firing every cron twice, a second Redis splitting the task queue, and a second API running the same startup migration.

Prerequisites

A GVC with exactly one location, and two dictionary secrets that exist before you install. The advisor’s own Control Plane token is set in the dashboard after install, not here.

The Advisor Credentials Secret

The keys are the application’s own environment variable names.

DB_PASS="$(openssl rand -hex 32)"

cpln secret create-dictionary --name advisor-config \
  --entry ADVISOR_API_TOKEN="$(openssl rand -hex 32)" \
  --entry ADVISOR_SECRET_KEY="$(openssl rand -hex 32)" \
  --entry ADVISOR_SESSION_SECRET="$(openssl rand -hex 32)" \
  --entry ADVISOR_USERNAME=admin \
  --entry ADVISOR_PASSWORD='YOUR-STRONG-PASSPHRASE' \
  --entry DATABASE_URL="postgresql+asyncpg://advisor:$DB_PASS@RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432/advisor"

Key	What it is
`ADVISOR_API_TOKEN`	Shared between the dashboard and the API. The API fails closed: without it, every route except `/health` returns `401`.
`ADVISOR_SECRET_KEY`	Encrypts the AI and Slack credentials stored in the database. Losing or changing it loses those credentials — unrecoverably, and the app then reports them as “not set” rather than erroring.
`ADVISOR_SESSION_SECRET`	Signs the dashboard session cookie. Rotating it is safe; it signs everyone out.
`ADVISOR_USERNAME` / `ADVISOR_PASSWORD`	The web UI login. A human types the password, so prefer a long passphrase.
`DATABASE_URL`	Must start `postgresql+asyncpg://`, not `postgres://` — SQLAlchemy needs the driver named. The host is `RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`, always fully qualified.

Set auth.secretName in the values file to the name you used.

The Database Credentials Secret

From version 3.4.0 the bundled Postgres template reads its credentials from a secret instead of taking them inline, which is what lets this chart bundle a database and still keep every credential out of values. Exactly three keys:

cpln secret create-dictionary --name advisor-db-credentials \
  --entry username=advisor \
  --entry password="$DB_PASS" \
  --entry database=advisor

Set postgres.config.credentialsSecretName in the values file to the name you used.

These three values must match DATABASE_URL above, and nothing cross-checks them. Helm cannot read secret values at render time, so a mismatch is not a render error — it is an authentication failure at runtime, after everything appears to have installed cleanly. Set DB_PASS once and use it in both commands, as shown.

Secret names are org-wide, so give each release its own pair of secret names.

A Service Account for the Advisor

The advisor’s Control Plane token is deliberately not a value and not in either secret. You set it once in the dashboard after signing in, under Configuration → Control Plane, where it is stored encrypted in the database. Create a service account whose token can, at minimum:

Permission	Why
`gvc: view`	List GVCs and their workloads
`workload: view`	Read specs, deployments and events
`org: readLogs`	Classify errors from workload logs
`org: readMetrics`	CPU, memory, latency and request metrics
`org: readUsage`	Real billed cost per workload rather than an estimate
`workload: edit`	Only to apply or revert a suggestion — it patches and redeploys the workload. Omit it to run the advisor read-only.

Without org: readUsage the scan still succeeds — it logs billing: charges query failed … falling back to the allocation estimate and reports estimated rather than billed cost.

Installation

Create both prerequisite secrets first, then install by whichever method you prefer:

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

The default values.yaml for this template:

# ═══ BEFORE YOU INSTALL ═══════════════════════════════════════════════════════
#
# 1. THE GVC MUST ALREADY EXIST. This template installs into the GVC you select
#    above; it does not create one.
#
#    That GVC must have EXACTLY ONE LOCATION. A workload runs in every location
#    of its GVC, so a second location gives you a second scheduler firing every
#    cron twice, and a second, independent database rather than a replica.
#
# 2. TWO SECRETS MUST ALREADY EXIST. Create both BEFORE installing — if either
#    is missing the deployment fails silently. Nothing sensitive is set in this 
#    file; the chart only ever reads these two secrets by name.
#
#    Use ONE password for the database in both commands — the URL in the first
#    secret must match the credentials in the second, and nothing cross-checks
#    them. A mismatch installs cleanly and fails to authenticate at runtime.
#
#    DB_PASS="$(openssl rand -hex 32)"
#
#    # a) the database's credentials  -> postgres.config.credentialsSecretName
#    cpln secret create-dictionary --name advisor-db-credentials --org YOUR_ORG \
#      --entry username=advisor \
#      --entry password="$DB_PASS" \
#      --entry database=advisor
#
#    # b) the advisor's credentials   -> auth.secretName
#    #    RELEASE below is the Helm release name; GVC is the one you install into.
#    cpln secret create-dictionary --name advisor-config --org YOUR_ORG \
#      --entry ADVISOR_API_TOKEN="$(openssl rand -hex 32)" \
#      --entry ADVISOR_SECRET_KEY="$(openssl rand -hex 32)" \
#      --entry ADVISOR_SESSION_SECRET="$(openssl rand -hex 32)" \
#      --entry ADVISOR_USERNAME=admin \
#      --entry ADVISOR_PASSWORD='YOUR-STRONG-PASSPHRASE' \
#      --entry DATABASE_URL="postgresql+asyncpg://advisor:$DB_PASS@RELEASE-postgres.GVC.cpln.local:5432/advisor"
#
#    Keep ADVISOR_SECRET_KEY somewhere durable: it encrypts the AI and Slack
#    credentials you later enter in the UI, and losing it loses them.
#
# ══════════════════════════════════════════════════════════════════════════════

# ─── Database (subchart: postgres) ────────────────────────────────────────────
postgres:
  config:
    # Secret (a) above. MUST EXIST BEFORE INSTALL.
    credentialsSecretName: advisor-db-credentials

  image: postgres:18 # 17+ is required for backups

  resources:
    minCpu: 150m
    maxCpu: 512m
    minMemory: 256Mi
    maxMemory: 512Mi

  volumeset:
    capacity: 10 # GiB, 10 is the minimum. Volumes never shrink.
    autoscaling:
      enabled: true
      maxCapacity: 50
      minFreePercentage: 20
      scalingFactor: 1.5

  # Who inside the GVC may reach the database. Narrow this if the GVC is shared.
  internalAccess:
    type: same-gvc

  # Connection pooling. The advisor holds few connections, so it is off.
  pgbouncer:
    enabled: false

  # OFF because it needs a bucket and a cloud account you create first.
  # TURN IT ON — a volume is not a backup, and nothing else protects your data.
  # backup.image is COUPLED to image above: 18.1.0 backs up Postgres 18.
  backup:
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *" # daily, 02:00 UTC
    provider: aws # aws, gcp or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: advisor/backups

# ─── Advisor credentials ──────────────────────────────────────────────────────
auth:
  # Secret (b) above. MUST EXIST BEFORE INSTALL.
  secretName: advisor-config

# ─── Images ───────────────────────────────────────────────────────────────────
# The API, worker and scheduler all run the SAME backend image with different
# commands, so they must never drift. Both packages are public — no pull secret.
#
# `:latest` resolves when a workload is DEPLOYED, not continuously. Two installs
# a week apart can differ, and there is nothing to roll back to. Every build also
# publishes a `:sha-<commit>` tag — pin one before you depend on going back.
images:
  backend: ghcr.io/controlplane-com/cpln-advisor/advisor-backend:latest
  web: ghcr.io/controlplane-com/cpln-advisor/advisor-web:latest

# ─── Dashboard URL ────────────────────────────────────────────────────────────
# Leave empty. The app derives its own public URL, and the chart tells it this
# release's dashboard workload name. Set it ONLY for a custom domain, which
# cannot be derived. Never "*" — it is also the CORS allowlist.
appUrl: ""

# ─── Sessions ─────────────────────────────────────────────────────────────────
# Idle windows: how long without activity before you must sign in again.
session:
  hours: 12
  rememberDays: 30

# INFO logs one line per scan. DEBUG is very noisy.
logLevel: INFO

# ─── Workloads ────────────────────────────────────────────────────────────────
# `maxCpu`/`maxMemory` are the limits. `minCpu`/`minMemory` are the floor
# Capacity AI scales from, and are set only where it is enabled.
#
# Where both are set, max:min must stay under 4:1 on cpu — Control Plane rejects
# the workload otherwise. The chart checks this at render time.

# The dashboard. The only workload reachable from the internet.
web:
  replicas:
    min: 1 # 0 scales to zero when idle, at the cost of a cold start
    max: 3
  resources:
    minCpu: 75m
    maxCpu: 250m
    minMemory: 128Mi
    maxMemory: 512Mi

# The API. Internal only; runs the database migration at startup.
api:
  resources:
    minCpu: 75m
    maxCpu: 256m
    minMemory: 128Mi
    maxMemory: 512Mi

# Runs the scans, applies Autopilot changes, sends the Slack digest.
worker:
  resources:
    maxCpu: 100m
    maxMemory: 256Mi

# Fires the crons that CREATE the scans. Without it nothing is ever scanned on a
# schedule, while everything still looks healthy.
scheduler:
  resources:
    minCpu: 25m
    maxCpu: 50m
    minMemory: 64Mi
    maxMemory: 128Mi

# Task broker and cache. Not persistent; not authenticated — its firewall admits
# only the three workloads that use it.
redis:
  image: redis:7-alpine
  resources:
    maxCpu: 50m
    maxMemory: 128Mi
  maxmemory: 100mb # Redis' own cache cap, below maxMemory on purpose

Location

global.cpln.gvc is injected by the platform at install time and is never declared in values. There is no gvc key — the chart refuses to render if it finds one.

Images

The API, worker and scheduler run the same backend image with different commands — a scan is executed by the worker and served by the API, so they must never drift apart. The login name and password are keys in your credentials secret, not values. The login is verified by the API, never by the dashboard, so one workload holds the credentials. There is one account for everyone: change history and activity attribute everything to a single user, and there is no per-person audit trail. session.hours is an idle window that slides forward while you work, under a hard ceiling the app enforces. It is in force, not merely rendered: a session cookie issued at the default setting carried an Expires exactly 12 hours after login. session.rememberDays is the equivalent window with “Keep me signed in” selected.

Access

The dashboard is public and there is no values knob to close it. That is not a toggle because it is not really a choice — the dashboard is the only way into this app, and nothing inside the GVC calls it. What stands between the internet and your fleet is the login:

the session cookie is HMAC-signed with ADVISOR_SESSION_SECRET, so it cannot be forged
both credentials come from a secret you create, so there is no shipped default password to look up

Everything else is closed to the internet, and internal traffic is admitted only from real callers:

Workload	Public	Reachable inside the GVC by
`RELEASE_NAME-web`	yes	nothing — it calls out, never in
`RELEASE_NAME-api`	no	the dashboard only
`RELEASE_NAME-redis`	no	the API, worker and scheduler only
`RELEASE_NAME-worker`, `-scheduler`	no	nothing
`RELEASE_NAME-postgres`	no	anything in the GVC (`same-gvc`) — see Database

To narrow the dashboard to an office or VPN range, edit inboundAllowCIDR on the RELEASE_NAME-web workload after installing. Access changes take roughly 30 seconds to a few minutes to propagate.

Public URL

appUrl is empty by default and should stay that way unless you use a custom domain. The app derives its own public URL from Control Plane’s built-in environment variables as https://{web workload}-{gvc alias}.cpln.app, and the chart passes it this release’s actual dashboard workload name so the derivation resolves to the right workload. Both the Slack “View in Advisor” links and the CORS allowlist come from it. Never set it to *: combined with credentials, a wildcard makes the server echo back whichever origin asked.

Resources

A block that exposes both a floor and a limit names them minCpu/maxCpu and minMemory/maxMemory; a block that exposes only the limit uses the API’s own field names, bare cpu/memory. minCpu and minMemory are the floor Capacity AI scales up from, and only the three tiers that enable it set one. The worker and Redis run with Capacity AI off — a long scan should not be resized underneath itself, and a broker should not be resized under load — so a floor there would be inert. The chart checks two limits at render time, because Control Plane enforces both but publishes neither in a schema, so each would otherwise surface as a 400 partway through an install:

maxCpu/minCpu must be strictly under 4:1, and memory is bounded the same way at 4:1 inclusive.
Unit typos. cpu and memory are bare strings with no numeric bound, so 512Gi written for 512Mi is accepted and the workload then never schedules.

Raising maxCpu or maxMemory on web, api, scheduler or postgres means raising its matching minimum too.

Database

Values under postgres are passed straight through to the bundled Postgres chart, pinned at 3.4.1. Memory is deliberately above that chart’s defaults, because a fleet scan writes in bursts. Three workloads write this database concurrently — the API serves the dashboard, the worker records scan results and Autopilot changes, and the scheduler writes cron state.

postgres.internalAccess: same-gvc is wider than it was in 1.0.0. That version created a dedicated GVC, so same-gvc meant “the advisor and nothing else”. The GVC is now yours and may hold unrelated workloads, any of which can open port 5432 — measured, the dashboard workload reached the database even though it is not a database client.If the GVC is shared, narrow it at install time with the real names. A subchart’s values cannot be templated, so the workload links have to be written out:

--set postgres.internalAccess.type=workload-list \
--set postgres.internalAccess.workloads[0]=//gvc/GVC_NAME/workload/RELEASE_NAME-api \
--set postgres.internalAccess.workloads[1]=//gvc/GVC_NAME/workload/RELEASE_NAME-worker \
--set postgres.internalAccess.workloads[2]=//gvc/GVC_NAME/workload/RELEASE_NAME-scheduler

Add RELEASE_NAME-postgres-backup to that list if you turn backups on.

Backups and Restore

Backups are off by default and you should turn them on. They are off only because they need a bucket and a cloud account you create first — and a volume is not a backup: losing it loses every scan, score and Autopilot record.

postgres:
  backup:
    enabled: true
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *"
    provider: aws            # or gcp, minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: advisor/backups

The bucket, cloud account and IAM policy steps are the Postgres template’s, passed through unchanged — see its backup prerequisites. provider: minio needs its own prerequisite dictionary secret holding accessKey and secretKey.

backup.image is coupled to image. Tag 18.1.0 backs up Postgres 18 and 17.1.0 backs up Postgres 17. Change one and change the other, or pg_dump meets a server it cannot read.

Each run writes one gzipped pg_dumpall plain-SQL file, postgres-<UTC-timestamp>.sql.gz, under <bucket>/<prefix>/. pg_dumpall produces a whole-cluster script including CREATE ROLE and CREATE DATABASE, so it restores into an empty server rather than merging into a running one.

Stop the writers

Scale the API, worker and scheduler to zero, or they will be writing while you restore.

Download the dump

Use your own cloud tooling — the Postgres container has neither aws nor gsutil.

Open a tunnel to the database

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

Load it

gunzip -c postgres-TIMESTAMP.sql.gz | \
  psql -v ON_ERROR_STOP=1 -h 127.0.0.1 -p 5432 -U USERNAME -d postgres

Use psql version 18 or newer, and pass -v ON_ERROR_STOP=1. The chart pins postgres:18, and a PostgreSQL 18 pg_dumpall wraps its output in the \restrict / \unrestrict meta-commands, which older clients do not have. Running the restore with an older client printed 11 error lines — invalid command \restrict, ERROR: role "advisor" already exists — and then exited 0, which is precisely the silently-wrong-restore case. -v ON_ERROR_STOP=1 turns that into a real failure. If you have no matching client locally, run the restore from inside the Postgres container, which already has one.

Connecting

What	Where
Dashboard	`https://<canonical-endpoint>` — always public. Read it from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-web -o yaml`; never hand-build it
API	`http://RELEASE_NAME-api.GVC_NAME.cpln.local:8000` — internal, reachable only from the dashboard. Plain `http` is correct; the sidecar adds mTLS
Database	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432` — internal; credentials come from your database secret

Both internal workloads are also reachable from your machine without opening anything up:

cpln port-forward RELEASE_NAME-api 8123:8000 --gvc GVC_NAME

Use the fully-qualified .cpln.local name for internal access. The short workload name does not resolve reliably from every workload type.

After the First Deploy

Open the dashboard and use the ADVISOR_USERNAME and ADVISOR_PASSWORD from your credentials secret.

Connect Control Plane

Go to Configuration → Control Plane, paste the service account token, and press Test connection. A working connection returns the org and the number of GVCs the token can see. The token round-trips encrypted through the database and reads back masked afterwards.

Add an AI provider, and Slack if you want digests

An Anthropic or OpenAI key, on the same page. These are stored encrypted using ADVISOR_SECRET_KEY — which is why losing that key loses them.

Enroll workloads and scan

Enable Scan on the workloads you want watched, then Scan now.

Diagnosing a Stuck Install

A missing prerequisite secret produces no log output at all. The container never starts, so cpln logs returns zero lines and the deployment simply looks slow.

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

Read status.versions[].message — it names the missing secret. Creating the missing secret repairs the deployment on its own, but slowly. A forced redeployment shortcuts it:

cpln workload force-redeployment RELEASE_NAME-api --gvc GVC_NAME

Important Notes

Install into a single-location GVC.
Create both prerequisite secrets before installing. A missing one wedges the deployment silently; Diagnosing a Stuck Install gives the one command that names it.
DATABASE_URL and the database credentials secret must agree, and nothing cross-checks them. A mismatch installs cleanly and then fails to authenticate at runtime.
Losing ADVISOR_SECRET_KEY loses every credential entered in the UI. They are unrecoverable and must be re-entered. Keep it somewhere durable before you deploy.
The dashboard is public and there is no values knob to close it. The login is the boundary. Narrow inboundAllowCIDR on the RELEASE_NAME-web workload after installing if you want it tighter.
The bundled database admits any workload in your GVC. If the GVC is shared, narrow postgres.internalAccess — see Database.
Backups are off by default and you should turn them on, and restore with a psql of version 18 or newer — see Backups and Restore.
A Postgres password is first-boot only. It is read when the data directory initializes; rotating it in the secret afterwards does not change the running server. You must also change it in Postgres itself and update DATABASE_URL to match.
Rotating any secret requires a forced redeployment. cpln://secret/… references resolve when a replica starts and are never re-resolved while it lives, so a rotated secret keeps working with the old value indefinitely while everything reports healthy.
Redis is not persistent and not authenticated. Everything in it is derived or transient, so a restart at worst skips one scan and repeats one digest. Its firewall admits exactly the three workloads that use it — do not widen it.
Autopilot redeploys your workloads. Each applied suggestion patches a live workload and restarts it. It is per-workload and off until you enable it.
The advisor’s token is as powerful as you make it. Grant workload: edit only if you want Autopilot and one-click apply; without it the advisor runs read-only.
uninstall deletes the database volume set and the scan history with it. It does not delete the GVC — this chart never owns one — and it does not delete your two prerequisite secrets.

External References

CPLN Advisor Template

View the source files, default values, and chart definition

Create a Service Account

Issue the token the advisor uses to read and tune your org

Capacity AI

How resource floors and automatic sizing work on Control Plane

Workload Firewall

Internal and external access controls used by every workload here

Template Catalog

Templates

Overview

What Gets Created

The Single Location Requirement

Prerequisites

The Advisor Credentials Secret

The Database Credentials Secret

A Service Account for the Advisor

Installation

UI

CLI

Terraform

Pulumi

Configuration

Location

Images

Access

Public URL

Resources

Database

Backups and Restore

Connecting

After the First Deploy

Diagnosing a Stuck Install

Important Notes

External References

CPLN Advisor Template

Create a Service Account

Capacity AI

Workload Firewall

​Overview

​What Gets Created

​The Single Location Requirement

​Prerequisites

​The Advisor Credentials Secret

​The Database Credentials Secret

​A Service Account for the Advisor

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Location

​Images

​Login and Sessions

​Access

​Public URL

​Resources

​Database

​Backups and Restore

​Connecting

​After the First Deploy

​Diagnosing a Stuck Install

​Important Notes

​External References

CPLN Advisor Template

Create a Service Account

Capacity AI

Workload Firewall

Overview

What Gets Created

The Single Location Requirement

Prerequisites

The Advisor Credentials Secret

The Database Credentials Secret

A Service Account for the Advisor

Installation

Configuration

Location

Images

Login and Sessions

Access

Public URL

Resources

Database

Backups and Restore

Connecting

After the First Deploy

Diagnosing a Stuck Install

Important Notes

External References