> ## Documentation Index > Fetch the complete documentation index at: https://controlplanecorporation-majid-docs-content-expansion.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # CPLN Advisor > Deploy CPLN Advisor on Control Plane using the Template Catalog. It scores your workloads from their own metrics, logs and billed cost and turns them into LLM tuning suggestions, with an optional Autopilot. Covers the prerequisite secrets and the single-location rule. ## 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](/guides/create-secret/dictionary) 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-catalog/templates/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. ```bash theme={null} 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: ```bash theme={null} 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](/guides/create-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: Browse, install, and manage templates visually Manage templates from your terminal }> Declare templates in your Terraform configurations Pulumi Icon Streamline Icon: https://streamlinehq.com } > Declare templates in your Pulumi programs ## Configuration The default `values.yaml` for this template: ```yaml theme={null} # ═══ 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-` 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. ### Login and Sessions 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](#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](/reference/workload/capacity) 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](/template-catalog/templates/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: ```bash theme={null} --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. ```yaml theme={null} 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](/guides/create-cloud-account) and IAM policy steps are the Postgres template's, passed through unchanged — see its [backup prerequisites](/template-catalog/templates/postgres#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-.sql.gz`, under `//`. `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. Scale the API, worker and scheduler to zero, or they will be writing while you restore. Use your own cloud tooling — the Postgres container has neither `aws` nor `gsutil`. ```bash theme={null} cpln port-forward RELEASE_NAME-postgres 5432:5432 --gvc GVC_NAME ``` ```bash theme={null} 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://` — 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: ```bash theme={null} 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. 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. 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. 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. ```bash theme={null} 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: ```bash theme={null} 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](#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](#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](#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 View the source files, default values, and chart definition Issue the token the advisor uses to read and tune your org How resource floors and automatic sizing work on Control Plane Internal and external access controls used by every workload here