cpln helm
Overview
The cpln helm command streamlines the process of managing Control Plane resources by leveraging the output generated by the helm template command. This functionality proves invaluable for those preferring to define their Control Plane resources within a helm chart, facilitating regular updates to these resources with ease.
To ensure a seamless transition for users familiar with the original helm commands, we have intentionally designed our CLI helm subcommands to closely resemble their helm counterparts. This approach aims to minimize confusion and provide a familiar environment, as our CLI helm command adheres to the same foundational principles and workflows as the traditional helm commands.
Prerequisites
- CLI installed.
- helm installed.
- Defined policies to create applicable Control Plane resources.
- Policy to reveal applicable secrets.
Definitions
cpln release
The definition of a cpln release
mirrors that of a helm release, essentially representing a deployed instance
of a helm chart within Control Plane. Executing a cpln release
involves the use of the cpln helm install command. Each upgrade ensures that the resources defined in the helm chart are appropriately applied. The upgrade also takes care of removing any resources that are no longer part of the chart and updates the cpln release state to reflect these changes.
When you run the cpln helm install command, it results in the creation of a secret of type opaque within your org. This secret is integral to the process, as it contains the payload corresponding to the cpln release state.
cpln release state
The cpln release state
is the single source of truth for managing releases via the CLI. It lets you track changes—like new or removed resources—by comparing the stored state with the output of helm template command.
The state is stored as a gzipped JSON object with these top-level keys:
schemaVersion
- Version of the generator that produced this state. Incremented when the CLI’s state format or logic changes.
name
- Name of the release.
info
- Metadata about this release:
firstDeployed
: Timestamp when the release was first installed.lastDeployed
: Timestamp of the most recent deployment.description
: Human-readable log entry for this release.status
: Current release status (e.g.deployed
,failed
).notes
: RenderedNOTES.txt
from the chart, if available.resources
- Array of active resources in this revision. Each entry has:
id
: Unique identifier for the resource.kind
: Control Plane resource kind (e.g.workload
).version
: Version of the resource.link
: Self-link of the resource.template
: The resource’s manifest as generated by helm template command.
- Array of active resources in this revision. Each entry has:
- Metadata about this release:
chart
- Details of the chart that was released:
metadata
- Contents of the chart’s
Chart.yaml
:name
: Chart name.home
: URL for the project homepage or repository.sources
: Array of URLs pointing to the chart’s source code.version
: Chart version (SemVer 2).description
: One-sentence summary of the chart.keywords
: Array of search keywords.maintainers
- A list of name and URL/email address combinations for the maintainer(s):
name
: Maintainer’s name or organization.email
: An optional email address to contact the named maintainer.url
: An optional URL to an address for the named maintainer.
- A list of name and URL/email address combinations for the maintainer(s):
icon
: URL for the chart icon.apiVersion
: Chart API version (e.g.v2
).condition
: The condition to check to enable chart.tags
: Array of tags for grouping charts.appVersion
: Version of the application contained in this chart.deprecated
: Boolean indicating if the chart is deprecated.annotations
: Arbitrary key/value pairs for external tooling.kubeVersion
: SemVer constraint for the required Kubernetes version.dependencies
- Array of chart dependencies, each with:
name
: Dependency chart name (must match itsChart.yaml
).version
: Version (range) of this chart.repository
: URL of the dependency’s chart repository.condition
: A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled).tags
: Tags to group dependencies.enabled
: Boolean to include the dependency by default.importValues
: Mapping of child values to parent keys (either string entries or{ child: parent }
pairs).alias
: Alternate name for the dependency.
- Array of chart dependencies, each with:
type
: Eitherapplication
orlibrary
.
- Contents of the chart’s
values
: Default configuration values for the chart.
- Details of the chart that was released:
config
: Merged user-provided values (overrides the chart’s defaults).manifest
: Full rendered manifest (as a YAML string).version
: Revision number of this release (incremented on each upgrade).gvc
: The GVC name for the release.valuesFiles
: Array of custom values files (contents of each-f
or--values
file).
Create a Helm Chart
To create a helm chart, follow these steps:
- In an empty directory, execute the command (substitute CHART_NAME with your desired name):
helm create CHART_NAME
- A directory named
CHART_NAME
will be created which will contain the following resources:- Directories:
charts
andtemplates
- Files:
.helmignore
,Chart.yaml
, andvalues.yaml
- Directories:
- Delete the contents of the
templates
directory. - Using your favorite text editor, open the
values.yaml
file and replace the contents with the following:
- Create a file called
resources.yaml
within thetemplates
directory and paste the following:
- Create a file called
NOTES.txt
within thetemplates
directory and paste the following:
Generate a Helm Template
The cpln helm template command will execute the helm template command in the background and will output to stdout.
Example:
Helm Template Options
For the list of options, browse to the cpln helm template command and expand the References
panel.
Injected Values
The following values get injected into the cpln helm template command which can be accessed from within your chart.
- Key:
cpln.org
, Value:Name of your organization
. - Key:
cpln.gvc
, Value:Name of your GVC
.
Example Usage:
It is recommended that you avoid defining a top-level cpln
property within your values.yaml
file, as the injected values above will
override them.
Chart Notes
After executing cpln helm install or cpln helm upgrade, the content of the NOTES.txt file that is defined within the chart directory will be output to stdout.
Injected Tags
When you install or upgrade, the specified tags are added to each resource that is being installed or upgraded.
- Key:
cpln/release
, Value: The name of the release.
Tell Helm Not To Uninstall a Resource
Sometimes there are resources that should not be uninstalled. Chart developers can add the helm.sh/resource-policy: keep
tag to a resource to prevent it from being uninstalled.
The tag helm.sh/resource-policy: keep
instructs the CLI to skip deleting this resource when a cpln helm
operation (such as cpln helm upgrade
or cpln helm rollback
) would result in its deletion.
Install a Release
The cpln helm install command accepts the same options as the cpln helm template command. It injects the same values and executes the helm template command in the background. It will use the output to create resources based on the content that is added within the chart.
The release name should follow the same naming convention that is used to name resources in Control Plane since the name of the release will be part of the secret name that will be created.
Example usage:
Wait for Workload Readiness
To guarantee the readiness of one or more workloads during a cpln helm install or a cpln helm upgrade, include the --wait
option in your command. This will enforce a default waiting period of 300 seconds (5 minutes). If you need to adjust this duration, use the --timeout
option with your preferred number of seconds.
Example usage:
or
Upgrade a Release
If you need to modify your release following alterations to your chart — be it adding a new resource, updating an existing one, or removing a resource — execute the cpln helm upgrade command. It’s crucial to use the same release name when running this command. This consistency enables the CLI to accurately determine which resources should be deleted and to appropriately update the cpln release state with these changes.
A release can only have up to 10 revisions. Every additional upgrade will omit the oldest one (i.e. the revision with the lowest revision
number that doesn’t have the deployed
status).
Using the above example, the updated template (resources.yaml) below has the identity and the identityLink (from the workload) removed.
Example usage:
Rollback a Release
The cpln helm rollback command rolls back a release to a previous revision. If no revision is specified, the command will rollback to the previous revision. To view the revision number of each deployment, refer to the cpln helm history command.
Example usage:
Release History
The cpln helm history command will output the deployments of a given release in the format defined in your profile (YAML, JSON, etc.). You can override the formatting with the --output
option.
Example usage:
Get
All
The cpln helm get all command fetches all information for a named release.
Example usage:
Manifest
The cpln helm get manifest command fetches the generated manifest for a given release.
Example usage:
You can always change the output format by adjusting the --output
option.
Notes
The cpln helm get notes command will output the notes for a named release.
Example usage:
Values
The cpln helm get values command will output the values of a given release.
Example usage:
You can always change the output format by adjusting the --output
option.
List Releases
The cpln helm list command lists all cpln releases.
Example usage:
You can always change the output format by adjusting the --output
option.
Uninstall a Release
The cpln helm uninstall command will help uninstall a cpln release, that includes deleting every resource defined in the cpln release state and will also delete the secert that has been created to represent the cpln release.
Example usage: