Integrating a DigitalOcean Kubernetes Cluster with GitLab

Integrating a DigitalOcean Kubernetes Cluster with GitLab

GitLab provides a turnkey continuous integration/continuous delivery software development platform.

Setting up Kubernetes on DigitalOcean

Step 1: Create a DigitalOcean Kubernetes Cluster

Login to your DigitalOcean account or Sign-up for a new one and navigate to the Kubernetes control panel in the dashboard or choose to create a new cluster from the drop down menu.

Once on the new cluster page, choose a datacenter region, name your node pool, choose machine types (droplets), a node plan (droplet size), and select the number of nodes to create. In this case begin with the smallest standard droplets, 2GB memory/1 vCPU, and select 3 nodes. You add tags if you like and be sure to give the cluster a name, then click ‘Create Cluster’.

Step 2: Install Kubernetes Management Tools on Your MacOS Administration Machine

Digital Ocean recommends installing both the official Kubernetes client and the DigitalOcean command-line tool.

Since these instructions are specifically for MacOS, we will be using the MacOS package manager, Homebrew, to manage them. If you don’t already have Homebrew installed, you can install it with the following command:

Install Homebrew

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install Kubernetes Control (kubectl) with Homebrew

brew install kubernetes-cli

Test to ensure the version you installed is up-to-date:

kubectl version

Install Digital Ocean Control (doctl) with Homebrew

brew install doctl

Step 3: Install the Kubernetes Configuration File to Connect to Your Cluster

In order to connect to your cluster from the command line, you need a configuration file containing an authentication certificate and other connection information.

Digital Ocean recommends using doctl to automate your certificate’s management rather than manual certificate management. Once doctl is available in your PATH and you’ve configured your API keys to access your account, doctl uses an exec-credential plugin to dynamically grab the client-certificate and client-key.

How to configure your Digital Ocean API keys with doctl:

  1. The API item in the Digital Ocean dashboard navigation will take you to a screen where you can generate a new API token for the purpose.
  2. Run the following command on your administration machine:
doctl auth init

3. Input your API token when requested.

If all goes well Digital Ocean will validate your token and you can now download your cluster’s configuration file with the following command:

doctl kubernetes cluster kubeconfig save example-cluster-01

Replace example-cluster-01 with your cluster’s handle.

Step 4: Adding Kubernetes Cluster Information to GitLab

To integrate your newly created Kubernetes cluster with GitLab, navigate to the GitLab Admin Area and select Kubernetes. The default environment can be left as *, this will ensure all your CI pipelines use this environment when they are run. To take advantage of Auto Review Apps and Auto Deploy stages for Auto DevOps, GitLab’s ability to manage name-based access to your Docker containers, you will need to register a TLD and create a wildcard DNS record pointing to your Load Balancer IP address. Enter the domain you wish to use in the Base domain field and create the DNS entry at your DNS provider.

Next you will be asked to provide authentication information required for GitLab to integrate with your Kubernetes cluster:

  • The Kubernetes cluster name
  • The URL used to access the Kubernetes API 
  • A CA Certificate used to authenticate to the Kubernetes cluster
  • A service token scoped to kube-system with cluster-admin privileges

GitLab Documentation: Connecting GitLab with a Kubernetes cluster

Kubernetes Cluster Name

The cluster name should match the name given to the cluster in the DigitalOcean dashboard.

API URL

The URL that GitLab uses to connect to Kubernetes can be obtained by running the following command:

kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'

CA Certificate

A valid Kubernetes certificate is needed to authenticate to the DigitalOcean cluster. List the secrets with kubectl get secrets, you should find one named default-token-xxxxx.

kubectl get secrets

Copy that token name and use it while running the following command:

kubectl get secret <SECRET_NAME> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode

Service Token

GitLab authenticates against Kubernetes using service tokens, which are scoped to a particular namespace. The token used should belong to a service account with cluster-admin privileges. To create this service account:

  1. Create a file called gitlab-admin-service-account.yaml with contents:
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-admin
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: gitlab-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: gitlab-admin
  namespace: kube-system

2. Apply the service account and cluster role binding to your cluster:

kubectl apply -f gitlab-admin-service-account.yaml

Output:

serviceaccount "gitlab-admin" created
clusterrolebinding "gitlab-admin" created

3. Retrieve the token for the gitlab-admin service account:

kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}')

Copy the <authentication_token> value from the output:

Name:         gitlab-admin-token-h7svs
Namespace:    kube-system
Labels:       <none>
Annotations:  kubernetes.io/service-account.name: gitlab-admin
              kubernetes.io/service-account.uid: 21a2a94e-a26c-11e9-8b5c-b2934143d63d

Type:  kubernetes.io/service-account-token

Data
====
namespace:  11 bytes
token:      <authentication_token>
ca.crt:     1156 bytes

Since Digital Ocean is a RBAC enabled cluster, be sure to check the box to enable it.

Also, we want GitLab to manage the cluster, so be sure to also check the box enabling it.

Step 5: Installing GitLab Applications in Kubernetes

To complete the integration of GitLab and your Kubernetes cluster you need to install the following applications to your cluster from the GitLab Admin Area:

  • Helm Tiller
  • Ingress
  • Cert-manager
  • Prometheus
  • Gitlab Runner

That’s it, you’ll now be able to run build and deployment pipelines in the Kubernetes cluster.

Like this article?

Share on twitter
Share on Twitter
Share on linkedin
Share on Linkedin
CAB408 Logo