Improve this page on GitHub

Helm Releases management

Manage Helm deployments from the Codefresh UI

Codefresh has built-in Helm integration that provides a unique view into your production Kubernetes cluster. In the “Helm Releases” page, you can see the current status of your cluster, including the currently deployed releases, their previous revisions including change tracking, and even roll back to a previous release.

Codefresh also offers an environment view for Helm releases as well as a promotion dashboard.

Helm Releases overview

Before using the dashboard you should have connected your Kubernetes cluster into Codefresh.

Then click on the left sidebar Helm and choose the Releases option to visit the dashboard.

Choosing between Helm 2 and Helm 3 releases

You can specify the type of Helm release for a cluster by clicking on the small gear icon. Then make sure to refresh the page.

For Helm 2 releases, Codefresh will try to find the server component (Tiller) in the cluster in the namespace that you define.

Viewing details and history from a Helm release

Clicking on a release name will take you to its details, showing the individual services that comprise it.

Notice that for better service visibility we suggest you add the recommended labels in your Kubernetes service.

apiVersion: v1
kind: Service
metadata:
  name: {{ template "fullname" . }}
  labels:
    app.kubernetes.io/name: "{{ template "name" . }}"  
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}"
    app.kubernetes.io/managed-by: "{{ .Release.Service  }}"
    app.kubernetes.io/instance: "{{ .Release.Name }}"

If you want to use the instance label for something different, you can also use a release label instead:

release: {{ .Release.Name }}

The history tab shows all previous releases.

You can further expand a release revision to see exactly what files were changed in this release.

Showing an upgrade message

Codefresh allows you to show a human readable description of each release in the UI of the release history. This message can help you showing the main reason behind each release (or any other text message that you find convenient).

You can set this message for your Helm release in 3 ways:

When you manually install a Helm release from the Helm charts screen there is a field for this message
You can setup the property commit_message inside the notes.txt file of your chart
By providing an environment variable called COMMIT_MESSAGE inside your pipeline Helm step

Rolling back a Helm release

You can issue a rollback to a previous revision by clicking on the rollback button on the desired revision row.

There are other tabs that show you the chart used, the values as well as the final manifests that were actually deployed.

Note that rolling back a release will take some time to finish and the change in Codefresh GUI is not instant. If you also use a custom rollback pipeline the delay between the cluster update and the GUI refresh will be even longer.

Helm GUI actions

From the main release screen, you have some additional actions.

You can issue a Helm test by clicking on the ‘Run Test’ button on the desired chart row.

You can delete a release by clicking on the ‘Delete’ button on the desired chart row. For deletion options, see the helm delete documentation, for example, purge will remove the revision from the release history.

Overriding the default Helm actions

By default Codefresh will just execute the native Helm command for each GUI action that you press

helm test for testing a chart
helm rollback for rollbacks
helm delete or helm uninstall --keep-history for delete
helm delete --purge or helm uninstall for purging a release

You can override these actions for a release by clicking on the gear icon on the main dashboard next to a cluster and input your own pipelines instead:

This way you can add your extra logic on top of these actions. For example your own Helm uninstall pipeline might also have a notification step that posts a message to a slack channel after the release is removed.

Overriding the default pipelines can only be done by Codefresh admin users.

If you do override any of these actions the following environment variables are available in the respective pipeline, so that you can use your own custom helm command.

Helm Test pipeline

CF_HELM_RELEASE - name of release
CF_HELM_KUBE_CONTEXT - kubectl context name of target cluster (cluster name from dashboard)
CF_HELM_NAMESPACE - namespace for Tiller Namespace (helm2) or namespace where release is stored (helm3)
CF_HELM_TIMEOUT - time in seconds to wait for any individual Kubernetes operation
CF_HELM_CLEANUP - delete test pods upon completion
CF_HELM_TILLER_VERSION - version of tiller for helm2

Helm Rollback pipeline

CF_HELM_VERSION - Helm version, ex.: 3.0.1, 2.7.0
CF_HELM_RELEASE - name of release on cluster
CF_HELM_REVISION - revision which will be used for rollback
CF_HELM_KUBE_CONTEXT - kubectl context name of target cluster (cluster name from dashboard)
CF_HELM_NAMESPACE - namespace for Tiller Namespace (helm2) or namespace where release is stored (helm3)

Helm delete pipeline

CF_HELM_PURGE - boolean, delete release from store
CF_HELM_RELEASE - name of release
CF_HELM_TIMEOUT - time in seconds to wait for any individual Kubernetes operation
CF_HELM_HOOKS - prevent hooks from running during install
CF_HELM_KUBE_CONTEXT - kubectl context name of target cluster (cluster name from dashboard)
CF_HELM_VERSION - Helm version, ex.: 3.0.1, 2.7.0
CF_HELM_NAMESPACE - namespace for Tiller Namespace (helm2) or namespace where release is stored (helm3)

Helm Deployment Badge

Similar to a build badge you can also get a deployment badge for a Helm release. On the main dashboard screen click on the 3-dots menu at the bottom right of a Helm release and select the Badge option.

Click on the Badge button and Codefresh will give you a Markdown/HTML/Link segment that you can embed in README or other documents to show deployment information.