Gitlab with Rancher

Review-Apps & Prometheus | Self-Hosted Installation Guide

Ruben Vitt
fme DevOps Stories
Published in
7 min readAug 11, 2020


In this article I’m describing how to set up a Kubernetes-Cluster using Rancher. If rancher is working, we’ll connect Gitlab and enabling review-apps.

Every system in this article is self-hosted | we’ll do nothing within cloud (no AWS, no GCP).

Some words before we start

Kubernetes is an open source system wich helps you to orchestrate containers in a so-called Kubernetes-Cluster. A cluster consists of one or more servers connected together. Kubernetes will handle the automatic distribution of the (Docker)-Container in it’s environment.

Rancher is a platform (f.e. hosted as a single-node Docker application or in a Kubernetes-Cluster) to manage one or more Kubernetes-Cluster — self-hosted or hosted in the cloud (AWS, GCP, …). It makes it really easy to handle the Kubernetes-Cluster in an easy to understand web-UI.

Gitlab-Review Apps “Review Apps is a collaboration tool that takes the hard work out of providing an environment to showcase product changes.” (Gitlab Docs). Your CI-Pipeline will build a test-deployment on a domain <group-project-branch-name>.your-domain.tld showing your application. This makes it easier to collaborate by reviewing the app without installing it somewhere manually or deploy each different branch on a Dev-System.


This article uses a single-node-cluster (but you’re able to add more nodes easily after the first steps). To follow this article, you need these components running:

  • Gitlab instance
  • VM / Server with CentOS (or another Linux distribution) capable to run Docker | f.e. with 32GB RAM, 4 Cores & enough storage for some Docker-images & containers
  • Wildcard SSL certificate (* or *
  • Wildcard DNS entry pointing to your Kubernetes- / Rancher-Server


Installing Docker should be an easy step for you. If not, please have a look at the the Docker website.


Installing Rancher is also easy with the following snippet:

With this script you’re installing rancher as a Docker-container. Rancher will be published on Port 8080 & 8443 (Port 443 & 80 will be used for the review-apps). The certificates will be added differently in a later step — but you may use them or use LetsEncrypt. To do so, please checkout the Rancher Documentation.


When configuring the firewall you can use the following snippet:

Open Port 443 and Port 80 for the review-apps, 6443 for Kubernetes-API and 8080 & 8443 for accessing the Rancher-Dashboard.

Start with Rancher

At this point all necessary components were installed and should be usable. In the next steps we’ll setup Rancher and create our Kubernetes-Cluster. In the next part we’ll install Gitlab and set up the review apps.

Open <server>:8443 to access the rancher installation page. The first steps are very easy:

  • Create an account
  • Specify your URL (I think ‘Save URL’ would do a good job there in most cases…)
The URL is prefilled by the actually opened address ( in my case).

After that you’ll get an empty dashboard making you able to create your own cluster. Click on the top-right button ‘Add Cluster’ and choose ‘from existing nodes (Custom)’ to create a local Kubernetes cluster. Enter a name for this cluster, scroll down and change some of the settings:

Custom Docker-Folder: If you moved your docker-folder from ‘’ to f.e. `/data/docker’ you have to change this: In ‘Advanced Options/Docker Root Directory’ enter the new docker-path ‘/data/docker’

Gitlab 12.x only: Gitlab 12 is using the v1beta-api (ticket was resolved now), which isn’t accessible with our Rancher/Kubernetes version without telling so. The API has to be enabled with following snippet:

No need to change it on newer Gitlab-Version (which I think all of you are using when accessing this article).

Root-Certificate: Gitlab Review Apps are being deployed on xxxx.<your-cluster-domain> and should be secured with ssl. Later we’ll use the default rancher-ingress — so we have to change the certificates for this container. Create a wildcard-certificate from a CA (or use your bought one available for use at xxx.<your-cluster-domain>), run the following steps and… Your review apps will be secured later on.

For this case we created a custom-CA which was trusted by all my colleagues accessing the review-domain.

You are finished configuring the new cluster and a click on ‘Next’ will be the next good thing to do.
There you get a page showing up your docker-run command. The nice thing is, that you don’t need to change this command unless you want to change the kind of cluster node to create.

Generate Docker Commands: Generally a cluster consists of all the following components: etcd, worker & control panel. Each component can run on any of your nodes. The worker-nodes do the work, so you’ll need some of them. But to get started with the cluster, it’s okay to create a single-node-cluster only and to increase the node-size later on — it’s very easy to add components in any next step.

If you decide to use a single-node-cluster, you may want to create a full-featured component including etcd, control-panel & worker. For this

  • check all three checkmarks,
  • copy the resulting docker-run command and
  • execute that on your Cluster-VM where you’ve installed Rancher before.

After running that command, the webpage notifies you about a newly created cluster. Now you’re finished setting up the cluster and it’s going to be installed by it’s own.

Gitlab Setup

Gitlab Service Account Creation

The Gitlab-Docs for connecting Kubernetes to Gitlab are very-well written and easy to understand. You only have to copy/paste their code and you’re done setting up. The collected instructions from Gitlab-Docs are the following:

First of all in the Rancher cluster-dashboard locate the button ‘kubectl’. You’ll get an online-terminal where you should create a new file:

Content of this file should be the following yaml:

With this you add a new service-account needed by Gitlab to access the Kubernetes-API. Close the editor by entering ‘:wq’ and run the following commands to load the yaml and print the user-token:

You’ll get an output of the newly created user, also it’s token will be displayed. Save this token somewhere, you’ll need that for Gitlab in a few moments.

Gitlab Network Setup

As a last step you should get the certificate of the Kubernetes-API. Open the cluster-settings (the point where you opened the kubectl) and open the Kubernetes config file (next to the kubectl-button). Search for the server with ‘<IP>:6443’ and copy the displayed certificate in a file (you need it also in one of the next steps).

The cluster is now finally set up 🎉. Now some settings in the Gitlab instance will follow.

Kubernetes Cluster Setup

Preparation: If you run Gitlab and the Kubernetes-Cluster in the same local network, Gitlab is detecting that and blocks the access for security reasons. For this you should make an exception for the Cluster-VM. This can be done at following Point in Gitlab:

Admin-Panel | Settings | Network | Outbound Requests
There you have two options: Allow local network communication for services or define an exception for your service-IP address.

Integration-Options: In Gitlab you may integrate Kubernetes on different levels: project-level, group-level or system-wide.
While integrating the cluster on project-level, you’re only able to access it from this specific project. If you choose to integrate it on group-level, the access it inherited by any sub-group / project of this specific group.

The best option might be to make it accessible everywhere — so you don’t have to add multiple clusters and everyone (every project) will get a benefit from the cluster and may use the review-apps.

Adding it to a project or a group is being done by click on Operations | Kubernetes, adding it globally is being done by accessing the Admin Panel | Kubernetes. From there, you click on Add Kubernetes Cluster | Existing Cluster.

After choosing the ‘existing Cluster’ option you should enter following settings:

With these settings Gitlab should accept the cluster and you’re ready to install helm. After that: install the GitLab Runner, too.

I already had working Gitlab Runners and had to deactivate them to make AutoDevOps work.

Gitlab Managed Apps

To get a better view what’s going on @ Rancher / Kubernetes, it’s the best to navigate to the rancher-namespace settings of your cluster and move the gitlab-managed-apps namespace to your Default Project (or a different one, maybe newly created). Then you’re able to inspect the container managed by Gitlab.

For each deployment you want to inspect, repeat the namespace-moving, than you are able to view the container-logs, too.


With the Rancher-Gitlab Setup you get a really-easy-to-work-with review-apps implementation with ability to run your branch-reviews.