GitLab Runner Infrastructure Toolkit

The GitLab Runner Infrastructure Toolkit (GRIT) is a library of Terraform modules you can use to create and manage many common runner configurations on public cloud providers.

Create a runner with GRIT

To use GRIT to deploy an autoscaling Linux Docker in AWS:

1. Set the following variables to provide access to GitLab and AWS:

   • GITLAB_TOKEN
   • AWS_REGION
   • AWS_SECRET_ACCESS_KEY
   • AWS_ACCESS_KEY_ID

2. Download the latest GRIT release and extract to .local/grit.

3. Create a main.tf Terraform module:

   module "runner" {
     source = ".local/grit/scenarios/aws/linux/docker-autoscaler-default"
   
     name               = "grit-runner"
     gitlab_project_id  = "39258790" # gitlab.com/josephburnett/hello-runner
     runner_description = "Autoscaling Linux Docker runner on AWS deployed with GRIT. "
     runner_tags        = ["aws", "linux"]
     max_instances      = 5
   }

4. Initialize and apply the module:

   terraform init
   terraform apply

These steps create a new runner in a GitLab project. The runner manager uses the docker-autoscaler executor to run jobs tagged as aws and linux. The runner provisions between 1 and 5 VMs through a new Autoscaling Group (ASG), based on workload. The ASG uses a public AMI owned by the runner team. Both the runner manager and the ASG operate in a new VPC. All resources are named based on the provided value (grit-runner), which lets you create multiple instances of this module with different names in a single AWS project.

Manage runner state

To maintain runners:

1. Check the module into a GitLab project.

2. Store the Terraform state in the GitLab Terraform backend.tf:

   terraform {
     backend "http" {}
   }

3. Apply the changes by using .gitlab-ci.yml:

   terraform-apply:
     variables:
       TF_HTTP_LOCK_ADDRESS: "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${NAME}/lock"
       TF_HTTP_UNLOCK_ADDRESS: ${TF_HTTP_LOCK_ADDRESS}
       TF_HTTP_USERNAME: ${GITLAB_USER_LOGIN}
       TF_HTTP_PASSWORD: ${GITLAB_TOKEN}
       TF_HTTP_LOCK_METHOD: POST
       TF_HTTP_UNLOCK_METHOD: DELETE
     script:
       - terraform init
       - terraform apply -auto-approve

Delete a runner

To remove the runner and its infrastructure:

terrafrom destroy

Supported configurations