Using Helm in a Codefresh pipeline
Deploying and pushing Helm charts with Codefresh
We have created a special Helm step for easy integration of Helm in Codefresh pipelines. The Helm step facilitates authentication, configuration and execution of Helm commands.
You can always use the regular
helm
cli in a freestyle step, if you have a special use case that is not covered by the Codefresh Helm step. In this case, you can use the simpler containercodefresh/kube-helm
which includes only the Kubectl and helm tools. kube-helm is available on DockerHub: https://hub.docker.com/r/codefresh/kube-helm/.
If you are just starting using Helm please also consult the Helm quick start guide. Also if you prefer to work directly with code see our full Helm example.
Helm setup
In order to use Helm in your Codefresh pipeline you must do the following:
- Make sure that your application has a Helm chart
- Create a Helm package for your application from the chart
- Add a Kubernetes cluster in Codefresh (enabled with Helm/Tiller if you still use Helm 2)
- Define a Helm repository or use the one offered by Codefresh to all accounts
- Import the Helm configuration in your pipeline variables
- Use the Helm step in your yml build definition
Let’s see these steps in order.
Step 1 - Create a Helm chart for your application
Helm applications are bundled in special archives called Charts. You can create a Helm chart for your application by following the official documentation on charts.
The example Codefresh application also comes with a sample chart that is used in the Helm quick start guide.
You can create the chart manually or by using the helm create command on your workstation. There are also several third part tools that can create Helm packages for you such as Draft.
Once you have your Helm chart ready, commit it to the same git repository that contains the source code of your application. It should be in a folder called charts
. Codefresh can also work with Helm charts that are in different Git repositories. We suggest however that you keep both the source code and the Helm chart of an application in the same git repository as this makes chart management much easier.
Step 2 - Kubernetes Configuration
The Helm pipeline step requires the configuration of a kube_context
variable that decides which Kubernetes cluster will be used for the deployment.
First, you’ll need to connect your Kubernetes cluster with Codefresh as described here. Once you have a Kubernetes cluster connected, provide it to the Helm step by adding the KUBE_CONTEXT
variable, where the value is the connection name that you’ve entered when creating the connection. The connection name also appears as the title of the cluster in Kubernetes integration settings (from the left sidebar go to Integrations -> Kubernetes).
If you are still using Helm 2 make sure also that your Kubernetes cluster has the server part of Helm installed (called Tiller).
The easiest way to do that is to run helm init
from the command shell of your cloud provider or
any other terminal that has access to your cluster via kubectl
. This process is not needed if you use Helm 3.
To verify that your cluster is setup for Helm select the Helm Releases item from the left sidebar in the Codefresh UI. You should see the Helm releases in your cluster or an empty screen if you just started using Helm.
Step 3 - Define a Helm repository
If you also wish to push your chart to a Helm repository (which is always a good practice) you should configure a Helm repository for the step to work with. Besides public HTTP repositories, we support a variety of private, authenticated Helm repositories. Codefresh also provides a free, managed Helm repository for every account.
You will need to connect your repository with Codefresh as described here, or obtain your managed Helm repository URL as described here.
Step 4 (optional) - Import the Helm Configuration in your pipeline definition
Once you have a Helm repository connected, attach it to the pipeline. Do this by opening the advanced options (the gear icon) in the variables section in the right sidebard. Then click on Import from shared configuration and choose the CF_HELM_DEFAULT
shared configuration.
You can also click on Add shared configuration directly from the three dots menu for the same functionality.
This concludes the Helm setup for Codefresh. Now you can use the Helm freestyle step in the pipeline codefresh.yml
file.
Note that this step is only needed in pipelines that actually upload/fetch Helm charts from/to Helm repositories. If you have a pipeline that directly installs a Helm chart from the git filesystem, there is no need to import a Helm configuration.
Currently only one Helm configuration can be used in the same pipeline. We are aware of this limitation and will soon improve the way Codefresh works with multiple Helm configurations.
Helm usage in a pipeline step
You can use the helm typed step from the Step Marketplace
The Helm step can be configured using environment variables, which can be provided in any of the various ways supported by Codefresh as described here.
For example, here’s how to provide variables as part of the helm step definition:
deploy:
type: helm
arguments:
action: install
chart_name: test_chart
release_name: first
helm_version: 3.0.3
kube_context: my-kubernetes-context
custom_values:
- 'pat.arr="{one,two,three}"'
- 'STR_WITH_COMAS="one\,two\,three"'
For Helm 2, the Docker image tag refers to the version of Helm/Tiller you need. For Helm 3, just use the newest Helm 3 image tag.
Action modes
The Helm step can operate in one of 3 modes:
- install - will install the chart into a Kubernetes cluster. This is the default mode if not explicitly set.
- push - will package chart and push it to the repository.
- authentication only - will only setup authentication and add the repo to the helm. This is useful if you want to write your own helm commands using the freestyle step’s
commands
property, but you still want the step to handle authentication.
The operation mode is set by the action
field, where the value is install
/push
/auth
.
Helm Values
To supply value file, add to the Helm step, custom_values_file
and the value should point to an existing values file.
To override specific values, add to the Helm step, custom_values
followed by the path to the value to set. For example, myservice_imageTag
. Note that .
(dot) should be replaced with _
(underscore). The value of the variable will be used to override or set the templated property.
Examples:
...
custom_values:
- 'myimage_pullPolicy=Always'
...
results in:
--set myimage.pullPolicy=Always
...
custom_value_files:
- 'values-prod.yaml'
...
results in:
--values values-prod.yaml
If a variable already contains a _
(underscore) in its name, replace it with __
(double underscore).
Examples
All three modes of Helm usage are demonstrated in the following sections.
You can also look at the GitHub repository of our Helm example for full pipelines:
- Pipeline YAML for deploying a chart
- Pipeline YAML for both storing and deploying a chart
Example: Installing a Chart
The following example demonstrates the minimum configuration for installing a chart from a repository. For more configuration options, see the Arguments reference.
deploy:
type: helm
arguments:
action: install
chart_name: path/to/charts
release_name: first
helm_version: 3.0.3
kube_context: my-kubernetes-context
Example: Pushing a Chart
The following example demonstrates packaging and pushing a chart into a repository.
deploy:
type: helm
arguments:
action: push
chart_name: /codefresh/volume/repo/chart
chart_repo_url: 'cm://h.cfcr.io/useraccount/default'
Notes:
- Assuming a git repository with the Helm chart files was cloned as a part of the pipeline.
- The Git repository contains the chart files under the
chart
directory. chart_repo_url
is optional. If a Helm repository configuration is attached to the pipeline, this setting is ignored.
Example: Authenticating only
The following example demonstrates executing custom commands.
deploy:
type: helm
arguments:
action: auth
kube_context: my-kubernetes-context
commands:
- helm list
Example: Custom Helm Commands
The following example demonstrates executing custom commands.
codefresh.yml
my_custom_helm_command:
type: helm
arguments:
action: auth
kube_context: my-kubernetes-context
commands:
- source /opt/bin/release_chart
- helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com/
- helm repo add stable https://kubernetes-charts.storage.googleapis.com
- helm repo list
- helm repo update
- helm list
Notes:
- The directory that contains a chart MUST have the same name as the chart. Thus, a chart named
my-chart
MUST be created in a directory calledmy-chart/
. This is a requirement of the Helm Chart format.
Configuration
Name | Required | Description |
---|---|---|
action | defaults to ‘install’ | Operation mode: install /push /auth |
chart_name | required for install/push | Chart reference to use, adhering to Helm’s lookup rules (path to chart folder, or name of packaged chart). There’s no need to prefix with /reponame if referencing a chart in a repository, this is handled automatically. a.k.a CHART_NAME but CHART_NAME shouldn’t be used anymore. |
chart_repo_url | optional | Helm chart repository URL. If a Helm repository configuration is attached to the pipeline, this setting is ignored |
chart_version | optional | Override or set the chart version |
cmd_ps | optional | Command Postscript - this will be appended as is to the generated helm command string. Can be used to set additional parameters supported by the command but not exposed as configuration options. |
commands | optional | commands to execute in plugin after auth action |
custom_value_files | optional | values file to provide to Helm as –values or -f |
custom_values | optional | values to provide to Helm as –set |
helm_version | optional | version of cfstep-helm image |
kube_context | required for install | Kubernetes context to use. The name of the cluster as configured in Codefresh |
namespace | optional | Target Kubernetes namespace to deploy to |
release_name | required for install | Helm release name. If the release exists, it will be upgraded |
repos | optional | array of custom repositories |
tiller_namespace | optional | Kubernetes namespace where Tiller is installed (unnecessary for Helm 3) |
Full Helm pipeline example
This pipeline builds a docker image, runs unit tests, stores the Helm chart in the Codefresh private Helm repository and finally deploys the Helm chart to a cluster.
This is the pipeline definition:
codefresh.yml
version: '1.0'
stages:
- checkout
- build
- test
steps:
clone:
title: Cloning main repository...
stage: checkout
type: git-clone
arguments:
repo: 'codefresh-contrib/python-flask-sample-app'
revision: with-helm
git: github
MyAppDockerImage:
title: Building Docker Image
stage: build
type: build
working_directory: '${{clone}}'
arguments:
image_name: kostis-codefresh/python-flask-sample-app
tag: 'master'
dockerfile: Dockerfile
MyUnitTests:
title: Running Unit tests
stage: test
type: freestyle
working_directory: '${{clone}}'
arguments:
image: ${{MyAppDockerImage}}
commands:
- python setup.py test
StoreChart:
title: Storing Helm Chart
type: helm
stage: store
working_directory: ./python-flask-sample-app
arguments:
action: push
chart_name: charts/python
kube_context: kostis-demo@FirstKubernetes
DeployMyChart:
type: helm
stage: deploy
working_directory: ./python-flask-sample-app
arguments:
action: install
chart_name: charts/python
release_name: my-python-chart
helm_version: 3.0.2
kube_context: kostis-demo@FirstKubernetes
custom_values:
- 'buildID=${{CF_BUILD_ID}}'
- 'image_pullPolicy=Always'
- 'image_tag=master'
- 'image_pullSecret=codefresh-generated-r.cfcr.io-cfcr-default'
You can see the source code in our example section.