Luc Juggery
Aug 9 · 5 min read


k3s is a lightweight Kubernetes distribution (less than 40 MB), is very easy to install, and only requires 512 MB of RAM. It’s a perfect candidate for IoT devices and edge computing but also to run CI jobs. In this article, we will create a k3s cluster and show how to integrate it in a GitLab project.

About k3s

k3s is a lightweight Kubernetes distribution made by Rancher Labs.

It’s a Certified Kubernetes distribution with minimal system requirements:

  • Linux 3.10+
  • 512 MB of ram per server
  • 75 MB of ram per node
  • 200 MB of disk space
  • x86_64, ARMv7, ARM64

This makes k3s a good fit for IoT-related things.

Creation of a project in GitLab

Before installing k3s, we create a new project on Gitlab, which we call api.

Once created, we go into the Operations > Kubernetes menu.

From there we have two choices:

  • We can create a Kubernetes cluster on GKE (Google Kubernetes Engine).
  • We can import the configuration of an existing Kubernetes cluster (no matter where it was created).

Note: In the current release of GitLab, the creation of a new cluster is limited to GKE. GitLab, any plan to allow this on other Kubernetes providers (AKS, EKS, DOKS …)? :)

We choose the Add existing cluster tab.

From there, we need to fill several fields to provide the configuration of the cluster we need to integrate. Let’s keep this tab open and create a brand new Kubernetes cluster first.

Creation of a k3s Cluster

We will now initiate a Kubernetes based on k3s. Why k3s? Because I want to show how easy it is to set this up. :) To keep it simple, we will only set up a one-node cluster.

I have provisioned an Ubuntu 18.04 server named node1. Once we get a shell on that host, we only need to run the following command to install k3s, a certified Kubernetes cluster. Really!

root@node1:~ $ curl -sfL | sh -

The above command is similar to the one used for a quick Docker installation: curl | sh

Once installed (it’s incredibly fast), the configuration file to connect to the cluster is available in /etc/rancher/k3s/k3s.yaml.

root@node1:~ $ cat /etc/rancher/k3s/k3s.yaml
apiVersion: v1
- cluster:
certificate-authority-data: LS0tL...tCg==
server: https://localhost:6443
name: default
- context:
cluster: default
user: default
name: default
current-context: default
kind: Config
preferences: {}
- name: default
password: 48f4b...4b4e7
username: admin

The local kubectl is automatically configured to use this configuration.

$ kubectl get nodes
node1 Ready master 3m v1.14.5-k3s.1

Note: adding additional nodes is very easy as we can see at the end of the Quick Start. It’s basically only getting a token from /var/lib/rancher/k3s/server/node-token on the master and joining some other nodes using the following command:

$ curl -sfL | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -

Integration in Gitlab

Let’s now get all the information needed to integrate our brand new k3s cluster in our Gitlab’s project.

  • Cluster name

Let’s call it k3s.

  • URL of the API Server

In the configuration file, the API Server is specified as https://localhost:6443. To access it from outside, we need to provide the external IP address of node1.

  • Cluster’s CA certificate

To provide the cluster CA certificate to Gitlab, we need to decode the one specified in the configuration (as it’s in base 64).

$ kubectl config view --raw \
-o=jsonpath='{.clusters[0].cluster.certificate-authority-data}' \
| base64 --decode
  • Service token

The process to get an identification token involves several steps. We first need to create a ServiceAccount and provide it with the cluster-admin role. This can be done with the following command:

$ cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
name: gitlab-admin
namespace: kube-system
kind: ClusterRoleBinding
name: gitlab-admin
kind: ClusterRole
name: cluster-admin
- kind: ServiceAccount
name: gitlab-admin
namespace: kube-system

Once the service account is created, we retrieve the resource of type secret that is associated:

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

The next step is to extract the JWT token associated with the secret:

$ TOKEN=$(kubectl -n kube-system get secret $SECRET -o jsonpath='{.data.token}' | base64 --decode)
$ echo $TOKEN

We’re all set. Let’s now use all the information and fill the fields of GitLab’s Add existing cluster form:

Once the cluster is integrated, we can install helm (Kubernetes package manager) directly from the web interface.

We can now check from the command line that the tiller daemon (helm’s server-side component) is running.

$ kubectl get deploy --all-namespaces | grep tiller
gitlab-managed-apps tiller-deploy 1/1 1 1 67s

The cluster is now ready to use. On top of this, GitLab’s web interface allows one-click installation of additional components:

  • Ingress Controller to expose services running within the cluster
  • Cert-Manager to manager TLS certificates with Let’s Encrypt
  • Prometheus to monitor applications running in the cluster
  • Knative to deploy Serverless workload
  • Etc.


In this article, we saw how to create a k3s cluster and integrate it in a GitLab project. Of course, the same process can be used for any Kubernetes cluster.

We can now add resources to the project :

  • source code
  • Dockerfile to specify how to create a Docker image from the code
  • Kubernetes resources such as Deployment, Service, …
  • a .gitlab-ci.yaml file defining the CI pipeline and how the application should be deployed and tested against the associated Kubernetes cluster

You may find this previous article useful. It provides additional information about how to setup the CI/CD pipeline.

Do you use Kubernetes integration for your GitLab projects?

Better Programming

Advice for programmers.

Luc Juggery

Written by

#DockerCaptain #Startups #Software #中文学生 Learning&Sharing

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade