In this article, I will show you how to create a Civo Kubernetes cluster using GitLab. This is done using the GitLab Agent for Kubernetes, which allows you to create, update and manage your Kubernetes clusters as part of your GitLab setup. To follow along with this guide you will need a GitLab account alongside a Civo account.

For more information about the capabilities of the connection, see the GitLab agent for Kubernetes documentation.

Setting up the repository

The first step is to set up a project from your GitLab account.

Create a new project

Projects bar heading in GitLab

From the given options, choose "import project"

Project creation options on GitLab, with the "Import project" option selected

Enter the Civo Gitlab Terraform Git repository URL (https://gitlab.com/civocloud/gitlab-terraform-civo.git) for the import and create the project:

Import options on GitLab, with "Repository by URL" selected

The full import screen on GItLab

Agent registration

Once the project is created successfully, the next step is to create a GitLab agent for Kubernetes.

After this, you need to select the Kubernetes clusters under "infrastrcture" which can be found in the left sidebar:

Infrastructure tab on the GitLab sidebar

Select "connect a cluster":

Connect a cluster button on GitLab

Choose civo-agent from the drop-down list and click "register":

Civo-agent being selected from the availabe cluster connections

GitLab will generate a secret token that will be used later on.

Secrets and other details shown by GitLab once the cluster agent is created

Configuring project environment variables

You need to configure a few environment variables in your project from the information you got after creating the agent.

Below is the list of variables you need to configure under the Settings > CI/CD > Variables section of your project:

GitLab sidebar settings selection

GitLab settings Variables screen

You will need to use the Variables section to save the following variable names, with the values described.

  • BASE64_CIVO_TOKEN: the token from your Civo account.
  • TF_VAR_agent_token: the agent token you received in the previous step.
  • TF_VAR_kas_address: the agent server address in the previous step.

Saved variables configured

Optional configuration:

The file variables.tf in the linked repository contains other pre-defined variables that you can override according to your needs:

  • TF_VAR_region: Set your cluster's region from the available Civo regions.
  • TF_VAR_cluster_name: Set your cluster's name.
  • TF_VAR_cluster_description: Set a description for the cluster. To create a reference to your GitLab project on your Civo cluster detail page, set this value to $CI_PROJECT_URL. This value helps you determine which project was responsible for provisioning the cluster you see on the Civo dashboard.
  • TF_VAR_target_nodes_size: Set the size of the nodes to use for the cluster.
  • TF_VAR_num_target_nodes: Set the number of Kubernetes nodes.
  • TF_VAR_agent_version: Set the version of the GitLab agent.
  • TF_VAR_agent_namespace: Set the Kubernetes namespace for the GitLab agent.

Refer to the Civo Terraform provider and the Kubernetes Terraform provider documentation for further resource options.

For this demo I will use the default values from the variables.tf file that is present in the project.

Screenshot of the default variables.tf file

Provisioning the cluster

Now you can go to your project pipelines from the CI/CD section.

GitLab sidebar CI/CD menu

Now run the pipeline for the magic to start (no magic as it is all Terraform!)

GitLab "Run pipeline" options

Once you hit the deploy button, you will be able to see the Kubernetes cluster created and then the GitLab agent being installed on that cluster. You can also see the cluster in your Civo dashboard.

GitLab deployment pipeline

Civo account dashboard showing a gitlab-civo cluster

If you download the KUBECONFIG file for the cluster from the cluster page on Civo, and set it to be your current KUBECONFIG, you will be able to see the agent deployed. 

kubectl get pods -A
NAMESPACE      NAME                          READY   STATUS    RESTARTS   AGE
kube-system    civo-ccm-7cb9c4b58f-tp5fp     1/1     Running   0          7h12m
kube-system    civo-csi-node-79p2m           2/2     Running   0          7h11m
kube-system    civo-csi-node-2rjq4           2/2     Running   0          7h11m
kube-system    civo-csi-node-hrgjf           2/2     Running   0          7h11m
kube-system    coredns-85cb69466-j4dqt       1/1     Running   0          7h12m
kube-system    civo-csi-controller-0         3/3     Running   0          7h12m
gitlab-agent   gitlab-agent-8fb766c7-gzgzx   1/1     Running   0          7h11m

That's it! You have successfully created a Civo Kubernetes cluster with a GitLab agent installed from within GitLab.

GitLab Agent status showing it is connected and active on a Civo cluster

Conclusion

The GitLab Agent will be aware of the state of your Kubernetes cluster, and be able to make adjustments to it based on your CI/CD and Terraform pipelines. Whether you're aiming for a GitOps workflow or to use the CI/CD process of managing applications, the Agent will be set up with the parameters you choose.