Installing the GitLab Runner the OpenShift Way

GitLab is a leader in the Dev/Ops community with more than 100,000 users and serves as the Dev/Ops engine of choice for many Fortune 500 companies. Like Red Hat, they have a strong open source heritage and a commitment to open source values. Red Hat and GitLab, already partnering on many important public sector and commercial accounts, are excited about the introduction of the GitLab Runner Operator, a certified operator for Red Hat OpenShift. With this, we start a new, enhanced, better story about our partnership.

For our customers, deploying GitLab and Red Hat together supports their journey to Dev/Ops and cloud native application development. As Red Hat builds credibility among the developer community, partnering with one of the most prominent CI/CD pipelining tools is undeniably the right thing to do. Not only do we share the same open source heritage, but we also share the ability to provide a cohesive end-to-end story that can improve the way developers and Site Reliability Engineering (SRE) teams work. Delivering this allows our customers to accelerate the process of moving from concept to production.

As a first step in this closer partnership, GitLab now has a Certified Runner Operator. Why is this important? The Certified Runner Operator can now be deployed into OpenShift from the OpenShift Operator Hub. This gives development and SRE teams a simple deployment mechanism for the GitLab Runner as they spin up new projects. Being managed by a level one operator, this makes the GitLab Runner a first-class Custom Resource in OpenShift, which means the Runner can evolve over time to include automatic updates, pipeline management during updates, and the ability to meter and capture other metrics about pipeline activities on OpenShift. The job of this GitLab Operator is creating and managing instances of the GitLab Runner. As shown in Figure 1, the GitLab Runner is part of the GitLab agent architecture. It allows GitLab to communicate with, push and manage jobs, and monitor activities on remote environments. In this case, that remote environment is OpenShift.

Figure 1

This article will cover the steps involved in installing and configuring the GitLab Operator and the instantiation of Runners for an OpenShift project.

Operator Installation and Configuration

The first step to installing and configuring the GitLab Runner Operator is for you to navigate to the OpenShift console from the Admin view and click on OperatorHub as illustrated in Figure 2. One valuable feature of OpenShift is the embedded OperatorHub. This secure Hub is a hosted local registry for certified operators that have been scanned and validated. When GitLab updates the operator in the partner portal, this operator will become available in the OperatorHub so project owners will have the latest Runner available to use.

Figure 2

As can be seen in the FIgure 3 below, the current GitLab Runner operator is only a Basic Install operator. Over time, the GitLab Runner operator will mature with more and more features and capabilities.

Figure 3

The next step is to create an Operator Subscription to the Runner Operator, as shown in Figure 4. The Operator Subscription tells OpenShift how to control the scope of this Operator as well its update policy.

For scoping, you get to define the Installation Mode. Currently, clusterwide scoping is not available. So, namespace scoping is selected by default, and a predefined namespace is required. Also, here is where you tell OpenShift whether to automatically update the operator as soon as a new one is available in the Operator Catalog or force the update to be a manual process.

Figure 4

After the Subscription definition has been created, the operator installation is complete, as shown below in Figure 5.

Figure 5

Creating and Using a GitLab Runner Instance

In order to create a Runner instance, users must first create an OpenShift Secret. This Secret will store the security token required for Runner instances to communicate with the privately or publicly hosted GitLab Server. This token is generated from your GitLab Server. To get the token, login to your GitLab server instance. Then, navigate to Settings -> CI/CD from the navigation panel. Once on this page, click the Expand button next to Runners. There, you will find this screen represented in Figure 6 below. GitLab will generate a token for the Runner. Press the copy button next to the generated token on item 3.

Figure 6

Now, open a command prompt where the OpenShift CLI is installed to communicate with your cluster. Enter the following command:

$ kubectl -n operators create secret generic <name of your secret> --from-literal runner-registration-token=<the token copied from GitLab Server>

Once the Secret is created, now you are ready to create the Runner instance. To create the Runner, you can go to the OpenShift console to Installed Operators -> Operator Details. Then, press Create Runner, which is depicted below in Figure 7.

Figure 7

The Runner needs to be configured with the appropriate secret. This can be done using YAML configuration in the console or from a terminal using the CLI. The following YAML definition should be used to define the Runner CRD:

Figure 8

There are some very important values in this YAML definition, with the most important being the URL field. This value is obtained from the GitLab server Runner configuration page. This URL can be seen in Figure 6 under item 2. Copy this value and paste into the URL attribute in the YAML definition. Next, insert the name of the Secret that was created earlier as the value for the token attribute.

Finally, Tags. Tags in GitLab allow pipelines to be configured so that only Runners with those tags are engaged as part of the pipeline. For our example, we’ll just use OpenShift and test. In the console, Figure 9, the installed Runners can be found in the Installed Operators → Operator Details page:

Figure 9

Summary

In summary, the process to install the GitLab Runner Operator and get the Runner installed and available is pretty straightforward. The biggest item to make note of is to be sure to configure the Secret properly. Otherwise, the GitLab Runner will not be able to connect to the GitLab server and participate in pipelines.

With the GitLab Runner installed, an OpenShift cluster and projects can participate in distributed pipelines. These pipelines could trigger jobs and actions such as automated testing, extended security scans, and hardening.

The partnership between GitLab and Red Hat continues to expand. Be on the lookout for increased Operator maturity for the GitLab Runner operator. Also, coming soon will be the GitLab Enterprise Server Operator. This feature will provide a world-class Dev/Ops platform as a first-class entity in the OpenShift Dev/Ops ecosystem.