Control Plane

Create a serverless/standard/stateful workload — or a SCHEDULED JOB by setting `type: "cron"`. Define the container(s) in the typed `containers[]` array (the only way — there are no flat image/cpu/port fields) and scaling in the single `autoscaling` block. For a cron workload set `type: "cron"` and a required `schedule` (plus optional job policy); autoscaling/timeoutSeconds/debug do not apply to cron and are rejected. Decide reachability IN THIS CALL: a user-facing service needs `public: true` (or an explicit `firewallConfig`); omitted = deny-by-default, no internet access — do not create closed and patch the firewall afterward. Use the production-grade defaults from get_cpln_rules: explicit readiness + liveness probes, minScale ≥ 2 for user-facing services, CPU/memory sized to the runtime (NOT the platform defaults of 50m / 128Mi), autoscaling metric matched to traffic shape, never scale-to-zero unless the user asked for it by name. Type and name are immutable — changing either = delete + recreate. For databases / caches / queues / brokers / search / gateways / WAF / S3-compatible storage, propose the matching Template Catalog entry first (see get_cpln_rules). Recommended reading before first use: get_cpln_skill("workload") — the runbook for this tool family (read once per session).

create_workload

Create a new identity in a GVC. Provider blocks can provision real resources in the connected cloud account, including AWS IAM roles, GCP service accounts, and Azure managed identities. Optionally seed networkResources (agent-based) and nativeNetworkResources (PrivateLink / PSC). Identities are assigned to workloads via spec.identityLink. Recommended reading before first use: get_cpln_skill("access-control") — the runbook for this tool family (read once per session).

create_identity

Delete one Control Plane resource by `kind` + `name` — the single delete tool for every deletable kind. Secrets are not deletable here — their lifecycle is managed by the user. Deletes on the call (your client confirms the write first). Before calling, read the resource and tell the user what the deletion removes and which dependents break, and proceed only on their explicit approval. Deletion is permanent. Never invent a name.

delete_resource

Increase the storage capacity of a volume in a volumeset. Live operation — no downtime, no data loss. Throttled: expansion is throttled to 4 per volume per rolling 24 hours — an HTTP 429 means the rolling window is exhausted (waiting briefly will NOT help; wait for the oldest expansion to age out). Available for all filesystem types (ext4, xfs, shared). Recommended reading before first use: get_cpln_skill("stateful-storage") — the runbook for this tool family (read once per session).

expand_volumeset

Generate Terraform (HCL) for EXISTING Control Plane resources from a self link. Single resource (`/org/acme/gvc/prod/workload/api`) or bulk by path depth — `/org/acme` exports the whole org, `/org/acme/gvc/prod/workload` exports every workload in a GVC. Set `generateImports` to get ready-to-run `terraform import` commands for adopting the resources into Terraform state, and `includeDependencies` to pull in referenced resources. Secrets are never exported — a ref that targets secrets is refused, and an export that would pull secrets in is refused wholesale. An unsupported kind is rejected with the supported list (list_terraform_kinds, full profile, enumerates them up front). For an in-memory manifest, use convert_to_terraform. Recommended reading: get_cpln_skill("iac-terraform-pulumi").

export_terraform

Returns the Control Plane operating guide — the resource model, how secrets/images/workloads/domains fit together, production-grade defaults, how to verify a change landed, and how to handle failures. Read it once per session before the first create/update/delete, and any time a multi-resource task spans unfamiliar ground.

get_cpln_rules

Show an installed release’s current status, revision, and the Control Plane resources it created (kind, name, link). Returns release metadata only — install values and manifests are never included. Requires the token to have `reveal` permission on the release’s helm bookkeeping secret, where release state is stored.

get_installed_template

Fetch available permissions for a resource kind from the /-schema/permissions endpoint. Recommended reading before first use: get_cpln_skill("access-control") — the runbook for this tool family (read once per session).

get_permissions

Return the exact object schema and REST API endpoints for a Control Plane resource kind, so you can author an accurate manifest for `cpln apply` or call the API directly. ALWAYS call this FIRST whenever you are about to write a cpln apply YAML/JSON file, set up CI/CD that applies Control Plane resources, or build a request body for the REST API — do not hand-write a manifest or guess field names from memory. Pick a `kind` and pass `org` (and `gvc` for workload/identity/volumeset). Large schemas come back as a shallow map with deep sections collapsed to {"_expand":"<path>"} stubs; pass `path` (e.g. "spec.containers") to expand a section on demand. Server-managed fields (id/status/version/etc.) are already removed; `name` and `kind` are required at create.

get_resource_schema

Show a catalog template’s available versions, prerequisites, whether it creates its own GVC, and the EXAMPLE values.yaml for the chosen (or latest) version. Read this before install_template — copy and edit the example values to configure the deployment.

get_template

Fetch one distributed trace by ID (from query_traces) and summarize it: span tree with per-span durations and services, plus an error-span list with status messages. Use it to pinpoint WHERE latency or failures sit inside a request path. Very large traces are truncated to the first spans in tree order — error spans are always listed.

get_trace

Fetch event log for a workload to diagnose readiness/liveness probe issues and errors. Use after a deploy fails — pair with list_deployments and get_workload_logs to triangulate the failure. Recommended reading before first use: get_cpln_skill("workload-troubleshooting") — the runbook for this tool family (read once per session).

get_workload_events

Query workload logs from a GVC. Provide structured params (gvc, workload, container, location, filter) OR a raw LogQL `query` — a raw query REPLACES the structured params, so it must embed ALL labels itself. Available labels: gvc, workload, container, location, provider, replica, stream — replica and stream are only reachable via a raw query. `filter` is a literal substring match (|=), not regex; for regex use a raw query with |~. Cron workload? Get jobExecutions via list_deployments (with `location`), then re-query with a raw query scoping replica= plus the execution's time window — embed gvc/workload/location labels in the raw query. Returns structured JSON with timestamps, messages, and labels. Recommended reading before first use: get_cpln_skill("workload-troubleshooting") — the runbook for this tool family (read once per session).

get_workload_logs

Fetch one asynchronous-operation command by its UUID, to check the status of a long-running operation issued against a workload or volumeset (cron run, replica stop, volume expand / shrink / snapshot / restore / delete). Returns the lifecycleStage, status messages, and full JSON. Pass `kind` (workload|volumeset), `gvc`, `name`, and the `commandId` (discover ids with list_commands).

get_command

Returns the runbook for one Control Plane task family — how to use the feature correctly, the platform constraints that are easy to miss, when it is the WRONG tool, and what to do with the result. Tools that belong to a family name their skill as recommended reading; read it once per session before the first such operation.

get_cpln_skill

Fetch one Control Plane resource by `kind` + `name` (no `name` for kind="org"). Returns a summary plus the full JSON. The single read-one tool for every resource kind. Secrets return metadata only — the API never includes their data. Call this before any update or delete to capture current state.

get_resource

Read a build started by build_image: its status, its progress events, and its log. Statuses are queued and building (still running), pushed (done), and failed. The log comes back automatically when the build failed, since that is where the cause is; pass includeLog to see it otherwise. Read on an interval, never in a tight loop. Recommended reading before first use: get_cpln_skill("image") — the runbook for this tool family (read once per session).

get_image_build

Grant an EXISTING workload access to a secret: ensures the workload has an identity and creates/updates a policy binding with the reveal permission. Never returns secret values. The workload must already exist — for a NEW workload, call create_workload first, then this (a deployment referencing a secret stays paused until access is granted, then resumes). The secret must exist too — if missing, draft its manifest with placeholder values for the user to fill in and apply themselves (setup-secret skill), then re-run. Does NOT modify workload env/volumes — reference the secret there via cpln://secret/<name> in the spec. Recommended reading before first use: get_cpln_skill("setup-secret") — the runbook for this tool family (read once per session).

grant_workload_secret_access

Install a catalog template as a new release. Provide `name` (release name), `template`, optional `version` (defaults to latest), the `values` YAML (from get_template), and `gvc` unless the template creates its own. Validate first where available: preview_template (full profile; same inputs) dry-runs the render and catches values mistakes before anything is created. Deployment is asynchronous — verify with get_installed_template afterwards. Recommended reading before first use: get_cpln_skill("template-catalog") — the runbook for this tool family (read once per session).

install_template

Discover what metrics you can query before calling `query_metrics`, so you never guess a metric name or label. Returns the documented Control Plane default metrics (with type and a correct PromQL template each), PLUS the metrics actually present in the org right now — including CUSTOM metrics your workloads expose and kube_/node_ families. Pass `filter` to narrow by substring. Pass `metric` to see that metric’s REAL label dimensions and values (workload, gvc, location, …) from live data so your PromQL filters are grounded, not invented. Reach for this whenever a metrics query returns nothing or you are unsure of names/labels — it is optional, not required when you already know the metric you want.

list_metrics

List the asynchronous operation commands issued against a workload or volumeset — cron runs and replica stops (workload), or volume expand / shrink / snapshot / restore / delete (volumeset). Each row shows the command id, type, lifecycleStage (pending → running → completed / failed), and message count. Pass `kind` (workload|volumeset), `gvc`, and `name`; optionally filter by `lifecycleStage`. Use get_command for one command’s full status.

list_commands

List the template releases installed in an org (name, template, version, GVC, revision). Use get_installed_template for the resources and status of a specific release.

list_installed_templates

List quotas for an organization (per-org Control Plane resource limits). Each entry includes current usage, max, unit, and any dimensions. Set nearLimit=true to filter to quotas currently using ≥80% of their max — use this as a quick "what is about to break?" check before provisioning. Read-only — to raise a quota, request an increase by pinging Control Plane on Slack or emailing [email protected].

list_quotas

List Control Plane resources of one `kind` as a summary table. The single read-list tool for every resource kind — pass `kind` (e.g. "workload", "secret", "gvc"), `org`, and `gvc` for GVC-scoped kinds. For a single item's full JSON use get_resource. Workload deployments are not a kind here — use list_deployments.

list_resources

A workload's deployments — its per-location rollout status. This is the PRIMARY readiness check after create_workload/update_workload: poll it (without `location`) until ready, then report the canonical endpoint as the public URL — never construct a URL by hand. Without `location`: every location with readiness, endpoints, and the canonical URL. With `location`: that single deployment in full detail — version chain, per-container readiness/restarts/messages, full JSON. For cron workloads, per-execution run history lives in status.jobExecutions of that per-location detail. Pair with get_workload_events and get_workload_logs to diagnose failures.

list_deployments

List the names of the running replicas (pods) of a workload in a location. Read-only operational inventory for confirming which replicas are currently serving. Recommended reading before first use: get_cpln_skill("workload-troubleshooting") — the runbook for this tool family (read once per session).

list_workload_replicas

Attach a volumeset to a workload — mounts into the FIRST container only. Creates the volumeset when missing; size/fileSystemType/performanceClass apply ONLY on that create path and are ignored when the volumeset already exists. Workload-type rule: ext4/xfs (read-write-once) volumesets require a stateful or vm workload and bind to ONE workload; shared-filesystem volumesets mount on any workload type. Workload types are immutable — switching requires deleting and recreating the workload (plan downtime). Recommended reading before first use: get_cpln_skill("stateful-storage") — the runbook for this tool family (read once per session).

mount_volumeset_to_workload

Query the Control Plane audit trail for mutations on one or more resources of the same kind. Omit `name` and `names` to fetch every event for that kind in the org. Supply `names` to audit multiple resources in one call (events are merged and sorted newest-first). Supports filtering by subject, audit context, and time range. Platform events live in the built-in `cpln` context.

query_audit_events

Search distributed traces (Tempo/TraceQL) — find slow or failing requests across workloads, then drill in with get_trace. Provide structured params (gvc, workload, location, errorsOnly, minDuration) OR a raw `traceql` query — a raw query REPLACES the structured params, so it must embed ALL filters itself. Span attributes available: resource.gvc, resource.workload, resource.location. Traces exist only where tracing is enabled on the GVC (`spec.tracing` via update_gvc/create_gvc) and only for sampled requests after enablement. Returns a table of trace IDs with root span, start time, and duration.

query_traces

Run a PromQL query against Control Plane metrics (Prometheus-compatible). Default is a range query over the last hour at 60s step — pass `resolution: "instant"` for a point-in-time query, `since` / `from` / `to` to adjust the window, and `step` to control resolution. Results are sliced to the first 50 series in prose; the full Prometheus response is included as JSON. If you already know the metric, just query it: gauges like `cpu_used`, `mem_used`, `replica_count` are used bare — as are the pre-rated `egress` and `requests_per_second` (never wrap these in rate()); genuine counters need rate(), e.g. `sum by (workload) (rate(container_restarts[5m]))`; latency is a histogram: `histogram_quantile(0.95, sum by (le) (request_duration_ms_bucket))`. Only when you are unsure of the exact metric name or label values — or a query returns no series — call `list_metrics` first to see what is actually present in the org (incl. custom metrics) and a metric’s real labels. Use this to verify autoscaling signals before changing scaling settings — measure first, then change.

query_metrics

Remove a port listener from a domain. Live traffic on that port stops immediately and any routed workloads become unreachable through this domain on that port.

remove_domain_port

Delete a single route entry from a port listener. Traffic that matched this route returns 404 on the affected listener until a new matching route is configured.

remove_domain_route

Search across the Control Plane knowledge base to find relevant information, code examples, API references, and guides. Use this tool when you need to answer questions about Control Plane, find specific documentation, understand how features work, or locate implementation details. The search returns contextual content with titles and direct links to the documentation pages. If you need the full content of a specific page, use the query_docs_filesystem_control_plane tool to `head` or `cat` the page path (append `.mdx` to the path returned from search — e.g. `head -200 /api-reference/create-customer.mdx`). In the default core profile, continue with search_control_plane; query_docs_filesystem_control_plane is available only in the full profile.

search_control_plane

Set or replace the TLS block on a port listener (cipher suites, minimum protocol version). Provide the complete TLS shape; existing TLS settings on this listener are overwritten. Recommended reading before first use: get_cpln_skill("domain") — the runbook for this tool family (read once per session).

set_domain_tls

Uninstall a release and remove the resources it created. Provide the release `name`. Recommended reading before first use: get_cpln_skill("template-catalog") — the runbook for this tool family (read once per session).

uninstall_template

Update a GVC. Scalars, description, tags, env, pullSecretLinks, and placement `addLocations` MERGE with existing values; remove* counterparts (removeLocations, removeTagKeys, removeEnvNames, removePullSecretLinks) take entries away, and remove* flags (removeLocationQuery, removeTracing, removeLoadBalancer, removeKeda, removeSidecarEnvoy, removeAliasWorkloadLink) delete an optional block entirely. The nested objects (loadBalancer, keda, tracing, sidecarEnvoy, locationOptions, locationQuery) are REPLACED wholesale: always submit the complete object, never a partial patch, or the omitted sub-fields are dropped. Custom domains are configured with the Domain resource (create_domain), not on the GVC. Placement and endpoint changes can redeploy workloads or affect public workload availability.

update_gvc

Update metadata (description, tags), top-level spec flags (acceptAllHosts, acceptAllSubdomains), or the GVC/workload binding. CANNOT change ports or routes directly — to add, repoint, or remove a route on an existing domain use add_domain_route / update_domain_route / remove_domain_route for routes, add_domain_port / remove_domain_port for listener ports, and set_domain_tls / clear_domain_tls for TLS (all core); only CORS edits (set_domain_cors / clear_domain_cors) are full profile. After binding gvcLink/workloadLink, re-read status.dnsConfig — bindings add records the user must create. Recommended reading before first use: get_cpln_skill("domain") — the runbook for this tool family (read once per session).

update_domain

Update a policy: metadata (description, tags), target scope (targetAll / targetLinks / removeTargetLinks / targetQuery / removeTargetQuery), and bindings (addBindings merges by permission set; removeBindings strips principals from matching bindings). Optimistic concurrency uses version/id from the current state. Call get_resource (kind="policy") first to capture state.

update_policy

Replace a single route entry on a port listener. Identify the existing route via prefix or regex (whichever it uses); the replacement route needs workloadLink and may omit optional matchers to match /. Returns the full updated domain JSON for inspection. Recommended reading before first use: get_cpln_skill("domain") — the runbook for this tool family (read once per session).

update_domain_route

Update mutable volumeset fields: description, tags, initialCapacity (for newly-provisioned volumes), snapshot policy, autoscaling, mountOptions. snapshots/autoscaling/mountOptions REPLACE the entire stored object — include every field you want to keep. Filesystem type and performance class are IMMUTABLE — to change either, snapshot first and recreate. customEncryption cannot be set here — apply a full manifest with the CLI (`cpln apply`; get_resource_schema kind=volumeset first). Changing initialCapacity does not resize existing volumes; expand_volumeset grows them. Recommended reading before first use: get_cpln_skill("stateful-storage") — the runbook for this tool family (read once per session).

update_volumeset