# Openchoreo Platform Engineer

> Platform-level OpenChoreo work via the control-plane MCP server (plus `kubectl` and Helm) — authoring ProjectTypes / ComponentTypes / ResourceTypes / Traits / Workflows, creating Environments and DeploymentPipelines, registering Planes, configuring secret stores and authorization. Use when the user says 'set up a new environment', 'create a deployment pipeline', 'add a ProjectType', 'add a ComponentType', 'add a ResourceType', 'register a data plane', 'configure auth', or 'install OpenChoreo'.

- Skill: `openchoreo/openchoreo-platform-engineer` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add openchoreo/openchoreo-platform-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openchoreo/openchoreo-platform-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: openchoreo (https://skillmd.com/u/openchoreo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openchoreo/openchoreo-platform-engineer

---


# OpenChoreo Platform Engineer Guide

Help with OpenChoreo platform-level work through the control-plane MCP server, with `kubectl` and Helm for cluster-native concerns. Keep this file lean, discover the live platform shape via MCP, and read detailed references only when the task actually needs them.

## Step 0 — Confirm MCP connectivity

Run `list_namespaces`. If the tool isn't reachable, tell the user the `openchoreo-cp` MCP server needs configuring per <https://openchoreo.dev/docs/ai/mcp-servers/> and stop MCP-dependent OpenChoreo actions. `kubectl` and Helm remain usable for cluster-native CRDs.

## Step 1 — Load the concepts reference

Before authoring or modifying any platform resource, read [`./references/concepts.md`](./references/concepts.md). It covers OpenChoreo's resource hierarchy, the Cell runtime model, endpoint visibility, planes, the API version OpenChoreo expects, and the per-task discovery-first workflow — facts the agent will reuse on every task. Memory of these is unreliable; the reference is short.

For each task you take on, also load the matching reference *before* acting on the task:

- **Authoring or updating a `ProjectType` / `ClusterProjectType`** (a project's cell-infrastructure template — cell namespace, quotas, network policy, baseline RBAC) → [`./references/project-types.md`](./references/project-types.md).
- **Authoring or updating a `ComponentType` / `ClusterComponentType` or a `Trait` / `ClusterTrait`** → [`./references/component-types-and-traits.md`](./references/component-types-and-traits.md).
- **Authoring or updating a `ResourceType` / `ClusterResourceType`** (managed-infrastructure template — databases, queues, caches) → [`./references/resource-types.md`](./references/resource-types.md).
- **Authoring or updating a `Workflow` / `ClusterWorkflow`** (CI build template or generic automation) → [`./references/workflows.md`](./references/workflows.md).
- **Writing CEL expressions** in templates / patches / validations → [`./references/cel.md`](./references/cel.md).
- **Authorization (`AuthzRole` / `ClusterAuthzRole` and bindings)** → [`./references/authz.md`](./references/authz.md).
- **Failure isolation across planes, controller / gateway / agent log inspection, gateway / route diagnostics** → [`./references/troubleshooting.md`](./references/troubleshooting.md).

For PE topics not bundled in these references — TLS / external CA, container registries, identity provider configuration, multi-cluster connectivity, deployment topology, observability adapter modules, API gateway modules, alert storage backend choice, IdP / bootstrap auth mappings, Helm upgrades — consult the official PE guide at **<https://openchoreo.dev/docs/platform-engineer-guide/>**. The docs are the source of truth for those topics; do not rely on memory.

## What this skill can do

These are the platform-engineering tasks this skill supports.

- **ProjectType / ClusterProjectType authoring** — a project's cell-infrastructure template: `parameters` + `environmentConfigs` schemas, CEL `validations`, the mandated cell-namespace entry + namespace-scoped policy (quotas, NetworkPolicies, RBAC, image-pull secrets) → [`project-types.md`](./references/project-types.md)
- **ComponentType / ClusterComponentType authoring** — schema, base workload type, resource templates, patches, validation rules, `allowedWorkflows` gating → [`component-types-and-traits.md`](./references/component-types-and-traits.md), [`recipes/author-a-componenttype.md`](./references/recipes/author-a-componenttype.md)
- **ResourceType / ClusterResourceType authoring** — parameter + environmentConfigs schemas, K8s manifest templates with CEL, outputs (`value` / `secretKeyRef` / `configMapKeyRef`), `includeWhen` / `readyWhen`, `retainPolicy` → [`resource-types.md`](./references/resource-types.md)
- **Trait / ClusterTrait authoring** — `creates[]` / `patches[]`, parameter schemas, environment-config overrides → [`component-types-and-traits.md`](./references/component-types-and-traits.md), [`recipes/author-a-trait.md`](./references/recipes/author-a-trait.md)
- **Workflow / ClusterWorkflow authoring** — Argo `runTemplate` shape, `allowedWorkflows` gating, ExternalRefs for secrets → [`workflows.md`](./references/workflows.md), [`recipes/author-a-ci-workflow.md`](./references/recipes/author-a-ci-workflow.md) for component-bound builds, [`recipes/author-a-generic-workflow.md`](./references/recipes/author-a-generic-workflow.md) for standalone automation
- **CEL expressions** in templates / patches / validations → [`cel.md`](./references/cel.md)
- **Authorization** — `AuthzRole` / `ClusterAuthzRole` and bindings → [`authz.md`](./references/authz.md)
- **Environment + DeploymentPipeline lifecycle** — create envs against existing planes, define linear / branching promotion paths → [`recipes/create-an-environment-and-promotion-path.md`](./references/recipes/create-an-environment-and-promotion-path.md)
- **Project + Namespace creation** — onboarding a new tenant namespace with a project, environments, and pipeline. Default to `default` namespace unless the user explicitly asks for a new one → [`recipes/bootstrap-a-namespace.md`](./references/recipes/bootstrap-a-namespace.md)
- **Pod-level diagnostics** — `get_resource_events`, `get_resource_logs` against a ReleaseBinding for app troubleshooting requested by a developer → [`troubleshooting.md`](./references/troubleshooting.md)
- **Cluster-native concerns** — Helm install / upgrade (control plane / planes / cluster-agent; upgrade order: control plane first), `ClusterSecretStore` / `SecretStore`, Argo `ClusterWorkflowTemplate`, Kubernetes Gateway API resources, raw controller / agent / gateway log inspection.
- **Troubleshooting platform-side failures** — failure isolation across planes, plane health checks, controller / gateway / agent logs → [`troubleshooting.md`](./references/troubleshooting.md)

## What this skill cannot do

- **Application-level work — `openchoreo-developer` owns this.** Authoring `Component` / `Workload` / `ReleaseBinding`, editing `workload.yaml`, attaching PE-authored Traits to a Component via `patch_component traits: [...]`, managing `SecretReference` CRUD (`create_secret_reference` / `update_secret_reference` / `delete_secret_reference` — the underlying `ClusterSecretStore` is still PE-owned), hard-deleting developer-side resources (`delete_component` / `delete_workload` / `delete_release_binding` / `delete_project` / `delete_component_release` — but **`delete_namespace` is PE-side**, not exposed via MCP), tracing a runtime crash, deploying or promoting an app, debugging a developer-shape problem. **Pair this skill with `openchoreo-developer`** when the task crosses the boundary — many "this app fails to deploy" problems turn out to be a missing `ClusterTrait` or a misconfigured `DeploymentPipeline`. If both skills are available, run them together immediately.
- **Initial OpenChoreo install from scratch** — Helm install for a fresh control plane and first plane, Colima / k3d / GCP / multi-cluster bootstrap walkthroughs. **`openchoreo-install`** owns this. Once OpenChoreo is running, day-2 platform work comes back here.
- **Aggregated runtime log / metric / trace queries** — log search across replicas, metric queries, trace lookups, alert and incident queries. For pod-level evidence under a binding use `get_resource_events` / `get_resource_logs`; for longer-horizon history, fall back to `kubectl logs` against the relevant plane, or query the observability backend (Loki / Prometheus / Tempo) via its own UI / API when configured.
- **External-system operations** — IdP / Thunder / SSO admin work, external secret-backend admin (Vault / AWS Secrets Manager / OpenBao), Git provider configuration (webhooks, deploy keys), commercial WSO2 Choreo cloud resources, and incident state changes (acknowledge / resolve / RCA). When the user asks for one, say so plainly and direct them to the relevant system; explain the OpenChoreo-side pieces this skill *can* set up.

## Tool surface

Two surfaces: **MCP** (`openchoreo-cp` server) for OpenChoreo CRDs, and **`kubectl` / Helm** for cluster-native concerns (Helm install / upgrade, `ClusterSecretStore`, Argo `ClusterWorkflowTemplate`, Kubernetes Gateway API resources, raw controller / agent / gateway pod logs). The recipes name the right surface for each step.

> **Tool naming.** Throughout this skill, MCP tools are referenced by their bare name (e.g. `create_environment`). The actual callable name carries an agent-specific prefix wrapping the server name — Claude Code uses `mcp__openchoreo-cp__<tool>`. Other coding agents use different prefixes. Apply whatever your agent expects.

> **Scope-collapsed tools.** ProjectType / ComponentType / ResourceType / Trait / Workflow, the three plane families, and the Authz role / binding families are each a single tool that takes a `scope` arg — `"namespace"` (default; requires `namespace_name`) or `"cluster"` for the platform-wide `Cluster*` resource. This skill uses the canonical name + `scope`; e.g. `create_component_type` with `scope: "cluster"` authors a `ClusterComponentType`, `create_resource_type` with `scope: "cluster"` authors a `ClusterResourceType`, and `create_project_type` with `scope: "cluster"` authors a `ClusterProjectType`. The old `*_cluster_*` names still exist as deprecated aliases (banner in v1.1, hidden in v1.2, removed in v1.3) and can be used alternatively against a v1.1 server — prefer the canonical form.

## Working style

The full per-task discovery flow is in `concepts.md` (loaded at *Step 1*). Durable principles to keep in mind:

- **Live cluster output beats memory.** Don't assume available ComponentTypes, Traits, Workflows, Environments, plane status, or field names — discover via MCP first.
- **Schema-first authoring.** Before writing a spec from scratch, fetch the creation schema (`get_component_type_creation_schema`, `get_trait_creation_schema`) or the resource schema (`get_*_schema`). MCP `create_*` / `update_*` calls take structured spec payloads, not YAML files — but the same schema applies.
- **`update_*` for ComponentType / Trait / Workflow is full-spec replacement.** `get_*` first, modify locally, send the complete spec back. Omitting a field deletes it.
- **MCP-first.** Reach for `kubectl` only for cluster-native CRDs (Helm, `ClusterSecretStore`, Argo `ClusterWorkflowTemplate`, Kubernetes Gateway API) or when MCP doesn't expose a write path for the operation.
- **Default to the `default` namespace.** Always ask before creating a new namespace — it's an organisational boundary, not a casual default.
- **Change one layer at a time** (Helm values → control-plane CRD → remote-plane resource → app-visible outcome). Don't fix an application symptom by guessing at platform internals.

## Stable guardrails

- **`update_environment` is partial, but `data_plane_ref` is immutable.** Re-pointing an environment to a different plane requires delete + recreate (and re-binding any existing ReleaseBindings).
- **Helm upgrade order matters.** Control plane first, never move a remote plane ahead of it.
- **Scope matters.** Cluster-scoped and namespace-scoped resources are not interchangeable. `ClusterComponentType` may only reference `ClusterTrait` and `ClusterWorkflow`, not their namespace-scoped counterparts. On the scope-collapsed MCP tools this is the `scope` arg — `scope: "cluster"` operates on the `Cluster*` resource, `scope: "namespace"` (default) on the namespaced one.
- **`status.conditions`, live resource YAML, and current controller logs are better truth sources than memory.** When a task needs exact controller behavior or CRD fields, inspect the repo or current docs instead of guessing.
- **Prefer reversible, inspectable changes** over broad edits across many planes or namespaces.
- **A handed-over migration plan is the spec.** When the user supplies a migration/onboarding plan, take namespace, type names, author-vs-reuse decisions, and per-env overrides from it. Deviate only out loud — state what you're changing and why (cluster reality differs, simplification) *before* acting, never silently substitute.
- **Never mutate a shared type to fit one app.** `update_component_type` / `update_trait` / `update_workflow` on an existing shared (especially cluster-scoped) type is full-spec replacement visible to every consumer. To fit one app's needs, author a new type modelled on the existing shape instead.
- **A missing tool means version skew, not absence.** When a documented MCP tool or `occ` subcommand isn't found, check the installed CLI / server version against the cluster before concluding the surface doesn't exist — report the mismatch to the user, then fall back.

## Anti-patterns

- **Skipping the recipe.** Before any new operation (new CRD kind this turn, lifecycle action, authoring task) — re-scan the recipe index above, load the matching recipe (one Read call), THEN call MCP / kubectl. Skipping is how kubectl falls multiply and existing MCP tools get missed. Concept references aren't enough — recipes name the right tool calls in sequence.
- Loading every reference file before identifying the actual problem.
- Repeating stale examples without checking the current cluster or resource schema.
- Performing wide cluster sweeps before checking the affected object and logs.
- Treating app-level deployment symptoms as purely platform issues without checking the app resource chain.
- Making several platform changes at once and losing the causal signal.
- Creating a new namespace without asking the user — default to `default` unless explicitly told otherwise.
- Reaching for `kubectl` when an MCP tool exists for the operation.
- Sending a partial `update_component_type` / `update_trait` / `update_workflow` spec — the call replaces the whole spec; missing fields are deleted.
- Inventing observability tools that don't exist in this skill (`query_*` log/metric/trace/alert/incident tools). Use `kubectl logs` against the relevant plane, or query the observability backend's own UI.