Connecting Gitlab and Kubernetes for continuous deployment

Gitlab has Kubernetes integration. This post is about getting started with that, rather than covering everything in massive detail. Maybe there’ll be a part two. If you'd like to see one, or have ideas or questions please let me know in the Civo community Slack (where I'm Mac), or tweet @lsdmacza.

It’s a good idea to first read the “about Kubernetes” page at Gitlab.com, and the other source I used heavily for this was Bitnami’s CI/CD pipeline tutorial. I had looked through a couple of other tutorials, but they were based on older versions of Gitlab before the Kubernetes integration had been polished to its current state, and so they were a bit dated. Nevertheless, there are some great demonstrations of the power of .gitlab-ci.yml which I am not covering in this post if you want to read further.

Prerequisites

To unable continuous deployment on Civo you will need to have:

1. A GitLab account. (Can be at Gitlab.com, or a self-hosted Gitlab platform). I used my Gitlab.com account.
2. A domain name to which you can add/remove DNS entries. Don’t have one? Get a free domain at Freenom.
3. An existing Kubernetes cluster, on which you have administrator privileges. Get yours at Civo for free whilst the Beta is running.
4. I created a Kubernetes cluster at Civo, without any default ingress controller, because once I add the cluster as a “managed” cluster in Gitlab, I could do all of that from there. If you want to follow along with this guide, you will need to remove the default ingress controller before you launch the cluster. You can do that using the Civo CLI like so:

Create a single-node Kubernetes cluster

1civo k3s create gitlab3 -s g3.k3s.large –nodes 1 -r Traefik --region NYC1

The above command creates a single-node Kubernetes cluster called gitlab3, with node size g3.k3s.large, in the region NYC1 while removing the default traefik ingress controller using the -r switch. You will need to have added your API Key to Civo CLI according to the instructions.

Create a service account for Gitlab

I followed the excellent documentation from Gitlab, and made sure to capture the external Kubernetes API URL and the cluster certificate, and then created a service account for Gitlab to use, to which I gave cluster-admin privileges. (Note that this is a bad idea if you are deploying to production. For the purposes of this demo it's fine, though).

Then in Gitlab, I created a new project, and in my project I navigated to Operations –> Kubernetes, and used the “add existing cluster” entry:

I followed the prompts, and the obtained a “service token” like this:

1. Create a yaml file containing service account definition and clusterrolebinding:

1apiVersion: v1
2kind: ServiceAccount
3metadata:
4name: gitlab
5namespace: kube-system
6---
7apiVersion: rbac.authorization.k8s.io/v1beta1
8kind: ClusterRoleBinding
9metadata:
10name: gitlab-admin
11roleRef:
12apiGroup: rbac.authorization.k8s.io
13kind: ClusterRole
14name: cluster-admin
15subjects:
16- kind: ServiceAccount
17name: gitlab
18namespace: kube-system

2. Apply the configuration file you created to your cluster:

1kubectl apply -f privs-gitlab-ci.yaml

When the service account is created, Kubernetes will create a token, stored as a secret. I found mine by running:

1kubectl get secret -n kube-system | grep gitlab

And then ran a command like this to obtain the “decoded” token string:

1kubectl -n kube-system get secret gitlab-token-XXYYZZ -o jsonpath="{\['data'\]\['token'\]}" | base64 --decode**

3. Added the service token on the GitLab site:

4. And then supplied the (optional) custom prefix to be used when creating namespaces. Once that was done, there was a cluster reflecting; like this:

Adding Gitlab runner in my Kubernetes cluster

There were a few more steps to do after that. So I selected the cluster, and added some Applications to it, so that Gitlab could show me metrics, and of course, so that there would be a Gitlab Runner deployed to actually handle the builds and deployments.

I installed the Nginx Ingress, Cert-Manager, Prometheus and the Gitlab Runner. There were several other applications, but I didn’t feel it was necessary to install a whole elastic stack. However the ability to do so could be very useful.

As an aside, dealing with which monitoring stack a platform wants installed is a bit of a pain. e.g Gitlab offers to deploy an Elastic Stack, and maybe Fluentd. Those will be deployed into a namespace called “gitlab-managed-apps”. But if you happen to be doing this on a RKE/Rancher-managed cluster, Rancher too has an observability toolset. And then throw in Elastic Cloud Enterprise for APM or Dynatrace or AppDynamics and what used to be a performant cluster can pretty quickly turn to sticky molasses. This bears further thought about what goes where. (Your thoughts and feedback are welcomed for that too).

So, back to the task at hand. I now had a Gitlab project with a Kubernetes cluster integrated:

1$ kubectl -n gitlab-managed-apps get pods --template \
2'{{range .items}}{{.metadata.name}}{{"\\n"}}{{end}}'
3
4ingress-nginx-ingress-default-backend-77d64745d9-5nq5r
5svclb-ingress-nginx-ingress-controller-7nw8m
6ingress-nginx-ingress-controller-6cbf95f5d4-bkpqp
7certmanager-cainjector-5995b97d7d-rsj6t
8certmanager-cert-manager-685dbd6f84-8v227
9certmanager-cert-manager-webhook-797b6b85bc-mbwzf
10prometheus-kube-state-metrics-7596c4bc64-m76rf
11prometheus-prometheus-server-597dc9d9c7-6q4lq
12runner-gitlab-runner-544f55698f-rv2bf

The next step was to disable shared runners, so that I could be sure that pipelines and tasks were only going to execute in my shiny new Kubernetes cluster.

After that, all I had was my own Gitlab Runner in my Kubernetes cluster.

And after some time, Gitlab began to show me some stats from my Kubernetes cluster too, under the Health tab.

Hmm, we’ve covered ingredients 1, 3 & 4 in the list at the start of this guide. What about the second ingredient: DNS?

Configure your DNS/domain name records

I entered gitlabci.trythis.ga as the Base domain in the Details tab of my new Kubernetes cluster. To use that, though, I had to make sure I had DNS pointing to my Kubernetes Ingress controller(s). In my case there was only one IP address I needed, and I had recorded it earlier when obtaining the Kubernetes API URL by running:

1$ civo kubernetes show gitlab4
2
3          ID : 55c64b1b-8fbf-4105-8f7b-15e6acd11cef
4        Name : gitlab4
5       Nodes : 1
6        Size : g2.large
7      Status : ACTIVE
8     Version : 1.18.6+k3s1
9API Endpoint : https://91.211.152.211:6443
10   Master IP : 91.211.152.211
11DNS A record : 55c64b1b-8fbf-4105-8f7b-15e6acd11cef.k8s.civo.com

And then I created a couple of DNS entries so that anything in the .gitlabci.trythis.ga domain would be directed to 91.211.152.211. (If you’re trying this, your IP will be different, and if you’re using GKE or EKS rather than Civo you may need to use a different approach to cluster ingress):

1$ civo domain record add trythis.ga -n gitlabci -e A -v \
291.211.152.211 -t 120
3
4$ civo domain record add trythis.ga -n \*.gitlabci -e A -v \
591.211.152.211 -t 120
6
7$ civo domain record add trythis.ga -n oncivo -e A -v \
891.211.152.211 -t 120
9
10$ civo domain record add trythis.ga -n \*.oncivo -e A -v \
1191.211.152.211 -t 120

Enable Auto DevOps and start deploying

Next I needed to enable Auto DevOps and push some code into my project. Auto DevOps tries to “do the right thing” with your application code and if it finds a Dockerfile or a matching build-pack. The list of scans and checks that are done by default against the code, without any additional configuration required, is impressive to say the least.

If you want more fine-grained control their Gitlab CI tooling, controlled via a .gitlab-ci.yml file is pretty amazing!

I added 3 files to my local git repo:

package.json:

1{
2  "name": "simple-node-app",
3  "version": "1.0.0",
4  "description": "Node.js on Docker",
5  "main": "server.js",
6  "scripts": {
7    "start": "node server.js"
8  },
9  "dependencies": {
10    "express": "^4.13"
11  }
12}

server.js:

1'use strict';
2
3const express = require('express');
4
5// Constants
6const PORT = process.env.PORT || 3000;
7
8// App
9const app = express();
10app.get('/', function (req, res) {
11  res.send('Hello world\\nHello Mac\\n');
12});
13
14app.listen(PORT);
15console.log('Running on [http://localhost:'](http://localhost:%27) \+ PORT);

Dockerfile:

1FROM bitnami/node:9 as builder
2ENV NODE_ENV="production"
3
4# Copy app's source code to the /app directory
5COPY . /app
6
7# The application's directory will be the working directory
8WORKDIR /app
9
10# Install Node.js dependencies defined in '/app/packages.json'
11RUN npm install
12
13FROM bitnami/node:9-prod
14ENV NODE_ENV="production"
15COPY --from=builder /app /app
16WORKDIR /app
17ENV PORT 5000
18EXPOSE 5000
19
20# Start the application
21CMD \["npm", "start"\]

I committed my freshly-minted application code, and as soon as I had finished uploading my changes with git push , Gitlab began its magic. Below is a screenshot of the pipeline that Gitlab used. With zero input from me in creating it:

And below, in the output of the job that formed the final step of the pipeline, you can see the URL at which my newly deployed app was available.

The app itself was just a tiny “hello world” Javascript app, so it didn’t look amazing, but it was definitely published and running. With the connection nicely secured with a LetsEncrypt certificate:

If you made it this far, then I’d like to thank you for reading. I’m sure there is a ton more that can be said about this topic, and there are also a lot of other posts that cover different aspects of Gitlab + Kubernetes.