Gitlab Project & GKE Integration

How to authenticate your GitLab project within a GKE Cluster using the Kubernetes Agent

*This is part-one of of a two-part series on Auto-Dev-Ops- Scaling your CI/CD builds.

Introduction

*Gitlab runs CI/CD pipelines through a a program that you define called a Gitlab runner. These runners can be managed by Gitlab (for a fee) on their servers or you can configure and set up your own self-managed one. Gitlab runners are configured to run your CI/CD Pipeline jobs for your codebase.

Recently my organization experienced a corruption of our container registry during a services upgrade. This forced us to manually re-build our container images in our registry via our GitLab runners.

Unfortunately, this task took about 3 hours because we only had four configured runners available to run pipeline jobs so while the task of running 25 pipelines was a relatively simple task, we were stuck waiting because our Gitlab runners were deployed on GCP compute instances, what should have taken an hour at most for our production environment, took over three as we waited for our Gitlab runners to become available to process our queue of pipeline jobs.

This made me this, is there a better way to deploy our existing runners to make them more scalable?

Certainly having multiple runners sitting idle in compute instances isn’t the most cost-effective either.

Which brought me to deploying Gitlab runner instead within a Kubernetes Cluster using a Kubernetes Agent.

What is a GitLab Kubernetes Agent?
Simply put, if you are looking to make your Gitlab runners more scalable, cost-effective, and move away from Gitlab’s deprecated certificate-based authentication method of connecting your GitLab project into your Kubernetes cluster, then it starts with authenticating your Kubernetes cluster with a Kubernetes Agent.

GitLab Kubernetes Agents not only are the way forward for authenticating your Kubernetes clusters with Gitlab but they also can be configured to automate the deployment of your Gitlab runners within your GKE Kubernetes cluster.

And since I just completed this project, I’m going to share a walk-thru with you on how you can automate the deploy your own Gitlab Kubernetes agent into your cluster using a helm chart and terraform.

Let’s get started:

Prerequisites

• A Gitlab Account with at least developer access to a project
• A Deployed Cluster to GCP with Cluster Admin Access
• Helm installed on your local IDE.
• IaC knowledge (preferably in terraform and .yaml)
• A google cloud account and CLI configured on your local machine

Note: If you anticipate utilizing your Kubernetes Agent for multiple projects, then you should configure it within it’s own project.

Step 1: Create a new GitLab Project:

Step 2: Create an agent configuration file — In your default branch, create a Kubernetes Agent configuration file with the following specs:

# File needs to be in this file structure. You can name the <agent-name> whatever you want

.gitlab/agents/<agent-name>/config.yaml

The config.yaml should contain the PATH the Gitlab project that you want to integrate with your agent and the name of your .yaml which will eventually be the configuration for your Gitlab runner (I will walk through the process in a later article).

gitops:
  manifest_projects:
  - id: "<_PATH_TO_YOUR_GITLABPROJECT_"
    paths:
    - glob: 'runner-manifest.yml'

Step 3: Create an Agent Access Token — Within your project settings, you need to create an Agent Access Token. On the left-side menu, under “Operate”, click “Kubernetes Clusters” link. Click the “agents” tab and when it prompts you to select an agent, select your agent that you created in the previous step.

Next GitLab will show you your ‘agent access token’ & your Kubernetes Agent Server, which is managed by GitLab. SAVE THEM.

The token is not reproducible, if you lose it. and it’s what gets configured on your GKE Cluster when you deploy the agent.

The token is what allows your agent on your cluster to maintain communication with your repository to monitor for any changes in your repository.

NOTE: YOU MUST REGISTER THE AGENT AND DO THE SET UP IN GITLAB BEFORE YOU DEPLOY THE AGENT TO THE CLUSTER.

In the coming steps I will show you the terraform configuration needed to deploy your agent into your cluster using helm.

However, if you deployed your agent BEFORE you configured your token, you will need to redeploy the agent in order for the agent to deploy and integrate correctly with your Gitlab project.

2. Create a Terraform configuration file with your KAS & token values This creates our Kubernetes agent via a Helm Chart, which will be used in our terraform to deploy the Kubernetes agent into our cluster.

I chose to create this .tf in the same directory as my cluser configuration so that it deploys it directly on my cluster when I run a terraform apply.

// Sample k8s_agent_helm.tf file:

resource "helm_release" "gitlab_agent" {
  name = "gitlab-agent"

  repository = "https://charts.gitlab.io"
  chart      = "gitlab-agent"

  create_namespace = true
  namespace        = var.agent_namespace

  set {
    name  = "config.kasAddress"
    value = var.kas_address
  }

  set {
    name  = "config.token"
    value = var.agent_token
  }

  set {
    name  = "image.tag"
    value = "v16.3.0"
  }
}

Make sure to define the values for your variables in your variables.tf file:

//Sample variable blocks for values in your variables.tf file

variable "agent_token" {
  type        = string
  default     = "<YOUR_RUNNER_TOKEN_VALUE>"
  description = "Agent token (provided when registering an Agent in GitLab)"
  sensitive   = true
}

variable "kas_address" {
  type        = string
  default     = "wss://<YOUR_KAS_AGENT_SERVER>"
  description = "Agent Server address (provided when registering an Agent in GitLab"
}

Step 3: Run ‘Terraform Apply” and confirm Kubernetes Agent Deployment

Save you file and run a terraform apply:

Verify the agent deployment via the GCloud Console:

Finally, we can verify the Kubernetes agent integration with our GitLab project by re-visiting the agent settings under the “Operate > Kubernetes Clusters > Agent” link within our project

Congrats! You have successfully deployed a Kubernetes Agent within your GKE Cluster. This is part one of my three part-series — auto-dev-ops.

Follow me so that you get notified when I post my next tutorial — How to use the Kubernetes Agent to deploy your GitLab runners for CI/CD Jobs.

If you found this article helpful, then you might also like a previous article I wrote about Kubernetes Deployments for Micro-service Applications.

Additionally, I would appreciate if you would leave a couple of ‘claps’ or a comment below. It helps this type of content reach more DevOps folks.

Until next time, Onward!