Skip to content

Create an Azure AKS cluster

You can create a cluster on Azure Kubernetes Service (AKS) through Infrastructure as Code (IaC). This process uses the Azure and Kubernetes Terraform providers to create AKS clusters. You connect the clusters to GitLab by using the GitLab agent for Kubernetes.

Prerequisites:

Steps:

  1. Import the example project.
  2. Register the agent for Kubernetes.
  3. Configure your project.
  4. Provision your cluster.

Import the example project

To create a cluster from GitLab using Infrastructure as Code, you must create a project to manage the cluster from. In this tutorial, you start with a sample project and modify it according to your needs.

Start by importing the example project by URL.

To import the project:

  1. On the left sidebar, at the top, select Create new ({plus}) and New project/repository.
  2. Select Import project.
  3. Select Repository by URL.
  4. For the Git repository URL, enter https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks.git.
  5. Complete the fields and select Create project.

This project provides you with:

Register the agent

To create a GitLab agent for Kubernetes:

  1. On the left sidebar, select Operate > Kubernetes clusters.
  2. Select Connect a cluster (agent).
  3. From the Select an agent dropdown list, select aks-agent and select Register an agent.
  4. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later.
  5. GitLab provides an address for the agent server (KAS), which you will also need later.

Configure your project

Use CI/CD environment variables to configure your project.

Required configuration:

  1. On the left sidebar, select Settings > CI/CD.
  2. Expand Variables.
  3. Set the variable ARM_CLIENT_ID to your Azure client ID.
  4. Set the variable ARM_CLIENT_SECRET to your Azure client secret.
  5. Set the variable ARM_TENANT_ID to your service principal.
  6. Set the variable TF_VAR_agent_token to the agent token displayed in the previous task.
  7. Set the variable TF_VAR_kas_address to the agent server address displayed in the previous task.

Optional configuration:

The file variables.tf contains other variables that you can override according to your needs:

  • TF_VAR_location: Set your cluster's region.
  • TF_VAR_cluster_name: Set your cluster's name.
  • TF_VAR_kubernetes_version: Set the version of Kubernetes.
  • TF_VAR_create_resource_group: Allow to enable or disable the creation of a new resource group. (Default set to true).
  • TF_VAR_resource_group_name: Set the name of resource group.
  • TF_VAR_agent_namespace: Set the Kubernetes namespace for the GitLab agent.

See the Azure Terraform provider and the Kubernetes Terraform provider documentation for further resource options.

Provision your cluster

After configuring your project, manually trigger the provisioning of your cluster. In GitLab:

  1. On the left sidebar, select Build > Pipelines.
  2. Next to Play ({play}), select the dropdown list icon ({chevron-lg-down}).
  3. Select Deploy to manually trigger the deployment job.

When the pipeline finishes successfully, you can view the new cluster:

  • In Azure: From the Azure portal, select Kubernetes services > View.
  • In GitLab: On the left sidebar, select Operate > Kubernetes clusters.

Use your cluster

After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection:

  1. On the left sidebar, select Operate > Kubernetes clusters.
  2. In the list, view the Connection status column.

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

Remove the cluster

A cleanup job is not included in your pipeline by default. To remove all created resources, you must modify your GitLab CI/CD template before running the cleanup job.

To remove all resources:

  1. Add the following to your .gitlab-ci.yml file:

    stages:
  - init
  - validate
  - test
  - build
  - deploy
  - cleanup

destroy:
  extends: .terraform:destroy
  needs: []

  2. On the left sidebar, select Build > Pipelines and select the most recent pipeline.

  3. For the destroy job, select Play ({play}).