Posted on 6 November 2019, updated on 6 August 2021.

You are new to GitLab, and bored by the obstacle course of deploying a single feature on Kubernetes or just curious about how GitLab CI-CD works? In 5 min you will know how to set up a simple automated GitLab pipeline to deploy your app in Kubernetes using Helm.

How does a GitLab pipeline work?

Firstly, I need to explain how GitLab pipeline works. You must have a .gitlab-ci.yml file in your repository. This file contains the different steps of your pipeline. Here is an example:

As you can see, I defined here 3 stages: test, build and deploy. I also have 2 jobs which belong to the stages: lint-test and build-push (they could be named after their stage but I choose to name them accordingly to their actions).

Stages are executed sequentially following the defined order, and if there are several jobs for one stage, they are executed in parallel. In this example, they are executed every time you push some code in your repository, but Gitlab allows you to add filter: execute a step on a specific branch, tag and even trigger it manually. You can notice that I don’t have a single job in the deploy stage: I will show it to you in the last part of this tutorial.

To understand the remaining parts of this CI, you must know what a gitlab-runner is. It is the process that executes your jobs. Gitlab-runners can be a process running on a VM, a pod in Kubernetes and even scale as you need to use them. You can have several runners and differentiate them using tags and assign specific jobs or projects to them.

When you run a job, you can choose to use the default runner image or to execute your job in a specific image: in my example, the lint-test job is ran inside a node:11.10.1 image.
I also set up a service in the second job: a service is a Docker image linked to your job and executed at the same time. For example, you can use it to link db instances for your tests or using docker-in-docker as I did.

What runners do I need and how to deploy them?

It’s a good practice to use runners as docker+machine to execute test and build stages as they use more resources. To deploy this kind of runners you will find more information in the GitLab documentation.

Let’s focus on the deploy stage. To deploy your app on your Kubernetes cluster it’s a good idea to have a gitlab runner as a pod. It can be deployed in a few minutes with the official Helm Chart and allows you to leverage the serviceAccount capabilities of Kubernetes in order to avoid handling authentication with API server directly in your CI. Here is the simplified values.yaml for the helm chart:

You must have Helm already set up in your cluster (Tiller side for Helm 2.x) before executing the following steps. Fill in the previous values.yaml with your own values and then execute the 2 commands below:

Your gitlab runner should be running in your Kubernetes cluster and you should see it inside the Gitlab interface.

Deploy your Kubernetes app with the pipeline

There is one condition to deploy your project with the job I showed you, your project must use Helm and so you need a path to your Helm Chart.

You can note the tags notation is used to select the kubernetes runner you just deployed.

Your runner and pipeline are now ready, you just have to add the previous job to your .gitlab-ci.yml to deploy your Kubernetes app using Gitlab-CI! Gitlab also provide a Kubernetes integration tools which allow you to manage and monitor your cluster using the GitLab interface!

If you are still indecisive between use GitLab pipeline or GitHub and CodeBuild this article can help you form your own opinion.

You can check out our article about Kubernetes productivity tips and tricks to go further on pipeline improvement.