From e30b3bd88df19c434ed38d9375c24cd88c026618 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Thu, 8 Oct 2026 12:38:23 +0300 Subject: [PATCH 01/12] Name the toolset needed for tools outside core --- CHANGELOG.md | 4 +++ plugins/cpln/rules/cpln-guardrails.md | 2 +- .../cpln/skills/autoscaling-capacity/SKILL.md | 2 +- plugins/cpln/skills/domain/SKILL.md | 2 +- .../skills/environment-promotion/SKILL.md | 2 +- plugins/cpln/skills/gitops-cicd/SKILL.md | 2 +- plugins/cpln/skills/stateful-storage/SKILL.md | 2 +- plugins/cpln/skills/template-catalog/SKILL.md | 4 +-- scripts/check-tool-mentions.mjs | 31 ++++++++++++------- scripts/tools-manifest.json | 10 +++--- 10 files changed, 37 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 636a582..10eced1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this ## [Unreleased] +### Changed + +- Skills say how to reach a tool outside the core profile (`?toolsets=full`), and treat the volume snapshot tools as core. + ## [2.4.4] - 2026-10-01 ### Removed diff --git a/plugins/cpln/rules/cpln-guardrails.md b/plugins/cpln/rules/cpln-guardrails.md index bffc6fa..8a869ce 100644 --- a/plugins/cpln/rules/cpln-guardrails.md +++ b/plugins/cpln/rules/cpln-guardrails.md @@ -28,7 +28,7 @@ The tag `cpln/managedByTerraform: "true"` marks a resource Terraform or Pulumi o - Keep generated values and user-entered values in separate secrets, so none is half filled. - Access needs three things, and a missing one fails silently: an identity on the workload, a policy granting `reveal` (not `view`), and a `cpln://secret/NAME.KEY` reference. `deploy_app` wires all three for its env; `grant_workload_secret_access` sets the identity and policy once the workload exists. - CLI and GitOps users may want a manifest: UPPERCASE placeholders they fill locally, then `cpln apply`. Never apply a file holding a placeholder. On the CLI a value goes in a file, never an inline flag. -- Service-account keys and agent bootstrap configs are shown once, in the Console: `add_key_to_service_account` and `create_agent` (full profile) return the link. +- Service-account keys and agent bootstrap configs are shown once, in the Console: `add_key_to_service_account` and `create_agent` (need `?toolsets=full`) return the link. - Redact passwords, tokens, keys, connection strings, and bearer headers from anything you repeat. ## Targets diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index a8a442b..d102dbd 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -42,7 +42,7 @@ spec: capacityAI: true ``` -- **Per-location overrides:** `spec.localOptions[]` (same fields + `location`) via `mcp__cpln__configure_workload_local_options` (full profile), the only MCP tool that sets `capacityAIUpdateMinutes` or `multiZone`; it replaces the full list. Both also exist on `spec.defaultOptions`, reachable with `cpln apply`. +- **Per-location overrides:** `spec.localOptions[]` (same fields + `location`) via `mcp__cpln__configure_workload_local_options` (needs `?toolsets=full`), the only MCP tool that sets `capacityAIUpdateMinutes` or `multiZone`; it replaces the full list. Both also exist on `spec.defaultOptions`, reachable with `cpln apply`. - **`scaleToZeroDelay` is dual-purpose:** on serverless it is the idle period before scaling to 0; on standard/stateful it sets the **scale-down stabilization window** (default 300s) — scale-up is immediate. ### Multi-metric (standard/stateful) diff --git a/plugins/cpln/skills/domain/SKILL.md b/plugins/cpln/skills/domain/SKILL.md index eb1be3c..cdd9fb1 100644 --- a/plugins/cpln/skills/domain/SKILL.md +++ b/plugins/cpln/skills/domain/SKILL.md @@ -98,7 +98,7 @@ spec: ## Which tool changes what -`create_domain` with `workload` and `gvc` derives the 443 listener, its route, and `cname` mode and returns the DNS records; pass `dnsMode` and `ports` for anything else. After creation, routes, ports, TLS, and CORS (full profile) each have their own tool; `update_domain` never changes ports, `dnsMode`, or `certChallengeType`. Domain names are FQDNs, passed as is. +`create_domain` with `workload` and `gvc` derives the 443 listener, its route, and `cname` mode and returns the DNS records; pass `dnsMode` and `ports` for anything else. After creation, routes, ports, TLS, and CORS each have their own tool (CORS needs `?toolsets=full`); `update_domain` never changes ports, `dnsMode`, or `certChallengeType`. Domain names are FQDNs, passed as is. ## Verify diff --git a/plugins/cpln/skills/environment-promotion/SKILL.md b/plugins/cpln/skills/environment-promotion/SKILL.md index f4a6fe3..65570b6 100644 --- a/plugins/cpln/skills/environment-promotion/SKILL.md +++ b/plugins/cpln/skills/environment-promotion/SKILL.md @@ -45,7 +45,7 @@ CLI-only (no MCP tool) and **still requires a running Docker daemon — `copy` h The target org pulls directly from the source org's registry. Four steps: -1. **Source org — puller credentials**: `mcp__cpln__add_key_to_service_account` (full profile; creates the service account if missing; the key is shown **once**). +1. **Source org — puller credentials**: `mcp__cpln__add_key_to_service_account` (needs `?toolsets=full`; creates the service account if missing; the key is shown **once**). 2. **Source org — grant pull**: `mcp__cpln__create_policy` with `targetKind: image`, `targetAll: true` (or `targetQuery` by repository), `addPermissions: ["pull"]`, `addServiceAccounts: [LINK]` — bindings go in the create call. 3. **Target org — docker secret**: have the user create a `docker` secret with this `dockerConfigJson` — offer a manifest scaffold (`data` is this JSON as one string; `setup-secret` skill); the username is the **literal string ``** (the registry rejects anything else; the password is the service-account key): diff --git a/plugins/cpln/skills/gitops-cicd/SKILL.md b/plugins/cpln/skills/gitops-cicd/SKILL.md index 2b8091a..5f5788b 100644 --- a/plugins/cpln/skills/gitops-cicd/SKILL.md +++ b/plugins/cpln/skills/gitops-cicd/SKILL.md @@ -14,7 +14,7 @@ cpln serviceaccount create --name ci-deployer --org ORG cpln serviceaccount add-key ci-deployer --description "ci key" --org ORG # --description is required ``` -The JSON response's `key` value is the credential — keep it on the user's machine and store it as a masked/secret variable in the CI platform; never paste it into chat. MCP: `mcp__cpln__add_key_to_service_account` (full profile) creates the service account if it is missing and returns a Console link where the user creates the key privately. +The JSON response's `key` value is the credential — keep it on the user's machine and store it as a masked/secret variable in the CI platform; never paste it into chat. MCP: `mcp__cpln__add_key_to_service_account` (needs `?toolsets=full`) creates the service account if it is missing and returns a Console link where the user creates the key privately. Grant least privilege (`access-control` skill): pushing images needs `create` on the `image` kind; `cpln apply` needs create/edit on every kind the manifests contain. `cpln group add-member superusers --serviceaccount ci-deployer` works but grants full org access — prefer a scoped policy (`mcp__cpln__create_policy`). diff --git a/plugins/cpln/skills/stateful-storage/SKILL.md b/plugins/cpln/skills/stateful-storage/SKILL.md index 81fca7d..ddb27d5 100644 --- a/plugins/cpln/skills/stateful-storage/SKILL.md +++ b/plugins/cpln/skills/stateful-storage/SKILL.md @@ -5,7 +5,7 @@ description: "Creates persistent storage for stateful workloads on Control Plane # Stateful Storage & VolumeSets -> **Tool availability:** the snapshot tools, `shrink_volumeset`, and `delete_volumeset_volume` need `?toolsets=full`; reconnect with it or use the CLI. +> **Tool availability:** `delete_volumeset_snapshot`, `shrink_volumeset`, and `delete_volumeset_volume` need `?toolsets=full`; reconnect with it or use the CLI. A **VolumeSet** is GVC-scoped persistent storage for workloads. The `workload` skill covers the basics (stateful type, reserved mount paths, the 15-volume limit, create-then-verify); this skill is the full volume-set detail. The one trap that drives most rework: **`fileSystemType` and `performanceClass` are immutable** (a PATCH that changes either returns HTTP 400) — to change either you must create a new volumeset, and the old data does not carry over. Choose both at creation. diff --git a/plugins/cpln/skills/template-catalog/SKILL.md b/plugins/cpln/skills/template-catalog/SKILL.md index 472d5ab..5ca5ed8 100644 --- a/plugins/cpln/skills/template-catalog/SKILL.md +++ b/plugins/cpln/skills/template-catalog/SKILL.md @@ -54,7 +54,7 @@ This is the choice the catalog can't make for you: ## Configure and upgrade -Reconfigure with `upgrade_template`: pass `name` plus the new `version` and/or `values`. **`values` REPLACES the release's values entirely — there is no reuse-merge** — so start from the current values, never a partial. `template` and `gvc` are immutable and read from the installed release, so you don't pass them. Roll back with `rollback_template` (full profile) or `cpln helm rollback`. +Reconfigure with `upgrade_template`: pass `name` plus the new `version` and/or `values`. **`values` REPLACES the release's values entirely — there is no reuse-merge** — so start from the current values, never a partial. `template` and `gvc` are immutable and read from the installed release, so you don't pass them. Roll back with `rollback_template` (needs `?toolsets=full`) or `cpln helm rollback`. Access scope lives in `values` under a per-template key (`internal_access.type`, `internalAccess.type`, `internalAllowType`, or `firewall.internal_inboundAllowType`), with values `same-gvc` (default), `same-org`, `workload-list` plus a `workloads:` list, and `none` on a few. @@ -90,7 +90,7 @@ Reference `values.yaml` for any template lives in the [templates repo](https://g | Symptom | Cause | Fix | |---|---|---| -| `rollback_template` (full profile) not found | core profile | reconnect `?toolsets=full` or use `cpln helm rollback` | +| `rollback_template` not found | core profile | reconnect `?toolsets=full` or use `cpln helm rollback` | | Upgrade lost settings | `values` replaces, not merges | re-supply full values from `cpln helm get values --all` | | Install failed / release stuck | partial apply, bad values, or unready workloads | inspect `get_installed_template` and `cpln helm history`; fix values and `upgrade_template`, or `uninstall` and reinstall | | Workloads pending after install | image pull / firewall / resources | `diagnose_workload`, then the `workload-troubleshooting` skill | diff --git a/scripts/check-tool-mentions.mjs b/scripts/check-tool-mentions.mjs index 426d6a7..3346d52 100644 --- a/scripts/check-tool-mentions.mjs +++ b/scripts/check-tool-mentions.mjs @@ -7,9 +7,10 @@ * * 1. A mentioned tool must EXIST in the registry — a stale name (a tool that was removed * or renamed) sends the model into a guaranteed-failing call. - * 2. A tool beyond the core tier must be marked on the line ("full profile" / - * "mk8s profile") or the file must carry a "**Tool availability:**" note, so a - * core-profile reader knows to ask the user to reconnect instead of improvising. + * 2. A tool beyond the core tier must be marked on the line with how to reach it + * (`?toolsets=full` / `?toolsets=mk8s`) or the file must carry a "**Tool availability:**" + * note, so a core-profile reader knows to ask the user to reconnect instead of improvising. + * A `name_*` wildcard mentions its whole family and takes the family's highest tier. * 3. `cpln_api_request` is registered only when its kill switch is on, so every mention * needs an availability hedge ("disabled by default", "only when advertised", …). * @@ -34,7 +35,7 @@ const PLUGIN = path.join(ROOT, 'plugins', 'cpln'); const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'tools-manifest.json'), 'utf8')).tools; const TIER = { core: 1, mk8s: 2, full: 3, conditional: 4 }; -const TOKEN_RE = /\b(?:mcp__cpln__)?([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b/g; +const TOKEN_RE = /\b(?:mcp__cpln__)?([a-z][a-z0-9]*(?:_[a-z0-9]+)+)(?:(_\*)|\b)/g; const VERB_PREFIXES = new Set([ 'list', 'get', 'create', 'update', 'delete', 'query', 'reveal', 'export', 'convert', 'install', 'build', 'write', 'uninstall', 'upgrade', 'rollback', 'browse', 'mount', 'configure', 'search', 'preview', 'set', @@ -44,14 +45,20 @@ const VERB_PREFIXES = new Set([ // Snake_case non-tool tokens that share a verb prefix (Prometheus endpoints, spec fields, …). const NOT_TOOLS = new Set(['query_range', 'start_period']); -const FULL_MARKER_RE = /full[- ](profile|toolset)/i; -const MK8S_MARKER_RE = /mk8s[- ](profile|toolset)|toolsets=mk8s/i; +const FULL_MARKER_RE = /toolsets=full/; +const MK8S_MARKER_RE = /toolsets=(?:mk8s|full)/; const API_REQUEST_HEDGE_RE = /disabled by default|only when advertised|if advertised|when advertised|kill switch|if enabled|when enabled/i; const NEGATION_RE = /no `|there is no |no create- or update-/i; const FILE_NOTE_RE = /\*\*Tool availability:\*\*/; const offenders = []; +// The tiers a mention names: the tool itself, or every tool in a `name_*` family. +function tiersNamedBy(token, isWildcard) { + if (!isWildcard) return manifest[token] ? [manifest[token]] : []; + return Object.keys(manifest).filter((name) => name.startsWith(`${token}_`)).map((name) => manifest[name]); +} + function checkFile(filePath) { const text = fs.readFileSync(filePath, 'utf8'); const fileHasNote = FILE_NOTE_RE.test(text); @@ -64,16 +71,18 @@ function checkFile(filePath) { const token = match[1]; if (NOT_TOOLS.has(token)) continue; - const tier = manifest[token]; + const tiers = tiersNamedBy(token, match[2] !== undefined); - if (!tier) { + if (tiers.length === 0) { const looksLikeTool = match[0].startsWith('mcp__cpln__') || VERB_PREFIXES.has(token.split('_')[0]); if (looksLikeTool && !NEGATION_RE.test(line)) { - offenders.push(`${where}: unknown tool "${token}" — ${line.trim().slice(0, 120)}`); + offenders.push(`${where}: unknown tool "${match[0]}" — ${line.trim().slice(0, 120)}`); } continue; } + const tier = tiers.reduce((highest, candidate) => (TIER[candidate] > TIER[highest] ? candidate : highest)); + if (tier === 'conditional') { if (!API_REQUEST_HEDGE_RE.test(line)) { offenders.push(`${where}: "${token}" is registered only when its kill switch is on — add an availability hedge — ${line.trim().slice(0, 120)}`); @@ -85,7 +94,7 @@ function checkFile(filePath) { const marker = tier === 'full' ? FULL_MARKER_RE : MK8S_MARKER_RE; if (!marker.test(line)) { - offenders.push(`${where}: "${token}" (${tier} profile) mentioned without a profile marker or a file-level "**Tool availability:**" note — ${line.trim().slice(0, 120)}`); + offenders.push(`${where}: "${token}" (${tier} profile) mentioned without a ?toolsets= marker or a file-level "**Tool availability:**" note — ${line.trim().slice(0, 120)}`); } } }); @@ -124,7 +133,7 @@ for (const [key, skill] of Object.entries(knowledgeMap.toolSkills ?? {})) { if (offenders.length > 0) { console.error(`✗ ${offenders.length} tool-mention violation(s):\n`); for (const offender of offenders) console.error(` ${offender}`); - console.error('\nFix the mention, add a profile marker / "**Tool availability:**" note, or regenerate scripts/tools-manifest.json if the registry changed.'); + console.error('\nFix the mention, add a ?toolsets= marker / "**Tool availability:**" note, or regenerate scripts/tools-manifest.json if the registry changed.'); process.exit(1); } diff --git a/scripts/tools-manifest.json b/scripts/tools-manifest.json index 64b371f..f7eefef 100644 --- a/scripts/tools-manifest.json +++ b/scripts/tools-manifest.json @@ -38,7 +38,7 @@ "create_secret": "core", "create_service_account": "full", "create_volumeset": "core", - "create_volumeset_snapshot": "full", + "create_volumeset_snapshot": "core", "create_workload": "core", "delete_resource": "core", "delete_volumeset_snapshot": "full", @@ -79,7 +79,7 @@ "list_orgs": "core", "list_quotas": "core", "list_resources": "core", - "list_volumeset_snapshots": "full", + "list_volumeset_snapshots": "core", "list_workload_replicas": "core", "mount_volumeset_to_workload": "core", "plan_app": "core", @@ -95,7 +95,7 @@ "remove_identity_network_resource": "full", "remove_ipset_location": "full", "restart_workload": "core", - "restore_volumeset_snapshot": "full", + "restore_volumeset_snapshot": "core", "rollback_template": "full", "rollback_workload": "core", "rotate_secret": "core", @@ -103,6 +103,8 @@ "set_domain_cors": "full", "set_domain_tls": "core", "shrink_volumeset": "full", + "start_workload_cron": "core", + "stop_workload_replica": "core", "uninstall_template": "core", "update_agent": "full", "update_cloud_account": "full", @@ -118,8 +120,6 @@ "update_volumeset": "core", "update_workload": "core", "upgrade_template": "core", - "workload_start_cron": "core", - "workload_stop_replica": "core", "write_app_files": "core" } } From 3ef5d1c7bc69c41019ed24c0ec331daa16648b1d Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Thu, 8 Oct 2026 15:02:51 +0300 Subject: [PATCH 02/12] Correct stateful Capacity AI limits and note the Terraform default --- plugins/cpln/skills/autoscaling-capacity/SKILL.md | 2 +- plugins/cpln/skills/iac-terraform-pulumi/SKILL.md | 1 + plugins/cpln/skills/workload-troubleshooting/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index d102dbd..d8a3219 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -122,7 +122,7 @@ spec: - Floors and the memory to CPU ratio: `workload` skill. `minCpu` and `minMemory` never exceed `cpu` and `memory`. - **With Capacity AI off:** `cpu`/`memory` are the fixed allocation and `minCpu`/`minMemory` are ignored — except on **stateful**, where `minCpu`/`minMemory` become the static **reserved** request and `cpu`/`memory` stay the burst ceiling. -- **Stateful `minCpu`/`minMemory` are bounded** whether or not Capacity AI is on: max/min ratio ≤ **4** AND gap ≤ **4000m** CPU / **4096Mi** memory. +- **Stateful `minCpu`/`minMemory` are bounded** unless Capacity AI is on in `defaultOptions` and in every `localOptions` entry: max/min ratio ≤ **4** AND gap ≤ **4000m** CPU / **4096Mi** memory. - **GPU:** `nvidia` model `t4` (quantity up to 4) or `a10g` (exactly 1); strict per-model CPU/memory minimums — fetch exact numbers with `mcp__cpln__get_resource_schema` (`kind: workload`). - **Cost:** billing follows reserved resources, so Capacity AI (or stateful `minCpu`) directly lowers cost. diff --git a/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md b/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md index 7c1cd8e..44723a1 100644 --- a/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md +++ b/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md @@ -108,3 +108,4 @@ Each registry page has an Import section with the exact form (composite kinds di | Export refused mentioning plaintext secrets | Narrow the ref/export to exclude secrets — secret export is not supported | | Org create or `auth_config` update fails despite a valid token | Those two operations require `CPLN_REFRESH_TOKEN` | | Pulumi lacks a feature the Terraform provider just shipped | The bridge tracks Terraform provider releases — upgrade the `@pulumiverse/cpln` package version | +| A stateful workload from Terraform or Pulumi runs with Capacity AI on | `capacity_ai` (Pulumi `capacityAi`) defaults to `true` in every `options` and `local_options` block on every workload type; set it to `false` to keep it off | diff --git a/plugins/cpln/skills/workload-troubleshooting/SKILL.md b/plugins/cpln/skills/workload-troubleshooting/SKILL.md index 82e8dce..c2a2b14 100644 --- a/plugins/cpln/skills/workload-troubleshooting/SKILL.md +++ b/plugins/cpln/skills/workload-troubleshooting/SKILL.md @@ -53,7 +53,7 @@ Serverless gets TCP readiness and liveness on the container port; standard, stat - CPU and memory must fit the org quota; `maxScale` times the per-replica resources is enforced at scheduling. - Capacity AI is off with the `cpu` metric or multi-metric scaling; check the stored `spec.defaultOptions.capacityAI` first. On cron a new reservation lands at the next run. -- Stateful sizing: `minCpu` to `cpu` at most 4 to 1 and 4000m apart; `minMemory` to `memory` at most 4 to 1 and 4096Mi apart. +- Stateful sizing, unless Capacity AI is on in `defaultOptions` and in every `localOptions` entry: `minCpu` to `cpu` at most 4 to 1 and 4000m apart; `minMemory` to `memory` at most 4 to 1 and 4096Mi apart. - Ephemeral storage is 1 GB per CPU core, at least 1 GB; exceeding it replaces the replica. ### Container will not start From 74f853a1804d9ad0547ca5c75e64feff2705bce4 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Thu, 8 Oct 2026 18:31:34 +0300 Subject: [PATCH 03/12] Rewrite the Template Catalog skill around template search --- CHANGELOG.md | 11 ++++ plugins/cpln/skills/template-catalog/SKILL.md | 52 +++++-------------- 2 files changed, 25 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10eced1..e68e734 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this ## [Unreleased] +### Added + +- The IaC skill says Terraform and Pulumi default `capacity_ai` to `true` on every workload type, stateful included. + ### Changed - Skills say how to reach a tool outside the core profile (`?toolsets=full`), and treat the volume snapshot tools as core. +- The Template Catalog skill finds a template with `browse_templates` and `query` (the user's need in their own words) and reads its prerequisites, the template to pick instead, and its README notes from the tools, replacing the table of common asks and the per-template secret keys. It covers any self-hosted component or product, and leaves an app the user asks to build to the `create-app` skill. +- The Template Catalog skill searches for the capability a goal needs when the user describes a goal rather than a component, and keeps `add_database` the default for the five databases, using the install steps only for a setting it does not take, such as backups. + +### Fixed + +- The stateful `minCpu`/`minMemory` ratio and gap limits apply only while Capacity AI is off in `defaultOptions` or in a `localOptions` entry. +- The Template Catalog skill no longer says `cockroach`, `tidb`, `nats`, `clickhouse`, `airflow`, `mongodb-cluster`, `redis-multi-location`, and `pgedge` create their own GVC; their current versions install into an existing GVC that already has every location their `locations` value lists. ## [2.4.4] - 2026-10-01 diff --git a/plugins/cpln/skills/template-catalog/SKILL.md b/plugins/cpln/skills/template-catalog/SKILL.md index 5ca5ed8..065b51f 100644 --- a/plugins/cpln/skills/template-catalog/SKILL.md +++ b/plugins/cpln/skills/template-catalog/SKILL.md @@ -1,55 +1,31 @@ --- name: template-catalog -description: "Recommends and installs templates from the Control Plane Template Catalog. Use when the user wants postgres, redis, kafka, mongodb, mysql, or any database, cache, queue, or gateway, or asks what templates exist." +description: "Recommends and installs templates from the Control Plane Template Catalog. Use when the user wants a self-hosted component or product: a database, cache, queue, search engine, object storage, gateway, AI tool, analytics, auth, security, automation, observability, or developer tool, a self-hosted replacement for a product they name, or asks what templates exist." --- # Template Catalog -Production-tested charts (Helm under the hood) for databases, caches, queues, brokers, search, and gateways, with storage, firewall, and HA variants wired. A catalog template is the default for any common component; a custom workload needs a hard reason, such as an extension or image the template cannot take. +Production-tested charts (Helm under the hood) for databases, caches, queues, search, storage, AI tools, analytics, auth, security, automation, observability, developer tools, and gateways, with storage, firewall, and HA variants wired. A catalog template is the default for any common component; a custom workload needs a hard reason, such as an extension or image the template cannot take. An app the user asks you to build, such as a blog, a wiki, or a shop, is written (`create-app` skill), not replaced by a template; install one for it only when the user names it. -**Postgres, MySQL, MariaDB, MongoDB, or Redis: `add_database`,** not the steps below. Calling it again with a new `allowWorkloads` changes who can connect by reapplying the installed template: the password, version, and storage stay as installed, but changes made outside its values, such as volume snapshot settings, are reset. Tell the user that before reapplying. The HA and multi-location variants (`postgres-highly-available`, `mongodb-cluster`, and the rest) go through the install steps. - -## Credentials: create the prerequisite secret first - -- Most templates name a secret in their `values` that **must exist before the install**: `postgres`, `mongodb`, and `pgvector` read `config.credentialsSecretName` (a `dictionary` with `username`, `password`, and `database`); `mysql` and `mariadb` read `credentialsSecretName` (the same three keys) and `rootPasswordSecretName` (an `opaque` secret). The `get_template` example values mark each one. -- A missing secret does not fail the install: the release installs and the workload **wedges silently**, with no logs. -- `values` key names differ per template (secret names, resources, access scope): copy them from `get_template`, never from memory. -- Create it with `create_secret` before installing: `values: "generate"` for passwords nobody needs to know, `values: "user"` for a key the user already has (they type it into the Console). Then put its name in `values`. -- Never write a password or key into `values`: values pass through the chat and are stored in the release. A template that still takes a secret value directly in `values` is installed from the Console, or with `cpln helm install -f` and a values file the user fills in locally. +**Postgres, MySQL, MariaDB, MongoDB, or Redis: `add_database` by default.** In one call it generates the credentials, lets the listed workloads connect, and waits until the database is ready. Use the install steps below for these only when the user needs a setting `add_database` does not take, such as backups, a connection pooler, an admin UI, or custom resources, creating the credentials secret with `create_secret` first. Calling `add_database` again with a new `allowWorkloads` changes who can connect by reapplying the installed template: the password, version, and storage stay as installed, but changes made outside its values, such as volume snapshot settings, are reset. Tell the user that before reapplying. The HA and multi-location variants (`postgres-highly-available`, `mongodb-cluster`, and the rest) go through the install steps. ## Find the right template -`browse_templates` returns the **live catalog** — name, category, latest version, a "creates its own GVC" flag, and description. It is the source of truth for what exists; the table below is only the common asks. Filter with a substring (e.g. `postgres`), then call `get_template ` for the version list, prerequisites, and an example `values.yaml` to copy. +Call `browse_templates` with `query` naming the capability or product needed. When the user describes a goal or a problem rather than a component ("my site is slow", "users should sign in with Google"), decide the capability it needs and search for that ("cache for database queries", "identity provider with Google login"); a goal searched in the user's own words ranks poorly. Recommend the result with what it does and why it fits. Take the first result unless its confidence is low or one of its `pickInsteadIf` needs matches the user; then use the template that entry names. A low-confidence first result is a guess: search again naming the capability, or ask the user about their goal. Each result also names its `variants` (the same software in other topologies), `related` templates (a `companion` is often installed alongside), and `includes` (bundled templates that install with it, never separately). Without `query`, `browse_templates` lists the catalog and its categories, or one `category`. -| Need | Templates | -|---|---| -| PostgreSQL | `postgres` (single + backup), `postgres-highly-available` (Patroni failover), `pgedge` (active-active multi-master), `postgis` (geospatial) | -| MySQL-compatible | `mysql`, `mariadb`, `tidb` (distributed) | -| Distributed SQL | `cockroach`, `tidb` | -| Document / NoSQL | `mongodb` (single), `mongodb-cluster` (replica set), `cassandra` | -| Analytics / columnar | `clickhouse` | -| Cache / KV | `redis` (replica + Sentinel), `redis-cluster` (sharded), `redis-multi-location` (cross-GVC), `etcd` | -| Streaming / queues | `kafka`, `redpanda`, `rabbitmq`, `nats`, `cpln-task-runner` | -| Search / vector | `manticore`, `opensearch`, `elasticsearch`, `weaviate` | -| Gateway / WAF / VPN | `nginx`, `tyk`, `coraza`, `tailscale` | -| Storage / AI / LLM | `minio` (S3), `ollama`, `langfuse` | -| Auth / dev / ops | `fusionauth`, `dbeaver`, `airflow`, `ess`, `secret-env-var-syncer`, `otel-collector` | - -## Choosing an HA / scaling variant - -This is the choice the catalog can't make for you: +## Credentials: create the prerequisite secret first -- **Postgres:** `postgres` is one instance with optional scheduled S3/GCS backups; `postgres-highly-available` adds Patroni leader election and an embedded etcd quorum (odd member count — 3/5/7) plus its own scheduled backups (logical or WAL-G mode); `pgedge` is active-active multi-master across regions. Pick HA when failover matters, pgEdge when you need multi-region writes. -- **MongoDB:** `mongodb` is single; `mongodb-cluster` is a replica set and creates its own GVC. -- **Redis:** `redis` (master-replica + Sentinel) for one location; `redis-cluster` (sharded, needs 6+ nodes) for horizontal scale; `redis-multi-location` (Valkey + Sentinel) for cross-location failover. -- **Distributed SQL:** `cockroach` and `tidb` are natively distributed — HA is built in through their consensus protocols, and they create their own multi-location GVCs. -- **Streaming:** `kafka` for the full Kafka ecosystem; `redpanda` is Kafka-API-compatible with a simpler single-binary footprint. +- Every search result and `get_template` list the template's prerequisites. A required secret comes with its `secretType`, its `keys`, and the `valuesPath` that takes its name; an optional one names the values that turn it on (`when`). +- A missing secret does not fail the install: the release installs and the workload **wedges silently**, with no logs. So `install_template` and `upgrade_template` refuse, creating nothing, while the release would read a required secret that does not exist or has another type (they render it to confirm the read). A secret named inside a list, such as a list of users, is not checked. +- `values` key names differ per template (secret names, resources, access scope): copy them from `get_template`, never from memory. +- Create it with `create_secret` before installing: `values: "generate"` for passwords nobody needs to know, `values: "user"` for a key the user already has (they type it into the Console). Then put its name in `values`. +- Never write a password or key into `values`: values pass through the chat and are stored in the release. A template that still takes a secret value directly in `values` (`get_template` says when its example values do) is installed from the Console, or with `cpln helm install -f` and a values file the user fills in locally. ## Install (MCP) -1. `get_template `: copy the example `values.yaml`; set the prerequisite secret names, replica count, resources, storage size, and access scope. -2. `install_template` with `dryRun: true`: renders the resources the install would create, without applying anything. -3. `install_template` with a unique release `name` (immutable) and the `values` YAML (at most 128 KiB). **Omit `gvc` for templates that create their own** (the `createsGvc` flag: `cockroach`, `tidb`, `nats`, `clickhouse`, `airflow`, `mongodb-cluster`, `redis-multi-location`, `pgedge`); every other template needs an existing `gvc`. +1. `get_template `: copy the example `values.yaml`; set the prerequisite secret names, replica count, resources, storage size, and access scope. It also returns the README's important notes. When a prerequisite has a `when` condition or the values are unclear, read the README's prerequisites with `get_template` and `readmeSection: "prerequisites"`; a README without that section answers with the sections it has. +2. `install_template` with `dryRun: true`: renders the resources the install would create, without applying anything, and lists in `missingSecrets` the required secrets the release reads that are still missing. +3. `install_template` with a unique release `name` (immutable) and the `values` YAML (at most 128 KiB). **Omit `gvc` only for a template that creates its own** (`createsGvc` in the search result and `get_template`); every other template needs an existing `gvc`, and a multi-location template's `locations` must be locations that GVC already has. 4. Installs are asynchronous: wait with `get_installed_template` and `waitSeconds`. Its token needs `reveal` on the release's state secret. ## Configure and upgrade @@ -84,7 +60,7 @@ Reference `values.yaml` for any template lives in the [templates repo](https://g ## Connection details and backups - An installed service is reachable in its GVC at `-..cpln.local:`, for example `my-pg-postgres..cpln.local:5432`; the exact names are in the `get_installed_template` resources. Workloads read the credentials as `cpln://secret/NAME.KEY` from the prerequisite secret. -- Backups (`postgres`, `mongodb`) need a cloud account and a storage IAM policy first, referenced in the `values` backup block. +- Backups need the optional prerequisites `get_template` lists for them, such as a bucket, a cloud account, and on AWS a bucket-scoped IAM policy, referenced in the `values` backup block. ## Troubleshooting From 6d1832d8f6dc171c84786af87b2510349682c121 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Wed, 14 Oct 2026 17:37:39 +0300 Subject: [PATCH 04/12] Follow the MCP core cut to 45 tools and move the operating guide into a skill --- CHANGELOG.md | 31 ++++++- CLAUDE.md | 8 +- README.md | 2 +- plugins/cpln/agents/k8s-migrator.md | 6 +- .../cpln/agents/workload-troubleshooter.md | 6 +- plugins/cpln/knowledge-map.json | 17 +--- plugins/cpln/rules/cpln-core.md | 2 +- plugins/cpln/skills/access-control/SKILL.md | 6 +- plugins/cpln/skills/audit-compliance/SKILL.md | 2 +- .../cpln/skills/autoscaling-capacity/SKILL.md | 6 +- .../cpln/skills/cdn-rate-limiting/SKILL.md | 2 +- plugins/cpln/skills/cpln/SKILL.md | 12 +-- plugins/cpln/skills/domain/SKILL.md | 3 +- .../skills/environment-promotion/SKILL.md | 8 +- .../cpln/skills/firewall-networking/SKILL.md | 2 +- plugins/cpln/skills/gitops-cicd/SKILL.md | 6 +- .../cpln/skills/iac-terraform-pulumi/SKILL.md | 10 +-- plugins/cpln/skills/image/SKILL.md | 2 +- plugins/cpln/skills/k8s-operator/SKILL.md | 2 +- .../cpln/skills/logql-observability/SKILL.md | 4 +- .../skills/metrics-observability/SKILL.md | 16 ++-- .../cpln/skills/migration-patterns/SKILL.md | 4 +- plugins/cpln/skills/mk8s-byok/SKILL.md | 10 +-- .../cpln/skills/native-networking/SKILL.md | 2 +- .../operating-guide/SKILL.md} | 10 +-- plugins/cpln/skills/org-management/SKILL.md | 4 +- plugins/cpln/skills/setup-agent/SKILL.md | 2 +- .../cpln/skills/setup-cloud-access/SKILL.md | 4 +- plugins/cpln/skills/setup-secret/SKILL.md | 9 +- plugins/cpln/skills/stateful-storage/SKILL.md | 14 ++-- plugins/cpln/skills/tag/SKILL.md | 2 +- plugins/cpln/skills/template-catalog/SKILL.md | 14 ++-- .../cpln/skills/workload-security/SKILL.md | 2 +- .../skills/workload-troubleshooting/SKILL.md | 8 +- plugins/cpln/skills/workload/SKILL.md | 10 +-- scripts/check-tool-mentions.mjs | 32 ++++--- scripts/tools-manifest.json | 84 ++++++++++--------- 37 files changed, 194 insertions(+), 170 deletions(-) rename plugins/cpln/{rules/cpln-guardrails.md => skills/operating-guide/SKILL.md} (87%) diff --git a/CHANGELOG.md b/CHANGELOG.md index e68e734..53f7702 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,19 +8,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this ### Added +- `run_volumeset_command` runs one volume set command (expand, shrink, snapshot, restore, or delete) and returns its command id for `get_command`, as `start_workload_cron` now does. +- `request_quota_increase` asks Control Plane to raise an org quota; every quota error names it, with the quota and, for a per-GVC quota, the GVC. +- `grant_workload_secret_access` takes `remove: true` to revoke one secret from a workload, keeping its identity. +- `list_deployments` names each location's running replicas, the `--replica` value the `cpln` workload commands take. +- Routes in `create_domain` and `update_domain` take the same fields: `canaries` split a route's traffic by weight, and `create_domain` routes take `mirror` too. +- `update_domain` switches `certChallengeType`, for example to `dns01` when a CDN or WAF blocks `http01`; `.internal` domains refuse it. +- `create_domain` and `update_domain` warn when a route sends clients to a workload that admits no external traffic, which the domain answers with 403. - The IaC skill says Terraform and Pulumi default `capacity_ai` to `true` on every workload type, stateful included. ### Changed -- Skills say how to reach a tool outside the core profile (`?toolsets=full`), and treat the volume snapshot tools as core. +- The default `core` profile advertises 45 tools instead of 71: tools fold into the tool that covers their family (see Removed). +- Tools few tasks need move from `core` to `full`: policies, identities, permissions, quota lists, promotion, events, replica and command lists, volume set creation, and the docs filesystem; the read tools among them stay on `readonly`. +- `workload_start_cron` and `workload_stop_replica` are renamed `start_workload_cron` and `stop_workload_replica`. +- `create_gvc` and `update_gvc` are titled "Create a GVC" and "Update a GVC". +- `promote_workload` creates or updates each mounted volume set in the target GVC with the source's settings, never copying data, and points firewall links at the target GVC's workloads. +- Skills say how to reach a tool outside the core profile (`?toolsets=full`). - The Template Catalog skill finds a template with `browse_templates` and `query` (the user's need in their own words) and reads its prerequisites, the template to pick instead, and its README notes from the tools, replacing the table of common asks and the per-template secret keys. It covers any self-hosted component or product, and leaves an app the user asks to build to the `create-app` skill. - The Template Catalog skill searches for the capability a goal needs when the user describes a goal rather than a component, and keeps `add_database` the default for the five databases, using the install steps only for a setting it does not take, such as backups. ### Fixed +- `update_workload` `public: false` now closes the workload to the internet, and `public: true` opens it without replacing its other firewall rules. +- `rollback_workload` finds the previous image even after a rollout has finished, from the last 30 days of changes. +- Quota rejections (HTTP 429) are not retried, and their errors carry the quota hint instead of the rate limit hint. +- An update that loses a write race with another change (HTTP 409 "Conflict: resource was changed") is retried once instead of failing with an "already exists" hint. +- Volume command refusals say what blocks them and what to do next. +- `grant_workload_secret_access`, `deploy_app`, and `promote_workload` check the secrets and the policy they need before writing anything, so a refusal leaves nothing half done. +- Logs, metrics, traces, and audit events are always read from the environment the request targets. +- Skills and agents now match the tools wherever they described a field or behavior wrongly, for example that shrinking a volume keeps its data. - The stateful `minCpu`/`minMemory` ratio and gap limits apply only while Capacity AI is off in `defaultOptions` or in a `localOptions` entry. - The Template Catalog skill no longer says `cockroach`, `tidb`, `nats`, `clickhouse`, `airflow`, `mongodb-cluster`, `redis-multi-location`, and `pgedge` create their own GVC; their current versions install into an existing GVC that already has every location their `locations` value lists. +### Removed + +- `get_cpln_rules` (now the `operating-guide` skill: plugin hosts load it, and MCP-only clients read it with `get_cpln_skill`). +- `add_domain_route`, `update_domain_route`, `remove_domain_route`, `add_domain_port`, `remove_domain_port`, `set_domain_tls`, `clear_domain_tls`, `set_domain_cors`, and `clear_domain_cors` (now `update_domain` with `addPorts`, `removePorts`, `addRoutes`, `removeRoutes`, `removeTls`, and `removeCors`, applied in one write). +- `expand_volumeset`, `shrink_volumeset`, `create_volumeset_snapshot`, `restore_volumeset_snapshot`, `delete_volumeset_snapshot`, and `delete_volumeset_volume` (now `run_volumeset_command`). +- `get_resource_schema` (now `get_resource` with `schema: true`), `list_volumeset_snapshots` (now `get_resource` on a volume set), `get_template` (now `browse_templates` with `name`), and `list_installed_templates` (now `get_installed_template` without `name`). +- `get_trace` (now `query_traces` with `traceId`), `list_metrics` (now `query_metrics` without `query`), and `convert_to_terraform` (now `export_terraform` with `manifest`, which refuses secrets as an export does). +- `cpln_api_request`, the raw API tool that was off by default; the `cpln` CLI covers what the tools do not. + ## [2.4.4] - 2026-10-01 ### Removed diff --git a/CLAUDE.md b/CLAUDE.md index 9f0e367..2b182cb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,17 +12,17 @@ End-user install and capability docs live in `README.md`. Development principles | `plugins/cpln/skills//SKILL.md` | One domain skill per folder. Companion files (`*.md`) load on demand. | | `plugins/cpln/agents/.md` | One self-contained guided workflow per file. | | `plugins/cpln/commands/.md` | Slash command for Claude / Codex / Cursor. | -| `plugins/cpln/rules/*.md` | `cpln-core.md` (`alwaysApply: true`) is the short core rule set: the `SessionStart` hook in `plugins/cpln/hooks/hooks.json` injects it (Claude / Codex), Cursor loads it in every chat, and the MCP server sends it in its handshake. `cpln-guardrails.md` (`alwaysApply: false`) is the operating guide, read on demand: Cursor applies it by its description and the MCP server serves it through `get_cpln_rules`. Antigravity has no SessionStart hook and does not load a plugin `rules/` dir (its rules live in `AGENTS.md`), so it gets the core through the MCP handshake. | +| `plugins/cpln/rules/*.md` | `cpln-core.md` (`alwaysApply: true`) is the short core rule set: the `SessionStart` hook in `plugins/cpln/hooks/hooks.json` injects it (Claude / Codex), Cursor loads it in every chat, and the MCP server sends it in its handshake. The operating guide is the `operating-guide` skill, read on demand: plugin hosts load it as a skill, and the MCP server serves it to MCP-only clients through `get_cpln_skill`. Antigravity has no SessionStart hook and does not load a plugin `rules/` dir (its rules live in `AGENTS.md`), so it gets the core through the MCP handshake. | | `plugins/cpln/.claude-plugin/plugin.json` | Claude plugin manifest. | | `plugins/cpln/.codex-plugin/plugin.json` + `mcp.json` | Codex manifest and MCP config. | | `plugins/cpln/.cursor-plugin/plugin.json` + `mcp.json` | Cursor manifest and MCP config. | -| `plugins/cpln/plugin.json` + `mcp_config.json` | Native Antigravity CLI (`agy`) manifest and MCP config (remote server uses `serverUrl`, not `httpUrl`). Antigravity has no `SessionStart` hook event (its hooks are PreToolUse/PostToolUse/PreInvocation/PostInvocation/Stop), so the core rules reach it through the MCP handshake and the operating guide through `get_cpln_rules`, not a hook. `agy plugin validate ./plugins/cpln` gates it; install with `agy plugin install https://github.com/controlplane-com/ai-plugin/plugins/cpln`. | +| `plugins/cpln/plugin.json` + `mcp_config.json` | Native Antigravity CLI (`agy`) manifest and MCP config (remote server uses `serverUrl`, not `httpUrl`). Antigravity has no `SessionStart` hook event (its hooks are PreToolUse/PostToolUse/PreInvocation/PostInvocation/Stop), so the core rules reach it through the MCP handshake and the operating guide as the `operating-guide` skill, not a hook. `agy plugin validate ./plugins/cpln` gates it; install with `agy plugin install https://github.com/controlplane-com/ai-plugin/plugins/cpln`. | | `plugins/cpln/.claude-mcp.json` | Claude MCP config. | | `.claude-plugin/marketplace.json` | Claude marketplace entry. Source: `"./plugins/cpln"`. | | `.agents/plugins/marketplace.json` | Codex marketplace entry. | | `.cursor-plugin/marketplace.json` | Cursor marketplace entry. | -Each per-client MCP config points at the hosted server with a profile chosen for that client. Claude Code (`.claude-mcp.json`) and Cursor (`.cursor-plugin/mcp.json`) use `https://mcp.cpln.io/mcp?toolsets=full&skills=plugin`, because both load tools on demand. Codex (`.mcp.json`) and Antigravity (`plugins/cpln/mcp_config.json`) use `https://mcp.cpln.io/mcp?toolsets=core&skills=plugin`, because Codex sends every tool on models without tool search. `skills=plugin` tells the server the plugin supplies the skills, so it does not advertise `get_cpln_skill`; the MCP handshake still carries the core rules for every client, since Antigravity loads no plugin rules and Codex runs the rules hook only when `plugin_hooks` is on. Keep them in sync when changing URL or auth shape. The remote-URL field name differs per client: Claude/Codex/Cursor/generic use `url`, Antigravity uses `serverUrl`. +Each per-client MCP config points at the hosted server with a profile chosen for that client. Claude Code (`.claude-mcp.json`) and Cursor (`.cursor-plugin/mcp.json`) use `https://mcp.cpln.io/mcp?toolsets=full&skills=plugin`, because both load tools on demand. Codex (`.mcp.json`) and Antigravity (`plugins/cpln/mcp_config.json`) use `https://mcp.cpln.io/mcp?toolsets=core&skills=plugin`, because Codex sends every tool on models without tool search. `skills=plugin` tells the server the plugin supplies the skills, so it does not advertise `get_cpln_skill`; the MCP handshake still carries the core rules for every client, since Antigravity loads no plugin rules and Codex runs the rules hook only once the user has reviewed and trusted the plugin's hooks. Keep them in sync when changing URL or auth shape. The remote-URL field name differs per client: Claude/Codex/Cursor/generic use `url`, Antigravity uses `serverUrl`. ## Plugin id vs display name @@ -93,6 +93,8 @@ Codex has no CLI validator; install the plugin and check `~/.codex/log/codex-tui The server validates entries on load and drops any that reference an unknown skill or tool. +The server knows the fetched map's skills plus those of the map bundled in its build, so a skill removed here stays listed and served (from the bundled copy) until the server is redeployed without it. + ## Versioning Work lands on `develop`, which the test MCP server reads; `main` is the released line that installs and the production MCP server read. A release is `scripts/bump-version.sh ` run on `develop`: it updates every plugin manifest and the marketplace entries in lockstep, promotes the CHANGELOG `[Unreleased]` block, commits, tags, and pushes `develop`, `main`, and the tag together. Don't edit version strings by hand. Details: `CONTRIBUTING.md`. diff --git a/README.md b/README.md index 318b9e5..c103f1c 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ Two workflows also have slash commands in Claude Code — `/cpln:troubleshoot WO - Domain skills across CLI usage, access control, autoscaling, networking, observability, migration, templates, stateful storage, and security. - Two guided agents: workload troubleshooting and Kubernetes / Compose / Helm migration. -- A short always-on rule set the assistant applies in every session, with the full operating guide read on demand. +- A short always-on rule set the assistant applies in every session, with the full operating guide as a skill read on demand. - Pre-configured access to the hosted Control Plane MCP server. ## Security diff --git a/plugins/cpln/agents/k8s-migrator.md b/plugins/cpln/agents/k8s-migrator.md index 10e757c..c0c98ab 100644 --- a/plugins/cpln/agents/k8s-migrator.md +++ b/plugins/cpln/agents/k8s-migrator.md @@ -11,7 +11,7 @@ You are the Control Plane migration operator. A user — or the `/cpln:migrate-k ## Load your reference first -Before anything else, call `mcp__cpln__get_cpln_skill` for **migration-patterns**. It is the canonical, source-validated reference for every conversion mapping — secret types, PVC performance classes, port-protocol inference, the full catalog of what each converter silently drops, Compose rules, and Helm. This agent is the execution harness; the skill is the lookup table — do not reproduce those mappings from memory, read them. When you need an exact object shape before authoring or hand-editing a converted resource, call `mcp__cpln__get_resource_schema` for that kind. +Before anything else, read the **migration-patterns** skill. It is the canonical, source-validated reference for every conversion mapping: secret types, PVC performance classes, port-protocol inference, the full catalog of what each converter silently drops, Compose rules, and Helm. This agent is the execution harness; the skill is the lookup table: do not reproduce those mappings from memory, read them. When you need an exact object shape before authoring or hand-editing a converted resource, call `mcp__cpln__get_resource` with `schema: true` for that kind. The converters are **CLI-only** — there is no MCP equivalent. Verify any `cpln` flag with `cpln --help` before you run it. @@ -76,7 +76,7 @@ For Docker Compose the equivalents live in the skill's Compose section — the g ## Phase 4 — Provision (MCP-first, dependency order) -Create resources in dependency order so each one's references resolve: GVC (with a location) first, then secrets (`mcp__cpln__create_secret`: values Control Plane generates, or `values: "user"` for a Console link the user fills; verify each exists with `mcp__cpln__get_resource` before referencing it), identities, policies, volumesets, workloads (mounting any volumesets), and finally domains. Prefer the typed MCP tools — they build a valid spec and let you verify each resource as you go: `mcp__cpln__create_gvc`, `mcp__cpln__create_identity`, `mcp__cpln__create_policy`, `mcp__cpln__create_volumeset` then `mcp__cpln__mount_volumeset_to_workload`, `mcp__cpln__create_workload`, and `mcp__cpln__create_domain` for converted Ingresses. +Create resources in dependency order so each one's references resolve: GVC (with a location) first, then secrets (`mcp__cpln__create_secret`: values Control Plane generates, or `values: "user"` for a Console link the user fills; verify each exists with `mcp__cpln__get_resource` before referencing it), identities, policies, volumesets, workloads (mounting any volumesets), and finally domains. Prefer the typed MCP tools, which build a valid spec and let you verify each resource as you go: `mcp__cpln__create_gvc`, `mcp__cpln__create_identity`, `mcp__cpln__create_policy`, `mcp__cpln__create_volumeset` then `mcp__cpln__mount_volumeset_to_workload`, `mcp__cpln__create_workload`, and `mcp__cpln__create_domain` for converted Ingresses. On the core profile, `mcp__cpln__mount_volumeset_to_workload` given a size creates the volume set, and `mcp__cpln__grant_workload_secret_access` creates and links a workload's identity and `reveal` policy once the workload exists. When a workload references a secret, the converter already emits an `identity-WORKLOAD` and a `policy-WORKLOAD` granting `reveal`, so applying the converted YAML carries them along. If you re-author through the create tools instead, wire that identity and `reveal` policy yourself or the deployment pauses waiting on secret access (access-control and setup-secret skills own this chain). @@ -102,7 +102,7 @@ Report back: each workload with its readiness, the **canonical endpoint** from ` ## Optional — Terraform / IaC target -If the goal is infrastructure-as-code rather than a live deploy, turn the converted Control Plane YAML into HCL with `mcp__cpln__convert_to_terraform` (it dry-run validates against the API first, so the HCL always matches a schema-valid resource) instead of applying it. For resources already created on Control Plane, generate HCL from their self links with `mcp__cpln__export_terraform` (set `generateImports` to emit `import {}` blocks for adoption). The iac-terraform-pulumi skill owns the full Terraform/Pulumi story. +If the goal is infrastructure-as-code rather than a live deploy, turn the converted Control Plane YAML into HCL with `mcp__cpln__export_terraform` and its `manifest` (it dry-run validates against the API first, so the HCL always matches a schema-valid resource) instead of applying it. For resources already created on Control Plane, pass their self links as its `resource` instead (set `generateImports` to get the `terraform import` commands that adopt them). The iac-terraform-pulumi skill owns the full Terraform/Pulumi story. ## When to stop and ask diff --git a/plugins/cpln/agents/workload-troubleshooter.md b/plugins/cpln/agents/workload-troubleshooter.md index 15e1344..57fdbaa 100644 --- a/plugins/cpln/agents/workload-troubleshooter.md +++ b/plugins/cpln/agents/workload-troubleshooter.md @@ -9,7 +9,7 @@ You are the Control Plane troubleshooting operator. A user — or the `/cpln:tro ## Load your reference first -Start with `mcp__cpln__diagnose_workload`: one call reads the deployments, events, logs, and spec and returns the likely cause with a fix. Read the **workload-troubleshooting** skill (the failure catalog, the verified constants, and the schema limits a fix must stay within) when the diagnosis is inconclusive or before a fix it did not suggest; do not diagnose from memory. For an exact object shape before authoring a manifest, call `mcp__cpln__get_resource_schema` for the `workload` kind. +Start with `mcp__cpln__diagnose_workload`: one call reads the deployments, events, logs, and spec and returns the likely cause with a fix. Read the **workload-troubleshooting** skill (the failure catalog, the verified constants, and the schema limits a fix must stay within) when the diagnosis is inconclusive or before a fix it did not suggest; do not diagnose from memory. For an exact object shape before authoring a manifest, call `mcp__cpln__get_resource` with `schema: true` for the `workload` kind. ## Operating rules @@ -21,7 +21,7 @@ Start with `mcp__cpln__diagnose_workload`: one call reads the deployments, event ## Phase 1 — Gather state -Establish where and how the workload is failing: `mcp__cpln__diagnose_workload` first, then the read tools for what it leaves open: `mcp__cpln__list_deployments` (per-location readiness with reason/message; pass `location` to drill into one failing location), `mcp__cpln__get_workload_events` (image / crash / probe / schedule events), `mcp__cpln__get_workload_logs` (app logs; the `_accesslog` container for HTTP codes), and `mcp__cpln__get_resource` for the spec. For resource pressure, `mcp__cpln__list_metrics` then `mcp__cpln__query_metrics`; `mcp__cpln__list_workload_replicas` confirms which replicas are running. +Establish where and how the workload is failing: `mcp__cpln__diagnose_workload` first (its 10 newest events cover image, crash, probe, and schedule failures), then the read tools for what it leaves open: `mcp__cpln__list_deployments` (per-location readiness with reason/message and the running replica names; pass `location` to drill into one failing location), `mcp__cpln__get_workload_logs` (app logs; the `_accesslog` container for HTTP codes), `mcp__cpln__get_resource` for the spec, and `mcp__cpln__get_workload_events` (needs `?toolsets=full`) for older events. For resource pressure, `mcp__cpln__query_metrics`, first without a `query` to list the metric names. ## Phase 2 — Diagnose @@ -29,7 +29,7 @@ Match the symptoms against the skill's failure catalog and isolate the root caus ## Phase 3 — Apply the fix and verify -Present each issue as **what's wrong** (with evidence), **why** (the root cause), and **the fix** (the exact tool call or config change). Apply only after the user approves — MCP-first with `mcp__cpln__update_workload` (PATCH), `mcp__cpln__grant_workload_secret_access` for the secret chain, or `mcp__cpln__get_resource_schema` + `cpln apply` for manifest-level changes. Keep every change within the schema limits the skill lists (memory ≤ 8× CPU, IDs 1-65534, grace ≤ 900, scale-to-zero needs `keda` on standard/stateful, a metric must be in the type's allow-list) so the update is not rejected. A restart without a spec change (fresh secret values, a wedged replica set) is `mcp__cpln__restart_workload`. Then wait with `mcp__cpln__list_deployments` and `waitSeconds` until ready across locations and report the canonical endpoint it returns — for a public workload, confirm it actually responds, not just that it is ready. +Present each issue as **what's wrong** (with evidence), **why** (the root cause), and **the fix** (the exact tool call or config change). Apply only after the user approves, MCP-first with `mcp__cpln__update_workload` (PATCH), `mcp__cpln__grant_workload_secret_access` for the secret chain, or `mcp__cpln__get_resource` with `schema: true` and then `cpln apply` for manifest-level changes. Keep every change within the schema limits the skill lists (memory ≤ 8× CPU, IDs 1-65534, grace ≤ 900, scale-to-zero needs `keda` on standard/stateful, a metric must be in the type's allow-list) so the update is not rejected. A restart without a spec change (fresh secret values, a wedged replica set) is `mcp__cpln__restart_workload`. Then wait with `mcp__cpln__list_deployments` and `waitSeconds` until ready across locations and report the canonical endpoint it returns; for a public workload, confirm it actually responds, not just that it is ready. ## When to stop and ask diff --git a/plugins/cpln/knowledge-map.json b/plugins/cpln/knowledge-map.json index ec332e7..89347a4 100644 --- a/plugins/cpln/knowledge-map.json +++ b/plugins/cpln/knowledge-map.json @@ -21,6 +21,7 @@ "migration-patterns": {}, "mk8s-byok": {}, "native-networking": {}, + "operating-guide": {}, "org-management": {}, "query-spec": {}, "setup-agent": {}, @@ -55,12 +56,7 @@ "create_volumeset": "stateful-storage", "update_volumeset": "stateful-storage", "mount_volumeset_to_workload": "stateful-storage", - "expand_volumeset": "stateful-storage", - "shrink_volumeset": "stateful-storage", - "delete_volumeset_volume": "stateful-storage", - "create_volumeset_snapshot": "stateful-storage", - "delete_volumeset_snapshot": "stateful-storage", - "restore_volumeset_snapshot": "stateful-storage", + "run_volumeset_command": "stateful-storage", "add_identity_network_resource": "native-networking", "add_identity_native_network_resource": "native-networking", "remove_identity_network_resource": "native-networking", @@ -76,11 +72,6 @@ "edit_audit_context": "audit-compliance", "create_domain": "domain", "update_domain": "domain", - "add_domain_route": "domain", - "update_domain_route": "domain", - "add_domain_port": "domain", - "set_domain_tls": "domain", - "set_domain_cors": "domain", "create_workload": "workload", "update_workload": "workload", "configure_workload_load_balancer": "workload", @@ -108,17 +99,13 @@ "allow_workload_access": "firewall-networking", "grant_cloud_access": "setup-cloud-access", "query_metrics": "metrics-observability", - "list_metrics": "metrics-observability", "query_traces": "metrics-observability", - "get_trace": "metrics-observability", "export_terraform": "iac-terraform-pulumi", - "convert_to_terraform": "iac-terraform-pulumi", "query_audit_events": "audit-compliance", "create_gvc": "workload", "update_gvc": "workload", "list_deployments": "workload", "browse_templates": "template-catalog", - "get_template": "template-catalog", "get_installed_template": "template-catalog", "create_mk8s": "mk8s-byok", "update_mk8s": "mk8s-byok", diff --git a/plugins/cpln/rules/cpln-core.md b/plugins/cpln/rules/cpln-core.md index 724823b..aff3fda 100644 --- a/plugins/cpln/rules/cpln-core.md +++ b/plugins/cpln/rules/cpln-core.md @@ -3,7 +3,7 @@ description: Control Plane core rules for AI agents, loaded in every session. Re alwaysApply: true --- -**Model**: org → `gvc` (locations; a workload runs in all) → `workload`. Org-wide: secrets, domains, policies, images, agents; gvc-scoped: workloads, identities, volume sets. Not Kubernetes: no namespaces, ingress, or canary weights. +**Model**: org → `gvc` (locations; a workload runs in all) → `workload`. Org-wide: secrets, domains, policies, images, agents; gvc-scoped: workloads, identities, volume sets. Not Kubernetes: no namespaces/ingress; canary via routes. **Where**: org: the granted one, else ask (`list_orgs`). Gvc: the named one, else the one jobs made for apps; others: ask; none: a job makes one where the user picks. Never guess other names; after a not-found, never retry name variants. diff --git a/plugins/cpln/skills/access-control/SKILL.md b/plugins/cpln/skills/access-control/SKILL.md index 631a77b..ea2c258 100644 --- a/plugins/cpln/skills/access-control/SKILL.md +++ b/plugins/cpln/skills/access-control/SKILL.md @@ -5,7 +5,7 @@ description: "Primary skill for access control, policies, and RBAC on Control Pl # Access Control & Policies — Primary Skill -> **Tool availability:** `create_group`, `edit_group`, `create_service_account`, `update_service_account`, `add_key_to_service_account`, and `invite_user_to_org` need `?toolsets=full`; reconnect with it or use the CLI. +> **Tool availability:** `create_policy`, `update_policy`, `get_permissions`, `create_group`, `edit_group`, `create_service_account`, `update_service_account`, `add_key_to_service_account`, and `invite_user_to_org` need `?toolsets=full`; reconnect with it or use the CLI. On core, `grant_workload_secret_access` (`remove: true` revokes) grants a workload secret access through its identity and a policy, creating either when missing; `grant_cloud_access` creates no policy: it makes sure the workload has an identity and sets that identity's cloud provider access. A **policy** targets one resource kind and binds **permissions** to **principals** (users, groups, service accounts, workload identities). The common failure is a policy that **exists but grants nothing** — a wrong `targetKind`, permission name, or principal link fails with no error — so read the policy back after writing. @@ -41,7 +41,7 @@ bindings: # ≤ 50 **Valid target kinds:** the `targetKind` enum accepts all **33** resource kinds, but only the **20 kinds with permission schemas** (the ones `get_permissions` accepts) are meaningful targets: `workload, secret, gvc, identity, image, org, policy, group, serviceaccount, user, volumeset, domain, location, ipset, mk8s, cloudaccount, agent, auditctx, quota, task`. **Create vs update:** -- `create_policy` builds **one** binding from `addPermissions` × (`addUsers`/`addGroups`/`addServiceAccounts`/`addIdentities`) — providing only one side is an **error** (a binding needs both). It also requires **exactly one** target scope (`targetAll` / `targetLinks` / `targetQuery`). For several distinct bindings, use `update_policy` `addBindings`. +- `create_policy` builds **one** binding from `addPermissions` × (`addUsers`/`addGroups`/`addServiceAccounts`/`addIdentities`) — providing only one side is an **error** (a binding needs both). It takes the target scope as `targetAll`, `targetLinks`, or `targetQuery`; they may be combined, and `targetAll` wins. For several distinct bindings, use `update_policy` `addBindings`. - `update_policy` **merges** bindings (matched by exact permission set — you can't extend a set) but **replaces** targets (`targetLinks` wholesale, `removeTargetLinks` incremental, `targetAll` — mutually exclusive). ## Permissions @@ -77,7 +77,7 @@ Members are **users and service accounts only** (≤ 200). Bind policies to grou ### Users (IDP-backed) - **Invite:** `invite_user_to_org` (`email`, optional `groupName`). -- **Read / remove:** `get_resource` (kind="user") / `delete_resource` (kind="user") take **`identifier`** (id or email); `list_resources` (kind="user") has an `email` filter. +- **Read / remove:** `get_resource` (kind="user") / `delete_resource` (kind="user") take the user's `name` exactly as `list_resources` (kind="user") shows it; `list_resources` has no filter argument, so find the user in its table. ## Built-ins (seeded per org) diff --git a/plugins/cpln/skills/audit-compliance/SKILL.md b/plugins/cpln/skills/audit-compliance/SKILL.md index ae9fca4..b414fc7 100644 --- a/plugins/cpln/skills/audit-compliance/SKILL.md +++ b/plugins/cpln/skills/audit-compliance/SKILL.md @@ -5,7 +5,7 @@ description: "Audit trail and compliance on Control Plane. Use when the user ask # Audit Trail & Compliance -> **Tool availability:** `create_audit_context` and `edit_audit_context` need `?toolsets=full`. +> **Tool availability:** `create_audit_context`, `edit_audit_context`, `create_identity`, `create_policy`, and `get_permissions` need `?toolsets=full`. Every mutation on every Control Plane resource — via Console, CLI, API, Terraform, Pulumi, or MCP — is recorded automatically in an append-only, tamper-proof audit trail; nothing to configure. Most tasks are answering **"who changed what, when"** with `mcp__cpln__query_audit_events`. Custom audit contexts exist for one purpose only: letting your own workloads write their own audit events. diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index d8a3219..23b0558 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -95,7 +95,7 @@ autoscaling: - Triggers needing auth reference a GVC-listed secret via `authenticationRef.name` (the TriggerAuthentication is named after the secret). - If the trigger source is a Control Plane workload, allow KEDA in the source's firewall: `internal.inboundAllowWorkload: [cpln://internal/keda]`. - Also supported: `keda.advanced.scalingModifiers` (custom formulas), `fallback`, `pollingInterval`, `cooldownPeriod`. -- **Prometheus trigger** — scale on any platform or custom metric: `type: prometheus` with `serverAddress: https://metrics.cpln.io:443/metrics/org/ORG`, a `query` (PromQL), `threshold`, and `customHeaders: Authorization=Bearer SERVICE_ACCOUNT_TOKEN` (service account needs `readMetrics`). **Before wiring any trigger, confirm the signal resolves:** `mcp__cpln__list_metrics` for real names/labels, then `mcp__cpln__query_metrics` to run the PromQL — a never-resolving signal pins the workload at `minScale`. Custom app metrics come from the container `metrics` block (see **metrics-observability**). +- **Prometheus trigger**, to scale on any platform or custom metric: `type: prometheus` with `serverAddress: https://metrics.cpln.io:443/metrics/org/ORG`, a `query` (PromQL), `threshold`, and `customHeaders: Authorization=Bearer SERVICE_ACCOUNT_TOKEN` (service account needs `readMetrics`). **Before wiring any trigger, confirm the signal resolves:** `mcp__cpln__query_metrics` without a `query` for real names (add `metric` for one metric's live label values), then with the PromQL as its `query` to run it; a never-resolving signal pins the workload at `minScale`. Custom app metrics come from the container `metrics` block (see **metrics-observability**). ## Capacity AI @@ -123,14 +123,14 @@ spec: - Floors and the memory to CPU ratio: `workload` skill. `minCpu` and `minMemory` never exceed `cpu` and `memory`. - **With Capacity AI off:** `cpu`/`memory` are the fixed allocation and `minCpu`/`minMemory` are ignored — except on **stateful**, where `minCpu`/`minMemory` become the static **reserved** request and `cpu`/`memory` stay the burst ceiling. - **Stateful `minCpu`/`minMemory` are bounded** unless Capacity AI is on in `defaultOptions` and in every `localOptions` entry: max/min ratio ≤ **4** AND gap ≤ **4000m** CPU / **4096Mi** memory. -- **GPU:** `nvidia` model `t4` (quantity up to 4) or `a10g` (exactly 1); strict per-model CPU/memory minimums — fetch exact numbers with `mcp__cpln__get_resource_schema` (`kind: workload`). +- **GPU:** `nvidia` model `t4` (quantity up to 4) or `a10g` (exactly 1); strict per-model CPU/memory minimums: fetch exact numbers with `mcp__cpln__get_resource` (`kind: workload`, `schema: true`). - **Cost:** billing follows reserved resources, so Capacity AI (or stateful `minCpu`) directly lowers cost. ## Troubleshooting | Symptom | Check | |---|---| -| Not scaling up | Does the signal exist? `mcp__cpln__list_metrics` then `mcp__cpln__query_metrics`; check `maxScale`; check replica readiness via `mcp__cpln__list_deployments` | +| Not scaling up | Does the signal exist? `mcp__cpln__query_metrics` without, then with, a `query`; check `maxScale`; check replica readiness via `mcp__cpln__list_deployments` | | Not scaling down | Standard/stateful stabilization window = `scaleToZeroDelay` (default 300s); check `minScale` | | Scale-to-zero not happening | Serverless needs `concurrency`/`rps`; standard/stateful need `metric: keda`; check `scaleToZeroDelay` | | KEDA not triggering | KEDA enabled on the GVC? Trigger auth secret listed in `gvc.spec.keda.secrets`? Source firewall allows `cpln://internal/keda`? | diff --git a/plugins/cpln/skills/cdn-rate-limiting/SKILL.md b/plugins/cpln/skills/cdn-rate-limiting/SKILL.md index c0ba78d..f09eeac 100644 --- a/plugins/cpln/skills/cdn-rate-limiting/SKILL.md +++ b/plugins/cpln/skills/cdn-rate-limiting/SKILL.md @@ -15,7 +15,7 @@ The pattern: the CDN proxies your domain and uses the workload's **canonical end 1. **DNS at Cloudflare:** proxied CNAME (orange cloud on) from your subdomain to the canonical endpoint; SSL/TLS mode **Full (strict)**. 2. **Origin certificate** (SSL/TLS, then Origin Server; RSA 2048) becomes a Control Plane **TLS secret** — `create_secret` type `tls` with `values: "user"` (the user types the cert and key in the Console), **TLS chain left empty** (the origin cert is self-signed). -3. **Domain at Control Plane:** `mcp__cpln__create_domain` (CNAME DNS mode), `mcp__cpln__set_domain_tls` with the secret as the custom **server certificate**, `mcp__cpln__add_domain_route` to the workload. **The apex domain must be verified before configuring a subdomain.** +3. **Domain at Control Plane:** `mcp__cpln__create_domain` (CNAME DNS mode), then one `mcp__cpln__update_domain` call: `addPorts` sets the secret as the listener's custom **server certificate** (`tls.serverCertificate.secretLink`) and `addRoutes` routes it to the workload. **The apex domain must be verified before configuring a subdomain.** ### Amazon CloudFront diff --git a/plugins/cpln/skills/cpln/SKILL.md b/plugins/cpln/skills/cpln/SKILL.md index b4071d9..5ce7073 100644 --- a/plugins/cpln/skills/cpln/SKILL.md +++ b/plugins/cpln/skills/cpln/SKILL.md @@ -5,7 +5,7 @@ description: "Writes cpln CLI commands and workflows for Control Plane. Use when # cpln CLI -**MCP first; the CLI covers what the MCP cannot.** With the MCP connected, its tools do every operation they cover, reads included; the CLI is for the CLI-only operations below (building a folder on disk among them), interactive debugging, scripted GitOps, and sessions without the MCP. A connected MCP that is signed out means the user signs in again, not a switch to the CLI. **In CI/CD the CLI is the primary interface** — pipelines authenticate with a service-account key in `CPLN_TOKEN`, build and push images (`cpln image build --push`, or `--remote` on a runner with no Docker daemon), and apply resources (`cpln apply --ready`). Platform rules (resource model, secrets, destructive ops, production defaults, scale-to-zero, firewall) live in the operating guide (`get_cpln_rules`); this skill is the CLI mechanics. +**MCP first; the CLI covers what the MCP cannot.** With the MCP connected, its tools do every operation they cover, reads included; the CLI is for the CLI-only operations below (building a folder on disk among them), interactive debugging, scripted GitOps, and sessions without the MCP. A connected MCP that is signed out means the user signs in again, not a switch to the CLI. **In CI/CD the CLI is the primary interface**: pipelines authenticate with a service-account key in `CPLN_TOKEN`, build and push images (`cpln image build --push`, or `--remote` on a runner with no Docker daemon), and apply resources (`cpln apply --ready`). Platform rules (resource model, secrets, destructive ops, production defaults, scale-to-zero, firewall) live in the `operating-guide` skill (through the MCP: `get_cpln_skill` with `skill: "operating-guide"`); this skill is the CLI mechanics. **Never write a `cpln` command from memory.** Verify every verb and flag with `cpln --help` before quoting it. If a command isn't in the resource command map below, assume it isn't real. @@ -24,7 +24,7 @@ No MCP equivalent — the CLI's primary job: One-shot and interactive container commands, TTY sessions (`workload connect`, `exec -it`), and streamed logs (`cpln logs --tail`) are also CLI-only; MCP's `get_workload_logs` covers bounded log fetches. Everything else — discovery and CRUD — prefer the MCP tools (generic `mcp__cpln__list_resources` / `get_resource` / `delete_resource` with a `kind`, typed `create_*`/`update_*` for mutations). -When no MCP tool covers a resource, field, or sub-endpoint, use the `cpln` CLI for that piece (ground the command in this skill and `--help`) or tell the user what is missing. The raw-API escape hatch (`cpln_api_request`) is disabled by default — it bypasses the typed tools' pre-call validation. +When no MCP tool covers a resource, field, or sub-endpoint, use the `cpln` CLI for that piece (ground the command in this skill and `--help`) or tell the user what is missing. ## Setup & auth @@ -205,9 +205,9 @@ Dedicated verb per operation; the flags are **singular** — `--location`, `--vo | Restore snapshot | `cpln volumeset snapshot restore REF --snapshot-name NAME --location LOC --volume-index N` (all required) | Overwrites volume state | | Delete snapshot | `cpln volumeset snapshot delete REF --snapshot-name NAME` | Destructive | | Delete volume | `cpln volumeset volume delete REF [--location LOC] [--volume-index N]` | Destructive (data loss) | -| Shrink volume | `cpln volumeset shrink REF --new-size GIB [--location LOC]` | **DESTRUCTIVE — permanent data loss** | +| Shrink volume | `cpln volumeset shrink REF --new-size GIB [--location LOC]` | **DESTRUCTIVE** (replaces the volume and restarts the replica) | -`shrink` provisions a new, smaller volume and removes the old one — data is **not** migrated. Safe only with built-in redundancy (Kafka replication; Cassandra/CockroachDB), on `ext4`/`xfs` (not `shared`). Apply the destructive-op confirmation from the operating guide (`get_cpln_rules`) first. Detail: `stateful-storage` skill. +`shrink` copies the data with rsync onto a new, smaller volume (the replica restarts for the final sync), then deletes the old one. It runs on `ext4`/`xfs` (not `shared`). The platform refuses a size below the volume set's `initialCapacity` or below used bytes plus 5% (HTTP 400), and a shrink that fails keeps the old volume. Apply the destructive-op confirmation from the operating guide first, and snapshot as a recovery point. Detail: `stateful-storage` skill. ## Commands that don't exist @@ -263,7 +263,7 @@ cpln workload get-deployments my-app --gvc my-gvc # verify readiness ## Workflow: Grant secret access (3 steps) -The 3-step rule (identity + policy + reference) is owned by the operating guide (`get_cpln_rules`). The secret must already exist (`create_secret`, or the manifest path in `setup-secret`). CLI fallback: +The 3-step rule (identity + policy + reference) is owned by the operating guide. The secret must already exist (`create_secret`, or the manifest path in `setup-secret`). CLI fallback: ```bash cpln identity create --name my-app-identity --gvc my-gvc --org my-org @@ -309,4 +309,4 @@ cpln port-forward my-app 8080:8080 --gvc my-gvc # probe ## Platform rules & integration -Scale-to-zero/autoscaling, production defaults/probes, Template Catalog first, destructive ops, secrets, and firewall rules live in the operating guide (`get_cpln_rules`) and their dedicated skills — not duplicated here. Before authoring any apply YAML / CI manifest / API body, call `get_resource_schema`. IaC: Terraform (`controlplane-com/cpln` provider), Pulumi (`@pulumiverse/cpln`), K8s Operator (`cpln operator install`). Docs index for agents: https://docs.controlplane.com/llms.txt +Scale-to-zero/autoscaling, production defaults/probes, Template Catalog first, destructive ops, secrets, and firewall rules live in the operating guide and their dedicated skills, not duplicated here. Before authoring any apply YAML / CI manifest / API body, call `get_resource` with `schema: true`. IaC: Terraform (`controlplane-com/cpln` provider), Pulumi (`@pulumiverse/cpln`), K8s Operator (`cpln operator install`). Docs index for agents: https://docs.controlplane.com/llms.txt diff --git a/plugins/cpln/skills/domain/SKILL.md b/plugins/cpln/skills/domain/SKILL.md index cdd9fb1..a27f390 100644 --- a/plugins/cpln/skills/domain/SKILL.md +++ b/plugins/cpln/skills/domain/SKILL.md @@ -61,6 +61,7 @@ spec: - **Subdomain matching on one domain** (`hostPrefix` / `hostRegex`, mutually exclusive) requires `acceptAllHosts` or `acceptAllSubdomains` (which exclude each other) AND a GVC with a dedicated load balancer. `hostPrefix` charset: alphanumeric, dot, underscore, hyphen. - **Header rewrites** (`headers.request.set`): values may use only `%REQUESTED_SERVER_NAME%`, `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%`, `%START_TIME%`. - **Traffic mirroring** per route: `mirror: [{workloadLink, percent 0-100, port}]` — same GVC, response comes only from the primary. +- **Canaries** per route: `canaries: [{workloadLink, weight, port}]` split traffic by weight; weights total at most 100 (the rest goes to the route's workload), 0 disables one, and a canary not deployed in a location is dropped there. - **CORS** per port: `allowOrigins` entries take `exact` XOR `regex`; header lists are lowercased; `maxAge` format is digits + `h`/`m`/`s` only. - **TLS** per port: `minProtocolVersion` default `TLSV1_2`; custom cert = keypair secret (PEM) on `serverCertificate.secretLink`; `clientCertificate` enables mTLS verification — client cert details reach the workload in the XFCC header. @@ -98,7 +99,7 @@ spec: ## Which tool changes what -`create_domain` with `workload` and `gvc` derives the 443 listener, its route, and `cname` mode and returns the DNS records; pass `dnsMode` and `ports` for anything else. After creation, routes, ports, TLS, and CORS each have their own tool (CORS needs `?toolsets=full`); `update_domain` never changes ports, `dnsMode`, or `certChallengeType`. Domain names are FQDNs, passed as is. +`create_domain` with `workload` and `gvc` derives the 443 listener, its route, and `cname` mode and returns the DNS records; pass `dnsMode` and `ports` for anything else. After creation, one `update_domain` call changes listeners and routes: `addPorts` adds a listener or sets its `protocol`, `tls`, or `cors`; `addRoutes` adds a route or replaces the one with the same path and host, and takes the route fields `create_domain` takes (`canaries` and `mirror` included) plus `portNumber`; `removePorts`, `removeRoutes`, `removeTls`, and `removeCors` delete. Removals run first, so `removeRoutes` plus `addRoutes` moves a route to a new path or host. It also switches `certChallengeType` (for example to `dns01`; refused on `.internal` domains), and never changes `dnsMode`. Domain names are FQDNs, passed as is. ## Verify diff --git a/plugins/cpln/skills/environment-promotion/SKILL.md b/plugins/cpln/skills/environment-promotion/SKILL.md index 65570b6..47417d5 100644 --- a/plugins/cpln/skills/environment-promotion/SKILL.md +++ b/plugins/cpln/skills/environment-promotion/SKILL.md @@ -27,8 +27,8 @@ cpln apply --file ./manifests/ --org my-org --gvc staging-gvc --ready # gvc- - Bootstrap manifests from a live environment with `cpln get REF -o yaml-slim` (plain `yaml` output breaks apply). - Environment differences (env vars, scaling, firewall) belong in the manifests per environment — or patch after apply with `mcp__cpln__update_workload` / `mcp__cpln__update_gvc` (both PATCH semantics). -- For IaC-based promotion, export live resources to Terraform: `mcp__cpln__export_terraform` (one self link, or bulk by path depth — a whole GVC or org), `mcp__cpln__convert_to_terraform` (manifest to HCL, dry-run validated). An unsupported kind is rejected with the supported list. -- **One workload into another GVC:** `mcp__cpln__promote_workload` (`workload`, `gvc`, `targetGvc`, optional `image` and `env` overrides) copies the spec without its identity or `cpln/` tags, creates or updates the target, grants its secret references, and waits. A volume set mount is refused: create the storage in the target GVC first. +- For IaC-based promotion, export live resources to Terraform with `mcp__cpln__export_terraform`: one self link, bulk by path depth (a whole GVC or org), or a `manifest` converted to HCL after a dry-run validation. An unsupported kind is rejected with the supported list. +- **One workload into another GVC:** `mcp__cpln__promote_workload` (needs `?toolsets=full`; `workload`, `gvc`, `targetGvc`, optional `image` and `env` overrides) copies the spec without its identity or `cpln/` tags, points internal firewall links to workloads of the source GVC at the same names in the target, creates or updates the target, grants its secret references, and waits. Each volume set it mounts is created in the target GVC from the source's settings, custom encryption keys included, or updated to them (capacity only grows; an existing one keeps its own keys); data is never copied. Before anything is written it refuses a referenced secret that does not exist, an existing `{targetGvc}-{workload}-secrets-policy` policy of another target kind, an existing target workload of another type, and a target volume set with another file system or performance class or one another workload uses. ## Sharing images across orgs @@ -46,7 +46,7 @@ CLI-only (no MCP tool) and **still requires a running Docker daemon — `copy` h The target org pulls directly from the source org's registry. Four steps: 1. **Source org — puller credentials**: `mcp__cpln__add_key_to_service_account` (needs `?toolsets=full`; creates the service account if missing; the key is shown **once**). -2. **Source org — grant pull**: `mcp__cpln__create_policy` with `targetKind: image`, `targetAll: true` (or `targetQuery` by repository), `addPermissions: ["pull"]`, `addServiceAccounts: [LINK]` — bindings go in the create call. +2. **Source org, grant pull**: `mcp__cpln__create_policy` (needs `?toolsets=full`) with `targetKind: image`, `targetAll: true` (or `targetQuery` by repository), `addPermissions: ["pull"]`, `addServiceAccounts: [LINK]`; bindings go in the create call. 3. **Target org — docker secret**: have the user create a `docker` secret with this `dockerConfigJson` — offer a manifest scaffold (`data` is this JSON as one string; `setup-secret` skill); the username is the **literal string ``** (the registry rejects anything else; the password is the service-account key): ```json @@ -107,7 +107,7 @@ cpln workload update my-app --set spec.containers.main.image=//image/my-app:v1.1 cpln workload get-deployments my-app --gvc my-gvc --org my-org # verify every location reports ready ``` -- MCP path: `mcp__cpln__rollback_workload` (`name`, optional `image`) re-points the first container at the newest earlier image the deployments recorded, or at the image passed, and waits. +- MCP path: `mcp__cpln__rollback_workload` (`name`, optional `image`) restores the previous image of every container whose image changed, read from the workload's audit trail (last 30 days; failing that, from an earlier version its deployments still run), or puts the image passed on the first container, and waits. Only images change. - Org-per-environment: confirm the older image still exists in **this** org's registry first (`mcp__cpln__list_resources` kind="image") — it may only have been copied forward once. - **Restart without changing the image**: `mcp__cpln__restart_workload`, or `cpln workload force-redeployment my-app --gvc GVC`; both stamp the `cpln/deployTimestamp` tag, a rolling restart. - Helm-managed releases are the exception with real revision history: `cpln helm rollback RELEASE [REVISION]`. diff --git a/plugins/cpln/skills/firewall-networking/SKILL.md b/plugins/cpln/skills/firewall-networking/SKILL.md index 7035427..c42652c 100644 --- a/plugins/cpln/skills/firewall-networking/SKILL.md +++ b/plugins/cpln/skills/firewall-networking/SKILL.md @@ -5,7 +5,7 @@ description: "Firewall rules and service-to-service communication on Control Pla # Firewall & Networking -Deep detail for `spec.firewallConfig` and the enforcement model behind it; the `workload` skill owns the summary (deny-by-default, exposure decided at create time, LB picker). Set `firewallConfig` with `create_workload` / `update_workload` — or `public: true`, the shortcut that opens inbound AND outbound to `0.0.0.0/0` (mutually exclusive with an explicit `firewallConfig`). A firewall change creates a new deployment version — a rolling replace, live in about a minute (`vm` workloads are the exception: firewall updates apply in place without restarting the VM). +Deep detail for `spec.firewallConfig` and the enforcement model behind it; the `workload` skill owns the summary (deny-by-default, exposure decided at create time, LB picker). Set `firewallConfig` with `create_workload` / `update_workload`, or use the `public` shortcut (mutually exclusive with an explicit `firewallConfig`): `public: true` opens inbound AND outbound to `0.0.0.0/0` (on `update_workload` it adds `0.0.0.0/0` to both external allow lists and keeps every other rule), and `public: false` on `update_workload` removes only `0.0.0.0/0` and `::/0` from external inbound. A firewall change creates a new deployment version — a rolling replace, live in about a minute (`vm` workloads are the exception: firewall updates apply in place without restarting the VM). ## How rules are enforced diff --git a/plugins/cpln/skills/gitops-cicd/SKILL.md b/plugins/cpln/skills/gitops-cicd/SKILL.md index 5f5788b..ae2f8d8 100644 --- a/plugins/cpln/skills/gitops-cicd/SKILL.md +++ b/plugins/cpln/skills/gitops-cicd/SKILL.md @@ -5,7 +5,7 @@ description: "Sets up CI/CD pipelines and GitOps for Control Plane. Use when the # GitOps & CI/CD -In pipelines the **CLI is the primary interface**: authenticate with a service-account key in `CPLN_TOKEN` (no profile needed), push an image, `cpln apply --ready` the manifests. MCP tools do the work around the pipeline — `mcp__cpln__get_resource_schema` before authoring manifests, `mcp__cpln__list_deployments` to confirm a deploy landed. The usual failure is image builds: `cpln image build` runs the build **locally through Docker**, so a runner without a daemon needs a different flow — a daemonless builder, or `--remote` to build on Control Plane. Pick by runner capability, not by habit. +In pipelines the **CLI is the primary interface**: authenticate with a service-account key in `CPLN_TOKEN` (no profile needed), push an image, `cpln apply --ready` the manifests. MCP tools do the work around the pipeline: `mcp__cpln__get_resource` with `schema: true` before authoring manifests, `mcp__cpln__list_deployments` to confirm a deploy landed. The usual failure is image builds: `cpln image build` runs the build **locally through Docker**, so a runner without a daemon needs a different flow (a daemonless builder, or `--remote` to build on Control Plane). Pick by runner capability, not by habit. ## Service-account authentication @@ -16,7 +16,7 @@ cpln serviceaccount add-key ci-deployer --description "ci key" --org ORG # --d The JSON response's `key` value is the credential — keep it on the user's machine and store it as a masked/secret variable in the CI platform; never paste it into chat. MCP: `mcp__cpln__add_key_to_service_account` (needs `?toolsets=full`) creates the service account if it is missing and returns a Console link where the user creates the key privately. -Grant least privilege (`access-control` skill): pushing images needs `create` on the `image` kind; `cpln apply` needs create/edit on every kind the manifests contain. `cpln group add-member superusers --serviceaccount ci-deployer` works but grants full org access — prefer a scoped policy (`mcp__cpln__create_policy`). +Grant least privilege (`access-control` skill): pushing images needs `create` on the `image` kind; `cpln apply` needs create/edit on every kind the manifests contain. `cpln group add-member superusers --serviceaccount ci-deployer` works but grants full org access; prefer a scoped policy (`mcp__cpln__create_policy`, needs `?toolsets=full`). Set in the platform's variable settings, never inline in scripts: @@ -72,7 +72,7 @@ On GitHub, `docker/login-action` + `docker/build-push-action` also work with the ## Applying manifests -Author YAML against the real shape first: `mcp__cpln__get_resource_schema` for each kind. The pipeline then runs: +Author YAML against the real shape first: `mcp__cpln__get_resource` with `schema: true` for each kind. The pipeline then runs: ```bash cpln apply --file ./manifests/ --ready diff --git a/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md b/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md index 44723a1..ebc47c0 100644 --- a/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md +++ b/plugins/cpln/skills/iac-terraform-pulumi/SKILL.md @@ -55,16 +55,16 @@ The hosted terraform-exporter produces provider-correct HCL. Route by what you h | You have | Use | |----------|-----| | Existing resource(s) | `mcp__cpln__export_terraform` — a single self link, or bulk by path depth: `/org/ORG` (whole org), `/org/ORG/KIND` (all of a kind), `/org/ORG/gvc/GVC/workload` (all workloads in the GVC) | -| A YAML/JSON manifest | `mcp__cpln__convert_to_terraform` — dry-run validated against the API first, so the returned HCL always matches a schema-valid resource; pass `gvc` for GVC-scoped kinds (workload, identity, volumeset) | -| Nothing yet | author the manifest against `mcp__cpln__get_resource_schema`, then convert it | +| A YAML/JSON manifest | `mcp__cpln__export_terraform` with `manifest` and `org`: dry-run validated against the API first, so the returned HCL always matches a schema-valid resource; pass `gvc` for GVC-scoped kinds (workload, identity, volumeset) | +| Nothing yet | author the manifest against `mcp__cpln__get_resource` with `schema: true`, then convert it | -Set `generateImports` on any of these to also get ready-to-run `terraform import` commands, one per resource with the IDs prefilled — run them after `terraform init` and before the first `terraform apply`, so apply updates the live resources instead of re-creating them. `includeDependencies` (export tools) pulls in referenced resources so the HCL is self-contained. +Set `generateImports` on any of these to also get ready-to-run `terraform import` commands, one per resource with the IDs prefilled; run them after `terraform init` and before the first `terraform apply`, so apply updates the live resources instead of re-creating them. `includeDependencies` (self link exports only) pulls in referenced resources so the HCL is self-contained. The exporter emits HCL only. For a Pulumi program, convert the exported HCL with the Pulumi CLI: `pulumi convert --from terraform --language typescript --out DIR` (also python, go, csharp, java, yaml). Conversion translates config, not state — adopt the live resources afterwards per Importing below. The exporter covers 16 kinds: agent, auditctx, cloudaccount, domain (routes emitted as `cpln_domain_route`), group, gvc, identity, ipset, location, mk8s, org, policy, secret, serviceaccount, volumeset, workload. An unsupported kind is rejected with that list; just attempt the export — an unsupported kind is rejected with the supported list. -**Secrets are never exported.** The upstream exporter would embed revealed values in the HCL, so the MCP tools refuse a ref that targets secrets and refuse wholesale any bulk export that pulled secrets in. Narrow the export to exclude secrets; the user authors secret resources in their own Terraform. +**Secrets are never exported.** The upstream exporter would embed revealed values in the HCL, so `export_terraform` refuses a ref or a `manifest` that targets a secret, and refuses wholesale any bulk export that pulled secrets in. Narrow the export to exclude secrets; the user authors secret resources in their own Terraform. ## CLI fallback: -o tf @@ -76,7 +76,7 @@ cpln workload get --gvc GVC -o tf > workloads.tf # no ref: every workloa cpln gvc get -o tf > gvcs.tf # every GVC in the org ``` -Differences from the MCP tools: the output is bare `resource` blocks only (write the `terraform {}` and `provider "cpln" {}` blocks yourself), no `terraform import` commands, no dependency closure, and no secret guard — never run `-o tf` against a secret (it can print revealed plaintext). Multiple explicit refs in one call are not supported with `-o tf`; export per resource or use the no-ref bulk form. The sibling `-o crd` emits Kubernetes CRD YAML for the operator path (k8s-operator skill). For stateless manifests instead of HCL, use `-o yaml-slim` with `cpln apply`. +Differences from `export_terraform`: the output is bare `resource` blocks only (write the `terraform {}` and `provider "cpln" {}` blocks yourself), no `terraform import` commands, no dependency closure, and no secret guard; never run `-o tf` against a secret (it can print revealed plaintext). Multiple explicit refs in one call are not supported with `-o tf`; export per resource or use the no-ref bulk form. The sibling `-o crd` emits Kubernetes CRD YAML for the operator path (k8s-operator skill). For stateless manifests instead of HCL, use `-o yaml-slim` with `cpln apply`. ## Importing existing resources diff --git a/plugins/cpln/skills/image/SKILL.md b/plugins/cpln/skills/image/SKILL.md index 3ff96d0..5789dd3 100644 --- a/plugins/cpln/skills/image/SKILL.md +++ b/plugins/cpln/skills/image/SKILL.md @@ -100,7 +100,7 @@ Attach with `mcp__cpln__update_gvc` (`pullSecretLinks` is **merged** with existi `view` is read-only; `manage` implies all of the above. -**Registry authorization is repository-granular.** When the registry checks a docker push or pull it evaluates the permission against `REPOSITORY:*` (tag wildcarded, no resource link) — so a policy whose `targetLinks` list specific `NAME:TAG` images **never authorizes a docker push or pull**. Scope registry policies to all images, or use a `targetQuery` on the `repository` property (`mcp__cpln__create_policy` with `targetKind: image`; image queries support `name`, `id`, `tag`, `digest`, `repository`, `created`, `lastModified`). Tag-specific `targetLinks` only gate API operations on that image record (view/edit/delete). +**Registry authorization is repository-granular.** When the registry checks a docker push or pull it evaluates the permission against `REPOSITORY:*` (tag wildcarded, no resource link), so a policy whose `targetLinks` list specific `NAME:TAG` images **never authorizes a docker push or pull**. Scope registry policies to all images, or use a `targetQuery` on the `repository` property (`mcp__cpln__create_policy` with `targetKind: image`, needs `?toolsets=full`; image queries support `name`, `id`, `tag`, `digest`, `repository`, `created`, `lastModified`). Tag-specific `targetLinks` only gate API operations on that image record (view/edit/delete). ## Tags, digests, and redeployment diff --git a/plugins/cpln/skills/k8s-operator/SKILL.md b/plugins/cpln/skills/k8s-operator/SKILL.md index bee4d73..9720ff9 100644 --- a/plugins/cpln/skills/k8s-operator/SKILL.md +++ b/plugins/cpln/skills/k8s-operator/SKILL.md @@ -5,7 +5,7 @@ description: "Manages Control Plane resources as Kubernetes CRDs. Use when the u # Kubernetes Operator -The operator (Helm chart `cpln-operator`) runs in any Kubernetes cluster and reconciles `cpln.io/v1` custom resources, plus labeled native Secrets, against the platform on a 30-second loop. Reach for it only when resources must live in Git and be reconciled from a cluster (ArgoCD/Flux); for direct provisioning prefer the typed MCP tools, and for pipeline-driven YAML prefer `cpln apply` (`gitops-cicd` skill). The recurring failure is manifest shape: `org`, `gvc`, and `description` sit at the **top level next to `spec`**, not inside it — author the `spec` block with `mcp__cpln__get_resource_schema`, or skip hand-writing entirely by exporting with `-o crd`. +The operator (Helm chart `cpln-operator`) runs in any Kubernetes cluster and reconciles `cpln.io/v1` custom resources, plus labeled native Secrets, against the platform on a 30-second loop. Reach for it only when resources must live in Git and be reconciled from a cluster (ArgoCD/Flux); for direct provisioning prefer the typed MCP tools, and for pipeline-driven YAML prefer `cpln apply` (`gitops-cicd` skill). The recurring failure is manifest shape: `org`, `gvc`, and `description` sit at the **top level next to `spec`**, not inside it; author the `spec` block from `mcp__cpln__get_resource` with `schema: true`, or skip hand-writing entirely by exporting with `-o crd`. ## Install diff --git a/plugins/cpln/skills/logql-observability/SKILL.md b/plugins/cpln/skills/logql-observability/SKILL.md index cb8c737..1b6a01d 100644 --- a/plugins/cpln/skills/logql-observability/SKILL.md +++ b/plugins/cpln/skills/logql-observability/SKILL.md @@ -94,7 +94,7 @@ Schema facts (nodelibs `cronjob.ts`) that bite scripts: - `status` is one of `successful | failed | active | pending | invalid | removed` (default `pending`). Running means `status == "active"` AND no `completionTime`; a missing `completionTime` alone proves nothing (the schema warns it is not an indication of success). - `completionTime: null` is stripped server-side and `startTime` may be absent for never-started runs — each field is present-with-value or absent, so guard flags with `${VAR:+--from "$VAR"}` and jq `// empty`. -- `replica` is optional: when missing, the run never got a pod and there are **no logs** — diagnose with the execution's `containers` map and `message` field (aggregated pod events) and `mcp__cpln__get_workload_events`. +- `replica` is optional: when missing, the run never got a pod and there are **no logs**; diagnose with the execution's `containers` map and `message` field (aggregated pod events) and `mcp__cpln__diagnose_workload`, which returns the newest events. **2. Query that replica, time-bounded.** MCP: raw `query` embedding ALL labels (structured params must be omitted) plus `from`/`to`. CLI: @@ -118,6 +118,6 @@ CI/CD and headless use: set `CPLN_TOKEN` and run `cpln logs` directly (no profil | Empty result for known activity | Window outside retention (default 30d), span over 31 days, or filters too narrow; app may not write to stdout/stderr | | `#### Replica logs were rate-limited ... ####` marker | Per-replica cap was hit; lines in that interval are gone — reduce log volume | | Line ends with `... [truncated N bytes]` | 16 KiB per-line cap — emit smaller lines | -| Health checks absent from `_accesslog` | Filtered by design; probe failures surface in `mcp__cpln__get_workload_events` | +| Health checks absent from `_accesslog` | Filtered by design; probe failures surface in the events `mcp__cpln__diagnose_workload` returns | | MCP rejects raw `query` combined with `workload` etc. | A raw query replaces the structured params — embed all labels in the query itself | | `cpln workload log` shows no app output | That is the eventlog alias; use `cpln logs` | diff --git a/plugins/cpln/skills/metrics-observability/SKILL.md b/plugins/cpln/skills/metrics-observability/SKILL.md index 2bc37ac..35ba58c 100644 --- a/plugins/cpln/skills/metrics-observability/SKILL.md +++ b/plugins/cpln/skills/metrics-observability/SKILL.md @@ -5,11 +5,11 @@ description: "Workload metrics, PromQL, Grafana, and tracing on Control Plane. U # Metrics, Tracing & Observability -Control Plane stores every workload's metrics as Prometheus-compatible time series in a managed backend (Mimir), queryable in PromQL through the per-org managed Grafana or the MCP tools. The org is the tenant — it comes from the endpoint path, so there is no `org=` label and no cross-org queries. Two traps dominate. **Series names are short:** memory is `mem_used` / `mem_reserved` / `mem_billable`, not `memory_*` — a `memory_used` query returns nothing, so ground names with `list_metrics` first. **Rate-shaped metrics are pre-rated:** `egress`, `requests_per_second`, and the latency buckets are already rated by the platform's recording rules, so you query them bare — wrapping them in `rate()` again returns garbage. Finally, a workload's in-pod `CPLN_TOKEN` cannot authenticate to the metrics endpoint; querying from outside the mesh needs a user or service-account token. +Control Plane stores every workload's metrics as Prometheus-compatible time series in a managed backend (Mimir), queryable in PromQL through the per-org managed Grafana or the MCP tools. The org is the tenant: it comes from the endpoint path, so there is no `org=` label and no cross-org queries. Two traps dominate. **Series names are short:** memory is `mem_used` / `mem_reserved` / `mem_billable`, not `memory_*`; a `memory_used` query returns nothing, so ground names first with `query_metrics` without a `query`. **Rate-shaped metrics are pre-rated:** `egress`, `requests_per_second`, and the latency buckets are already rated by the platform's recording rules, so you query them bare; wrapping them in `rate()` again returns garbage. Finally, a workload's in-pod `CPLN_TOKEN` cannot authenticate to the metrics endpoint; querying from outside the mesh needs a user or service-account token. ## Two ways to query -- **MCP (primary for agents):** `mcp__cpln__query_metrics` runs a PromQL query — a range query over the last `1h` at `60s` step by default; pass `resolution: "instant"` for a single point, or `since` / `from` / `to` / `step` to adjust. `mcp__cpln__list_metrics` discovers the metric names and real label values present in the org right now (built-in, `kube_`/`node_`, and custom); pass `metric:` to ground one metric's live labels before filtering. Reach for it whenever a query returns no series. Measure first, then change scaling settings. +- **MCP (primary for agents):** `mcp__cpln__query_metrics` runs a PromQL `query`: a range query over the last `1h` at `60s` step by default; pass `resolution: "instant"` for a single point, or `since` / `from` / `to` / `step` to adjust. Without a `query`, it lists the documented metric catalog, the documented and custom metric names live in the org right now, and a count of `kube_*` and `node_*` series (`filter` lists those); pass `metric:` to get one metric's live label values before filtering. List them whenever a query returns no series. Measure first, then change scaling settings. - **Grafana:** the managed per-org instance — open **Metrics** in the Console sidebar (or the **Metrics** link on any workload), use **Explore** for ad-hoc PromQL, and dashboards/alerting for the rest. The `grafanaAdmin` org permission grants the Grafana Admin role; everyone else is Viewer. ## PromQL: query the right shape @@ -32,7 +32,7 @@ sum by (gvc, workload) (increase(container_restarts[5m])) # restarts i ## Built-in metrics -Collected for every workload, no configuration. Names and types below are the recording-rule outputs (the queryable series). Call `list_metrics` for the complete live set, including your custom metrics. +Collected for every workload, no configuration. Names and types below are the recording-rule outputs (the queryable series). Call `query_metrics` without a `query` for the complete live set, including your custom metrics. **Resource & network** (per replica): `cpu_used` / `cpu_reserved` / `cpu_billable` (cores, gauge); `mem_used` / `mem_reserved` / `mem_billable` (bytes, gauge); `egress` / `cross_zone_traffic` (bytes/minute, pre-rated gauge); `replica_count` / `workload_ready_replicas` / `workload_desired_replicas` (gauge). @@ -48,7 +48,7 @@ mk8s clusters with metrics enabled also expose `kube_*` (kube-state-metrics) and ## Custom metrics -A container exposes Prometheus-format metrics by declaring a `metrics` block; the platform scrapes every replica every **30 seconds** (5s timeout). Set it at creation with `mcp__cpln__create_workload` or add it later with `mcp__cpln__update_workload`; if the typed tool doesn't surface the nested field, fall back to `mcp__cpln__get_resource_schema` for `workload` then `cpln apply -f workload.yaml`. +A container exposes Prometheus-format metrics by declaring a `metrics` block; the platform scrapes every replica every **30 seconds** (5s timeout). Set it at creation with `mcp__cpln__create_workload` or add it later with `mcp__cpln__update_workload`; if the typed tool doesn't surface the nested field, fall back to `mcp__cpln__get_resource` with `schema: true` for `workload`, then `cpln apply -f workload.yaml`. ```yaml spec: @@ -76,7 +76,7 @@ Tracing answers a different question than metrics: not "is latency high?" but ** `customTags` adds fixed key/values to every span (each value max 50 chars). Only requests served after enablement, in the sampled fraction, produce traces. Apps wanting to emit their own spans to the `controlplane` provider send OTLP to `tracing.controlplane:80` (gRPC) or `tracing.controlplane:4318` (HTTP). -Query the built-in backend with `mcp__cpln__query_traces`, newest first: structured params (`gvc`, `workload`, `location`, `httpMethod: "POST"`, `requestId` from an access or request log line, `errorsOnly`, `minDuration: "500ms"`) or a raw `traceql` query that replaces them. Span attributes: `resource.gvc`, `resource.workload`, `resource.location`, `span.http.method`, `span.http.url` (the full URL), `span.http.status_code` (a string, `"503"`), `span."guid:x-request-id"`. Then `mcp__cpln__get_trace` reads one trace's span tree, with each span's kind, method, path, and status, to name the slow or failed span. **Empty results are usually configuration:** confirm tracing is enabled, sampling catches traffic, and the window saw requests. Triage flow: `query_traces` (`minDuration` or `errorsOnly`) to the worst trace, `get_trace` to the culprit span, then `mcp__cpln__get_workload_logs` for the application error, over the same window or filtered to the request id `get_trace` shows. +Query the built-in backend with `mcp__cpln__query_traces`, newest first: structured params (`gvc`, `workload`, `location`, `httpMethod: "POST"`, `requestId` from an access or request log line, `errorsOnly`, `minDuration: "500ms"`) or a raw `traceql` query that replaces them. Span attributes: `resource.gvc`, `resource.workload`, `resource.location`, `span.http.method`, `span.http.url` (the full URL), `span.http.status_code` (a string, `"503"`), `span."guid:x-request-id"`. Then `mcp__cpln__query_traces` with one trace's `traceId` reads its span tree, with each span's kind, method, path, and status, to name the slow or failed span. **Empty results are usually configuration:** confirm tracing is enabled, sampling catches traffic, and the window saw requests. Triage flow: `query_traces` (`minDuration` or `errorsOnly`) to the worst trace, `query_traces` with its `traceId` to the culprit span, then `mcp__cpln__get_workload_logs` for the application error, over the same window or filtered to the request id the trace shows. ## Built-in Grafana alert rules @@ -92,7 +92,7 @@ The managed Grafana provisions five rules, all annotated to the `cpln-metrics-ov ## Retention & billing -Retention and default alert recipients live in the org `observability` block. No typed MCP tool edits it (the `org-management` skill owns org-spec edits) — apply via CLI: `mcp__cpln__get_resource_schema` for `org`, then `cpln apply -f org.yaml`. +Retention and default alert recipients live in the org `observability` block, set with `mcp__cpln__update_org` (needs `?toolsets=full`; the `org-management` skill owns org-spec edits). CLI fallback: `mcp__cpln__get_resource` with `schema: true` for `org`, then `cpln apply -f org.yaml`. ```yaml kind: org @@ -147,13 +147,13 @@ This skill covers only which scaling metrics each workload type allows; for stra - **Metrics endpoint:** `https://metrics.cpln.io/metrics/org/{ORG}` (federation adds `/api/v1/federate`). - **Permission:** `readMetrics` (federation endpoint + Grafana data source). -- No typed tool edits the org `observability` block, the GVC `tracing` block, or a container `metrics` block — fall back to `get_resource_schema` + `cpln apply`. +- Typed tools set each block: the org `observability` block with `update_org` (needs `?toolsets=full`), the GVC `tracing` block with `create_gvc` / `update_gvc`, and a container `metrics` block with `create_workload` / `update_workload`. Without them: `get_resource` with `schema: true`, then `cpln apply`. ## Troubleshooting | Symptom | Cause and fix | |:---|:---| -| Query returns no series | Wrong name — memory is `mem_used`, not `memory_used`; run `list_metrics` to confirm live names | +| Query returns no series | Wrong name: memory is `mem_used`, not `memory_used`; run `query_metrics` without a `query` to confirm live names | | `egress`/latency values look tiny or wrong | Pre-rated series wrapped in `rate()` — query `egress` bare, latency via `histogram_quantile(..., request_duration_ms_bucket)` | | Custom `metrics` block rejected | `port` is reserved (`9090`/`9091`/`15000`+) or below 80 — use `9100`/`2112` | | Custom metrics never appear | Names prefixed `cpln_` are dropped; scrape runs every 30s — allow a cycle | diff --git a/plugins/cpln/skills/migration-patterns/SKILL.md b/plugins/cpln/skills/migration-patterns/SKILL.md index 884eea6..42e63df 100644 --- a/plugins/cpln/skills/migration-patterns/SKILL.md +++ b/plugins/cpln/skills/migration-patterns/SKILL.md @@ -98,7 +98,7 @@ The decisive question for any bind-mounted file: **does it change between enviro Baking config into the image couples that image to one environment: a hostname or feature-flag change then forces a rebuild. Mounting application content as secret volumes is the opposite mistake — it decouples content from its image version and makes rollbacks strange. A single container's migration is usually **mixed**, decided file by file. Rule of thumb: if changing the file between environments would not count as a code change, it is config and belongs in a secret volume. -Workloads mount secrets as read-only files via `cpln://secret/` volumes (the `workload`/`stateful-storage` skills own the mechanism; `get_resource_schema` for `workload` gives the exact shape): +Workloads mount secrets as read-only files via `cpln://secret/` volumes (the `workload`/`stateful-storage` skills own the mechanism; `get_resource` with `schema: true` for `workload` gives the exact shape): - **Opaque** (single config file): the path needs at least one subpath; the last segment becomes the file name and holds the `payload`. - **Dictionary** (multi-key ConfigMap): mount the secret at a directory path and each key becomes a file. @@ -118,7 +118,7 @@ Release-name rules, `--history-limit`, OCI charts, and `--wait` are general helm ## Exporting to Terraform / IaC -When the target is Infrastructure-as-Code rather than live resources, turn the converted Control Plane YAML into HCL with `mcp__cpln__convert_to_terraform` (dry-run validated against the API first, so the HCL always matches a schema-valid resource), or capture already-created resources with `mcp__cpln__export_terraform`. The `iac-terraform-pulumi` skill owns the full Terraform/Pulumi story, including `terraform import`. +When the target is Infrastructure-as-Code rather than live resources, turn the converted Control Plane YAML into HCL with `mcp__cpln__export_terraform` and its `manifest` (dry-run validated against the API first, so the HCL always matches a schema-valid resource), or capture already-created resources with the same tool from their self links. The `iac-terraform-pulumi` skill owns the full Terraform/Pulumi story, including `terraform import`. ## Verify diff --git a/plugins/cpln/skills/mk8s-byok/SKILL.md b/plugins/cpln/skills/mk8s-byok/SKILL.md index 8efe3d4..2ffa84b 100644 --- a/plugins/cpln/skills/mk8s-byok/SKILL.md +++ b/plugins/cpln/skills/mk8s-byok/SKILL.md @@ -44,11 +44,11 @@ Exactly one provider per cluster (the schema enforces XOR). For every provider e | `triton` | **keypair** secret (`connection.privateKeySecretLink`) | `packageId` | `location` | | `generic` | none — you join your own nodes | n/a (external nodes) | `location` | -**Azure uses an `opaque` secret, not an `azure-sdk` secret** — the create tool rejects the typed one. Triton/Generic/Ephemeral `location` is a *Control Plane* location (e.g. `aws-us-east-2`), not a cloud region. A 12th provider, `ephemeral`, exists in the schema but has **no create tool or CLI create** — ignore it for real clusters. Other required fields (network/VPC, image, SSH keys, region enum) vary per provider; `mcp__cpln__get_resource_schema` (kind `mk8s`) and the create tool's own validation give the exact required set. Generic nodes you supply each need Linux kernel ≥ 5.4, ≥ 1 CPU / 512 MB, mutual connectivity, and SSH access. +**Azure uses an `opaque` secret, not an `azure-sdk` secret**: the platform checks it before creating the cluster and refuses any other type; the payload is JSON with `appId`, `password`, and `tenant`. Triton/Generic/Ephemeral `location` is a *Control Plane* location (e.g. `aws-us-east-2`), not a cloud region. A 12th provider, `ephemeral`, exists in the schema and `create_mk8s` accepts it, but its nodes run as containers, at most 4 per pool, with no autoscaler: ignore it for real clusters. Other required fields (network/VPC, image, SSH keys, region enum) vary per provider; `mcp__cpln__get_resource` (kind `mk8s`, `schema: true`) and the create tool's own validation give the exact required set. Generic nodes you supply each need Linux kernel ≥ 5.4, ≥ 1 CPU / 512 MB, mutual connectivity, and SSH access. ## The cluster spec essentials -- **`version`** — required, no default, a **closed enum** of specific patch versions (currently `1.26.0` through `1.35.3`). The set drifts as versions are added/retired; pull the live list from `get_resource_schema`, or just submit and let the typed tool's validation error name the valid values. Updating it is **upgrade-only** — mk8s rejects downgrades. +- **`version`**: required, no default, a **closed enum** of specific patch versions (currently `1.26.0` through `1.35.3`). The set drifts as versions are added/retired; pull the live list from `get_resource` with `schema: true`, or just submit and let the typed tool's validation error name the valid values. Updating it is **upgrade-only**: mk8s rejects downgrades. - **`nodePools`** (per provider) — give at least one to get worker capacity. Common fields are `name`/`labels`/`taints`; the rest are provider-specific. Each pool's **`minSize`/`maxSize` drive the cluster autoscaler** (set `maxSize > minSize` to allow scale-up). - **`autoscaler`** (per provider) — defaults: `expander: [most-pods]`, `unneededTime: 10m`, `unreadyTime: 20m`, `utilizationThreshold: 0.7`. Usually leave it. - **`networking`** (per provider) — `serviceNetwork` (default `10.43.0.0/16`) and `podNetwork` (default `10.42.0.0/16`) must differ and are **unmodifiable after creation**; pick non-overlapping CIDRs up front. AWS and GCP additionally accept `podNetwork: vpc`. @@ -80,11 +80,11 @@ Exactly one provider per cluster (the schema enforces XOR). For every provider e ## Create & update (MCP) -`mcp__cpln__create_mk8s` takes `provider` (any row of the table above) and `spec`, the provider block; the tool names the fields the provider requires, and `get_resource_schema` (kind `mk8s`, path `spec.provider.`) has the exact shape. Supply `version` and at least one node pool. Read with `mcp__cpln__get_resource` / `list_resources` (kind `mk8s`); delete with `mcp__cpln__delete_resource` (destructive — confirm the blast radius). +`mcp__cpln__create_mk8s` takes `provider` (any row of the table above) and `spec`, the provider block; the tool names the fields the provider requires, and `get_resource` (kind `mk8s`, `schema: true`, path `spec.provider.`) has the exact shape. Supply `version` and at least one node pool. Read with `mcp__cpln__get_resource` / `list_resources` (kind `mk8s`); delete with `mcp__cpln__delete_resource` (destructive: confirm the blast radius). `mcp__cpln__update_mk8s` (same `provider`, `spec` with the changed fields, `removeSpecFields` to delete one) is a **merge-patch**: send only what changes. Provided **arrays** (`nodePools`, `firewall`) **replace the previous values wholesale** — include the full set you want to keep. `addOns` merge-patches per key, so the update tool **cannot disable a toggle add-on by passing `false`** — remove one with `cpln apply` (set the key to `null`). `region`/`networking` and the provider/name are unmodifiable after creation. -Fallback (MCP unavailable, or CI/CD): author a YAML manifest from `get_resource_schema` (kind `mk8s`) and `cpln apply --file mk8s.yaml`. +Fallback (MCP unavailable, or CI/CD): author a YAML manifest from `get_resource` (kind `mk8s`, `schema: true`) and `cpln apply --file mk8s.yaml`. ## CLI (mk8s) @@ -130,7 +130,7 @@ Once the location exists, prefer MCP for the GVC and workload work: `mcp__cpln__ | Symptom | Cause and fix | |:---|:---| -| Version create/update rejected | `version` must be in the closed enum, and updates are **upgrade-only** (no downgrade); read the valid set from `get_resource_schema` or the error. | +| Version create/update rejected | `version` must be in the closed enum, and updates are **upgrade-only** (no downgrade); read the valid set from `get_resource` with `schema: true` or the error. | | Create rejected: secret type | Azure needs an **opaque** secret (not `azure-sdk`); GCP needs a **gcp** secret; Triton a **keypair** secret; token providers an **opaque** secret. Create it first. | | Cluster reachable from anywhere | The API-server `firewall` defaulted to `0.0.0.0/0` — set it to your admin CIDRs. | | Update wiped node pools / a rule | `nodePools` and `firewall` arrays replace wholesale on update — resend the full set. | diff --git a/plugins/cpln/skills/native-networking/SKILL.md b/plugins/cpln/skills/native-networking/SKILL.md index ddee9d5..10ebc16 100644 --- a/plugins/cpln/skills/native-networking/SKILL.md +++ b/plugins/cpln/skills/native-networking/SKILL.md @@ -5,7 +5,7 @@ description: "Connects Control Plane workloads to private VPCs, on-prem networks # Native Networking & Agent Connectivity -> **Tool availability:** the agent and identity network-resource tools need `?toolsets=full`; reconnect with it or use the CLI. +> **Tool availability:** the agent tools, the identity network-resource tools, and `create_identity` need `?toolsets=full`; reconnect with it or use the CLI. A Control Plane workload reaches a private or cross-cloud endpoint through an **identity** (gvc-scoped) carrying one of two resource arrays. Attach that identity to the workload (`spec.identityLink`) — without the attachment, nothing routes. Both paths are wired **independently of the workload's external egress firewall**: you do *not* open an `outboundAllow*` rule to reach them. The two options: diff --git a/plugins/cpln/rules/cpln-guardrails.md b/plugins/cpln/skills/operating-guide/SKILL.md similarity index 87% rename from plugins/cpln/rules/cpln-guardrails.md rename to plugins/cpln/skills/operating-guide/SKILL.md index 8a869ce..c07fa0e 100644 --- a/plugins/cpln/rules/cpln-guardrails.md +++ b/plugins/cpln/skills/operating-guide/SKILL.md @@ -1,6 +1,6 @@ --- -description: Control Plane operating guide for AI agents. The platform facts tools do not enforce or report, the high-impact approval rule, secrets beyond the core rules, targets, CLI fallback, and failure handling. Read it when a task goes beyond what the job tools cover. -alwaysApply: false +name: operating-guide +description: "Control Plane operating guide: platform facts tools do not enforce or report, high-impact approvals, secrets beyond the core rules, targets, CLI fallback, failures. Use when a task goes beyond what the job tools cover." --- # Control Plane Operating Guide @@ -12,10 +12,10 @@ The core rules arrive with every MCP connection. This guide holds only what they A destructive call needs the user's explicit approval after you say what it removes or breaks. Three kinds need a fresh yes that answers the stated blast radius, even when the opening message already asked: - **Cascades:** deleting a GVC removes every workload and identity in it; the platform refuses while a volume set remains. -- **Data loss:** deleting, shrinking, or restoring volumes and snapshots; uninstalling a template release deletes its volume data. +- **Data loss:** deleting or restoring volumes and snapshots; uninstalling a template release deletes its volume data. - **Production targets:** a name that says so, or public traffic, custom domains, several replicas, or real users. -Also destructive: removing bindings, members, routes, locations, or policies; changing a workload's type or name, or a volume set's filesystem or performance class, which means delete and recreate. Hesitation, "maybe", or a counter-question is not approval. A resource you created by mistake this session, and only that, you remove and report. +Also destructive: removing bindings, members, routes, locations, or policies; shrinking a volume, which moves its data to a new volume and restarts its replica; changing a workload's type or name, or a volume set's filesystem or performance class, which means delete and recreate. Hesitation, "maybe", or a counter-question is not approval. A resource you created by mistake this session, and only that, you remove and report. ## Reads @@ -46,7 +46,7 @@ The tag `cpln/managedByTerraform: "true"` marks a resource Terraform or Pulumi o - **Shutdown:** the default `preStop` runs `sleep`; an image without it, or a failing custom `preStop`, kills every container at once. A container running as UID 1337 bypasses the mesh, losing mTLS and firewall enforcement. - **Hand-written specs:** ports go in `containers[].ports`, never the deprecated `port`; custom domains use the Domain resource, never the GVC's deprecated `spec.domain`. - **Domains** stay pending until their DNS records resolve. Pending is a wait, not an error to retry. -- **Public** needs both an external inbound and an external outbound CIDR. +- **Public** means external inbound allows `0.0.0.0/0` or `::/0`; outbound is a separate list, which the `public: true` shortcut of `create_workload` and `update_workload` also opens. - **Reachability:** after ready, a real HTTP GET of the canonical URL settles it. 2xx, 3xx, 401, and 403 mean serving; a timeout points at firewall inbound; a TLS or DNS error means propagation, so wait. Never claim reachability without a response. - **App code:** before changing an app's code, `get_app_files` with the NAME from `//image/NAME:TAG` says where the code lives. Never rewrite an app from scratch under an existing name. - **Other databases, caches, queues, and search** come from the Template Catalog, never built by hand. diff --git a/plugins/cpln/skills/org-management/SKILL.md b/plugins/cpln/skills/org-management/SKILL.md index 654979b..c1cfbb8 100644 --- a/plugins/cpln/skills/org-management/SKILL.md +++ b/plugins/cpln/skills/org-management/SKILL.md @@ -5,7 +5,7 @@ description: "Manages organizations, billing, users, and authentication on Contr # Organization & User Management -> **Tool availability:** `update_org`, `configure_external_logging`, `invite_user_to_org`, `edit_group`, and `add_key_to_service_account` need `?toolsets=full`; reconnect with it or use the CLI. +> **Tool availability:** `update_org`, `configure_external_logging`, `invite_user_to_org`, `edit_group`, `create_policy`, and `add_key_to_service_account` need `?toolsets=full`; reconnect with it or use the CLI. An **org** is the top-level isolation boundary: every GVC, workload, secret, policy, image, domain, user, group, and service account lives inside one, with no cross-org sharing. An org **cannot be renamed or deleted** once created (every DELETE on `/org` returns 405) and its name is **globally unique** across all of Control Plane — so the first job is choosing a name you can live with permanently. @@ -40,7 +40,7 @@ Read with `mcp__cpln__get_resource` (kind `org`); change with `mcp__cpln__update | `observability.defaultAlertEmails` | Yes | Default Grafana alert recipients | | `security.threatDetection` | Yes | Forward detected threats to a syslog target (`enabled` + optional `minimumSeverity` + syslog host/port) | | `logging` / `extraLogging` | **No** | Use `mcp__cpln__configure_external_logging` — see **external-logging** | -| `tracing` | **No** | Escape hatch: `mcp__cpln__get_resource_schema` (kind `org`), author the block, `cpln apply -f org.yaml` | +| `tracing` | **No** | Escape hatch: `mcp__cpln__get_resource` (kind `org`, `schema: true`), author the block, `cpln apply -f org.yaml` | ## Billing diff --git a/plugins/cpln/skills/setup-agent/SKILL.md b/plugins/cpln/skills/setup-agent/SKILL.md index 774f8c5..d8f8e07 100644 --- a/plugins/cpln/skills/setup-agent/SKILL.md +++ b/plugins/cpln/skills/setup-agent/SKILL.md @@ -5,7 +5,7 @@ description: Deploys a Control Plane wormhole agent connecting workloads to priv # Agent Setup -> **Tool availability:** the agent and identity network-resource tools need `?toolsets=full`; reconnect with it or use the CLI. +> **Tool availability:** the agent tools, the identity network-resource tools, `create_identity`, and `update_identity` need `?toolsets=full`; reconnect with it or use the CLI. A wormhole agent is a lightweight VM or container you run **inside the target network**. It opens a persistent **outbound** connection to Control Plane and tunnels workload traffic to any TCP/UDP endpoint on the private side — VPC, on-prem, data center, Azure VNet, cross-cloud, or a laptop. A workload reaches the endpoint by attaching an **identity** (gvc-scoped) that carries a `networkResources` entry pointing at the agent. No external egress firewall rule is needed. diff --git a/plugins/cpln/skills/setup-cloud-access/SKILL.md b/plugins/cpln/skills/setup-cloud-access/SKILL.md index 7c4d476..7e48350 100644 --- a/plugins/cpln/skills/setup-cloud-access/SKILL.md +++ b/plugins/cpln/skills/setup-cloud-access/SKILL.md @@ -5,7 +5,7 @@ description: Credential-free cloud access (Universal Cloud Identity) for a Contr # Cloud Access Setup (Universal Cloud Identity) -> **Tool availability:** `create_cloud_account`, `update_cloud_account`, and `how_to_create_cloud_account` need `?toolsets=full`; `grant_cloud_access` is core. +> **Tool availability:** `create_cloud_account`, `update_cloud_account`, `how_to_create_cloud_account`, `create_identity`, and `update_identity` need `?toolsets=full`; `grant_cloud_access` is core. A workload reads cloud resources with **no embedded keys**: a GVC-scoped **identity** carries a per-provider cloud-access block that federates with the provider's IAM, and Control Plane vends short-lived credentials at runtime. Cloud SDKs (boto3, google-cloud, @azure/sdk) pick them up automatically — no SDK config. @@ -68,7 +68,7 @@ spec: policyRefs: ["aws::AmazonS3ReadOnlyAccess", "MyCustomPolicy"] ``` -CLI fallback (MCP unavailable / CI-CD): `cpln identity get NAME --gvc GVC -o yaml-slim > id.yaml`, add the block under `spec`, `cpln apply -f id.yaml`. Confirm the exact shape with `get_resource_schema` (kind `identity`) before authoring YAML by hand. +CLI fallback (MCP unavailable / CI-CD): `cpln identity get NAME --gvc GVC -o yaml-slim > id.yaml`, add the block under `spec`, `cpln apply -f id.yaml`. Confirm the exact shape with `get_resource` (kind `identity`, `schema: true`) before authoring YAML by hand. ## Step 4 — Link to the workload and verify diff --git a/plugins/cpln/skills/setup-secret/SKILL.md b/plugins/cpln/skills/setup-secret/SKILL.md index 33feec8..5e79f8c 100644 --- a/plugins/cpln/skills/setup-secret/SKILL.md +++ b/plugins/cpln/skills/setup-secret/SKILL.md @@ -21,10 +21,11 @@ A workload reads a secret only when three things are in place. Miss one and the ## Wiring access -- **`deploy_app`** wires all three steps for the references in its env. -- **`grant_workload_secret_access`** (`gvc`, `workloadName`, `secretName`) creates the identity if missing (default `{gvc}-{workloadName}`), creates or updates a `reveal` policy (default `{gvc}-{workloadName}-secrets-policy`), links the identity, and redeploys a workload already waiting on the secret. It does not add the reference. The workload must exist first: create it (its deployment pauses on the reference), then grant, and it resumes. +- **`deploy_app`** wires all three steps for the references in its env, and refuses a referenced secret that does not exist before it builds or writes anything. +- **`grant_workload_secret_access`** (`gvc`, `workloadName`, `secretName`) creates the identity if missing (default `{gvc}-{workloadName}`), creates or updates a `reveal` policy (default `{gvc}-{workloadName}-secrets-policy`), links the identity, and redeploys a workload already waiting on the secret. Before writing anything it checks that the secret exists and that an existing policy of that name targets secrets. It does not add the reference. The workload must exist first: create it (its deployment pauses on the reference), then grant, and it resumes. - The platform checks access once per deployed version. A version it refused stays refused after the policy changes, until a new version deploys, so the tool grants before it links and redeploys a workload still waiting. -- **By hand**, only when the tool cannot: `create_identity`, then `create_policy` with target kind `secret` and a `reveal` binding for the identity (`access-control` skill), then `update_workload` to set `spec.identityLink` last. +- **By hand**, only when the tool cannot: `create_identity`, then `create_policy` (both need `?toolsets=full`) with target kind `secret` and a `reveal` binding for the identity (`access-control` skill), then `update_workload` to set `spec.identityLink` last. +- **Revoking:** `grant_workload_secret_access` with `remove: true` takes the secret out of that policy (deleting the policy once it targets nothing) and keeps the identity; it refuses, changing nothing, a policy that also binds another principal or grants by `target: all` or a query. Also drop the `cpln://secret/` reference with `update_workload`: a deploy that still references a revoked secret fails, and running replicas keep the value until they are replaced. - Identities are GVC-scoped: one per workload, shareable within a GVC, never across GVCs. ## References @@ -73,7 +74,7 @@ data: >- | `gcp` | **JSON string** | a full service-account key: `type`, `project_id`, `private_key_id`, `private_key`, `client_email`, `client_id`, `auth_uri`, `token_uri`, `auth_provider_x509_cert_url`, `client_x509_cert_url` | | `azure-sdk` | **JSON string** | `subscriptionId`, `tenantId`, `clientId` (UUIDs) and `clientSecret` | -`get_resource_schema` (kind "secret") has the apply schema and REST endpoints. +`get_resource` (kind "secret", `schema: true`) has the apply schema and REST endpoints. ## Verify diff --git a/plugins/cpln/skills/stateful-storage/SKILL.md b/plugins/cpln/skills/stateful-storage/SKILL.md index ddb27d5..63c6b52 100644 --- a/plugins/cpln/skills/stateful-storage/SKILL.md +++ b/plugins/cpln/skills/stateful-storage/SKILL.md @@ -5,8 +5,6 @@ description: "Creates persistent storage for stateful workloads on Control Plane # Stateful Storage & VolumeSets -> **Tool availability:** `delete_volumeset_snapshot`, `shrink_volumeset`, and `delete_volumeset_volume` need `?toolsets=full`; reconnect with it or use the CLI. - A **VolumeSet** is GVC-scoped persistent storage for workloads. The `workload` skill covers the basics (stateful type, reserved mount paths, the 15-volume limit, create-then-verify); this skill is the full volume-set detail. The one trap that drives most rework: **`fileSystemType` and `performanceClass` are immutable** (a PATCH that changes either returns HTTP 400) — to change either you must create a new volumeset, and the old data does not carry over. Choose both at creation. **Most databases don't need this skill:** `mcp__cpln__add_database` installs Postgres, MySQL, MariaDB, MongoDB, or Redis with the volume set and generated credentials wired, and the `template-catalog` skill covers the rest. An app that only needs a data directory passes `storage` to `mcp__cpln__deploy_app`, which creates and mounts the volume set and picks the workload type. Hand-build only for anything else. @@ -29,7 +27,7 @@ When `fileSystemType: shared`, `performanceClass` is **auto-set to `shared`** ## Create a volumeset -Use `mcp__cpln__create_volumeset` (MCP create/mount tools default `fileSystemType` to **xfs** and `performanceClass` to `general-purpose-ssd`; the raw API/`cpln apply` default is **ext4**). YAML for IaC / CLI fallback: +`mcp__cpln__mount_volumeset_to_workload` creates the volume set when given a size and mounts it in the same call (see Mount below); `mcp__cpln__create_volumeset` (needs `?toolsets=full`) creates one alone. MCP create/mount tools default `fileSystemType` to **xfs** and `performanceClass` to `general-purpose-ssd`; the raw API/`cpln apply` default is **ext4**. YAML for IaC / CLI fallback: ```yaml kind: volumeset @@ -99,13 +97,15 @@ spec: ## Snapshots -Snapshots are **ext4/xfs only — never `shared`**. Automatic policy lives in `spec.snapshots`: `createFinalSnapshot` (default `true` — a snapshot is taken before any volume in the set is deleted), `retentionDuration`, and `schedule` (cron whose minute field must be a single concrete value, so no more than once per hour). Manual: `mcp__cpln__create_volumeset_snapshot`, `list_volumeset_snapshots`, `restore_volumeset_snapshot`, `delete_volumeset_snapshot`. A restore creates a **new volume** and discards everything written since the snapshot. +Snapshots are **ext4/xfs only, never `shared`**. Automatic policy lives in `spec.snapshots`: `createFinalSnapshot` (default `true`: a snapshot is taken before any volume in the set is deleted), `retentionDuration`, and `schedule` (cron whose minute field must be a single concrete value, so no more than once per hour). Manual: `mcp__cpln__run_volumeset_command` with `createVolumeSnapshot`, `restoreVolume`, or `deleteVolumeSnapshot`; `mcp__cpln__get_resource` (kind `volumeset`) lists them. A restore creates a **new volume** and discards everything written since the snapshot. ## Resize and delete volumes -- **Expand** is live, with no downtime, on every filesystem; `expand_volumeset` states its throttle. -- **Shrink** (ext4/xfs only) — data is migrated to the new smaller volume via an online presync + final delta sync, and the replica restarts during the swap. The platform **rejects the shrink with HTTP 400 when known used bytes (+5% metadata headroom) would not fit**; data is only lost if used bytes genuinely exceed the new capacity. Floor is the class minimum (10 / 200 GB). `mcp__cpln__shrink_volumeset`. -- **Delete a volume** (ext4/xfs only) — permanent loss of that volume's data. `mcp__cpln__delete_volumeset_volume`. +Each of these is one `mcp__cpln__run_volumeset_command` call on a volume picked by `location` and `volumeIndex`; it returns a command id that `get_command` follows until the command completes. + +- **Expand** (`expandVolume`) is live, with no downtime, on every filesystem, at most 4 times per volume per rolling 24 hours. +- **Shrink** (`shrinkVolume`, ext4/xfs only): data is migrated to the new smaller volume via an online presync + final delta sync, and the replica restarts during the swap. The platform **refuses the shrink with HTTP 400 below the volume set's `initialCapacity`, below used bytes plus 5% metadata headroom, or when it cannot read the volume's used bytes**, and a shrink that fails keeps the old volume. Floor is the class minimum (10 / 200 GB). +- **Delete a volume** (`deleteVolume`, ext4/xfs only): permanent loss of that volume's data. Shrink, volume-delete, snapshot-delete, and restore are destructive: **snapshot first** as the recovery net, then present the blast radius and get the user's approval before the call (it runs at once, with no server-side preview). diff --git a/plugins/cpln/skills/tag/SKILL.md b/plugins/cpln/skills/tag/SKILL.md index 47f0d85..cf91fd3 100644 --- a/plugins/cpln/skills/tag/SKILL.md +++ b/plugins/cpln/skills/tag/SKILL.md @@ -27,7 +27,7 @@ The payoff is **retroactive and self-maintaining**: tag a new workload `environm | CLI, dedicated | `cpln KIND tag NAME --tag key=value` (repeatable); `--remove-tag key` drops one | | CLI, on create | `cpln KIND create ... --tag key=value` | | CLI, generic update | `cpln KIND update NAME --set tags.key=value` (kinds with no `tag` subcommand, e.g. `user`) | -| MCP | The `mcp__cpln__create_*` / `update_*` tool for the kind accepts a `tags` object | +| MCP | Each kind's `mcp__cpln__create_*` and `update_*` tool takes `tags` as a list of `{key, value}` pairs, as do `edit_group` and `edit_audit_context` (`?toolsets=full`); updates merge them into the existing tags, and `removeTagKeys` drops keys. Exceptions: `create_secret` and `update_org` take no tags, and `update_mk8s` takes no `removeTagKeys` | | Manifest | A top-level `tags:` map, then `cpln apply -f FILE` | ```bash diff --git a/plugins/cpln/skills/template-catalog/SKILL.md b/plugins/cpln/skills/template-catalog/SKILL.md index 065b51f..2734a8b 100644 --- a/plugins/cpln/skills/template-catalog/SKILL.md +++ b/plugins/cpln/skills/template-catalog/SKILL.md @@ -11,21 +11,21 @@ Production-tested charts (Helm under the hood) for databases, caches, queues, se ## Find the right template -Call `browse_templates` with `query` naming the capability or product needed. When the user describes a goal or a problem rather than a component ("my site is slow", "users should sign in with Google"), decide the capability it needs and search for that ("cache for database queries", "identity provider with Google login"); a goal searched in the user's own words ranks poorly. Recommend the result with what it does and why it fits. Take the first result unless its confidence is low or one of its `pickInsteadIf` needs matches the user; then use the template that entry names. A low-confidence first result is a guess: search again naming the capability, or ask the user about their goal. Each result also names its `variants` (the same software in other topologies), `related` templates (a `companion` is often installed alongside), and `includes` (bundled templates that install with it, never separately). Without `query`, `browse_templates` lists the catalog and its categories, or one `category`. +Call `browse_templates` with `query` naming the capability or product needed. When the user describes a goal or a problem rather than a component ("my site is slow", "users should sign in with Google"), decide the capability it needs and search for that ("cache for database queries", "identity provider with Google login"); a goal searched in the user's own words ranks poorly. Recommend the result with what it does and why it fits. Take the first result unless its confidence is low or one of its `pickInsteadIf` needs matches the user; then use the template that entry names. A low-confidence first result is a guess: search again naming the capability, or ask the user about their goal. Each result also names its `variants` (the same software in other topologies), `related` templates (a `companion` is often installed alongside), and `includes` (bundled templates that install with it, never separately). Without `query`, `browse_templates` lists the catalog and its categories, or one `category`; with a template's `name`, it returns that template's detail. ## Credentials: create the prerequisite secret first -- Every search result and `get_template` list the template's prerequisites. A required secret comes with its `secretType`, its `keys`, and the `valuesPath` that takes its name; an optional one names the values that turn it on (`when`). +- Every search result and the template's detail (`browse_templates` with its `name`) list the template's prerequisites. A required secret comes with its `secretType`, its `keys`, and the `valuesPath` that takes its name; an optional one names the values that turn it on (`when`). - A missing secret does not fail the install: the release installs and the workload **wedges silently**, with no logs. So `install_template` and `upgrade_template` refuse, creating nothing, while the release would read a required secret that does not exist or has another type (they render it to confirm the read). A secret named inside a list, such as a list of users, is not checked. -- `values` key names differ per template (secret names, resources, access scope): copy them from `get_template`, never from memory. +- `values` key names differ per template (secret names, resources, access scope): copy them from the template's detail, never from memory. - Create it with `create_secret` before installing: `values: "generate"` for passwords nobody needs to know, `values: "user"` for a key the user already has (they type it into the Console). Then put its name in `values`. -- Never write a password or key into `values`: values pass through the chat and are stored in the release. A template that still takes a secret value directly in `values` (`get_template` says when its example values do) is installed from the Console, or with `cpln helm install -f` and a values file the user fills in locally. +- Never write a password or key into `values`: values pass through the chat and are stored in the release. A template that still takes a secret value directly in `values` (its detail says when its example values do) is installed from the Console, or with `cpln helm install -f` and a values file the user fills in locally. ## Install (MCP) -1. `get_template `: copy the example `values.yaml`; set the prerequisite secret names, replica count, resources, storage size, and access scope. It also returns the README's important notes. When a prerequisite has a `when` condition or the values are unclear, read the README's prerequisites with `get_template` and `readmeSection: "prerequisites"`; a README without that section answers with the sections it has. +1. `browse_templates` with the template's `name`: copy the example `values.yaml`; set the prerequisite secret names, replica count, resources, storage size, and access scope. It also returns the README's important notes. When a prerequisite has a `when` condition or the values are unclear, add `readmeSection: "prerequisites"` to read that README section; a README without that section answers with the sections it has. 2. `install_template` with `dryRun: true`: renders the resources the install would create, without applying anything, and lists in `missingSecrets` the required secrets the release reads that are still missing. -3. `install_template` with a unique release `name` (immutable) and the `values` YAML (at most 128 KiB). **Omit `gvc` only for a template that creates its own** (`createsGvc` in the search result and `get_template`); every other template needs an existing `gvc`, and a multi-location template's `locations` must be locations that GVC already has. +3. `install_template` with a unique release `name` (immutable) and the `values` YAML (at most 128 KiB). **Omit `gvc` only for a template that creates its own** (`createsGvc` in the search result and the template's detail); every other template needs an existing `gvc`, and a multi-location template's `locations` must be locations that GVC already has. 4. Installs are asynchronous: wait with `get_installed_template` and `waitSeconds`. Its token needs `reveal` on the release's state secret. ## Configure and upgrade @@ -60,7 +60,7 @@ Reference `values.yaml` for any template lives in the [templates repo](https://g ## Connection details and backups - An installed service is reachable in its GVC at `-..cpln.local:`, for example `my-pg-postgres..cpln.local:5432`; the exact names are in the `get_installed_template` resources. Workloads read the credentials as `cpln://secret/NAME.KEY` from the prerequisite secret. -- Backups need the optional prerequisites `get_template` lists for them, such as a bucket, a cloud account, and on AWS a bucket-scoped IAM policy, referenced in the `values` backup block. +- Backups need the optional prerequisites the template's detail lists for them, such as a bucket, a cloud account, and on AWS a bucket-scoped IAM policy, referenced in the `values` backup block. ## Troubleshooting diff --git a/plugins/cpln/skills/workload-security/SKILL.md b/plugins/cpln/skills/workload-security/SKILL.md index e2e2004..66bf6cc 100644 --- a/plugins/cpln/skills/workload-security/SKILL.md +++ b/plugins/cpln/skills/workload-security/SKILL.md @@ -170,7 +170,7 @@ Each direct-LB location also gets a public Geo DNS address with latency-based ro ## Verify - After any change, wait with `mcp__cpln__list_deployments` and `waitSeconds` until each location reports ready: it surfaces probe failures per location. -- `mcp__cpln__get_workload_events` gives the probe/liveness failure reason and message; `mcp__cpln__get_workload_logs` shows app-side errors. +- `mcp__cpln__diagnose_workload` gives the probe/liveness failure reason and message from the newest events; `mcp__cpln__get_workload_logs` shows app-side errors. - For JWT, send a request with and without a valid token (expect 401 without) and confirm the `claim_to_headers` header arrives at the workload. ## Troubleshooting diff --git a/plugins/cpln/skills/workload-troubleshooting/SKILL.md b/plugins/cpln/skills/workload-troubleshooting/SKILL.md index c2a2b14..4993e0b 100644 --- a/plugins/cpln/skills/workload-troubleshooting/SKILL.md +++ b/plugins/cpln/skills/workload-troubleshooting/SKILL.md @@ -12,10 +12,10 @@ Maps a symptom to its platform-specific cause and a fix the schema accepts. Diag `mcp__cpln__diagnose_workload` first: one call reads the deployments, events, and error log lines, matches them against this catalog, and returns the likely cause with its evidence. When it is not conclusive: - `list_deployments`, with `location` for one location in full detail. -- `get_workload_events` for image pulls, crashes, scheduling, probe failures, and `OOMKilled`. +- `get_workload_events` (needs `?toolsets=full`) for event history past the 10 newest events `diagnose_workload` returns: image pulls, crashes, scheduling, probe failures, and `OOMKilled`. - `get_workload_logs`; the `_accesslog` container holds HTTP status codes and latency. -- `list_metrics`, then `query_metrics`, for memory, CPU, and latency pressure. -- `query_traces`, then `get_trace`, for a slow request; needs tracing on the GVC (`metrics-observability` skill). +- `query_metrics`, first without a `query` to list the metric names, for memory, CPU, and latency pressure. +- `query_traces`, then again with one trace's `traceId`, for a slow request; needs tracing on the GVC (`metrics-observability` skill). - In-container inspection goes through the CLI (`cpln` skill). ## Failure catalog @@ -51,7 +51,7 @@ Serverless gets TCP readiness and liveness on the container port; standard, stat ### Resources and Capacity AI -- CPU and memory must fit the org quota; `maxScale` times the per-replica resources is enforced at scheduling. +- CPU and memory must fit the org quota; `maxScale` times the per-replica resources is enforced at scheduling. A quota error names its quota (a workload's total CPU or memory error means `cpu-per-workload` or `memory-per-workload`); `request_quota_increase` asks for a higher max when the user wants one. - Capacity AI is off with the `cpu` metric or multi-metric scaling; check the stored `spec.defaultOptions.capacityAI` first. On cron a new reservation lands at the next run. - Stateful sizing, unless Capacity AI is on in `defaultOptions` and in every `localOptions` entry: `minCpu` to `cpu` at most 4 to 1 and 4000m apart; `minMemory` to `memory` at most 4 to 1 and 4096Mi apart. - Ephemeral storage is 1 GB per CPU core, at least 1 GB; exceeding it replaces the replica. diff --git a/plugins/cpln/skills/workload/SKILL.md b/plugins/cpln/skills/workload/SKILL.md index 027793f..bdb93a6 100644 --- a/plugins/cpln/skills/workload/SKILL.md +++ b/plugins/cpln/skills/workload/SKILL.md @@ -5,9 +5,9 @@ description: "Primary skill for creating, updating, running, and debugging workl # Workloads -> **Tool availability:** the `configure_workload_*` tools need `?toolsets=full`; `create_workload`, `update_workload`, and the job tools are core. +> **Tool availability:** the `configure_workload_*` tools and `promote_workload` need `?toolsets=full`; `create_workload`, `update_workload`, and the other job tools are core. -A workload is the unit of deployment: one to eight containers plus how they scale, get exposed, store data, and stay healthy. `mcp__cpln__deploy_app` covers a single-container HTTP app, image, or repository: a standard workload, with a data directory every replica shares (`storage` with `shared: true`), or a stateful workload on one replica when the data directory is per replica (`storage` without `shared`). `create_workload` and `update_workload` cover the rest: serverless, several containers, cron, non-HTTP ports, custom firewall rules, probes and scaling tuned in depth. `restart_workload`, `rollback_workload`, `promote_workload`, and `allow_workload_access` do those jobs in one call. +A workload is the unit of deployment: one to eight containers plus how they scale, get exposed, store data, and stay healthy. `mcp__cpln__deploy_app` covers a single-container HTTP app, image, or repository: a standard workload, with a data directory every replica shares (`storage` with `shared: true`), or a stateful workload on one replica when the data directory is per replica (`storage` without `shared`). `create_workload` and `update_workload` cover the rest: serverless, several containers, cron, non-HTTP ports, custom firewall rules, probes and scaling tuned in depth. `restart_workload`, `rollback_workload`, `promote_workload` (`?toolsets=full`), and `allow_workload_access` do those jobs in one call. ## Workload type (immutable, standard by default) @@ -39,7 +39,7 @@ A workload is the unit of deployment: one to eight containers plus how they scal | `securityOptions` (`runAsUser`, `filesystemGroupId`) | `configure_workload_security` | | `requestRetryPolicy` | `configure_workload_retry` | -`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. +`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. `start_workload_cron` runs a cron workload now, with optional `containerOverrides` for that run only; each call starts another run, and it returns a command id that `get_command` follows. ## Production defaults beyond the core rules @@ -98,5 +98,5 @@ Changing a workload's type or name means delete and recreate. Recreating under t ## Metrics and live replicas -- Custom Prometheus metrics: `containers[].metrics` with `port` and `path` (default `/metrics`). Query with `list_metrics`, then `query_metrics`; measure before changing scaling. -- `list_workload_replicas` lists replicas; a command inside one goes through the CLI (`cpln` skill), with confirmation for anything that changes state. +- Custom Prometheus metrics: `containers[].metrics` with `port` and `path` (default `/metrics`). List them with `query_metrics` without a `query`, then query them; measure before changing scaling. +- `list_deployments` names each location's running replicas, the `--replica` value for `cpln workload exec` and `cpln workload connect`; a command inside one goes through the CLI (`cpln` skill), with confirmation for anything that changes state. diff --git a/scripts/check-tool-mentions.mjs b/scripts/check-tool-mentions.mjs index 3346d52..afcd6cd 100644 --- a/scripts/check-tool-mentions.mjs +++ b/scripts/check-tool-mentions.mjs @@ -6,20 +6,19 @@ * MCP on ANY toolset profile (core ⊂ mk8s ⊂ full, core is the default), so: * * 1. A mentioned tool must EXIST in the registry — a stale name (a tool that was removed - * or renamed) sends the model into a guaranteed-failing call. + * or renamed) sends the model into a guaranteed-failing call. A name in the manifest's + * `removed` list, or a `name_*` wildcard of a removed family, is flagged even without a verb prefix. * 2. A tool beyond the core tier must be marked on the line with how to reach it * (`?toolsets=full` / `?toolsets=mk8s`) or the file must carry a "**Tool availability:**" * note, so a core-profile reader knows to ask the user to reconnect instead of improvising. * A `name_*` wildcard mentions its whole family and takes the family's highest tier. - * 3. `cpln_api_request` is registered only when its kill switch is on, so every mention - * needs an availability hedge ("disabled by default", "only when advertised", …). * * Deliberate "this tool does not exist" prose is fine: lines matching the negation * patterns (e.g. "There is no `create_user`") are exempt from the existence check. * * The `readonly` profile sits outside this tier ladder — it withholds every write tool, so * markers would have to sit on nearly every mention. Content covers it in prose instead: the - * guardrails define it, and availability notes name the tools that survive on it. + * operating guide defines it, and availability notes name the tools that survive on it. * * The manifest is generated from the MCP server's tool registry — regenerate it there after tool changes. * @@ -32,8 +31,13 @@ import { fileURLToPath } from 'node:url'; const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..'); const PLUGIN = path.join(ROOT, 'plugins', 'cpln'); -const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'tools-manifest.json'), 'utf8')).tools; -const TIER = { core: 1, mk8s: 2, full: 3, conditional: 4 }; +const manifestFile = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'tools-manifest.json'), 'utf8')); +const manifest = manifestFile.tools; +if (!Array.isArray(manifestFile.removed)) { + throw new Error('scripts/tools-manifest.json has no removed list: regenerate it from the MCP server.'); +} +const REMOVED = new Set(manifestFile.removed); +const TIER = { core: 1, mk8s: 2, full: 3 }; const TOKEN_RE = /\b(?:mcp__cpln__)?([a-z][a-z0-9]*(?:_[a-z0-9]+)+)(?:(_\*)|\b)/g; const VERB_PREFIXES = new Set([ @@ -47,7 +51,6 @@ const NOT_TOOLS = new Set(['query_range', 'start_period']); const FULL_MARKER_RE = /toolsets=full/; const MK8S_MARKER_RE = /toolsets=(?:mk8s|full)/; -const API_REQUEST_HEDGE_RE = /disabled by default|only when advertised|if advertised|when advertised|kill switch|if enabled|when enabled/i; const NEGATION_RE = /no `|there is no |no create- or update-/i; const FILE_NOTE_RE = /\*\*Tool availability:\*\*/; @@ -71,25 +74,20 @@ function checkFile(filePath) { const token = match[1]; if (NOT_TOOLS.has(token)) continue; - const tiers = tiersNamedBy(token, match[2] !== undefined); + const isWildcard = match[2] !== undefined; + const tiers = tiersNamedBy(token, isWildcard); if (tiers.length === 0) { - const looksLikeTool = match[0].startsWith('mcp__cpln__') || VERB_PREFIXES.has(token.split('_')[0]); + const isRemoved = REMOVED.has(token) || (isWildcard && [...REMOVED].some((name) => name.startsWith(`${token}_`))); + const looksLikeTool = isRemoved || match[0].startsWith('mcp__cpln__') || VERB_PREFIXES.has(token.split('_')[0]); if (looksLikeTool && !NEGATION_RE.test(line)) { - offenders.push(`${where}: unknown tool "${match[0]}" — ${line.trim().slice(0, 120)}`); + offenders.push(`${where}: ${isRemoved ? 'removed' : 'unknown'} tool "${match[0]}": ${line.trim().slice(0, 120)}`); } continue; } const tier = tiers.reduce((highest, candidate) => (TIER[candidate] > TIER[highest] ? candidate : highest)); - if (tier === 'conditional') { - if (!API_REQUEST_HEDGE_RE.test(line)) { - offenders.push(`${where}: "${token}" is registered only when its kill switch is on — add an availability hedge — ${line.trim().slice(0, 120)}`); - } - continue; - } - if (TIER[tier] <= TIER.core || fileHasNote) continue; const marker = tier === 'full' ? FULL_MARKER_RE : MK8S_MARKER_RE; diff --git a/scripts/tools-manifest.json b/scripts/tools-manifest.json index f7eefef..8e8286e 100644 --- a/scripts/tools-manifest.json +++ b/scripts/tools-manifest.json @@ -1,9 +1,7 @@ { - "$comment": "GENERATED FILE — do not hand-edit. Tiers are nested: core ⊂ mk8s ⊂ full; \"conditional\" = registered only when its kill switch is on.", + "$comment": "GENERATED FILE: do not hand-edit. Tiers are nested: core ⊂ mk8s ⊂ full. `removed` lists tools no longer registered.", "tools": { "add_database": "core", - "add_domain_port": "core", - "add_domain_route": "core", "add_gvc_locations": "full", "add_identity_native_network_resource": "full", "add_identity_network_resource": "full", @@ -12,8 +10,6 @@ "allow_workload_access": "core", "browse_templates": "core", "build_image": "core", - "clear_domain_cors": "full", - "clear_domain_tls": "core", "configure_external_logging": "full", "configure_workload_extras": "full", "configure_workload_load_balancer": "full", @@ -22,8 +18,6 @@ "configure_workload_rollout": "full", "configure_workload_security": "full", "configure_workload_sidecar": "full", - "convert_to_terraform": "core", - "cpln_api_request": "conditional", "create_agent": "full", "create_app_files_upload_link": "core", "create_audit_context": "full", @@ -31,95 +25,107 @@ "create_domain": "core", "create_group": "full", "create_gvc": "core", - "create_identity": "core", + "create_identity": "full", "create_ipset": "full", "create_mk8s": "mk8s", - "create_policy": "core", + "create_policy": "full", "create_secret": "core", "create_service_account": "full", - "create_volumeset": "core", - "create_volumeset_snapshot": "core", + "create_volumeset": "full", "create_workload": "core", "delete_resource": "core", - "delete_volumeset_snapshot": "full", - "delete_volumeset_volume": "full", "deploy_app": "core", "diagnose_workload": "core", "edit_audit_context": "full", "edit_group": "full", - "expand_volumeset": "core", "export_terraform": "core", "get_agent_eventlog": "full", "get_agent_info": "full", "get_app_files": "core", "get_command": "core", - "get_cpln_rules": "core", "get_cpln_skill": "core", "get_external_logging": "full", "get_image_build": "core", "get_installed_template": "core", - "get_permissions": "core", + "get_permissions": "full", "get_quota": "full", "get_resource": "core", - "get_resource_schema": "core", - "get_template": "core", - "get_trace": "core", - "get_workload_events": "core", + "get_workload_events": "full", "get_workload_logs": "core", "grant_cloud_access": "core", "grant_workload_secret_access": "core", "how_to_create_cloud_account": "full", "install_template": "core", "invite_user_to_org": "full", - "list_commands": "core", + "list_commands": "full", "list_deployments": "core", "list_identity_network_resources": "full", - "list_installed_templates": "core", - "list_metrics": "core", "list_orgs": "core", - "list_quotas": "core", + "list_quotas": "full", "list_resources": "core", - "list_volumeset_snapshots": "core", - "list_workload_replicas": "core", + "list_workload_replicas": "full", "mount_volumeset_to_workload": "core", "plan_app": "core", - "promote_workload": "core", + "promote_workload": "full", "query_audit_events": "core", - "query_docs_filesystem_control_plane": "core", + "query_docs_filesystem_control_plane": "full", "query_metrics": "core", "query_traces": "core", - "remove_domain_port": "core", - "remove_domain_route": "core", "remove_external_logging": "full", "remove_gvc_locations": "full", "remove_identity_network_resource": "full", "remove_ipset_location": "full", + "request_quota_increase": "core", "restart_workload": "core", - "restore_volumeset_snapshot": "core", "rollback_template": "full", "rollback_workload": "core", "rotate_secret": "core", + "run_volumeset_command": "core", "search_control_plane": "core", - "set_domain_cors": "full", - "set_domain_tls": "core", - "shrink_volumeset": "full", "start_workload_cron": "core", - "stop_workload_replica": "core", + "stop_workload_replica": "full", "uninstall_template": "core", "update_agent": "full", "update_cloud_account": "full", "update_domain": "core", - "update_domain_route": "core", "update_gvc": "core", - "update_identity": "core", + "update_identity": "full", "update_ipset": "full", "update_mk8s": "mk8s", "update_org": "full", - "update_policy": "core", + "update_policy": "full", "update_service_account": "full", "update_volumeset": "core", "update_workload": "core", "upgrade_template": "core", "write_app_files": "core" - } + }, + "removed": [ + "add_domain_port", + "add_domain_route", + "clear_domain_cors", + "clear_domain_tls", + "convert_to_terraform", + "cpln_api_request", + "create_volumeset_snapshot", + "delete_volumeset_snapshot", + "delete_volumeset_volume", + "expand_volumeset", + "get_cpln_rules", + "get_resource_schema", + "get_template", + "get_trace", + "list_installed_templates", + "list_metrics", + "list_volumeset_snapshots", + "remove_domain_port", + "remove_domain_route", + "restore_volumeset_snapshot", + "set_domain_cors", + "set_domain_tls", + "shrink_volumeset", + "update_domain_route", + "workload_start_cron", + "workload_stop_replica" + ] } From c2f9ce05634440e81271bbda41fb9812d9b33768 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Fri, 23 Oct 2026 14:49:44 +0300 Subject: [PATCH 05/12] Point the localOptions guidance at update_workload and remove configure_workload_local_options --- CHANGELOG.md | 2 ++ plugins/cpln/knowledge-map.json | 1 - plugins/cpln/skills/autoscaling-capacity/SKILL.md | 9 +++++++-- plugins/cpln/skills/workload/SKILL.md | 4 ++-- scripts/tools-manifest.json | 2 +- 5 files changed, 12 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53f7702..1ab233c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `update_domain` switches `certChallengeType`, for example to `dns01` when a CDN or WAF blocks `http01`; `.internal` domains refuse it. - `create_domain` and `update_domain` warn when a route sends clients to a workload that admits no external traffic, which the domain answers with 403. - The IaC skill says Terraform and Pulumi default `capacity_ai` to `true` on every workload type, stateful included. +- `update_workload` sets per-location overrides on every profile: `localOptions` merges by location (a new override starts as a copy of `defaultOptions`), `removeLocalOptions` deletes one, and naming a location in both rebuilds it from `defaultOptions`. The result says how each override was built and which locations a `defaultOptions` change does not reach. ### Changed @@ -49,6 +50,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `get_resource_schema` (now `get_resource` with `schema: true`), `list_volumeset_snapshots` (now `get_resource` on a volume set), `get_template` (now `browse_templates` with `name`), and `list_installed_templates` (now `get_installed_template` without `name`). - `get_trace` (now `query_traces` with `traceId`), `list_metrics` (now `query_metrics` without `query`), and `convert_to_terraform` (now `export_terraform` with `manifest`, which refuses secrets as an export does). - `cpln_api_request`, the raw API tool that was off by default; the `cpln` CLI covers what the tools do not. +- `configure_workload_local_options` (now `update_workload` with `localOptions` and `removeLocalOptions`, merged by location instead of replacing the list). ## [2.4.4] - 2026-10-01 diff --git a/plugins/cpln/knowledge-map.json b/plugins/cpln/knowledge-map.json index 89347a4..228c5d7 100644 --- a/plugins/cpln/knowledge-map.json +++ b/plugins/cpln/knowledge-map.json @@ -77,7 +77,6 @@ "configure_workload_load_balancer": "workload", "configure_workload_sidecar": "workload-security", "configure_workload_extras": "workload", - "configure_workload_local_options": "autoscaling-capacity", "configure_workload_rollout": "workload-security", "configure_workload_security": "workload-security", "configure_workload_retry": "workload", diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index 23b0558..6d7767c 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -42,7 +42,12 @@ spec: capacityAI: true ``` -- **Per-location overrides:** `spec.localOptions[]` (same fields + `location`) via `mcp__cpln__configure_workload_local_options` (needs `?toolsets=full`), the only MCP tool that sets `capacityAIUpdateMinutes` or `multiZone`; it replaces the full list. Both also exist on `spec.defaultOptions`, reachable with `cpln apply`. +- **Per-location overrides:** `spec.localOptions[]` (the `defaultOptions` fields plus `location`), set with `mcp__cpln__update_workload` `localOptions`, the only MCP path to `capacityAIUpdateMinutes` and `multiZone` (both also exist on `spec.defaultOptions`, reachable with `cpln apply`). An override **replaces** `defaultOptions` in its location and inherits nothing afterwards, so a later `defaultOptions` change skips every location that has one. The tool merges by location, and locations not named keep their overrides: + - **Before writing:** read the workload with `mcp__cpln__get_resource` and tell the user which locations already have an override and what it holds. Use the GVC's own location names; an override for a location the GVC does not run in has no effect until it does. + - **A location with an override:** send only the fields that change; the rest of the stored override stays, and `autoscaling` merges key by key. + - **A location without one:** the new override starts as a copy of the current `defaultOptions` plus the fields sent. + - **Back to `defaultOptions`:** `removeLocalOptions` with the location link. Naming a location in both `removeLocalOptions` and `localOptions` rebuilds its override from `defaultOptions` in one write, for example to drop a stored `multi` or `keda` block that a merge would keep. + - **After writing:** the result says how each override was built and its autoscaling now; check that it matches what the user asked. - **`scaleToZeroDelay` is dual-purpose:** on serverless it is the idle period before scaling to 0; on standard/stateful it sets the **scale-down stabilization window** (default 300s) — scale-up is immediate. ### Multi-metric (standard/stateful) @@ -115,7 +120,7 @@ spec: - **With `metric: cpu`:** explicitly enabling Capacity AI is **rejected** (dynamic CPU allocation fights CPU-based scaling); left unset with `cpu` or `multi`, it silently defaults to **off**. - **GPU containers reject Capacity AI.** -- Adjustments land **in place** on standard and stateful when the cluster supports pod resize (no restart; otherwise a rolling update); serverless rolls a new revision; **cron picks up the new reservation on its next execution** — a run already in flight is never resized. Throttle frequency with `capacityAIUpdateMinutes` (min 2 — via `localOptions` or `cpln apply`; not on create/update tools). +- Adjustments land **in place** on standard and stateful when the cluster supports pod resize (no restart; otherwise a rolling update); serverless rolls a new revision; **cron picks up the new reservation on its next execution** — a run already in flight is never resized. Throttle frequency with `capacityAIUpdateMinutes` (min 2; per location through `update_workload` `localOptions`, or on `defaultOptions` through `cpln apply`). - Idle floor is **25m** CPU, rising with memory at **1 millicore per 3 MiB**. A just-changed workload pauses adjustments while history rebuilds — apps that reserve resources at startup may not benefit. ### Resource bounds (all types) diff --git a/plugins/cpln/skills/workload/SKILL.md b/plugins/cpln/skills/workload/SKILL.md index bdb93a6..3775b87 100644 --- a/plugins/cpln/skills/workload/SKILL.md +++ b/plugins/cpln/skills/workload/SKILL.md @@ -29,17 +29,17 @@ A workload is the unit of deployment: one to eight containers plus how they scal |---|---| | `containers[]`: image, ports, cpu/memory, env, command/args, probes, metrics, volumes | `create_workload` / `update_workload` | | `autoscaling`, `capacityAI`, `timeoutSeconds`, `suspend`, `debug` | `create_workload` / `update_workload` | +| `localOptions` (per-location overrides, also the path to `multiZone`, `capacityAIUpdateMinutes`) and `removeLocalOptions` | `update_workload` | | `firewallConfig`, or the `public` shortcut | `create_workload` / `update_workload` | | `schedule` and job policy (`concurrencyPolicy`, `historyLimit`, `restartPolicy`, `activeDeadlineSeconds`) | the same tools with `type: cron` | | `loadBalancer` (direct, geo, replicaDirect) | `configure_workload_load_balancer` | | `sidecar.envoy` (JWT auth, Envoy filters) | `configure_workload_sidecar` | | `extras` (BYOK affinity, tolerations, topology) | `configure_workload_extras` | -| `localOptions` (per-location overrides, `multiZone`, `capacityAIUpdateMinutes`) | `configure_workload_local_options` | | `rolloutOptions` (termination grace, surge) | `configure_workload_rollout` | | `securityOptions` (`runAsUser`, `filesystemGroupId`) | `configure_workload_security` | | `requestRetryPolicy` | `configure_workload_retry` | -`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. `start_workload_cron` runs a cron workload now, with optional `containerOverrides` for that run only; each call starts another run, and it returns a command id that `get_command` follows. +`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. It merges `localOptions` by location the same way; read the **autoscaling-capacity** skill before changing one, since an override replaces `defaultOptions` in its location. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. `start_workload_cron` runs a cron workload now, with optional `containerOverrides` for that run only; each call starts another run, and it returns a command id that `get_command` follows. ## Production defaults beyond the core rules diff --git a/scripts/tools-manifest.json b/scripts/tools-manifest.json index 8e8286e..3ed420b 100644 --- a/scripts/tools-manifest.json +++ b/scripts/tools-manifest.json @@ -13,7 +13,6 @@ "configure_external_logging": "full", "configure_workload_extras": "full", "configure_workload_load_balancer": "full", - "configure_workload_local_options": "full", "configure_workload_retry": "full", "configure_workload_rollout": "full", "configure_workload_security": "full", @@ -105,6 +104,7 @@ "add_domain_route", "clear_domain_cors", "clear_domain_tls", + "configure_workload_local_options", "convert_to_terraform", "cpln_api_request", "create_volumeset_snapshot", From 7c34884dd7e82a7b5b72ebc89c4b133b771eeb14 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Fri, 23 Oct 2026 20:08:26 +0300 Subject: [PATCH 06/12] Move rollout and security options to create_workload and update_workload --- CHANGELOG.md | 4 ++++ plugins/cpln/knowledge-map.json | 2 -- plugins/cpln/skills/autoscaling-capacity/SKILL.md | 4 ++-- plugins/cpln/skills/workload-security/SKILL.md | 13 +++++++------ plugins/cpln/skills/workload/SKILL.md | 9 ++++----- scripts/tools-manifest.json | 4 ++-- 6 files changed, 19 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ab233c..2259a85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `create_domain` and `update_domain` warn when a route sends clients to a workload that admits no external traffic, which the domain answers with 403. - The IaC skill says Terraform and Pulumi default `capacity_ai` to `true` on every workload type, stateful included. - `update_workload` sets per-location overrides on every profile: `localOptions` merges by location (a new override starts as a copy of `defaultOptions`), `removeLocalOptions` deletes one, and naming a location in both rebuilds it from `defaultOptions`. The result says how each override was built and which locations a `defaultOptions` change does not reach. +- `create_workload` and `update_workload` set `rolloutOptions` and `securityOptions` on every profile, including `rolloutOnReferenceChange`, which restarts replicas when a referenced secret or the identity changes. `update_workload` merges the given fields into the stored ones, `removeSecurityOptions: true` deletes the security block, and the result shows what the platform stored. +- `create_workload` takes `localOptions`: each override starts as a copy of the `defaultOptions` the same call sets, so a location never runs on the defaults first. +- `create_workload` and `update_workload` set `multiZone` and `capacityAIUpdateMinutes` for every location, which before took an override in each location. ### Changed @@ -51,6 +54,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `get_trace` (now `query_traces` with `traceId`), `list_metrics` (now `query_metrics` without `query`), and `convert_to_terraform` (now `export_terraform` with `manifest`, which refuses secrets as an export does). - `cpln_api_request`, the raw API tool that was off by default; the `cpln` CLI covers what the tools do not. - `configure_workload_local_options` (now `update_workload` with `localOptions` and `removeLocalOptions`, merged by location instead of replacing the list). +- `configure_workload_rollout` and `configure_workload_security` (now `rolloutOptions`, `securityOptions`, and `removeSecurityOptions` on `create_workload` and `update_workload`). ## [2.4.4] - 2026-10-01 diff --git a/plugins/cpln/knowledge-map.json b/plugins/cpln/knowledge-map.json index 228c5d7..0641ada 100644 --- a/plugins/cpln/knowledge-map.json +++ b/plugins/cpln/knowledge-map.json @@ -77,8 +77,6 @@ "configure_workload_load_balancer": "workload", "configure_workload_sidecar": "workload-security", "configure_workload_extras": "workload", - "configure_workload_rollout": "workload-security", - "configure_workload_security": "workload-security", "configure_workload_retry": "workload", "install_template": "template-catalog", "add_database": "template-catalog", diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index 6d7767c..cd917ee 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -42,10 +42,10 @@ spec: capacityAI: true ``` -- **Per-location overrides:** `spec.localOptions[]` (the `defaultOptions` fields plus `location`), set with `mcp__cpln__update_workload` `localOptions`, the only MCP path to `capacityAIUpdateMinutes` and `multiZone` (both also exist on `spec.defaultOptions`, reachable with `cpln apply`). An override **replaces** `defaultOptions` in its location and inherits nothing afterwards, so a later `defaultOptions` change skips every location that has one. The tool merges by location, and locations not named keep their overrides: +- **Per-location overrides:** `spec.localOptions[]` (the `defaultOptions` fields plus `location`), set with `localOptions` on `mcp__cpln__create_workload` or `mcp__cpln__update_workload`. `capacityAIUpdateMinutes` and `multiZone` are top-level fields on both tools and apply to every location; set them in an override only when one location needs a different value. An override **replaces** `defaultOptions` in its location and inherits nothing afterwards, so a later `defaultOptions` change skips every location that has one. `update_workload` merges by location, and locations not named keep their overrides: - **Before writing:** read the workload with `mcp__cpln__get_resource` and tell the user which locations already have an override and what it holds. Use the GVC's own location names; an override for a location the GVC does not run in has no effect until it does. - **A location with an override:** send only the fields that change; the rest of the stored override stays, and `autoscaling` merges key by key. - - **A location without one:** the new override starts as a copy of the current `defaultOptions` plus the fields sent. + - **A location without one:** the new override starts as a copy of the current `defaultOptions` plus the fields sent; on `create_workload`, a copy of the `defaultOptions` the same call sets. - **Back to `defaultOptions`:** `removeLocalOptions` with the location link. Naming a location in both `removeLocalOptions` and `localOptions` rebuilds its override from `defaultOptions` in one write, for example to drop a stored `multi` or `keda` block that a merge would keep. - **After writing:** the result says how each override was built and its autoscaling now; check that it matches what the user asked. - **`scaleToZeroDelay` is dual-purpose:** on serverless it is the idle period before scaling to 0; on standard/stateful it sets the **scale-down stabilization window** (default 300s) — scale-up is immediate. diff --git a/plugins/cpln/skills/workload-security/SKILL.md b/plugins/cpln/skills/workload-security/SKILL.md index 66bf6cc..ce30a79 100644 --- a/plugins/cpln/skills/workload-security/SKILL.md +++ b/plugins/cpln/skills/workload-security/SKILL.md @@ -100,7 +100,7 @@ For any OIDC provider (Auth0, Firebase, Cognito, Okta), set `issuer` to its issu ## Security Options -`spec.securityOptions` (set with `configure_workload_security`): +`spec.securityOptions` (set with `create_workload` or `update_workload`, which merges the given fields; `removeSecurityOptions: true` deletes the block): | Field | Range | Purpose | |---|---|---| @@ -148,15 +148,16 @@ Each direct-LB location also gets a public Geo DNS address with latency-based ro ## Graceful Termination -`spec.rolloutOptions` (set with `configure_workload_rollout`) governs how replicas are removed during scaling, version updates, Capacity AI rollouts, and maintenance. +`spec.rolloutOptions` (set with `create_workload` or `update_workload`, which merges the given fields) governs how replicas are removed during scaling, version updates, Capacity AI rollouts, and maintenance. | Field | Range / values | Default | |---|---|---| -| `minReadySeconds` | integer ≥0 | 0 | -| `maxSurgeReplicas` | integer or percent | unset (not for `vm`) | -| `maxUnavailableReplicas` | integer or percent | unset (not for `stateful`) | -| `scalingPolicy` | `OrderedReady` / `Parallel` | `OrderedReady` (not for `vm`) | +| `minReadySeconds` | integer ≥0 (standard and stateful) | 0 | +| `maxSurgeReplicas` | integer or percent (standard only) | 25% | +| `maxUnavailableReplicas` | integer or percent (standard only) | 25% | +| `scalingPolicy` | `OrderedReady` / `Parallel` (stateful only) | `OrderedReady` | | `terminationGracePeriodSeconds` | 0-900 (3600 with the `cpln/relaxGracePeriodMax` tag) | 90 | +| `rolloutOnReferenceChange` | `true` restarts replicas when a referenced secret or the identity changes | unset | `terminationGracePeriodSeconds` is the total budget for a replica to shut down before SIGKILL; raise it for long-running requests. Termination sequence: diff --git a/plugins/cpln/skills/workload/SKILL.md b/plugins/cpln/skills/workload/SKILL.md index 3775b87..adae68f 100644 --- a/plugins/cpln/skills/workload/SKILL.md +++ b/plugins/cpln/skills/workload/SKILL.md @@ -28,18 +28,17 @@ A workload is the unit of deployment: one to eight containers plus how they scal | Spec block | Set with | |---|---| | `containers[]`: image, ports, cpu/memory, env, command/args, probes, metrics, volumes | `create_workload` / `update_workload` | -| `autoscaling`, `capacityAI`, `timeoutSeconds`, `suspend`, `debug` | `create_workload` / `update_workload` | -| `localOptions` (per-location overrides, also the path to `multiZone`, `capacityAIUpdateMinutes`) and `removeLocalOptions` | `update_workload` | +| `autoscaling`, `capacityAI`, `capacityAIUpdateMinutes`, `multiZone`, `timeoutSeconds`, `suspend`, `debug` | `create_workload` / `update_workload` | +| `localOptions` (per-location overrides); `removeLocalOptions` on update | `create_workload` / `update_workload` | | `firewallConfig`, or the `public` shortcut | `create_workload` / `update_workload` | +| `rolloutOptions` (termination grace, surge, `rolloutOnReferenceChange`) and `securityOptions` (`runAsUser`, `filesystemGroupId`) | `create_workload` / `update_workload` | | `schedule` and job policy (`concurrencyPolicy`, `historyLimit`, `restartPolicy`, `activeDeadlineSeconds`) | the same tools with `type: cron` | | `loadBalancer` (direct, geo, replicaDirect) | `configure_workload_load_balancer` | | `sidecar.envoy` (JWT auth, Envoy filters) | `configure_workload_sidecar` | | `extras` (BYOK affinity, tolerations, topology) | `configure_workload_extras` | -| `rolloutOptions` (termination grace, surge) | `configure_workload_rollout` | -| `securityOptions` (`runAsUser`, `filesystemGroupId`) | `configure_workload_security` | | `requestRetryPolicy` | `configure_workload_retry` | -`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. It merges `localOptions` by location the same way; read the **autoscaling-capacity** skill before changing one, since an override replaces `defaultOptions` in its location. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. `start_workload_cron` runs a cron workload now, with optional `containerOverrides` for that run only; each call starts another run, and it returns a command id that `get_command` follows. +`update_workload` merges `containers[]` by name: send only the containers that change; an unknown name adds a container. It merges `localOptions` by location the same way; read the **autoscaling-capacity** skill before changing one, since an override replaces `defaultOptions` in its location. It merges `rolloutOptions` and `securityOptions` field by field, and `removeSecurityOptions: true` deletes the security block. On `create_workload`, each `localOptions` override starts as a copy of the `defaultOptions` the same call sets. On cron it patches the schedule, job policy, `suspend`, `capacityAI`, and containers, and rejects autoscaling, `timeoutSeconds`, and `debug`; schedule and job fields are rejected on other types. `start_workload_cron` runs a cron workload now, with optional `containerOverrides` for that run only; each call starts another run, and it returns a command id that `get_command` follows. ## Production defaults beyond the core rules diff --git a/scripts/tools-manifest.json b/scripts/tools-manifest.json index 3ed420b..0d3672e 100644 --- a/scripts/tools-manifest.json +++ b/scripts/tools-manifest.json @@ -14,8 +14,6 @@ "configure_workload_extras": "full", "configure_workload_load_balancer": "full", "configure_workload_retry": "full", - "configure_workload_rollout": "full", - "configure_workload_security": "full", "configure_workload_sidecar": "full", "create_agent": "full", "create_app_files_upload_link": "core", @@ -105,6 +103,8 @@ "clear_domain_cors", "clear_domain_tls", "configure_workload_local_options", + "configure_workload_rollout", + "configure_workload_security", "convert_to_terraform", "cpln_api_request", "create_volumeset_snapshot", From ca88fa08ac0fd6ddbbac3b1f5bf0333807ce32cc Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Fri, 23 Oct 2026 21:23:12 +0300 Subject: [PATCH 07/12] Describe mk8s cluster logs and metrics in the observability and mk8s skills --- CHANGELOG.md | 4 ++++ plugins/cpln/skills/logql-observability/SKILL.md | 3 ++- plugins/cpln/skills/metrics-observability/SKILL.md | 2 +- plugins/cpln/skills/mk8s-byok/SKILL.md | 2 ++ 4 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2259a85..ac2c405 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `create_workload` and `update_workload` set `rolloutOptions` and `securityOptions` on every profile, including `rolloutOnReferenceChange`, which restarts replicas when a referenced secret or the identity changes. `update_workload` merges the given fields into the stored ones, `removeSecurityOptions: true` deletes the security block, and the result shows what the platform stored. - `create_workload` takes `localOptions`: each override starts as a copy of the `defaultOptions` the same call sets, so a location never runs on the defaults first. - `create_workload` and `update_workload` set `multiZone` and `capacityAIUpdateMinutes` for every location, which before took an override in each location. +- `get_workload_logs` reads an mk8s cluster's own logs: `cluster` in place of `gvc`, narrowed by `namespace`, `pod`, `container`, `node`, and `job`. When nothing comes back from a cluster whose `logs` add-on is off, the result says so. +- `get_resource` on an mk8s cluster with the `logs` or `metrics` add-on names the calls that read its logs and metrics. ### Changed @@ -31,6 +33,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - Skills say how to reach a tool outside the core profile (`?toolsets=full`). - The Template Catalog skill finds a template with `browse_templates` and `query` (the user's need in their own words) and reads its prerequisites, the template to pick instead, and its README notes from the tools, replacing the table of common asks and the per-template secret keys. It covers any self-hosted component or product, and leaves an app the user asks to build to the `create-app` skill. - The Template Catalog skill searches for the capability a goal needs when the user describes a goal rather than a component, and keeps `add_database` the default for the five databases, using the install steps only for a setting it does not take, such as backups. +- `query_metrics` without `query` lists the metrics mk8s clusters ship apart from custom metrics, and its description names the `cluster_name` and `node` labels mk8s series carry. ### Fixed @@ -55,6 +58,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `cpln_api_request`, the raw API tool that was off by default; the `cpln` CLI covers what the tools do not. - `configure_workload_local_options` (now `update_workload` with `localOptions` and `removeLocalOptions`, merged by location instead of replacing the list). - `configure_workload_rollout` and `configure_workload_security` (now `rolloutOptions`, `securityOptions`, and `removeSecurityOptions` on `create_workload` and `update_workload`). +- `logs.events` on the `create_mk8s` and `update_mk8s` add-ons, which no mk8s log collector reads. ## [2.4.4] - 2026-10-01 diff --git a/plugins/cpln/skills/logql-observability/SKILL.md b/plugins/cpln/skills/logql-observability/SKILL.md index 1b6a01d..82d5b5b 100644 --- a/plugins/cpln/skills/logql-observability/SKILL.md +++ b/plugins/cpln/skills/logql-observability/SKILL.md @@ -9,7 +9,8 @@ Control Plane stores workload stdout/stderr in Loki and queries it with LogQL. T ## Two ways to query -- **MCP (primary for agents):** `mcp__cpln__get_workload_logs` — structured params `gvc` (required), `workload`, `container`, `location`, `filter` (literal substring, LogQL `|=`, not regex); window `since` (default `1h`) or `from`/`to` (ISO 8601, `from` inclusive, `to` exclusive); `limit` (default 30, max 999, single request — `truncated: true` means narrow the window or filter harder); `order` (`oldest_first` default, or `newest_first`). For regex, parsers, or the `replica`/`stream`/`version` labels, pass a raw `query` (max 500 chars) instead of the structured selectors. +- **MCP (primary for agents):** `mcp__cpln__get_workload_logs`: structured params `gvc`, `workload`, `container`, `location`, `filter` (literal substring, LogQL `|=`, not regex); window `since` (default `1h`) or `from`/`to` (ISO 8601, `from` inclusive, `to` exclusive); `limit` (default 30, max 999, single request: `truncated: true` means narrow the window or filter harder); `order` (`oldest_first` default, or `newest_first`). For regex, parsers, or the `replica`/`stream`/`version` labels, pass a raw `query` (max 500 chars) instead of the structured selectors. +- **mk8s cluster logs** (the cluster's `logs` add-on): the same tool with `cluster` in place of `gvc`, narrowed by `namespace`, `pod`, `container`, `node`, and `job` (`kubernetes-pods`, `kubelet`, `kernel`, `docker-containers`, `audit`). These streams carry `cluster_name` and `cluster_alias`, never `gvc`; Control Plane workloads running on the cluster log under their GVC. - **CLI:** `cpln logs ''` — interactive debugging (live `--tail`), scripts, CI. ```bash diff --git a/plugins/cpln/skills/metrics-observability/SKILL.md b/plugins/cpln/skills/metrics-observability/SKILL.md index 35ba58c..e6e548b 100644 --- a/plugins/cpln/skills/metrics-observability/SKILL.md +++ b/plugins/cpln/skills/metrics-observability/SKILL.md @@ -44,7 +44,7 @@ Collected for every workload, no configuration. Names and types below are the re **Org-wide** (no workload label): `logs_storage_mb` / `metrics_storage_mb` / `tracing_storage_mb`; `agent_peers_count` / `agent_services_count` (gauge) and `agent_{tx,rx}_{bytes,packets}_total` (counter) from wormhole agents; `threat_detection_alerts` / `threat_detection_forward_total` / `threat_detection_forward_enabled`. -mk8s clusters with metrics enabled also expose `kube_*` (kube-state-metrics) and `node_*` (node-exporter). +mk8s clusters with the `metrics` add-on also ship `kube_*` (kube-state-metrics), `node_*` (node-exporter), kubelet, and cadvisor series. Every one carries `cluster_name` and `cluster_alias`, and node-exporter, kubelet, and cadvisor series also carry `node`: select a cluster with `{cluster_name="CLUSTER"}`. ## Custom metrics diff --git a/plugins/cpln/skills/mk8s-byok/SKILL.md b/plugins/cpln/skills/mk8s-byok/SKILL.md index 2ffa84b..3612313 100644 --- a/plugins/cpln/skills/mk8s-byok/SKILL.md +++ b/plugins/cpln/skills/mk8s-byok/SKILL.md @@ -78,6 +78,8 @@ Exactly one provider per cluster (the schema enforces XOR). For every provider e | `azureACR` | pull from private ACR (`clientId` required) | all | | `byok` | register this cluster as a BYOK location (`addOns.byok.location` is a `//location/NAME` link) | all | +With the `logs` or `metrics` add-on on, read the cluster's own logs with `mcp__cpln__get_workload_logs` (`cluster` in place of `gvc`) and its metrics with `mcp__cpln__query_metrics` on `cluster_name`. + ## Create & update (MCP) `mcp__cpln__create_mk8s` takes `provider` (any row of the table above) and `spec`, the provider block; the tool names the fields the provider requires, and `get_resource` (kind `mk8s`, `schema: true`, path `spec.provider.`) has the exact shape. Supply `version` and at least one node pool. Read with `mcp__cpln__get_resource` / `list_resources` (kind `mk8s`); delete with `mcp__cpln__delete_resource` (destructive: confirm the blast radius). From f3d3f1199b40edc703f9ac10961ed8d0dae601b2 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Mon, 26 Oct 2026 16:18:10 +0200 Subject: [PATCH 08/12] Note that a reused role or service account gets no identity status --- CHANGELOG.md | 1 + plugins/cpln/skills/setup-cloud-access/SKILL.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac2c405..87b7f4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - Skills and agents now match the tools wherever they described a field or behavior wrongly, for example that shrinking a volume keeps its data. - The stateful `minCpu`/`minMemory` ratio and gap limits apply only while Capacity AI is off in `defaultOptions` or in a `localOptions` entry. - The Template Catalog skill no longer says `cockroach`, `tidb`, `nats`, `clickhouse`, `airflow`, `mongodb-cluster`, `redis-multi-location`, and `pgedge` create their own GVC; their current versions install into an existing GVC that already has every location their `locations` value lists. +- `grant_cloud_access` returns at once for a reused `roleName` or `serviceAccount`, which never gets a status, instead of waiting on one, and refuses an input data-service would refuse before the workload gets an identity. The cloud access skill says a reused role or service account gets no status. ### Removed diff --git a/plugins/cpln/skills/setup-cloud-access/SKILL.md b/plugins/cpln/skills/setup-cloud-access/SKILL.md index 7e48350..225fc87 100644 --- a/plugins/cpln/skills/setup-cloud-access/SKILL.md +++ b/plugins/cpln/skills/setup-cloud-access/SKILL.md @@ -11,7 +11,7 @@ A workload reads cloud resources with **no embedded keys**: a GVC-scoped **ident ## The chain -**One call once the cloud account exists:** `mcp__cpln__grant_cloud_access` (`workload`, `provider`, `cloudAccount`, and the provider block from step 3) ensures the workload's identity, attaches the cloud account to it, and waits for `status..usable`. Steps 3 and 4 below are what it does, for hand-built setups. +**One call once the cloud account exists:** `mcp__cpln__grant_cloud_access` (`workload`, `provider`, `cloudAccount`, and the provider block from step 3) ensures the workload's identity, attaches the cloud account to it, and waits for `status..usable` (none comes for a reused `roleName` or `serviceAccount`). Steps 3 and 4 below are what it does, for hand-built setups. | Step | What must be true | Without it | |---|---|---| @@ -74,7 +74,7 @@ CLI fallback (MCP unavailable / CI-CD): `cpln identity get NAME --gvc GVC -o yam `update_workload` sets `spec.identityLink = //identity/NAME` (CLI: `cpln workload update NAME --set spec.identityLink=//identity/NAME`). -Read the identity back with `get_resource` (kind `identity`): `status..usable` must be `true`; if `false`, read `status..lastError`. Cloud CLIs are usually absent from production containers, so a missing `aws`/`gcloud`/`az` does **not** mean access is broken — the SDK path still works. +Read the identity back with `get_resource` (kind `identity`): `status..usable` must be `true`; if `false`, read `status..lastError`. Control Plane writes none for a reused `roleName` or `serviceAccount`: the workload's own cloud calls are the check there. Cloud CLIs are usually absent from production containers, so a missing `aws`/`gcloud`/`az` does **not** mean access is broken: the SDK path still works. ## Private-network resources @@ -86,6 +86,6 @@ Reaching a private VPC / on-prem endpoint is a different mechanism on the **same - **Skipping the how-to** — the org-specific account/external IDs and SA email are required and can't be guessed. - **Full ARN in AWS `policyRefs`** — use the policy name with an optional `aws::` prefix, no colons. - **Both `policyRefs` + `roleName` (AWS) or `bindings` + `serviceAccount` (GCP)** — exactly one. -- **Not checking `status..usable`** — verify `true` before linking to the workload. +- **Not checking `status..usable`**: verify `true` before linking to the workload (it is never set for a reused `roleName` or `serviceAccount`). - **Confusing cloud access with secret access** — cloud access is the identity's `aws`/`gcp`/`azure`/`ngs` block; secret access is a `reveal` policy on a `cpln://secret/` reference (see **setup-secret**). - **Sharing an identity across GVCs** — recreate it per GVC. From fac31c7ca0a80d74501e4cd99023f6c7781451cd Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Wed, 28 Oct 2026 22:10:02 +0200 Subject: [PATCH 09/12] Keep chat apps off the cpln CLI and sync skills with the MCP --- CHANGELOG.md | 15 +++++++++++++++ plugins/cpln/rules/cpln-core.md | 2 +- plugins/cpln/skills/autoscaling-capacity/SKILL.md | 2 +- plugins/cpln/skills/cdn-rate-limiting/SKILL.md | 2 +- plugins/cpln/skills/cpln/SKILL.md | 7 ++++--- plugins/cpln/skills/create-app/SKILL.md | 8 ++++---- plugins/cpln/skills/k8s-operator/SKILL.md | 2 +- .../cpln/skills/metrics-observability/SKILL.md | 3 ++- plugins/cpln/skills/mk8s-byok/SKILL.md | 2 +- plugins/cpln/skills/operating-guide/SKILL.md | 6 +++--- plugins/cpln/skills/org-management/SKILL.md | 6 +++--- plugins/cpln/skills/stateful-storage/SKILL.md | 8 ++++---- plugins/cpln/skills/template-catalog/SKILL.md | 4 ++-- 13 files changed, 42 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87b7f4d..82b7446 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,9 +22,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `create_workload` and `update_workload` set `multiZone` and `capacityAIUpdateMinutes` for every location, which before took an override in each location. - `get_workload_logs` reads an mk8s cluster's own logs: `cluster` in place of `gvc`, narrowed by `namespace`, `pod`, `container`, `node`, and `job`. When nothing comes back from a cluster whose `logs` add-on is off, the result says so. - `get_resource` on an mk8s cluster with the `logs` or `metrics` add-on names the calls that read its logs and metrics. +- `run_volumeset_command` takes `copyVolume`, which copies a volume to the same index in another location or volume set and replaces the volume there; skills list it with the destructive commands. +- `create_secret` takes `defaults` with values `"user"` and a dictionary: starting values that are not secret, such as a host or port, filled into the Console form for the user to change. +- `create_mk8s` and `update_mk8s` take a `*Drop` regex per metrics collector, dropping every series whose metric name matches it in full. +- The metrics skill names `container_last_terminated_reason`, the reason each container last stopped, such as `OOMKilled`. ### Changed +- Skills and the core rules run `cpln` only in a shell on the user's machine. A chat app such as ChatGPT never looks for, installs, or runs it, even in its code sandbox; it stores app files with `write_app_files` and gives the user a command to run only for a step no tool covers. +- The mk8s skill gives the current version range, `1.26.0` through `1.36.5`. +- `upgrade_template` and the Template Catalog skill start an upgrade from the values the release runs with, which the user reads in the Console, instead of a `cpln helm get values` command that would bring credentials into the chat. +- `allow_workload_access` says that `remove: true` takes callers off the list, while a `same-gvc` or `same-org` rule still admits them. +- Live credentials stay with the user: the agent never runs `cpln profile token` or prints an API token, the user runs those in their own terminal, and the Secret YAML from `cpln operator install --export` stays out of Git unless encrypted. +- The KEDA Prometheus trigger authenticates with `authModes: bearer` and a dictionary secret (`bearerToken`) named in `authenticationRef`, never a token written into the workload spec. +- Skills say the ChatGPT listing always runs `core`, so a step that needs another profile goes through the Console or a CLI command the user runs. +- The rate limiting setup no longer mentions `spot`, which the platform removes from every workload. + - The default `core` profile advertises 45 tools instead of 71: tools fold into the tool that covers their family (see Removed). - Tools few tasks need move from `core` to `full`: policies, identities, permissions, quota lists, promotion, events, replica and command lists, volume set creation, and the docs filesystem; the read tools among them stay on `readonly`. - `workload_start_cron` and `workload_stop_replica` are renamed `start_workload_cron` and `stop_workload_replica`. @@ -38,6 +51,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this ### Fixed - `update_workload` `public: false` now closes the workload to the internet, and `public: true` opens it without replacing its other firewall rules. +- `get_app_files` never shows the content of a file holding credentials, such as a `.env` with values uploaded from a folder; it returns the file's details instead. - `rollback_workload` finds the previous image even after a rollout has finished, from the last 30 days of changes. - Quota rejections (HTTP 429) are not retried, and their errors carry the quota hint instead of the rate limit hint. - An update that loses a write race with another change (HTTP 409 "Conflict: resource was changed") is retried once instead of failing with an "already exists" hint. @@ -60,6 +74,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this - `configure_workload_local_options` (now `update_workload` with `localOptions` and `removeLocalOptions`, merged by location instead of replacing the list). - `configure_workload_rollout` and `configure_workload_security` (now `rolloutOptions`, `securityOptions`, and `removeSecurityOptions` on `create_workload` and `update_workload`). - `logs.events` on the `create_mk8s` and `update_mk8s` add-ons, which no mk8s log collector reads. +- `recoveryPolicy` on `mount_volumeset_to_workload` and on container volumes in `create_workload` and `update_workload`, which the platform does not act on. ## [2.4.4] - 2026-10-01 diff --git a/plugins/cpln/rules/cpln-core.md b/plugins/cpln/rules/cpln-core.md index aff3fda..363296c 100644 --- a/plugins/cpln/rules/cpln-core.md +++ b/plugins/cpln/rules/cpln-core.md @@ -7,7 +7,7 @@ alwaysApply: true **Where**: org: the granted one, else ask (`list_orgs`). Gvc: the named one, else the one jobs made for apps; others: ask; none: a job makes one where the user picks. Never guess other names; after a not-found, never retry name variants. -**Tools first**: these tools do all they cover, reads too; `cpln` only for a local folder's `image build`, `connect`, `exec`, `port-forward`, `cp`, CI/CD. +**Tools first**: these tools do all they cover, reads too; `cpln` only for a local folder's `image build`, `connect`, `exec`, `port-forward`, `cp`, CI/CD; a chat app gives the user the command. **Destructive actions**: first say what is removed or broken, then act only on explicit approval. Cascades, gvc location changes, data loss, and production need a fresh yes. diff --git a/plugins/cpln/skills/autoscaling-capacity/SKILL.md b/plugins/cpln/skills/autoscaling-capacity/SKILL.md index cd917ee..bb6ded4 100644 --- a/plugins/cpln/skills/autoscaling-capacity/SKILL.md +++ b/plugins/cpln/skills/autoscaling-capacity/SKILL.md @@ -100,7 +100,7 @@ autoscaling: - Triggers needing auth reference a GVC-listed secret via `authenticationRef.name` (the TriggerAuthentication is named after the secret). - If the trigger source is a Control Plane workload, allow KEDA in the source's firewall: `internal.inboundAllowWorkload: [cpln://internal/keda]`. - Also supported: `keda.advanced.scalingModifiers` (custom formulas), `fallback`, `pollingInterval`, `cooldownPeriod`. -- **Prometheus trigger**, to scale on any platform or custom metric: `type: prometheus` with `serverAddress: https://metrics.cpln.io:443/metrics/org/ORG`, a `query` (PromQL), `threshold`, and `customHeaders: Authorization=Bearer SERVICE_ACCOUNT_TOKEN` (service account needs `readMetrics`). **Before wiring any trigger, confirm the signal resolves:** `mcp__cpln__query_metrics` without a `query` for real names (add `metric` for one metric's live label values), then with the PromQL as its `query` to run it; a never-resolving signal pins the workload at `minScale`. Custom app metrics come from the container `metrics` block (see **metrics-observability**). +- **Prometheus trigger**, to scale on any platform or custom metric: `type: prometheus` with `serverAddress: https://metrics.cpln.io:443/metrics/org/ORG`, a `query` (PromQL), `threshold`, and `authModes: bearer`, with `authenticationRef.name` naming a dictionary secret listed in `gvc.spec.keda.secrets` whose `bearerToken` key holds a service-account key with `readMetrics` (each key becomes a trigger parameter; the user enters the value in the Console). **Before wiring any trigger, confirm the signal resolves:** `mcp__cpln__query_metrics` without a `query` for real names (add `metric` for one metric's live label values), then with the PromQL as its `query` to run it; a never-resolving signal pins the workload at `minScale`. Custom app metrics come from the container `metrics` block (see **metrics-observability**). ## Capacity AI diff --git a/plugins/cpln/skills/cdn-rate-limiting/SKILL.md b/plugins/cpln/skills/cdn-rate-limiting/SKILL.md index f09eeac..00fc0d9 100644 --- a/plugins/cpln/skills/cdn-rate-limiting/SKILL.md +++ b/plugins/cpln/skills/cdn-rate-limiting/SKILL.md @@ -41,7 +41,7 @@ cpln apply --file rate-limiting.yaml --org ORG --gvc ratelimit The manifest assumes the GVC is named `ratelimit` (edit it if yours differs) and pins an older `envoyproxy/ratelimit` image tag; substitute a newer tag if desired. -**As shipped, the manifest is a trial setup, not a production one:** both workloads run `minScale: 1` with `spot: true`. Because enforcement is fail-closed, the ratelimit stack is tier-1 infrastructure for every tagged workload — for production raise its `minScale` to 2+, set `spot: false`, and run the GVC in the same locations as the workloads it protects (every request pays the check's round trip). A Redis restart only resets counters; a ratelimit outage denies traffic. +**As shipped, the manifest is a trial setup, not a production one:** both workloads run `minScale: 1`. Because enforcement is fail-closed, the ratelimit stack is tier-1 infrastructure for every tagged workload: for production raise its `minScale` to 2+ and run the GVC in the same locations as the workloads it protects (every request pays the check's round trip). A Redis restart only resets counters; a ratelimit outage denies traffic. ### 2. Configure the rules diff --git a/plugins/cpln/skills/cpln/SKILL.md b/plugins/cpln/skills/cpln/SKILL.md index 5ce7073..44e06c4 100644 --- a/plugins/cpln/skills/cpln/SKILL.md +++ b/plugins/cpln/skills/cpln/SKILL.md @@ -7,7 +7,7 @@ description: "Writes cpln CLI commands and workflows for Control Plane. Use when **MCP first; the CLI covers what the MCP cannot.** With the MCP connected, its tools do every operation they cover, reads included; the CLI is for the CLI-only operations below (building a folder on disk among them), interactive debugging, scripted GitOps, and sessions without the MCP. A connected MCP that is signed out means the user signs in again, not a switch to the CLI. **In CI/CD the CLI is the primary interface**: pipelines authenticate with a service-account key in `CPLN_TOKEN`, build and push images (`cpln image build --push`, or `--remote` on a runner with no Docker daemon), and apply resources (`cpln apply --ready`). Platform rules (resource model, secrets, destructive ops, production defaults, scale-to-zero, firewall) live in the `operating-guide` skill (through the MCP: `get_cpln_skill` with `skill: "operating-guide"`); this skill is the CLI mechanics. -**Never write a `cpln` command from memory.** Verify every verb and flag with `cpln --help` before quoting it. If a command isn't in the resource command map below, assume it isn't real. +**Never write a `cpln` command from memory.** In a shell on the user's machine, verify every verb and flag with `cpln --help` before quoting it. A chat app (ChatGPT, Claude web and desktop) has no `cpln` to run, its code sandbox included: never look for or install it there; quote commands from this skill for the user to run on their machine. If a command isn't in the resource command map below, assume it isn't real. ## CLI-only operations @@ -24,7 +24,7 @@ No MCP equivalent — the CLI's primary job: One-shot and interactive container commands, TTY sessions (`workload connect`, `exec -it`), and streamed logs (`cpln logs --tail`) are also CLI-only; MCP's `get_workload_logs` covers bounded log fetches. Everything else — discovery and CRUD — prefer the MCP tools (generic `mcp__cpln__list_resources` / `get_resource` / `delete_resource` with a `kind`, typed `create_*`/`update_*` for mutations). -When no MCP tool covers a resource, field, or sub-endpoint, use the `cpln` CLI for that piece (ground the command in this skill and `--help`) or tell the user what is missing. +When no MCP tool covers a resource, field, or sub-endpoint, use the `cpln` CLI for that piece (ground the command in this skill, and in `--help` where you can run it) or tell the user what is missing. ## Setup & auth @@ -35,7 +35,7 @@ cpln profile update default --org ORG --gvc GVC # set defaults ("update" create **CI/CD needs no profile.** With `CPLN_TOKEN` set (service-account key, from `cpln serviceaccount add-key`), the CLI runs a profile-less session against `api.cpln.io`. Add `CPLN_ORG` / `CPLN_GVC` for defaults and `CPLN_SKIP_UPDATE_CHECK=1` to silence update checks. Resolution everywhere is **flag, then env var, then profile**: `--org` beats `CPLN_ORG` beats the profile default — same for `--gvc`/`CPLN_GVC`, `--profile`/`CPLN_PROFILE`, `--endpoint`/`CPLN_ENDPOINT`, `--token`/`CPLN_TOKEN`. Profiles live in `~/.config/cpln` (override with `CPLN_HOME`). -**Never pass `--token`** — it leaks into logs and shell history; use `CPLN_TOKEN` or a profile. Inspect context with `cpln profile get` — **there is no `cpln whoami`.** **`cpln profile token` (prints the profile's live access JWT) is break-glass** — it exposes a live credential: never suggest it or run it on your own; use it only when the user explicitly asks. **Secret data commands belong to the user**: never run `cpln secret reveal`, `cpln secret create-*`, or `cpln secret edit` yourself; a user may run `cpln secret create-* --file` with a value they hold. Explain any profile state changes so operators can revert them. +**Never pass `--token`** — it leaks into logs and shell history; use `CPLN_TOKEN` or a profile. Inspect context with `cpln profile get` — **there is no `cpln whoami`.** **`cpln profile token` prints the profile's live access JWT**, a live credential: never run it or suggest it, since its output would land in the conversation; a user who asks for the token runs it in their own terminal. **Secret data commands belong to the user**: never run `cpln secret reveal`, `cpln secret create-*`, or `cpln secret edit` yourself; a user may run `cpln secret create-* --file` with a value they hold. Explain any profile state changes so operators can revert them. ## Command structure & shared flags @@ -206,6 +206,7 @@ Dedicated verb per operation; the flags are **singular** — `--location`, `--vo | Delete snapshot | `cpln volumeset snapshot delete REF --snapshot-name NAME` | Destructive | | Delete volume | `cpln volumeset volume delete REF [--location LOC] [--volume-index N]` | Destructive (data loss) | | Shrink volume | `cpln volumeset shrink REF --new-size GIB [--location LOC]` | **DESTRUCTIVE** (replaces the volume and restarts the replica) | +| Copy volume | no CLI verb: `run_volumeset_command` with `copyVolume`, or `POST .../volumeset/NAME/-command` with `type: copyVolume` | **DESTRUCTIVE** (deletes the volume at the destination index) | `shrink` copies the data with rsync onto a new, smaller volume (the replica restarts for the final sync), then deletes the old one. It runs on `ext4`/`xfs` (not `shared`). The platform refuses a size below the volume set's `initialCapacity` or below used bytes plus 5% (HTTP 400), and a shrink that fails keeps the old volume. Apply the destructive-op confirmation from the operating guide first, and snapshot as a recovery point. Detail: `stateful-storage` skill. diff --git a/plugins/cpln/skills/create-app/SKILL.md b/plugins/cpln/skills/create-app/SKILL.md index 569fd4c..fb628a6 100644 --- a/plugins/cpln/skills/create-app/SKILL.md +++ b/plugins/cpln/skills/create-app/SKILL.md @@ -11,10 +11,10 @@ You write the app's files, Control Plane builds them into an image, and `mcp__cp | Your environment | Files live | Build | |---|---|---| -| You can write files and run commands, and the `cpln` CLI is installed and logged in | **Local:** a folder `./NAME` on the user's machine, theirs to keep and version | `cpln image build --remote --dir ./NAME --name NAME:v1 --org ORG`, then `deploy_app` with `image: //image/NAME:v1` | -| No filesystem or commands (ChatGPT, Claude web and desktop), or no working CLI | **Stored:** on Control Plane through `mcp__cpln__write_app_files`, kept across sessions | `deploy_app` with the same `name` builds the stored files | +| You run in a shell on the user's machine (a coding agent such as Claude Code, Codex, or Cursor), and the `cpln` CLI is installed and logged in | **Local:** a folder `./NAME` on the user's machine, theirs to keep and version | `cpln image build --remote --dir ./NAME --name NAME:v1 --org ORG`, then `deploy_app` with `image: //image/NAME:v1` | +| A chat app (ChatGPT, Claude web and desktop), even one with a code sandbox, or no working CLI | **Stored:** on Control Plane through `mcp__cpln__write_app_files`, kept across sessions | `deploy_app` with the same `name` builds the stored files | -With a filesystem and a working CLI, local is the default; stored is fine when the user asks for it. The CLI only builds: `ORG` is the org the tools use, and the deploy, every read, and every secret go through the tools. Never hand a CLI command to a user without a filesystem. Say which way you are taking. +In a shell on the user's machine with a working CLI, local is the default; stored is fine when the user asks for it. The CLI only builds: `ORG` is the org the tools use, and the deploy, every read, and every secret go through the tools. A chat app's sandbox is not the user's machine: never look for, install, or run `cpln` there, and give the user a CLI command only when they ask for one or a step has no tool, such as building a folder they already have. Say which way you are taking. Other starting points: an existing image or a git repository goes straight to `deploy_app` (`image` or `repoUrl`); a folder the user already has is built with the CLI. A database or Redis the app needs comes from `mcp__cpln__add_database`, whose result lists the env values to pass to `deploy_app`; other infrastructure comes from the Template Catalog (`template-catalog` skill). An app the user asks for, for example a blog, a wiki, or a shop, is one you write; install a template instead only when they name one. Never build a database from source or inline an app into a base image. @@ -42,7 +42,7 @@ A change to the workload's settings (scaling, env, exposure, probes) is `update_ | `get_app_files` says | Source of truth | What to do | |---|---|---| | Files written through `write_app_files` | Control Plane's copy | Read the file, edit with `write_app_files` (`edits` need the exact current text), then `deploy_app`. To move the app local: download the archive and continue there | -| Files uploaded by the CLI from a folder | The user's folder | With a filesystem: edit there, rebuild with `cpln image build --remote --dir PATH --name NAME:TAG --org ORG`, then `deploy_app` with the new `image`. Without: tell the user what to change; `write_app_files` refuses without `adopt: true` | +| Files uploaded by the CLI from a folder | The user's folder | In a shell on their machine: edit there, rebuild with `cpln image build --remote --dir PATH --name NAME:TAG --org ORG`, then `deploy_app` with the new `image`. In a chat app: tell the user what to change and give them that build command; `write_app_files` refuses without `adopt: true` | | No files; images built from a repository | The repository | Change it there, then `deploy_app` with `repoUrl` | | No files; images pushed outside a build | Unknown | Ask the user where the code lives; never rewrite it | | No files, no images | A new app | Start the journey | diff --git a/plugins/cpln/skills/k8s-operator/SKILL.md b/plugins/cpln/skills/k8s-operator/SKILL.md index 9720ff9..8c8648a 100644 --- a/plugins/cpln/skills/k8s-operator/SKILL.md +++ b/plugins/cpln/skills/k8s-operator/SKILL.md @@ -22,7 +22,7 @@ kubectl get pods -n controlplane -l app=operator cpln operator install --serviceaccount k8s-operator --org ORG ``` -`cpln operator install` configures **auth only** (the Helm step deploys the operator): it gets-or-creates the service account, adds it to a group (`--serviceaccount-group`, default `superusers` — any other group prints a warning), mints a **new key**, and applies a Secret named after the org in the `controlplane` namespace. Re-running with the same `--serviceaccount` is a no-op; a different name replaces the secret with a fresh key; an org-named secret the operator does not own aborts the install. `--export` prints the Secret YAML for Git instead of applying it — but still creates the service account and key on the platform. +`cpln operator install` configures **auth only** (the Helm step deploys the operator): it gets-or-creates the service account, adds it to a group (`--serviceaccount-group`, default `superusers` — any other group prints a warning), mints a **new key**, and applies a Secret named after the org in the `controlplane` namespace. Re-running with the same `--serviceaccount` is a no-op; a different name replaces the secret with a fresh key; an org-named secret the operator does not own aborts the install. `--export` prints the Secret YAML instead of applying it, and still creates the service account and key on the platform. The YAML holds that key: the user runs it in their own terminal, and it stays out of Git unless encrypted (Sealed Secrets, SOPS). Manual equivalent (one secret per org; multiple orgs = multiple secrets): diff --git a/plugins/cpln/skills/metrics-observability/SKILL.md b/plugins/cpln/skills/metrics-observability/SKILL.md index e6e548b..815ce37 100644 --- a/plugins/cpln/skills/metrics-observability/SKILL.md +++ b/plugins/cpln/skills/metrics-observability/SKILL.md @@ -28,6 +28,7 @@ egress # outbound bytes/minute (a sum by (workload) (requests_per_second{response_class="500"}) # 5xx rate; response_class is "200".."500" histogram_quantile(0.95, sum by (le) (request_duration_ms_bucket)) # p95 latency (ms); no rate() wrapper sum by (gvc, workload) (increase(container_restarts[5m])) # restarts in the last 5m +increase(container_restarts[5m]) and on (uid, container_name) container_last_terminated_reason{reason="OOMKilled"} # OOM-killed restarts ``` ## Built-in metrics @@ -38,7 +39,7 @@ Collected for every workload, no configuration. Names and types below are the re **Traffic** (per pod): `requests_per_second` and `requests_initiated_per_second` (pre-rated gauge, label `response_class`); `request_duration_ms_bucket` (latency histogram, keeps `le`). -**Stability**: `container_restarts`, `workload_progress_failure`, `workload_rescheduled_replicas`, `cron_executions`, `domain_warnings` (cumulative counters); `cron_execution_rate` (pre-rated); `capacity_ai_updates`, `load_balancer` (gauge). +**Stability**: `container_restarts`, `workload_progress_failure`, `workload_rescheduled_replicas`, `cron_executions`, `domain_warnings` (cumulative counters); `cron_execution_rate` (pre-rated); `capacity_ai_updates`, `load_balancer`, `container_last_terminated_reason` (gauge; `reason` label, e.g. `OOMKilled`). **Volume** (per volume set): `volume_set_capacity_bytes`, `volume_set_used_bytes`, `volume_set_free_bytes`, `volume_set_billable_bytes`, `volume_set_capacity_billable`, `volume_set_snapshots_billable`. diff --git a/plugins/cpln/skills/mk8s-byok/SKILL.md b/plugins/cpln/skills/mk8s-byok/SKILL.md index 3612313..ab85cb5 100644 --- a/plugins/cpln/skills/mk8s-byok/SKILL.md +++ b/plugins/cpln/skills/mk8s-byok/SKILL.md @@ -48,7 +48,7 @@ Exactly one provider per cluster (the schema enforces XOR). For every provider e ## The cluster spec essentials -- **`version`**: required, no default, a **closed enum** of specific patch versions (currently `1.26.0` through `1.35.3`). The set drifts as versions are added/retired; pull the live list from `get_resource` with `schema: true`, or just submit and let the typed tool's validation error name the valid values. Updating it is **upgrade-only**: mk8s rejects downgrades. +- **`version`**: required, no default, a **closed enum** of specific patch versions (currently `1.26.0` through `1.36.5`). The set drifts as versions are added/retired; pull the live list from `get_resource` with `schema: true`, or just submit and let the typed tool's validation error name the valid values. Updating it is **upgrade-only**: mk8s rejects downgrades. - **`nodePools`** (per provider) — give at least one to get worker capacity. Common fields are `name`/`labels`/`taints`; the rest are provider-specific. Each pool's **`minSize`/`maxSize` drive the cluster autoscaler** (set `maxSize > minSize` to allow scale-up). - **`autoscaler`** (per provider) — defaults: `expander: [most-pods]`, `unneededTime: 10m`, `unreadyTime: 20m`, `utilizationThreshold: 0.7`. Usually leave it. - **`networking`** (per provider) — `serviceNetwork` (default `10.43.0.0/16`) and `podNetwork` (default `10.42.0.0/16`) must differ and are **unmodifiable after creation**; pick non-overlapping CIDRs up front. AWS and GCP additionally accept `podNetwork: vpc`. diff --git a/plugins/cpln/skills/operating-guide/SKILL.md b/plugins/cpln/skills/operating-guide/SKILL.md index c07fa0e..f983889 100644 --- a/plugins/cpln/skills/operating-guide/SKILL.md +++ b/plugins/cpln/skills/operating-guide/SKILL.md @@ -12,7 +12,7 @@ The core rules arrive with every MCP connection. This guide holds only what they A destructive call needs the user's explicit approval after you say what it removes or breaks. Three kinds need a fresh yes that answers the stated blast radius, even when the opening message already asked: - **Cascades:** deleting a GVC removes every workload and identity in it; the platform refuses while a volume set remains. -- **Data loss:** deleting or restoring volumes and snapshots; uninstalling a template release deletes its volume data. +- **Data loss:** deleting or restoring volumes and snapshots; copying a volume, which deletes the volume at the destination index; uninstalling a template release deletes its volume data. - **Production targets:** a name that says so, or public traffic, custom domains, several replicas, or real users. Also destructive: removing bindings, members, routes, locations, or policies; shrinking a volume, which moves its data to a new volume and restarts its replica; changing a workload's type or name, or a volume set's filesystem or performance class, which means delete and recreate. Hesitation, "maybe", or a counter-question is not approval. A resource you created by mistake this session, and only that, you remove and report. @@ -53,9 +53,9 @@ The tag `cpln/managedByTerraform: "true"` marks a resource Terraform or Pulumi o ## CLI and profiles -With the MCP connected, its tools do everything they cover, reads included: never `cpln workload get` or `cpln gvc get` to look around. The `cpln` CLI is only for what the tools cannot do: building a folder on disk (`cpln image build --remote --dir PATH --name NAME:TAG --org ORG`, with the org the MCP uses), `cpln workload connect`, `cpln workload exec`, port-forward, `cpln cp`, `cpln image copy`, `cpln convert`, and CI/CD with a service-account `CPLN_TOKEN`. When the MCP is connected but signed out, ask the user to sign in again rather than switch to the CLI: the CLI acts as its own profile and can reach orgs the user never granted. Without the MCP, use the CLI. Every command comes from the `cpln` skill and `--help`, never from memory. When a tool covers the action, call it rather than running or handing the user a command; when none covers a field, use the CLI or say what is missing. +With the MCP connected, its tools do everything they cover, reads included: never `cpln workload get` or `cpln gvc get` to look around. The `cpln` CLI is only for what the tools cannot do: building a folder on disk (`cpln image build --remote --dir PATH --name NAME:TAG --org ORG`, with the org the MCP uses), `cpln workload connect`, `cpln workload exec`, port-forward, `cpln cp`, `cpln image copy`, `cpln convert`, and CI/CD with a service-account `CPLN_TOKEN`. When the MCP is connected but signed out, ask the user to sign in again rather than switch to the CLI: the CLI acts as its own profile and can reach orgs the user never granted. Without the MCP, use the CLI. Run `cpln` only in a shell on the user's machine; a chat app's sandbox is not one, so there never look for, install, or run it, and give the user the command instead. Every command comes from the `cpln` skill (and `--help` where you can run it), never from memory. When a tool covers the action, call it rather than running or handing the user a command; when none covers a field, use the CLI or say what is missing. -`?toolsets=` on the MCP URL picks the tools: `core` (default), `mk8s`, `full`, or `readonly`. When a task needs a tool this connection lacks, tell the user which profile to reconnect with. +`?toolsets=` on the MCP URL picks the tools: `core` (default), `mk8s`, `full`, or `readonly`. When a task needs a tool this connection lacks, tell the user which profile to reconnect with. The ChatGPT listing always runs `core`: there, do that step in the Console or give the user the CLI command instead. ## Failures diff --git a/plugins/cpln/skills/org-management/SKILL.md b/plugins/cpln/skills/org-management/SKILL.md index c1cfbb8..528e859 100644 --- a/plugins/cpln/skills/org-management/SKILL.md +++ b/plugins/cpln/skills/org-management/SKILL.md @@ -84,15 +84,15 @@ Profiles store CLI credentials and default context (org, GVC). A user can belong | Action | Command | |:---|:---| | Interactive login (creates `default` profile) | `cpln login [PROFILE]` | -| Create / update profile (`create` is an alias of `update`) | `cpln profile update PROFILE --org ORG --gvc GVC --token TOKEN` | +| Create / update profile (`create` is an alias of `update`) | `cpln profile update PROFILE --org ORG --gvc GVC` | | Set default | `cpln profile set-default PROFILE` | -| List / show token | `cpln profile get` / `cpln profile token PROFILE` | +| List / show token (the user runs `token` in their own terminal) | `cpln profile get` / `cpln profile token PROFILE` | **Token precedence:** `--token` flag, then `CPLN_TOKEN` env var, then the profile token. Env overrides: `CPLN_PROFILE`, `CPLN_TOKEN`, `CPLN_ORG`, `CPLN_GVC`. Prefer `CPLN_TOKEN` (or a profile) over `--token` in CI — flags leak into shell history and logs. > **Switching org clears the default GVC.** `cpln profile update --org NEWORG` without `--gvc`, or saving a service-account `--token` (which carries its own org) without `--gvc`, **unsets the profile's GVC** (the new org rarely has a same-named GVC). Re-pass `--gvc`. A user `--token` leaves the GVC intact. -REST/API calls use `Authorization: Bearer TOKEN` against `https://api.cpln.io`; get a token from a service-account key or `cpln profile token`. +REST/API calls use `Authorization: Bearer TOKEN` against `https://api.cpln.io`, with a service-account key the user keeps in `CPLN_TOKEN` or a `cpln profile token` they run in their own terminal; a token never goes into the chat. ## SSO / SAML diff --git a/plugins/cpln/skills/stateful-storage/SKILL.md b/plugins/cpln/skills/stateful-storage/SKILL.md index 63c6b52..8e36ef4 100644 --- a/plugins/cpln/skills/stateful-storage/SKILL.md +++ b/plugins/cpln/skills/stateful-storage/SKILL.md @@ -11,7 +11,7 @@ A **VolumeSet** is GVC-scoped persistent storage for workloads. The `workload` s ## Filesystem types and performance classes -| Filesystem | Access | Workloads | Volumes provisioned | Snapshots / shrink / delete-volume | +| Filesystem | Access | Workloads | Volumes provisioned | Snapshots / shrink / copy / delete-volume | |---|---|---|---|---| | `ext4` | read-write-once | one stateful/vm workload | one per replica, per location | yes | | `xfs` | read-write-once | one stateful/vm workload | one per replica, per location | yes | @@ -74,7 +74,6 @@ Mount with `mcp__cpln__mount_volumeset_to_workload` — it attaches to the **fir - **ext4/xfs require a `stateful` or `vm` workload** (mounting on serverless/standard returns HTTP 400); `shared` mounts on any type. Workload type is immutable — see "Migrating to stateful" below. - Up to **15 volumes** per container. **Reserved mount paths** (rejected): `/dev`, `/dev/log`, `/tmp`, `/var`, `/var/log`. -- `recoveryPolicy`: `retain` (default — reuse an existing volume's data on a new replica) or `recycle` (start fresh). - `path` is required for non-vm workloads and rejected for `vm` (VM disks use `name`/`bus`/`bootOrder` instead). - Stateful workloads give each replica a stable index and its own volume; `spec.loadBalancer.replicaDirect` (stateful-only) exposes per-replica endpoints — see the `workload` skill. @@ -106,12 +105,13 @@ Each of these is one `mcp__cpln__run_volumeset_command` call on a volume picked - **Expand** (`expandVolume`) is live, with no downtime, on every filesystem, at most 4 times per volume per rolling 24 hours. - **Shrink** (`shrinkVolume`, ext4/xfs only): data is migrated to the new smaller volume via an online presync + final delta sync, and the replica restarts during the swap. The platform **refuses the shrink with HTTP 400 below the volume set's `initialCapacity`, below used bytes plus 5% metadata headroom, or when it cannot read the volume's used bytes**, and a shrink that fails keeps the old volume. Floor is the class minimum (10 / 200 GB). - **Delete a volume** (`deleteVolume`, ext4/xfs only): permanent loss of that volume's data. +- **Copy** (`copyVolume`, ext4/xfs only): copies the volume to the same `volumeIndex` in `targetLocation`, of this volume set or of `targetVolumeSet` (`//volumeset/`, `//gvc//volumeset/`, or `/org//gvc//volumeset/`, same org, needs `exec.copyVolume` on it). The device already at the destination is **deleted and replaced**, so `acknowledgeDestinationVolumeDeletion: true` is always required. Within one volume set the target location must differ from the source. Both locations run the command, and `get_command` shows each side's stage. -Shrink, volume-delete, snapshot-delete, and restore are destructive: **snapshot first** as the recovery net, then present the blast radius and get the user's approval before the call (it runs at once, with no server-side preview). +Shrink, volume-delete, snapshot-delete, restore, and copy are destructive: **snapshot first** as the recovery net (for a copy, snapshot the destination volume; the source is unchanged), then present the blast radius and get the user's approval before the call (it runs at once, with no server-side preview). ## Shared filesystem -A `shared` volumeset is mounted read-write by many workloads at once but supports only expand (no snapshots, shrink, or volume-delete). Each mount point is provisioned its own CPU/memory, tuned with `mountOptions.resources`: +A `shared` volumeset is mounted read-write by many workloads at once but supports only expand (no snapshots, shrink, copy, or volume-delete). Each mount point is provisioned its own CPU/memory, tuned with `mountOptions.resources`: ```yaml spec: diff --git a/plugins/cpln/skills/template-catalog/SKILL.md b/plugins/cpln/skills/template-catalog/SKILL.md index 2734a8b..1e08f00 100644 --- a/plugins/cpln/skills/template-catalog/SKILL.md +++ b/plugins/cpln/skills/template-catalog/SKILL.md @@ -30,7 +30,7 @@ Call `browse_templates` with `query` naming the capability or product needed. Wh ## Configure and upgrade -Reconfigure with `upgrade_template`: pass `name` plus the new `version` and/or `values`. **`values` REPLACES the release's values entirely — there is no reuse-merge** — so start from the current values, never a partial. `template` and `gvc` are immutable and read from the installed release, so you don't pass them. Roll back with `rollback_template` (needs `?toolsets=full`) or `cpln helm rollback`. +Reconfigure with `upgrade_template`: pass `name`, the new `version` (omit it for the latest), and the complete `values`. **`values` REPLACES the release's values entirely, with no reuse-merge**, so start from the values it runs with now, which the user reads in the Console and never pastes into the chat; never send a partial. `template` and `gvc` are immutable and read from the installed release, so you don't pass them. Roll back with `rollback_template` (needs `?toolsets=full`) or `cpln helm rollback`. Access scope lives in `values` under a per-template key (`internal_access.type`, `internalAccess.type`, `internalAllowType`, or `firewall.internal_inboundAllowType`), with values `same-gvc` (default), `same-org`, `workload-list` plus a `workloads:` list, and `none` on a few. @@ -67,7 +67,7 @@ Reference `values.yaml` for any template lives in the [templates repo](https://g | Symptom | Cause | Fix | |---|---|---| | `rollback_template` not found | core profile | reconnect `?toolsets=full` or use `cpln helm rollback` | -| Upgrade lost settings | `values` replaces, not merges | re-supply full values from `cpln helm get values --all` | +| Upgrade lost settings | `values` replaces, not merges | re-supply the full values, which the user reads in the Console | | Install failed / release stuck | partial apply, bad values, or unready workloads | inspect `get_installed_template` and `cpln helm history`; fix values and `upgrade_template`, or `uninstall` and reinstall | | Workloads pending after install | image pull / firewall / resources | `diagnose_workload`, then the `workload-troubleshooting` skill | | Install succeeded, database never starts, logs empty | the prerequisite secret did not exist at install | create it with `create_secret` (or use `add_database`), then `upgrade_template` or reinstall | From 328f5c5fcb05a6e9c41263ca32337685a57a707c Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Thu, 29 Oct 2026 00:28:24 +0200 Subject: [PATCH 10/12] Bump version to 2.5.0 --- .claude-plugin/marketplace.json | 2 +- .cursor-plugin/marketplace.json | 4 ++-- CHANGELOG.md | 2 ++ plugins/cpln/.claude-plugin/plugin.json | 2 +- plugins/cpln/.codex-plugin/plugin.json | 2 +- plugins/cpln/.cursor-plugin/plugin.json | 2 +- plugins/cpln/plugin.json | 2 +- 7 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f8d89d5..e6a40f0 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ "name": "cpln", "source": "./plugins/cpln", "description": "Control Plane AI workflows, skills, guardrails, and MCP configuration.", - "version": "2.4.4", + "version": "2.5.0", "author": { "name": "Control Plane", "email": "support@controlplane.com", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 43170f8..fd1ce96 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Control Plane plugins for Cursor — multi-cloud workload deployment, networking, troubleshooting.", - "version": "2.4.4" + "version": "2.5.0" }, "plugins": [ { "name": "cpln", "source": "plugins/cpln", - "version": "2.4.4", + "version": "2.5.0", "description": "Control Plane — hybrid multi-cloud platform. Skills, agents, and guardrails for deploying workloads, configuring networking, troubleshooting, and migrating from Kubernetes across AWS, GCP, Azure, and private clouds." } ] diff --git a/CHANGELOG.md b/CHANGELOG.md index 82b7446..8d93bf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this ## [Unreleased] +## [2.5.0] - 2026-10-29 + ### Added - `run_volumeset_command` runs one volume set command (expand, shrink, snapshot, restore, or delete) and returns its command id for `get_command`, as `start_workload_cron` now does. diff --git a/plugins/cpln/.claude-plugin/plugin.json b/plugins/cpln/.claude-plugin/plugin.json index 64c3086..5ef2225 100644 --- a/plugins/cpln/.claude-plugin/plugin.json +++ b/plugins/cpln/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cpln", - "version": "2.4.4", + "version": "2.5.0", "description": "Control Plane — hybrid multi-cloud platform. Skills, agents, and guardrails for deploying workloads, configuring secret access and networking, troubleshooting, and migrating from Kubernetes across AWS, GCP, Azure, and private clouds.", "author": { "name": "Control Plane", diff --git a/plugins/cpln/.codex-plugin/plugin.json b/plugins/cpln/.codex-plugin/plugin.json index 08a2bb6..c006c17 100644 --- a/plugins/cpln/.codex-plugin/plugin.json +++ b/plugins/cpln/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cpln", - "version": "2.4.4", + "version": "2.5.0", "description": "Control Plane skills, operating rules, and MCP server for building, deploying, and running containerized apps across AWS, GCP, Azure, Oracle Cloud, and your own hardware.", "author": { "name": "Control Plane", diff --git a/plugins/cpln/.cursor-plugin/plugin.json b/plugins/cpln/.cursor-plugin/plugin.json index f3377dc..65f6635 100644 --- a/plugins/cpln/.cursor-plugin/plugin.json +++ b/plugins/cpln/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cpln", - "version": "2.4.4", + "version": "2.5.0", "description": "Control Plane — hybrid multi-cloud platform. Skills, agents, and guardrails for deploying workloads, configuring secret access and networking, troubleshooting, and migrating from Kubernetes across AWS, GCP, Azure, and private clouds.", "author": { "name": "Control Plane", diff --git a/plugins/cpln/plugin.json b/plugins/cpln/plugin.json index b1b7b39..0631bce 100644 --- a/plugins/cpln/plugin.json +++ b/plugins/cpln/plugin.json @@ -1,6 +1,6 @@ { "name": "cpln", - "version": "2.4.4", + "version": "2.5.0", "description": "Control Plane skills, operating rules, and MCP server for building, deploying, and running containerized apps across AWS, GCP, Azure, Oracle Cloud, and your own hardware.", "author": { "name": "Control Plane Corporation", From a2f43314a4b2255be3916d8ef6b15094bc046092 Mon Sep 17 00:00:00 2001 From: MajidAbuRmila Date: Thu, 29 Oct 2026 00:41:45 +0200 Subject: [PATCH 11/12] Release through a pull request to main --- CLAUDE.md | 2 +- CONTRIBUTING.md | 18 ++++-- scripts/bump-version.sh | 135 +++++++++++++++++++++++++++++++--------- 3 files changed, 120 insertions(+), 35 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2b182cb..4b0f638 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -97,6 +97,6 @@ The server knows the fetched map's skills plus those of the map bundled in its b ## Versioning -Work lands on `develop`, which the test MCP server reads; `main` is the released line that installs and the production MCP server read. A release is `scripts/bump-version.sh ` run on `develop`: it updates every plugin manifest and the marketplace entries in lockstep, promotes the CHANGELOG `[Unreleased]` block, commits, tags, and pushes `develop`, `main`, and the tag together. Don't edit version strings by hand. Details: `CONTRIBUTING.md`. +Work lands on `develop`, which the test MCP server reads; `main` is the released line that installs and the production MCP server read. A release is `scripts/bump-version.sh ` run on `develop`: it updates every plugin manifest and the marketplace entries in lockstep, promotes the CHANGELOG `[Unreleased]` block, commits, pushes `develop`, and opens the release pull request to `main`. Once it is approved and merged with Rebase and merge, `scripts/bump-version.sh --finish` tags `main` and rebases `develop` onto it. Don't edit version strings by hand. Details: `CONTRIBUTING.md`. In the CHANGELOG, keep only the headings that have entries — omit empty `Added` / `Changed` / `Fixed` / `Removed` sections (including under `[Unreleased]`). Keep each entry as short as possible — one customer-facing line that summarizes rather than enumerates; specifics and internal refactors live in git history, not the changelog. Avoid arrow characters like `→` — write `to`, `-`, or `/` instead. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e20673..52dd34b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ For Markdown-only changes, review links, tables, frontmatter, and command exampl ## Branches - `develop` is where work lands: open pull requests against it. The test MCP server reads it, so a merged change reaches the test environment within the hour. -- `main` is the released line. Installs, the marketplaces, and the production MCP server read it, and only the release script updates it. +- `main` is the released line. Installs, the marketplaces, and the production MCP server read it, and it changes only through the approved release pull request the release script opens. A fix that must ship fast is a normal pull request to `develop` plus a patch release, so `main` never diverges from `develop`. @@ -69,7 +69,7 @@ Pick the bump based on what changed since the last tag: ## Cutting a release -Maintainers release from `develop` with one script; CI does the rest. +Maintainers release from `develop` with one script in two steps, since `main` takes changes only through a pull request with one approval; CI does the rest. 1. **Write the release notes as changes merge**, under `[Unreleased]` in `CHANGELOG.md`. Keep entries operational and user-facing: describe what changed for someone using the plugin, not what changed in the repo. Keep only the subsections that have entries. @@ -80,14 +80,22 @@ Maintainers release from `develop` with one script; CI does the rest. git switch develop && git pull --ff-only ``` -4. **Rehearse, then release.** +4. **Rehearse, then open the release pull request.** ```bash ./scripts/bump-version.sh 1.1.0 --dry-run ./scripts/bump-version.sh 1.1.0 ``` - The script stops before changing anything when it is not on `develop`, the tree is dirty, `develop` is out of sync with `origin`, `main` cannot fast-forward, the tag exists, `[Unreleased]` is empty, or the tool-mention check fails. Otherwise it bumps every manifest, promotes `[Unreleased]` to `[1.1.0] - YYYY-MM-DD`, commits `Bump version to 1.1.0`, tags `v1.1.0`, and pushes `develop`, `main` (fast-forwarded to the release commit), and the tag in one atomic push. If the push is rejected, nothing changes on `origin`, and the script prints how to retry or undo. + The script stops before changing anything when it is not on `develop`, the tree is dirty, `develop` is out of sync with `origin`, the tag exists, `main` holds commits `develop` lacks (the previous release was never finished), a release pull request is already open, `[Unreleased]` is empty, or the tool-mention check fails. Otherwise it bumps every manifest, promotes `[Unreleased]` to `[1.1.0] - YYYY-MM-DD`, commits `Bump version to 1.1.0`, pushes `develop`, and opens the pull request `Release 1.1.0` from `develop` to `main` with the `[1.1.0]` notes. It needs `gh` signed in. If the push is rejected, nothing changes on `origin`, and the script prints how to retry or undo. -5. **The release workflow takes over.** On the `v1.1.0` tag push, `.github/workflows/release.yml`: +5. **Merge with Rebase and merge, then finish the release.** Once a teammate approves the pull request, merge it with **Rebase and merge** (`main` requires linear history), then: + ```bash + git switch develop && git pull --ff-only + ./scripts/bump-version.sh 1.1.0 --finish --dry-run + ./scripts/bump-version.sh 1.1.0 --finish + ``` + The script stops unless `main` carries version `1.1.0` and the tag does not exist. It tags `main` as `v1.1.0` and pushes the tag. Rebase and merge gives the commits new ids on `main`, so it then rebases `develop` onto `main`, which drops the released commits and replays anything that landed on `develop` since, and pushes `develop` with `--force-with-lease`. It refuses to push when the rebase conflicts or would change `develop`'s content, and prints how to realign by hand. Anyone with a branch cut from the old `develop` rebases it onto the new one. + +6. **The release workflow takes over.** On the `v1.1.0` tag push, `.github/workflows/release.yml`: - Verifies all manifests carry version `1.1.0`, which catches drift if a manifest was hand-edited. - Validates every JSON file parses. - Extracts the `## [1.1.0]` section from `CHANGELOG.md`. diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh index c30af6a..42cde2c 100755 --- a/scripts/bump-version.sh +++ b/scripts/bump-version.sh @@ -1,19 +1,28 @@ #!/usr/bin/env bash # -# Cut a release from develop: bump the plugin version across the manifests, -# promote the CHANGELOG [Unreleased] section, commit, tag, and push develop, -# main (fast-forwarded to the release commit), and the tag in one atomic push. -# The tag push triggers the release workflow. +# Cut a release from develop in two steps, since main takes changes only +# through an approved pull request: # -# Usage: scripts/bump-version.sh [--dry-run] +# 1. scripts/bump-version.sh +# Bump the plugin version across the manifests, promote the CHANGELOG +# [Unreleased] section, commit "Bump version to X.Y.Z" on develop, push +# develop, and open the release pull request from develop to main. +# 2. scripts/bump-version.sh --finish +# Once that pull request merges with Rebase and merge: tag the release on +# main and push the tag, which triggers the release workflow, then move +# develop onto main's rewritten commits so the next release pull request +# holds only new work. # -# --dry-run run every check and print what the release would do; changes nothing +# Usage: scripts/bump-version.sh [--finish] [--dry-run] # -# Run it on develop, clean and in sync with origin, with the release notes -# already under [Unreleased] in CHANGELOG.md. When the release names MCP tools -# that production does not serve yet, deploy the MCP to production first. +# --finish run step 2 +# --dry-run run every check and print what the step would do; changes nothing # -# Files updated (kept in lockstep): +# Run it on develop, clean and in sync with origin. Step 1 needs the release +# notes already under [Unreleased] in CHANGELOG.md. When the release names MCP +# tools that production does not serve yet, deploy the MCP to production first. +# +# Files updated by step 1 (kept in lockstep): # - plugins/cpln/.claude-plugin/plugin.json .version # - .claude-plugin/marketplace.json .plugins[0].version # - plugins/cpln/.codex-plugin/plugin.json .version @@ -24,7 +33,7 @@ # - CHANGELOG.md [Unreleased] -> [X.Y.Z] - YYYY-MM-DD, # plus a fresh empty [Unreleased] above it # -# Dependencies: git, jq, node, awk (BSD or GNU), date. +# Dependencies: git, gh (signed in, step 1 only), jq, node, awk (BSD or GNU), date. set -euo pipefail @@ -43,8 +52,8 @@ MANIFESTS=( ) usage() { - echo "Usage: $0 [--dry-run]" >&2 - echo "Example: $0 1.1.0" >&2 + echo "Usage: $0 [--finish] [--dry-run]" >&2 + echo "Example: $0 1.1.0, then after the release pull request merges: $0 1.1.0 --finish" >&2 exit 1 } @@ -55,10 +64,12 @@ fail() { VERSION="" DRY_RUN=0 +FINISH=0 for arg in "$@"; do case "$arg" in --dry-run) DRY_RUN=1 ;; + --finish) FINISH=1 ;; -*) usage ;; *) [ -z "$VERSION" ] || usage; VERSION="$arg" ;; esac @@ -77,7 +88,7 @@ done TAG="v$VERSION" TODAY="$(date +%Y-%m-%d)" -# Preflight: every check runs before anything changes. +# Preflight shared by both steps: every check runs before anything changes. branch="$(git rev-parse --abbrev-ref HEAD)" [ "$branch" = "$RELEASE_BRANCH" ] || fail "releases are cut from $RELEASE_BRANCH (currently on $branch)" @@ -89,13 +100,68 @@ git fetch --quiet --tags "$REMOTE" "$RELEASE_BRANCH" "$PRODUCTION_BRANCH" [ "$(git rev-parse HEAD)" = "$(git rev-parse "$REMOTE/$RELEASE_BRANCH")" ] \ || fail "$RELEASE_BRANCH is not in sync with $REMOTE/$RELEASE_BRANCH; pull or push first" -git merge-base --is-ancestor "$REMOTE/$PRODUCTION_BRANCH" HEAD \ - || fail "$REMOTE/$PRODUCTION_BRANCH has commits $RELEASE_BRANCH lacks, so it cannot fast-forward; merge it into $RELEASE_BRANCH first" - if git rev-parse --quiet --verify "refs/tags/$TAG" >/dev/null; then fail "tag $TAG already exists" fi +# Step 2: tag the merged release on main and move develop onto main's commits. + +if [ "$FINISH" -eq 1 ]; then + released="$(git show "$REMOTE/$PRODUCTION_BRANCH:plugins/cpln/.claude-plugin/plugin.json" | jq -r '.version')" + [ "$released" = "$VERSION" ] \ + || fail "$REMOTE/$PRODUCTION_BRANCH is at $released, not $VERSION; merge the release pull request first" + + release_commit="$(git rev-parse "$REMOTE/$PRODUCTION_BRANCH")" + + if [ "$DRY_RUN" -eq 1 ]; then + cat </dev/null + fail "the tag push was rejected, so nothing changed on $REMOTE" + fi + echo "Pushed $TAG on $(git rev-parse --short "$release_commit"); the release workflow now publishes the GitHub Release." + + # GitHub's Rebase and merge writes new commit ids, so develop still holds the + # old ones. Rebasing drops them as already applied and replays anything newer. + before="$(git rev-parse HEAD)" + realign_by_hand="git rebase $REMOTE/$PRODUCTION_BRANCH && git push --force-with-lease=$RELEASE_BRANCH:$before $REMOTE HEAD:refs/heads/$RELEASE_BRANCH" + if ! git rebase --quiet "$REMOTE/$PRODUCTION_BRANCH"; then + git rebase --abort + fail "$RELEASE_BRANCH does not rebase cleanly onto $REMOTE/$PRODUCTION_BRANCH (was the pull request squashed?); $TAG is released, and $RELEASE_BRANCH is unchanged. Realign it by hand: $realign_by_hand" + fi + if ! git diff --quiet "$before" HEAD; then + git reset --quiet --hard "$before" + fail "rebasing $RELEASE_BRANCH onto $REMOTE/$PRODUCTION_BRANCH would change its content, so it is unchanged; $TAG is released. Compare them before realigning: git diff $before $REMOTE/$PRODUCTION_BRANCH" + fi + git push --quiet --force-with-lease="$RELEASE_BRANCH:$before" "$REMOTE" "HEAD:refs/heads/$RELEASE_BRANCH" \ + || fail "the $RELEASE_BRANCH push was rejected; $TAG is released. Realign by hand: $realign_by_hand" + + git fetch --quiet "$REMOTE" "$PRODUCTION_BRANCH:$PRODUCTION_BRANCH" \ + || echo "Note: local $PRODUCTION_BRANCH was not updated; run: git fetch $REMOTE $PRODUCTION_BRANCH:$PRODUCTION_BRANCH" + + echo "Released $VERSION: $RELEASE_BRANCH now builds on $REMOTE/$PRODUCTION_BRANCH." + exit 0 +fi + +# Step 1 preflight. + +command -v gh >/dev/null 2>&1 || fail "gh is required to open the release pull request" +gh auth status >/dev/null 2>&1 || fail "gh is not signed in; run: gh auth login" + +git merge-base --is-ancestor "$REMOTE/$PRODUCTION_BRANCH" HEAD \ + || fail "$REMOTE/$PRODUCTION_BRANCH has commits $RELEASE_BRANCH lacks; finish the previous release first: $0 $(git show "$REMOTE/$PRODUCTION_BRANCH:plugins/cpln/.claude-plugin/plugin.json" | jq -r '.version') --finish" + +open_pr="$(gh pr list --base "$PRODUCTION_BRANCH" --head "$RELEASE_BRANCH" --state open --json number --jq '.[0].number // empty')" +[ -z "$open_pr" ] || fail "release pull request #$open_pr is already open; merge it and run --finish, or close it first" + current="$(jq -r '.version' plugins/cpln/.claude-plugin/plugin.json)" highest="$(printf '%s\n' "$current" "$VERSION" | sort -V | tail -n 1)" [ "$VERSION" != "$current" ] && [ "$highest" = "$VERSION" ] || fail "$VERSION is not above the current version $current" @@ -109,8 +175,9 @@ if [ "$DRY_RUN" -eq 1 ]; then cat <&2 < "$notes" +printf '\nMerge with **Rebase and merge**, then run `scripts/bump-version.sh %s --finish` on %s to tag the release and realign %s.\n' \ + "$VERSION" "$RELEASE_BRANCH" "$RELEASE_BRANCH" >> "$notes" + +if ! pr_url="$(gh pr create --base "$PRODUCTION_BRANCH" --head "$RELEASE_BRANCH" --title "Release $VERSION" --body-file "$notes")"; then + fail "pushed $RELEASE_BRANCH, but the pull request was not opened; open it with: gh pr create --base $PRODUCTION_BRANCH --head $RELEASE_BRANCH --title \"Release $VERSION\"" +fi cat < Date: Thu, 29 Oct 2026 01:11:55 +0200 Subject: [PATCH 12/12] Fix the workload-security router and the CI token advice --- plugins/cpln/skills/gitops-cicd/SKILL.md | 2 +- plugins/cpln/skills/workload-security/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/cpln/skills/gitops-cicd/SKILL.md b/plugins/cpln/skills/gitops-cicd/SKILL.md index ae2f8d8..442e1ec 100644 --- a/plugins/cpln/skills/gitops-cicd/SKILL.md +++ b/plugins/cpln/skills/gitops-cicd/SKILL.md @@ -27,7 +27,7 @@ Set in the platform's variable settings, never inline in scripts: | `CPLN_GVC` | Target GVC, when the pipeline targets one | | `CPLN_SKIP_UPDATE_CHECK=1` | Silence CLI update checks in logs | -With `CPLN_TOKEN` set the CLI runs a profile-less session; resolution is flag, then env var, then profile (`cpln` skill). The official example repos persist the token instead — `cpln profile update default --token "$CPLN_TOKEN"` (`create` is an alias of `update`) — either works. Never pass `--token` on ad-hoc commands and never echo the token. +With `CPLN_TOKEN` set the CLI runs a profile-less session; resolution is flag, then env var, then profile (`cpln` skill). Prefer that session: it keeps the token off the command line. The official example repos persist the token with `cpln profile update default --token "$CPLN_TOKEN"` instead (`create` is an alias of `update`); keep that only in a job that never prints its commands. Never pass `--token` on ad-hoc commands and never echo the token. ## Installing the CLI on runners diff --git a/plugins/cpln/skills/workload-security/SKILL.md b/plugins/cpln/skills/workload-security/SKILL.md index ce30a79..e5a56fc 100644 --- a/plugins/cpln/skills/workload-security/SKILL.md +++ b/plugins/cpln/skills/workload-security/SKILL.md @@ -7,7 +7,7 @@ description: "Production hardening for Control Plane workloads. Use when asked a Deep-dive companion to the `workload` skill, which owns workload types, the spec shape, and the readiness-vs-liveness model. Everything below is production-hardening detail for an existing workload. -**Where settings live.** Health probes go inline in `containers[]` via `create_workload` / `update_workload`. Every other block here — `sidecar.envoy`, `loadBalancer`, `securityOptions`, `rolloutOptions` — is set by its own `configure_workload_*` tool, a set-or-clear PATCH on that one field (`remove: true` clears it). **Tool availability:** these tools live in the `full` toolset profile; if one isn't advertised, reconnect with `?toolsets=full` or use the CLI. +**Where settings live.** Health probes go inline in `containers[]`, and `securityOptions` and `rolloutOptions` are fields of `create_workload` / `update_workload`. `sidecar.envoy` and `loadBalancer` are each set by their own `configure_workload_*` tool, a set-or-clear PATCH on that one field (`remove: true` clears it). **Tool availability:** those two tools live in the `full` toolset profile; if one isn't advertised, reconnect with `?toolsets=full` or use the CLI. ## Health Probes