Gitlab with Rancher

Review-Apps & Prometheus | Self-Hosted Installation Guide

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.

Prerequisites

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 (*.your-domain.com or *.sub.your-domain.com)
• Wildcard DNS entry pointing to your Kubernetes- / Rancher-Server

Docker

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

Rancher

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.

Firewall

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 (cluster.domain.com 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.

Conclusion

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