Helm Environment Promotion

Manage your Helm environments with the Codefresh UI

Apart from the basic Helm board that shows your Kubernetes clusters at the application level, Codefresh also comes with a special environment board that allows you to track one or more applications as they move within your infrastructure (e.g. Dev, QA, Prod).

The environment board can function both as an overview of the whole lifecycle of the application as well as a tool to shift-left/right Helm releases between environments.

Here is an example board:

Helm Environment Dashboard

Helm Environment Dashboard

This board has 3 environments that correspond to Kubernetes clusters:

  • A Load-testing environment where applications are stress-tested
  • A Staging environment where smoke tests are performed
  • The production environment where applications go live

You can see that a Python example app at version 0.2.0 is already in production. Version 0.3.0 is awaiting in the staging environment for smoke tests. Once it is tested it can be dragged to the production column therefore promoting it to production status.

Using the Helm environment board

You can create and manage as many Helm promotion boards as you want. For each board you define how many columns it will contain, where each column is a Helm-enabled Kubernetes cluster.

Helm environments column structure

Helm environments column structure

You can use different clusters for each column or different namespaces from the same cluster. You can even mix and match both approaches. As an example, you could create a Helm board with the following environments:

  • Column 1 - dev cluster showing all namespaces (DEV).
  • Column 2 - namespace qa from cluster staging (QA).
  • Column 3 - namespace staging from cluster staging (STAGING).
  • Column 4 - namespace production from cluster prod (PRODUCTION).

Once you have your columns in place, you can move Helm releases between clusters/namespaces by drag-n-drop. Each Helm release can be dragged to any other column either promoting it (e.g. qa to production) or shifting it left (e.g. prod to qa)

Creating your own Helm board

To create your own boards, select Helm -> Boards from the left sidebar. You can have as many boards as you want. Each board can deal with a single or multiple Helm applications.

Helm board selection

Helm board selection

To create a new board click the Add board button from the top right corner. There are two fields in the dialog that will appear

  • board name - the title of your board.
  • release name regex - if present, this board will automatically filter all its environments to show only Helm releases that match this regular expression.

The second option is very helpful if you want your environment board to only focus on a single Helm application (or set of applications that match). For the most usual case leave it empty, so that you can see all Helm releases of your clusters.

You can edit both options for an existing board if you change your mind later.

Defining clusters/namespaces for each environment

Once your Helm environment board is created, you are ready to define its columns. To add a column click the Add environment button on the top right corner. You will see the environment details dialog:

Edit Helm environment

Edit Helm environment

For each environment you can select

  • A name for that column
  • The Kubernetes cluster it corresponds to
  • One or more namespaces that define this environment (You can even toggle the switch for a regex match)
  • A presentation color to easily identify the environment on the board (For example, a “production” environment should have a red color).

You can also select no namespace at all. In that case the column will show Helm releases for all namespaces in that cluster. You can change all these options after creation, so feel free to change your mind.

Repeat the same process for additional environments. Remember that you can name your environment as you want and define any combination of cluster/namespace for any of the columns. This gives you a lot of power to define a Helm environment board that matches exactly your own process.

You don’t have to define the environments in order. You can drag-n-drop columns to change their order after the initial creation.

Installing Helm releases on each environment

If you already have pipelines that deploy Helm releases, you should see your columns get populated automatically with information.

For each Helm release you will get some basic details such as the chart version and the name of the release. You can expand a release by clicking on the arrow button to get additional information such as the docker images and the replicas of each pod that are contained in the release.

Helm release details

Helm release details

You can even install manually a Helm release from any external repository by clicking on the PLUS button at the header of each column. In that case you will see a list of possible Helm applications to choose from.

You will be able to select the target cluster and namespace as well as the chart values as any other Helm release.

Moving releases between environments

A Helm environment board can be used by different stakeholders in order to get the detailed status of all defined environments. In that aspect it can act as a read-only tool that simply shows the results of Codefresh pipelines that deploy Helm applications.

Promoting Helm releases with the GUI

You can also use the board as an action tool in order to promote/demote a Helm release between individual environments. To move a Helm release between environments just drag-n-drop it to a different column.

Promoting a Helm release

Promoting a Helm release

Once you drop the release you will also see the promotion dialog. From here you can override the chart values, import a specific shared configuration or add new values.

Changing deployment values

Changing deployment values

By default Codefresh will use a built-in install/upgrade pipeline for performing the promotion. You can choose your own pipeline from the promotion dialog. That pipeline will be automatically provided with the following environment variables:

  • CF_HELM_RELEASE - name of release
  • CF_HELM_KUBE_CONTEXT - kubectl context name of target cluster (cluster name from dashboard)
  • CF_HELM_NAMESPACE - namespace where release is stored now
  • CF_HELM_INSTALLATION_NAMESPACE - namespace where release is promoted to
  • CF_HELM_CONTEXTS - shared configuration Helm contexts
  • CF_HELM_VALUES - Helm chart values
  • CF_HELM_SET - Additional values there were overriden
  • CF_HELM_CHART_JSON_GZIP - Gzipped JSON of Helm chart (only for Helm 3)
  • CF_HELM_CHART_JSON - JSON of Helm chart (only for Helm 2)

Note that the variable CF_HELM_CHART_JSON_GZIP is both compressed and base64 encoded. To get the raw value you need a command like echo $CF_HELM_CHART_JSON_GZIP | base64 -d | gunzip

Once you click the update button, a new build will run that will perform the deployment.

Note that you can move releases to any column both on the right and on the left of the current column. This is helpful if for example you find a bug in your production environment and you want to bring it back to a staging environment for debugging.

Promoting Helm releases programmatically

You can also promote Helm releases with the Codefresh CLI.

Once you have installed the CLI you can use it from an external script or terminal with the helm-promotion parameter:

codefresh helm-promotion --board MySampleBoard --source Staging --target Production --source-release my-app --set myenv=prod

Here we promote the Helm release my-app to the Production column overriding also the myenv value.

Remember that the Codefresh CLI can also run in a Codefresh pipeline with a freestyle step. Here is an example of a Helm promotion from within a Codefresh pipeline.


version: '1.0'
    title: trigger
    image: codefresh/cli
      - 'codefresh helm-promotion --board MySampleBoard --source Staging --target Production --source-release my-app --namespace my-namespace --set myenv=prod'

Editing your Helm boards

For any existing Helm board, you have the following options:

Editing a Helm environment

Editing a Helm environment
  1. The refresh button will update the board with the current state of the clusters.
  2. The filtering menu can be used to further constrain the Helm releases shown on each column.
  3. The edit properties button allows you to change again the title of the board as well as a global filter for Helm releases.
  4. The remove board completely deletes the present board from the Codefresh UI.
  5. The environment details on the environment header are:
    • The edit button to change again the options for this column (shown on mouse hover)
    • The delete button to remove this column from the board (shown on mouse hover)
    • The plus button to install a new chart
    • A numeric value that shows how many releases are contained on this environment
  6. The delete button allows you to uninstall a Helm release for an environment.

The filtering options allow you to further constrain the Helm release shown for the whole board.

Filtering options

Filtering options

The filters are especially helpful in Helm boards with a large numbers of environments and/or releases.