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.
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.
The cpln release state
serves as the definitive source for managing releases through the CLI. This functionality is crucial for understanding the dynamics of
your deployments, such as identifying when a new resource is introduced or an existing one is removed. The CLI achieves this by comparing the current cpln release state
with the output from the helm template command.
The cpln release state
is structured as a JSON object, which includes:
schemaVersion
cpln release state
. This is particularly important for version control, especially when updates are made to the state's structure or functionalities by the CLI.release
deployments
revision
: The revision number of the deployment. Each time you update or roll back a release, the revision number increases. It helps you keep track of changes made to your deployment over time.updated
: The last modified date and time in UTC format.status
: The status of the deployment is equivalent to the helm deployment status. The value could be one of the following:chart
: The name of the helm chart.appVersion
: The appVersion
that is defined within the Chart.yml file.description
: The string passed to the --description
flag in the cpln helm install and cpln helm upgrade commands, providing contextual information about the release.resources
id
: A unique identifier for the resource.kind
: Specifies the type of the resource.version
: The version of the resource.link
: The self-link of the resource.template
: The resource definition extracted from the output generated by the helm template command.To create a helm chart, follow these steps:
helm create CHART_NAME
CHART_NAME
will be created which will contain the following resources:charts
and templates
.helmignore
, Chart.yaml
, and values.yaml
templates
directory.values.yaml
file and replace the contents with the following:copyexampleGvc:name: example-gvcdescription: This is a descriptionlocationLinks:- //location/aws-eu-central-1exampleHttpbinWorkload:name: httpbin-exampleexampleIdentity:name: example-identity
resources.yaml
within the templates
directory and paste the following:copykind: gvcname: {{ .Values.exampleGvc.name }}description: {{ .Values.exampleGvc.description }}spec:staticPlacement:locationLinks:{{- range .Values.exampleGvc.locationLinks }}- {{ . }}{{- end }}---kind: identityname: {{ .Values.exampleIdentity.name }}description: {{ .Values.exampleIdentity.name }}gvc: {{ .Values.exampleGvc.name }}---kind: workloadname: {{ .Values.exampleHttpbinWorkload.name }}description: {{ .Values.exampleHttpbinWorkload.name }}gvc: {{ .Values.exampleGvc.name }}spec:identityLink: //gvc/{{ .Values.exampleGvc.name }}/identity/{{ .Values.exampleIdentity.name }}type: serverlesscontainers:- name: httpbincpu: 50mimage: kennethreitz/httpbininheritEnv: falsememory: 128Miports:- number: 80protocol: httpdefaultOptions:autoscaling:maxConcurrency: 1000maxScale: 1metric: concurrencyminScale: 1scaleToZeroDelay: 300target: 100capacityAI: truedebug: falsesuspend: truetimeoutSeconds: 5firewallConfig:external:inboundAllowCIDR:- 0.0.0.0/0outboundAllowCIDR:- 0.0.0.0/0outboundAllowHostname: []outboundAllowPort: []internal:inboundAllowType: noneinboundAllowWorkload: []localOptions: []supportDynamicTags: false
The cpln helm template command will execute the helm template command in the background and will output to stdout.
Example:
copycpln helm template NAME PATH_TO_HELM_CHART
copy---# Source: test-chart/templates/resources.yamlkind: gvcname: example-gvcdescription: This is a descriptionspec:staticPlacement:locationLinks:- //location/aws-eu-central-1---# Source: test-chart/templates/resources.yamlkind: identityname: example-identitydescription: example-identitygvc: example-gvc---# Source: test-chart/templates/resources.yamlkind: workloadname: httpbin-exampledescription: httpbin-examplegvc: example-gvcspec:identityLink: //gvc/example-gvc/identity/example-identitytype: serverlesscontainers:- name: httpbincpu: 50mimage: kennethreitz/httpbininheritEnv: falsememory: 128Miports:- number: 80protocol: httpdefaultOptions:autoscaling:maxConcurrency: 1000maxScale: 1metric: concurrencyminScale: 1scaleToZeroDelay: 300target: 100capacityAI: truedebug: falsesuspend: truetimeoutSeconds: 5firewallConfig:external:inboundAllowCIDR:- 0.0.0.0/0outboundAllowCIDR:- 0.0.0.0/0outboundAllowHostname: []outboundAllowPort: []internal:inboundAllowType: noneinboundAllowWorkload: []localOptions: []supportDynamicTags: false
For the list of options, browse to the cpln helm template command and expand the References
panel.
If the release name is not specified, the flag --generate-name
must be added and will auto generate a release name.
The following values get injected into the cpln helm template command which can be accessed from within your chart.
cpln.org
, Value: Name of your organization
.cpln.gvc
, Value: Name of your GVC
.Example Usage:
copy{{ .Values.cpln.org }}
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.
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.
When you install or upgrade, the specified tags are added to each resource that is being installed or upgraded.
cpln/release
, Value: The name of the release.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.
copykind: locationtags:helm.sh/resource-policy: keep[...]
The tag helm.sh/resource-policy: keep
instructs the CLI to skip deleting this resource when a cpln helm
operation (such as cpln helm uninstall
, cpln helm upgrade
or cpln helm rollback
) would result in its deletion.
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, update, and remove resources based on content that is added/modified 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:
copycpln helm install NAME PATH_TO_HELM_CHART
copyCreated /org/cpln-test-org/gvc/example-gvcCreated /org/cpln-test-org/gvc/example-gvc/identity/example-identityCreated /org/cpln-test-org/gvc/example-gvc/workload/httpbin-exampleRelease 'example' has been installed successfully!
To guarantee the readiness of one or more workloads during the cpln helm install, 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:
copycpln helm install NAME PATH_TO_HELM_CHART --wait --timeout 600
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 and a new deployment.
A release can only have up to 10 deployments. Every additional upgrade will omit the oldest one (i.e. the deployment with the lowest revision number).
Using the above example, the updated template (resources.yaml) below has the identity and the identityLink (from the workload) removed.
copykind: gvcname: {{ .Values.exampleGvc.name }}description: {{ .Values.exampleGvc.description }}spec:staticPlacement:locationLinks:{{- range .Values.exampleGvc.locationLinks }}- {{ . }}{{- end }}---kind: workloadname: {{ .Values.exampleHttpbinWorkload.name }}description: {{ .Values.exampleHttpbinWorkload.name }}gvc: {{ .Values.exampleGvc.name }}spec:type: serverlesscontainers:- name: httpbincpu: 50mimage: kennethreitz/httpbininheritEnv: falsememory: 128Miports:- number: 80protocol: httpdefaultOptions:autoscaling:maxConcurrency: 1000maxScale: 1metric: concurrencyminScale: 1scaleToZeroDelay: 300target: 100capacityAI: truedebug: falsesuspend: truetimeoutSeconds: 5firewallConfig:external:inboundAllowCIDR:- 0.0.0.0/0outboundAllowCIDR:- 0.0.0.0/0outboundAllowHostname: []outboundAllowPort: []internal:inboundAllowType: noneinboundAllowWorkload: []localOptions: []supportDynamicTags: false
Example usage:
copycpln helm upgrade NAME PATH_TO_HELM_CHART
copyUpdated gvc 'example-gvc'Updated workload 'httpbin-example'Performing cleanup...Deleted /org/cpln-test-org/gvc/example-gvc/identity/example-identityRelease 'example' has been installed successfully!
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:
copycpln helm rollback NAME [REVISION]
copyUpdated gvc 'example-gvc'Updated identity 'example-identity'Updated workload 'httpbin-example'Rollback to deployment revision '1' has been successfully!
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:
copycpln helm history NAME
copy+---------+--------------+-----------+--------+------------+-----------------+|REVISION |UPDATED |STATUS |CHART |APP VERSION |DESCRIPTION ||---------|--------------|-----------|--------|------------|-----------------||1 |0 minutes ago |superseded |example |1.16.0 |Install complete ||2 |0 minutes ago |deployed |example |1.16.0 |Upgrade complete |+---------+--------------+-----------+--------+------------+-----------------+
The cpln helm show command
will output the cpln release state in the format defined in your profile (YAML, JSON, etc.). You can override the formatting with the --output
option.
Example usage:
copycpln helm show NAME
copy{"release": "example","schemaVersion": "2","revision": 1,"updated": "2024-03-29T21:55:44.400Z","status": "deployed","deployments": [{"description": "Install complete","appVersion": "1.16.0","chart": "example","resources": [{"kind": "gvc","link": "/org/cpln-test-org/gvc/example-gvc","template": {"kind": "gvc","name": "example-gvc","description": "This is a description","tags": {"cpln/release": "cpln-release-example"},"spec": {"staticPlacement": {"locationLinks": ["//location/aws-eu-central-1"]}}},"version": 1,"id": "02a11a3b-06ca-492b-89fc-b54e7d2cecc2"},{"kind": "identity","link": "/org/cpln-test-org/gvc/example-gvc/identity/example-identity","template": {"kind": "identity","name": "example-identity","description": "example-identity","tags": {"cpln/release": "cpln-release-example"},"gvc": "example-gvc"},"version": 2,"id": "da185c8c-f274-438e-b812-2bf5387bcaed"},{"kind": "workload","link": "/org/cpln-test-org/gvc/example-gvc/workload/httpbin-example","template": {"kind": "workload","name": "httpbin-example","description": "httpbin-example","tags": {"cpln/release": "cpln-release-example"},"gvc": "example-gvc","spec": {"type": "serverless","containers": [{"name": "httpbin","cpu": "50m","image": "kennethreitz/httpbin","inheritEnv": false,"memory": "128Mi","ports": [{"number": 80,"protocol": "http"}]}],"defaultOptions": {"autoscaling": {"maxConcurrency": 1000,"maxScale": 1,"metric": "concurrency","minScale": 1,"scaleToZeroDelay": 300,"target": 100},"capacityAI": true,"debug": false,"suspend": true,"timeoutSeconds": 5},"firewallConfig": {"external": {"inboundAllowCIDR": ["0.0.0.0/0"],"outboundAllowCIDR": ["0.0.0.0/0"],"outboundAllowHostname": [],"outboundAllowPort": []},"internal": {"inboundAllowType": "none","inboundAllowWorkload": []}},"identityLink": "//gvc/example-gvc/identity/example-identity","localOptions": [],"supportDynamicTags": false}},"version": 2,"id": "65c7022d-6aa3-4419-9d55-9b68dc6bf363"}]}]}
The cpln helm list command will output the cpln release names in the
format defined in your profile (YAML, JSON, etc.). You can override the formatting with the --output
option.
Example usage:
copycpln helm list
Output
copy["example"]
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:
copycpln helm uninstall NAME
copyDeleted /org/cpln-test-org/gvc/example-gvc/workload/httpbin-exampleDeleted /org/cpln-test-org/gvc/example-gvcRelease 'example' has been uninstalled successfully!