Gitlab with Rancher
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 (*.your-domain.com or *.sub.your-domain.com)
- 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:
When configuring the firewall you can use the following snippet:
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…)
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:
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 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.