Skip to content
Back to skills

Control Plane Secrets

ASecurity

Upgrade v0.1.45 environments from optional or hand-provisioned telemetry secrets to declared ControlPlaneSecret delivery.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentpythongonode

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill control-plane-secrets --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Control Plane Secrets?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Control Plane Secrets
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-control-plane-secrets/badge)](https://www.skillsdirectory.com/skills/reliant-labs-control-plane-secrets)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: migration-v0.1.45-control-plane-secrets
description: Upgrade v0.1.45 environments from optional or hand-provisioned telemetry secrets to declared ControlPlaneSecret delivery.
relevance: migration
---

# v0.1.45 — control-plane delivered secrets

Use when an env declares a control plane (`control_plane = forge.ControlPlane {}`) that mints and renews a Secret your workloads read, and that Secret is modelled today as an env var with `secret_optional = True` (to dodge the first-deploy block), as a `required_secrets` `ExternalSecret` you then provision by hand, or as a Secret someone mints on a calendar.

### What changed

- New primitive `forge.ControlPlaneSecret` on `Bundle.control_plane_secrets`. It declares a Secret whose value the control plane supplies and renews. It is **recorded in the env shape** (`shape.control_plane_secrets`: name, namespace, cluster, connected cluster, kind, keys; never a value), **never blocks a first deploy**, and is **refused without a connected-cluster binding** (and without `control_plane`). There is no k3d exemption: delivery is the control plane dialing the cluster.
- A cluster workload in the same cluster and namespace as a `telemetry_token` gets, automatically, an **optional** Secret volume `forge-otlp-auth` at `/var/run/secrets/forge/otlp` and `OTEL_EXPORTER_OTLP_HEADERS_FILE=/var/run/secrets/forge/otlp/headers`. `pkg/observe` re-reads that file, so a renewal needs **no restart**.
- `forge.ObservabilityDestination` gained `token_from_control_plane = True`: for a destination that is the control plane's OTLP ingest, forge declares the node agent's `ControlPlaneSecret` (`forge-otlp-token` in `agent.namespace`, key `token`) on every cluster that runs the agent. Exclusive with `headers_secret` / `token_secret`.
- The Secret volume source gained `optional` (an author can set it on a volume of their own). `output.control_plane_secrets[]` is a new render-contract key (empty when none); every `render_contract` golden gained `"control_plane_secrets": []`.

### Steps

1. Delete the workaround. Remove `secret_optional = True` from the `SecretRef` that read the delivered token, and remove the `required_secrets` `ExternalSecret` for it if there is one. Declaring the same Secret as both is refused ("one Secret has one provider").
2. Declare the Secret, on a cluster that names its connected cluster:

   ```python
   control_plane_secrets = [
       forge.ControlPlaneSecret {name = "reliant-otel-auth", cluster = _prod}
   ]
   ```

   `_prod` needs `connected_cluster = "<name>"` (or `connected_clusters = {"<context>": "<name>"}` on the Bundle); register the cluster once with `forge cluster connect <name> --context <ctx> --env <env>`.
3. Drop the env var that carried the headers (`OTEL_EXPORTER_OTLP_HEADERS` from a `SecretRef`). A workload that still sets it, or `OTEL_EXPORTER_OTLP_HEADERS_FILE`, is left alone and gets no volume.
4. For a node agent that exports to the control plane's ingest, replace `headers_secret` / `token_secret` plus the `required_secrets` entry with `token_from_control_plane = True` on the destination.
5. `forge env render <env>`, then `forge env deploy <env> --dry-run`: the preflight no longer asks for the Secret, and the pod spec gains the `forge-otlp-auth` volume (one rolling restart).

### Verify

`forge env shape <env> --json | jq .shape.control_plane_secrets` lists the Secret; a first `forge env deploy` where it does not exist yet passes the preflight.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.