Template Catalog

Tool availability: preview_template (dry-run) and rollback_template are in the full MCP toolset; browse_templates, get_template, install_template, upgrade_template, uninstall_template, list_installed_templates, and get_installed_template are in core. If a full tool is not advertised, reconnect the MCP server with ?toolsets=full or use the cpln helm CLI fallback.

The Template Catalog ships production-tested charts (Helm under the hood) for databases, caches, queues, brokers, search, gateways, and more — persistent storage wired up, credentials generated as Control Plane secrets, a sane firewall posture, and HA variants where they matter. For any common component the catalog template is the default recommendation, not the fallback: hand-rolled workload + volumeset + secret + firewall stacks routinely ship without backups, with a public database, or single-replica. Lead with the template, and move to a custom workload only when the user has a hard reason — an unusual extension, a legacy image they must reuse, or a feature the template doesn't expose. Template-first is also enforced by the operating guide's skill router.

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 <name> for the version list, prerequisites, and an example values.yaml to copy.

Choosing an HA / scaling variant

This is the choice the catalog can't make for you:

• 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.

Install (MCP)

1. get_template <name> — copy the example values.yaml; edit credentials, replica count, resources, storage size, and access scope.
2. preview_template (full profile) — dry-run render the resources the install would create, without applying anything.
3. install_template — pass org, a unique name (the release id, immutable), template, the values YAML (required, max 128 KiB), an optional version (latest if omitted), and gvc. Omit `gvc` for templates that create their own (the createsGvc flag in browse_templates / get_template; e.g. cockroach, tidb, nats, clickhouse, airflow, mongodb-cluster, redis-multi-location, pgedge).
4. Installs are asynchronous — confirm with get_installed_template <name>.

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.

Access scope lives in the template's values — but the key name varies per template (e.g. internal_access.type, internalAccess.type, internalAllowType, or firewall.internal_inboundAllowType). Values are same-gvc (default), same-org, workload-list (with an explicit workloads: list), and none on a few. Copy the example from get_template rather than writing keys from memory.

CLI fallback (CI/CD)

When MCP is unavailable, or in pipelines with a service-account CPLN_TOKEN, use cpln helm against the OCI registry oci://ghcr.io/controlplane-com/templates/<TEMPLATE> (the slug is the template name):

cpln helm install my-pg oci://ghcr.io/controlplane-com/templates/postgres -f values.yaml  # omit --version for latest
cpln helm template my-pg oci://ghcr.io/controlplane-com/templates/postgres -f values.yaml # preview rendered resources
cpln helm list                                  # releases in the org
cpln helm get values <RELEASE> --all            # currently applied values
cpln helm upgrade <RELEASE> oci://... -f values.yaml
cpln helm history <RELEASE>                      # revision numbers, for rollback
cpln helm rollback <RELEASE> [<REVISION>]        # previous revision if omitted
cpln helm uninstall <RELEASE>

Reference values.yaml for any template lives in the templates repo at <template>/versions/<version>/values.yaml.

Verify

After install, get_installed_template <name> shows the release status, revision, and every resource it created (it decodes the release secret, so the token needs secret reveal permission). Then confirm the workloads are healthy with list_deployments, and check the generated secrets with list_resources (kind secret). Add firewall rules or a domain for any workload that needs external access.

Connection details: an installed service is reachable inside its GVC at <release>-<component>.<gvc>.cpln.local:<port> (e.g. my-pg-postgres.<gvc>.cpln.local:5432); credentials live in the generated dictionary secret — reveal it to read them. The exact workload name, port, and secret keys are in get_installed_template (created resources) and the get_template example values.

Traps

• upgrade_template replaces values — there is no partial merge, so start from the current values, not a fragment.
• Templates with createsGvc make their own GVC — omit `gvc` on install; others require an existing gvc.
• Uninstall removes the resources the release created, including volume data — confirm the blast radius first.
• values key names (credentials, resources, access scope) differ across templates — copy from get_template, don't hand-write from memory.
• Backups (e.g. postgres, mongodb) need a Cloud Account + storage IAM policy to exist first, referenced in the values backup block — see the get_template prerequisites.

Troubleshooting

Quick reference

CLI fallback (CI/CD via a service-account CPLN_TOKEN): cpln helm install|template|list|get|upgrade|rollback|uninstall|history against oci://ghcr.io/controlplane-com/templates/<TEMPLATE>.

Related skills

Documentation

• Template Catalog Overview
• Install via CLI · Terraform · Pulumi · UI