Skip to main content
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

Install the Control Plane CLI. See Installation.
Install Helm (v3 or later).
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 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

​
Quick start

1

Create a chart

Generate a new Helm chart:
helm create my-chart
2

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
3

Configure values

Update my-chart/values.yaml:
my-chart/values.yaml
gvc:
  name: my-gvc

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

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: 
cpln helm install my-release ./my-chart

​
Wait for readiness

Wait for workloads to become ready: 
cpln helm install my-release ./my-chart --wait --timeout 600

​
Upgrade a release

Update a release after modifying the chart: 
cpln helm upgrade my-release ./my-chart
The CLI:
  1. Renders the updated chart
  2. Applies new and modified resources
  3. Deletes resources removed from the chart
  4. Updates the release state
Use the same release name to ensure proper tracking of resources.

​
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.
ValueBehavior
10 (default)Keeps the 10 most recent revisions
0Keeps all revisions indefinitely
NKeeps 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.

​
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

​
View release information

cpln helm list

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

​
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:
KeyDescription
cpln.orgCurrent organization name
cpln.gvcCurrent GVC name
Use in templates: 
gvc: {{ .Values.cpln.gvc }}
Avoid defining a top-level cpln key in your values.yaml as it will be overwritten.

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

​
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

Use upgrade instead of install for existing releases:
cpln helm upgrade my-release ./my-chart
Ensure you’re using the same release name. Resources are only tracked within a single release.
Check available revisions with cpln helm history. By default, only 10 revisions are retained. See Manage revision history to adjust this limit.
Ensure you have reveal permission on secrets to manage release state.

​
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