cpln helm

Overview

The CLI 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

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 execution of this command ensures that the resources defined in the helm chart are appropriately applied. It 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 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
    • Represents the version of the generator used to create the 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
    • This key stores the name of the release, allowing for easy identification and reference.
  • description
    • The string passed to the --description flag in the cpln helm install command, providing contextual information about the release.
  • resources
    • A list of the active resources that were defined in the last cpln release install. Each item is an object that has the following properties that are relative to the resource:
      • 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.

Create a Helm Chart

To create a helm chart, follow these steps:

  1. In an empty directory, execute the command (substitute CHART_NAME with your desired name):
    • helm create CHART_NAME
  2. A directory named CHART_NAME will be created which will contain the following resources:
    • Directories: charts and templates
    • Files: .helmignore, Chart.yaml, and values.yaml
  3. Delete the contents of the templates directory.
  4. Using your favorite text editor, open the values.yaml file and replace the contents with the following:
copy
exampleGvc:
name: example-gvc
description: This is a description
locationLinks:
- //location/aws-eu-central-1
exampleHttpbinWorkload:
name: httpbin-example
exampleIdentity:
name: example-identity
  1. Create a file called resources.yaml within the templates directory and paste the following:
copy
kind: gvc
name: {{ .Values.exampleGvc.name }}
description: {{ .Values.exampleGvc.description }}
spec:
staticPlacement:
locationLinks:
{{- range .Values.exampleGvc.locationLinks }}
- {{ . }}
{{- end }}
---
kind: identity
name: {{ .Values.exampleIdentity.name }}
description: {{ .Values.exampleIdentity.name }}
gvc: {{ .Values.exampleGvc.name }}
---
kind: workload
name: {{ .Values.exampleHttpbinWorkload.name }}
description: {{ .Values.exampleHttpbinWorkload.name }}
gvc: {{ .Values.exampleGvc.name }}
spec:
identityLink: //gvc/{{ .Values.exampleGvc.name }}/identity/{{ .Values.exampleIdentity.name }}
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: []
localOptions: []
supportDynamicTags: false

Generate a Helm Template

The cpln helm template command will execute the helm template command in the background and will output to stdout.

Example:

copy
cpln helm template NAME PATH_TO_HELM_CHART
Output from executing the chart created in the above example
copy
---
# Source: test-chart/templates/resources.yaml
kind: gvc
name: example-gvc
description: This is a description
spec:
staticPlacement:
locationLinks:
- //location/aws-eu-central-1
---
# Source: test-chart/templates/resources.yaml
kind: identity
name: example-identity
description: example-identity
gvc: example-gvc
---
# Source: test-chart/templates/resources.yaml
kind: workload
name: httpbin-example
description: httpbin-example
gvc: example-gvc
spec:
identityLink: //gvc/example-gvc/identity/example-identity
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: []
localOptions: []
supportDynamicTags: false

Help Template Options

For the list of options, browse to the cpln helm template command and expand the References panel.

TIP

If the chart name is not specified, the flag --generate-name must be added and will auto generate a chart name.

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:

copy
{{ .Values.cpln.org }}
CAUTION

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.

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, update, and remove resources based on content that is added/modified within the chart.

NOTE

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:

copy
cpln helm install NAME PATH_TO_HELM_CHART
Output from executing the chart created in the above example
copy
Created /org/cpln-test-org/gvc/example-gvc
Created /org/cpln-test-org/gvc/example-gvc/identity/example-identity
Created /org/cpln-test-org/gvc/example-gvc/workload/httpbin-example
Release 'example' has been installed successfully!

Wait for Workload Readiness

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:

copy
cpln helm install NAME PATH_TO_HELM_CHART --wait --timeout 600

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 — you must execute the cpln helm install command once more. 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.

Using the above example, the updated template (resources.yaml) below has the identity and the identityLink (from the workload) removed.

Updated Resources Template
copy
kind: gvc
name: {{ .Values.exampleGvc.name }}
description: {{ .Values.exampleGvc.description }}
spec:
staticPlacement:
locationLinks:
{{- range .Values.exampleGvc.locationLinks }}
- {{ . }}
{{- end }}
---
kind: workload
name: {{ .Values.exampleHttpbinWorkload.name }}
description: {{ .Values.exampleHttpbinWorkload.name }}
gvc: {{ .Values.exampleGvc.name }}
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: []
localOptions: []
supportDynamicTags: false

Example usage:

copy
cpln helm install NAME PATH_TO_HELM_CHART
Output from executing the updated template
copy
Updated gvc 'example-gvc'
Updated workload 'httpbin-example'
Performing cleanup...
Deleted /org/cpln-test-org/gvc/example-gvc/identity/example-identity
Release 'example' has been installed successfully!

Show a Release

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:

copy
cpln helm show NAME
Output
copy
{
"description": "",
"release": "example",
"resources": [
{
"kind": "gvc",
"link": "/org/cpln-test-org/gvc/example-gvc",
"version": 1,
"id": "0bc7697b-5b7f-4903-9294-436ab359162b"
},
{
"kind": "identity",
"link": "/org/cpln-test-org/gvc/example-gvc/identity/example-identity",
"version": 2,
"id": "0a9f995f-8a74-46d8-a17e-ef5f554e6805"
},
{
"kind": "workload",
"link": "/org/cpln-test-org/gvc/example-gvc/workload/httpbin-example",
"version": 3,
"id": "c53e460f-64eb-475c-a54f-1bf3e9f03c6f"
}
],
"schemaVersion": "1"
}

List Releases

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:

copy
cpln helm list

Output

copy
[
"example"
]

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:

copy
cpln helm uninstall NAME
Output
copy
Deleted /org/cpln-test-org/gvc/example-gvc/workload/httpbin-example
Deleted /org/cpln-test-org/gvc/example-gvc
Release 'example' has been uninstalled successfully!
Copyright © 2024 Control Plane Corporation. All rights reserved. Revision 971d27e5
Contents