Auto DevOps with the GitLab Agent for Kubernetes

March 10, 2022


This is meant as a quick-start to connect an existing Kubernetes cluster with GitLab for use with Auto DevOps. The intended audience includes those who are new to GitLab as well as people migrating from the deprecated certificate-based integration.

Pre-requisites and assumptions

  1. Existing Kubernetes Cluster where you will be able to install the GitLab Agent for Kubernetes
  2. Although the following steps should work on both GitLab self-managed and, I have only tested them on


We will be using three projects for this walkthrough.

  1. A project for the agent configuration
  2. A Cluster Management Project
  3. A project where Auto DevOps will be enabled


  1. Navigate to the Subgroup where you will create the three projects. Ex.
  2. From the left menu, select Kubernetes, then check that the Subgroup does not have access to a certificate-based cluster connection.
  3. Create a project for the Kubernetes Agent. Ex.

    1. Decide on an agent name, and create an empty file in your project under .gitlab/agents/<your agent name>/config.yaml.The extension must be yaml and not yml! I called my agent ec-agent, so the file is under .gitlab/agents/ec-agent/config.yaml
    2. Once the configuration file is in place, visit Infrastructure/Kubernetes and add a new cluster using the Agent. A dialog will pop up where you can select your agent:

    Agent Registration UI

    1. Once you hit “next,” you will see the registration token and a docker command for easy installation. The docker command includes the token too and you can run it to quickly set up an agentk inside of your cluster.
    2. Open a shell in your cluster and run the docker command from the previous step.
    3. Check that cluster syncronization is working. We will deploy a ConfigMap to test the setup. Create kubernetes/test_config.yaml with the following content:
    apiVersion: v1
    kind: ConfigMap
      name: agent-test
      namespace: gitlab-agent
      key: It works!
    1. Modify your Agent configuration file under .gitlab/demo-agent/config.yaml, and add the following to it:
      # Manifest projects are watched by the agent. Whenever a project changes,
      # GitLab deploys the changes using the agent.
      - id: edmond-demo/sandbox/kubernetes-agent 
      #- id: path/to/your/project
        default_namespace: gitlab-agent
        # Paths inside of the repository to scan for manifest files.
        # Directories with names starting with a dot are ignored.
        - glob: '/kubernetes/*.yaml'
        # - glob: '/kubernetes/**/*.yaml'
    # The CI/CD tunnel is always enabled in the project where you register and configure the Agent. 
    # This connection can be shared with other groups and projects. 
      # projects:
      # - id: path/to/project
      - id: edmond-demo/sandbox
      # - id: path/to/group that is a parent to the agent configuration project

    Once you commit the above changes, GitLab notifies agentk about the changed files. First, agentk updates its configuration; second, it retrieves the ConfigMap.

    Wait a few seconds, and run kubectl --namespace gitlab-agent describe configmap agent-test to check that the changes got appliedd to your cluster. You should see something similar:

    Name:         agent-test
    Namespace:    gitlab-agent
    Labels:       <none>
    Annotations: 502-28431043
    It works!
    Events:  <none>
  4. Create a project for the Cluster Management Project using the “Cluster Management Project” template. Open the create new project from template page, search for “GitLab Cluster Management”, and start a new project with that template.

    You will receive a project that already contains quite a lot of things! It comes with a ready-made .gitlab-ci.yml file and helmfile based setup for 11 applications that integrate with various GitLab functionalities. Each application might require different configurations. You can read about these in the linked documentation.

    We will install NGINX Ingress and cert-manager using the cluster management project.

    1. Install NGINX Ingress - In your cluster management project, edit helmfile.yaml and uncomment the line that points to the ingress application. Commit the changes to install.
    2. Install cert-manager - Next, edit helmfile.yaml and uncomment the line that points to the cert-manager application. Commit the changes to install.
  5. Set group level environment variables

    Variable Value
    KUBE_CONTEXT <path to agent>:<agent-name> (ex. edmond-demo/kubernetes-agent:ec-agent)
    KUBE_INGRESS_BASE_DOMAIN <cluster IP address>

    I used kubectl get service --all-namespaces to get the external-ip address of my ingress controller.

  6. Import your favorite Auto DevOps repo into the group you shared your CI/CD tunnel with and let the magic begin.

Resources that I borrowed heavilly from for this short writeup

(Thank you Viktor Nagy)

  1. How does the Agent work?
  2. GitOps with GitLab: The CI/CD Tunnel

Profile picture

Written by Edmond Chan. A collection of simple answers that are sometimes hard to find.