How to Integrate GitLab-Ci w/ Azure Kubernetes + Kubectl + ACR for Deployments?

Creating the integration

I had the same problem of how to integrate the GitLab CI/CD with my Azure AKS Kubernetes cluster. I created this question because I was having some error when I tried to add my Kubernetes cluester info into GitLab.

How to integrate them:

1. Inside GitLab, go to "Operations" > "Kubernetes" menu.
2. Click on the "Add Kubernetes cluster" button on the top of the page
3. You will have to fill some form fields, to get the content that you have to put into these fields, connect to your Azure account from the CLI (you need Azure CLI installed on your PC) using az login command, and then execute this other command to get the Kubernetes cluster credentials: az aks get-credentials --resource-group <resource-group-name> --name <kubernetes-cluster-name>
4. The previous command will create a ~/.kube/config file, open this file, the content of the fields that you have to fill in the GitLab "Add Kubernetes cluster" form are all inside this .kube/config file

These are the fields:

1. Kubernetes cluster name: It's the name of your cluster on Azure, it's in the .kube/config file too.
2. API URL: It's the URL in the field server of the .kube/config file.
3. CA Certificate: It's the field certificate-authority-data of the .kube/config file, but you will have to base64 decode it.

After you decode it, it must be something like this:

-----BEGIN CERTIFICATE-----
...
some base64 strings here
...
-----END CERTIFICATE-----

4. Token: It's the string of hexadecimal chars in the field token of the .kube/config file (it might also need to be base 64 decoded?). You need to use a token belonging to an account with cluster-admin privileges, so GitLab can use it for authenticating and installing stuff on the cluster. The easiest way to achieve this is by creating a new account for GitLab: create a YAML file with the service account definition (an example can be seen here under Create a gitlab service account in the default namespace) and apply it to your cluster by means of kubectl apply -f serviceaccount.yml.
5. Project namespace (optional, unique): I leave it empty, don't know yet for what or where this namespace can be used.

Click in "Save" and it's done. Your GitLab project must be connected to your Kubernetes cluster now.

Deploy

In your deploy job (in the pipeline), you'll need some environment variables to access your cluster using the kubectl command, here is a list of all the variables available:

https://docs.gitlab.com/ee/user/project/clusters/index.html#deployment-variables

To have these variables injected in your deploy job, there are some conditions:

• You must have added correctly the Kubernetes cluster into your GitLab project, menu "Operations" > "Kubernetes" and these steps that I described above
• Your job must be a "deployment job", in GitLab CI, to be considered a deployment job, your job definition (in your .gitlab-ci.yml) must have an environment key (take a look at the line 31 in this example), and the environment name must match the name you used in menu "Operations" > "Environments".

Here are an example of a .gitlab-ci.yml with three stages:

• Build: it builds a docker image and push it to gitlab private registry
• Test: it doesn't do anything yet, just put an exit 0 to change it later
• Deploy: download a stable version of kubectl, copy the .kube/config file to be able to run kubectl commands in the cluster and executes a kubectl cluster-info to make sure it is working. In my project I didn't finish to write my deploy script to really execute a deploy. But this kubectl cluster-info command is executing fine.

Tip: to take a look at all the environment variables and their values (Jenkins has a page with this view, GitLab CI doesn't) you can execute the command env in the script of your deploy stage. It helps a lot to debug a job.