Manage Helm Releases - Control Plane

The cpln helm command lets you manage Control Plane resources using Helm charts. Define your infrastructure as Helm templates and deploy them as versioned releases with full rollback support.

When to use this

Templated deployments

Use Helm’s templating engine for complex, parameterized configurations

Environment management

Deploy the same chart with different values for dev, staging, and production

Versioned releases

Track deployment history and rollback to previous versions

Helm ecosystem

Leverage existing Helm workflows and chart repositories

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Helm installed

Install Helm (v3 or later).

Required permissions

You need policies to create the resources defined in your chart, plus reveal permission on secrets to manage release state.

Core concepts

Releases

A release is a deployed instance of a Helm chart. Each release:

Has a unique name within your organization
Stores its state in an opaque secret
Tracks revisions for rollback (10 by default, configurable with --history-limit)
Tags resources with cpln/release for tracking

Release name constraints

Release names must follow these rules:

Rule	Detail
Format	DNS-1123 label — lowercase alphanumeric characters and hyphens only
Pattern	Must match `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
Max length	53 characters
Uniqueness	Must be unique within the same organization

Alternatively, use --generate-name (or -g) to auto-generate a name in the format <chart-name>-<unix-timestamp>.

Release state

The release state tracks all resources deployed by the release, enabling:

Detection of added, modified, or removed resources
Automatic cleanup of deleted resources on upgrade
Rollback to any previous revision

Supported resource types

Charts must contain only Control Plane resource definitions. Standard Kubernetes manifests (objects with apiVersion or metadata fields) are not supported and will cause the operation to fail.

If your chart contains any resource with an apiVersion or metadata field, or an unsupported kind, the install/upgrade will abort with:

ERROR: Some resources in the rendered template are not CPLN resources.

Remove any Kubernetes manifests and ensure every resource kind is a supported Control Plane kind.

GVC-scoped resources

The following resource kinds require a GVC context (via --gvc or your default profile context). The GVC must already exist or be created earlier in the same chart: workload, identity, volumeset

Quick start

Create a chart

Generate a new Helm chart:

helm create my-chart

Define resources

Replace the contents of my-chart/templates/ with Control Plane resources:

my-chart/templates/resources.yaml

kind: gvc
name: {{ .Values.gvc.name }}
spec:
  staticPlacement:
    locationLinks:
      - //location/aws-eu-central-1
---
kind: workload
name: {{ .Values.workload.name }}
gvc: {{ .Values.gvc.name }}
spec:
  type: serverless
  containers:
    - name: main
      image: {{ .Values.workload.image }}
      ports:
        - number: 80
          protocol: http

Configure values

Update my-chart/values.yaml:

my-chart/values.yaml

gvc:
  name: my-gvc

workload:
  name: my-app
  image: nginx:latest

Install the release

Deploy the chart:

cpln helm install my-release ./my-chart

Install a release

cpln helm install <release-name> <chart-path>

Install from different sources:

Local chart
Helm repository
OCI registry
Auto-generated name

cpln helm install my-release ./my-chart

cpln helm install my-release postgres \
  --repo https://controlplane-com.github.io/helm-packages \
  --version 2.1.0

cpln helm install my-release \
  <oci-url> \
  --version <version>

cpln helm install --generate-name ./my-chart

Creates a release named <chart-name>-<unix-timestamp> (e.g., my-chart-1709913600).

Wait for readiness

Wait for workloads to become ready:

cpln helm install my-release ./my-chart --wait --timeout 600

Handle chart dependencies

If your chart has dependencies defined in Chart.yaml, use --dependency-update to fetch them automatically:

cpln helm install my-release ./my-chart --dependency-update

Without this flag, missing dependencies will cause an error prompting you to re-run with the flag.

Upgrade a release

Update a release after modifying the chart:

cpln helm upgrade my-release ./my-chart

The CLI:

Renders the updated chart
Applies new and modified resources
Deletes resources removed from the chart (unless they have helm.sh/resource-policy: keep)
Updates the release state

Install or upgrade

Use --install to create the release if it does not exist, or upgrade it if it does:

cpln helm upgrade my-release ./my-chart --install

This is useful in CI/CD pipelines where you don’t want to check whether the release already exists.

Use the same release name and chart name to ensure proper tracking of resources. Upgrading with a different chart name than the original install will fail with:

ERROR: UPGRADE FAILED: cannot upgrade with different chart name

Manage revision history

By default, each release retains up to 10 revisions for rollback. Use --history-limit on upgrade to adjust this:

# Keep 20 revisions
cpln helm upgrade my-release ./my-chart --history-limit 20

# Keep unlimited revisions
cpln helm upgrade my-release ./my-chart --history-limit 0

The --history-limit flag must be provided on every upgrade. If omitted, it resets to the default of 10 revisions. For consistent behavior, always include --history-limit in your upgrade commands or CI/CD pipelines.

You can also set the HELM_MAX_HISTORY environment variable as an alternative to the --history-limit flag. The CLI flag takes precedence over the environment variable.

Value	Behavior
`10` (default)	Keeps the 10 most recent revisions
`0`	Keeps all revisions indefinitely
`N`	Keeps the N most recent revisions

Setting --history-limit 0 is useful for audit compliance or when you need the ability to rollback to any previous state.

Release description

Use --description (or --desc) to attach a custom description to a release revision. It appears in cpln helm history output:

cpln helm install my-release ./my-chart --description "Initial deployment"
cpln helm upgrade my-release ./my-chart --description "Added caching layer"

On rollback, if no description is provided, it auto-generates "Rollback to <version>".

Rollback a release

Revert to a previous revision:

# Rollback to previous revision
cpln helm rollback my-release

# Rollback to specific revision
cpln helm rollback my-release 2

Clean up on failure

Use --cleanup-on-fail to automatically delete resources created during a failed rollback:

cpln helm rollback my-release --cleanup-on-fail

View release information

cpln helm list

Lists all releases across all GVCs in the organization.

+------------+--------+---------+---------------+---------+--------+
|NAME        |GVC     |REVISION |UPDATED        |STATUS   |CHART   |
+------------+--------+---------+---------------+---------+--------+
|my-release  |my-gvc  |3        |5 minutes ago  |deployed |my-chart|
+------------+--------+---------+---------------+---------+--------+

cpln helm history my-release

+---------+--------------+-----------+----------+----------------------+
|REVISION |UPDATED       |STATUS     |CHART     |DESCRIPTION           |
+---------+--------------+-----------+----------+----------------------+
|1        |1 hour ago    |superseded |my-chart  |Install complete      |
|2        |30 min ago    |superseded |my-chart  |Upgrade complete      |
|3        |5 min ago     |deployed   |my-chart  |Upgrade complete      |
+---------+--------------+-----------+----------+----------------------+

cpln helm get manifest my-release

Shows the rendered YAML for the current release.

cpln helm get all my-release

Shows combined release info, values, and manifest.

# User-provided values only
cpln helm get values my-release

# All values (chart defaults + user overrides)
cpln helm get values my-release --all

cpln helm get notes my-release

Shows the chart notes (from NOTES.txt) for the current release.

All helm get subcommands accept --revision <num> to view data from a specific historical revision:

cpln helm get values my-release --revision 2
cpln helm get manifest my-release --revision 2

Uninstall a release

Remove all resources and delete the release:

cpln helm uninstall my-release

This deletes:

All resources tracked by the release
The release state secret

Template preview

Preview the rendered output without deploying:

cpln helm template my-release ./my-chart

Injected values

The CLI automatically injects these values into your chart, making them available in templates without requiring you to define them:

Key	Description
`cpln.org`	Current organization name
`cpln.gvc`	Current GVC name (when `--gvc` is provided)

Use in templates:

gvc: {{ .Values.cpln.gvc }}

Avoid defining a top-level cpln key in your values.yaml as it will be overwritten by the injected values.

--set and --values are not carried over between operations. Each upgrade generates a fresh config from the chart defaults plus whatever you pass in that command. CI/CD pipelines must pass the full set of values on every upgrade.

Tags and labels

Tagging resources

Use --tag to attach custom tags to all resources deployed by the release:

cpln helm install my-release ./my-chart \
  --tag environment=production \
  --tag team=backend

Tags defined in your chart templates are also applied. The precedence order (highest wins):

Helm metadata tags (cpln/release) — always applied, cannot be overridden
Template-level tags — tags defined on individual resources in your chart YAML
Release-level tags — tags from --tag and --state-tag flags

This means tags set on a specific resource in your template override the same key passed via --tag. Use --remove-tag on upgrade to remove tags from resources:

cpln helm upgrade my-release ./my-chart --remove-tag environment

Tagging the release secret

Use --state-tag to attach tags to the release state secret itself (not the deployed resources):

cpln helm install my-release ./my-chart \
  --state-tag managed-by=ci \
  --state-tag pipeline-id=12345

Use --remove-state-tag on upgrade to remove state tags:

cpln helm upgrade my-release ./my-chart --remove-state-tag pipeline-id

Tag behavior across revisions

Unlike values, tags carry over between revisions. You don’t need to re-specify --tag or --state-tag on every upgrade — previous tags are used as a base and new ones merge on top. Use --remove-tag or --remove-state-tag to explicitly drop a tag.

Secret change detection

When a chart contains both secrets and workloads that reference those secrets, the CLI automatically tags workloads with a hash of each referenced secret’s content:

cpln/secret:<secret-name> = <hash>

When you upgrade a release and a secret’s content changes, the hash changes, triggering a workload redeployment. This ensures workloads always run with the latest secret values.

Protect resources from deletion

Prevent a resource from being deleted during upgrades or uninstalls:

kind: volumeset
name: persistent-data
tags:
  helm.sh/resource-policy: keep

Resources with this tag are skipped during cleanup operations. The CLI will print a message confirming the resource was preserved:

Skipped deletion of /org/{org}/gvc/{gvc}/volumeset/persistent-data because it has resource-policy=keep

Chart notes

Create templates/NOTES.txt to display messages after install/upgrade:

Release {{ .Release.Name }} deployed!
Access your app at: https://{{ .Values.workload.name }}.cpln.app

Environment-specific values

Use different values files for each environment:

# Development
cpln helm install dev-release ./my-chart -f values-dev.yaml

# Production
cpln helm install prod-release ./my-chart -f values-prod.yaml

Troubleshooting

Release already exists

Use upgrade instead of install for existing releases:

cpln helm upgrade my-release ./my-chart

Or use upgrade --install to handle both cases:

cpln helm upgrade my-release ./my-chart --install

Release is stuck in pending state

If a previous operation was interrupted, the release may be stuck in pending-install, pending-upgrade, or pending-rollback status. The CLI will show an error that includes the exact secret name and the command to delete it:

ERROR: Release 'my-release' is 'pending-install', please wait for the install
or upgrade to finish. If this release revision is still pending or stuck, you
will need to manually delete the secret 'cpln-helm-release-my-release-abc12xyz-v1'.
Use the 'cpln secret delete cpln-helm-release-my-release-abc12xyz-v1' command to do so.

Run the cpln secret delete command shown in the error message to unblock the release.

Non-CPLN resources in chart

If your chart contains Kubernetes manifests (resources with apiVersion or metadata fields), you’ll see:

ERROR: Some resources in the rendered template are not CPLN resources.

Remove any standard Kubernetes resources from your templates. Charts must contain only Control Plane resource definitions.

Cannot upgrade with different chart name

When upgrading a release, the chart name must match the one used during install:

ERROR: UPGRADE FAILED: cannot upgrade with different chart name

If you need to switch charts, uninstall the release first, then install with the new chart.

Resources not deleted on upgrade

Ensure you’re using the same release name. Resources are only tracked within a single release. Also check if the resources have the helm.sh/resource-policy: keep tag, which prevents deletion.

Rollback fails

Check available revisions with cpln helm history. Rollback can only target revisions with deployed or superseded status. By default, only 10 revisions are retained. See Manage revision history to adjust this limit.

Missing chart dependencies

If your chart has dependencies in Chart.yaml that haven’t been fetched:

ERROR: Helm chart dependencies are missing.

Re-run with the --dependency-update flag:

cpln helm install my-release ./my-chart --dependency-update

GVC does not exist

GVC-scoped resources (workload, identity, volumeset) require the GVC to exist. Either create the GVC in a separate step before installing, or include the GVC as a resource in your chart so it’s created first.

Permission denied on install

Ensure you have reveal permission on secrets to manage release state.

Release name invalid

Release names must be DNS-1123 compliant: lowercase alphanumeric and hyphens only, max 53 characters, cannot start or end with a hyphen. Use --generate-name if you don’t want to manage names manually.

Next steps

Apply YAML Manifests

Apply resources without Helm

CI/CD Usage

Automate Helm deployments

Workload Reference

Understand workload configuration

Helm Command Reference

Full helm command reference

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Workload Access

​When to use this

Templated deployments

Environment management

Versioned releases

Helm ecosystem

​Prerequisites

​Core concepts

​Releases

​Release name constraints

​Release state

​Supported resource types

​GVC-scoped resources

​Quick start

​Install a release

​Wait for readiness

​Handle chart dependencies

​Upgrade a release

​Install or upgrade

​Manage revision history

​Release description

​Rollback a release

​Clean up on failure

​View release information

​Uninstall a release

​Template preview

​Injected values

​Tags and labels

​Tagging resources

​Tagging the release secret

​Tag behavior across revisions

​Secret change detection

​Protect resources from deletion

​Chart notes

​Environment-specific values

​Troubleshooting

​Next steps