Deployment to Kubernetes with Helm
Using the Helm package Manager in Codefresh
In the previous quick start guide we have seen how you can deploy quickly an application directly to Kubernetes. In this guide we will see how we can use Helm for deployments and what facilities Codefresh offers to make it easier to work with Helm packages.
Helm is a package manager for Kubernetes. It behaves similar to other package managers (yum, apt, npm, maven, pip, gems) but it works at the application level allowing you to deploy multiple manifests together.
Helm offers several extra features on top of vanilla Kubernetes deployments, some of which are:
- The ability to group multiple Kubernetes manifests together and treat them as a single entity (for deployments, rollbacks, and storage). Groups of Manifests are called Helm Charts.
- Built-in templating for Kubernetes manifests, putting an end to custom template systems that you might use for replacing things such as the Docker tag inside a manifest.
- The ability to create Charts of Charts which contain the templates as well as default values. This means that you can describe the dependencies of an application in the service level and deploy everything at the same time.
- The ability to create catalogs of applications (Helm repositories) that function similar to traditional package repositories (think npm registry, cpan, maven central, ruby gems etc).
Codefresh has native support for Helm in a number of ways:
- You can easily deploy existing Helm packages to your Kubernetes cluster overriding the default values.
- You can easily create new Helm packages and push them to a Helm repository.
- Codefresh gives you an integrated Helm Repository.
- You can see the Helm releases and even perform rollbacks from the Helm Dashboard.
- You can browse Helm packages both from public repositories and your internal Helm repository.
- You can see Helm releases in the Environment dashboard
- You can promote Helm releases with the Promotion dashboard
In this guide we will see how you can:
- Deploy a Helm application with Codefresh in an automated manner
- Manage your Helm releases from within Codefresh
- Store a Helm package inside the integrated Codefresh repository
For simplicity reasons, we will use the default Docker registry that is setup globally in your Codefresh account. For your own application you can also use any other of your registries even if it is not the default.
It is assumed that:
- You have already added your Kubernetes cluster into Codefresh
- You have connected at least one Docker registry in your Codefresh account
- You have already an application that has a Dockerfile and a Helm chart
- Your cluster has pull access to your default Docker registry. If not read the previous guide or look at the documentation
First, verify that your cluster is setup for Helm by selecting the Helm Releases item from the left sidebar. You should see the Helm releases in your cluster or an empty screen if you just started.
Deploying a Helm Release to your Kubernetes cluster
Under the hood, we use the
cfstep-helm image to deploy a chart. There are 3 environment variables that are required. The
chart_name points to the chart inside the git repository. The
release_name defines the name of the deployment that will be created
in the cluster. And finally, the
kube_context defines which cluster will be used. The name is the same as defined in Codefresh Integrations.
For the full list of variables and modes see the section using Helm in Codefresh pipelines
Notice that we use Helm 3.x in the example above. If you still use Helm 2.x then select another tag of the
codefresh/cfstep-helmimage that matches your Tiller version. For example if you have installed Tiller 2.9.1 then you need to use the 2.9.1 version instead.
This step will deploy the Helm chart using the default values as found in
values.yaml inside the chart folder. It would make sense to override the defaults using some parameters in the build. For example instead of tagging your docker image with the branch name (which is always the same for each build), you could tag it with the hash of the source revision which is one of the offered variables.
Thus, the whole pipeline is the following:
custom_values override the default chart values. The underscores are replaced with dots.
Here we override the name of tag (to match the Docker image built in the previous step) and the pull policy.
You can see the value replacements in the Helm logs inside the pipeline:
This is the easiest way to deploy to Kubernetes without having to manually change values in manifests, Helm and Codefresh already take care of replacements using the built-in steps.
Viewing Helm releases
Once a Helm package is deployed in your Kubernetes cluster, Codefresh will show it under Helm releases.
If you don’t see your release click on the gear icon on the top right of the cluster and make sure that you choose the correct Helm version along with the namespace of your application.
You can click on the release and get information regarding its chart, its revisions, changed files and the resulting manifests.
The build values that we defined in the
codefresh.yml are shown here in a separate tab so it is very easy to
verify the correct parameters.
You also visit the main Kubernetes dashboard and view the services/pods/deployments that comprise the helm release.
Rolling back a Helm release
Another big advantage of Helm is the way it gives you easy rollbacks for free. If you make some commits in your project Helm will keep the same deployment and add new revisions on it.
You can easily rollback to any previous version without actually re-running the pipeline.
The server part of Helm keeps a history of all releases and knows the exact contents of each respective Helm package.
Codefresh allows you to do this right from the GUI. Select the History tab in the Helm release and from the list of revisions you can select any of them as the rollback target. Notice that rolling back will actually create a new revision. So, you can go backward and forward in time to any revision possible.
Storing a Helm chart
Codefresh includes a built-in Helm repository that comes integrated to all accounts. You can use this repository to store charts like any other public Helm repository. It is also possible to manually deploy applications from your repository.
To store a Helm chart, first of all you need to import the shared configuration that defines the integrated Helm Repository, or, you can define the repository URL directly.
Within the pipeline editor click the Variables taskbar on the right and click on the vertical ellipsis, select Add Shared Configuration. Then, select the shared configuration of the integrated Helm repository and add the variable to your pipeline.
Once that is done you add or modify the deploy step in your
We use the same
helm step as before. But this time we define
push as the action (the default is deploying a helm package). In this pipeline we only store the Helm chart in the internal repository.
Once the pipeline finishes, you can see your chart in the Helm charts part in the left sidebar.
There is even an install button if you want to deploy manually the chart. Codefresh will allow to enter your own values in that case and also select your target cluster.
You can also create a single pipeline that both stores the chart as well as deploys it in a cluster. You can learn more about Helm best practices and Helm pipelines to determine which solution is best.