Skip to content

GitLab Runners

Grove provides helper scripts to start private GitLab runners using Terraform.

Note

GitLab Runners are the only resources not supported by both AWS and DigitalOcean. It does not utilize the wrapper scripts under the control directory and, in addition, uses a separate Terraform state file.

Treat GitLab Runners as a standalone collection of scripts that are packaged with Grove for easier use, rather than as part of Grove itself.

Setting up GitLab runners is only available on AWS at the moment.

Prerequisites

  • Docker installation
  • GitLab runner registration token obtained from your repository's CI/CD settings
  • GitLab username and belonging Private Access Token
  • AWS Access Key ID and Secret Access Key

Usage

Before running any of the commands below, ensure the following environment variables are set and docker is running.

export AWS_ACCESS_KEY_ID="<YOUR AWS ACCESS KEY ID>"
export AWS_SECRET_ACCESS_KEY="<YOUR AWS SECRET ACCESS KEY>"
export GITLAB_PROJECT_ID="<YOUR GITLAB PROJECT ID>"
export GITLAB_USERNAME="<YOUR GITLAB USERNAME>"
export GITLAB_ACCESS_TOKEN="<YOUR GITLAB ACCESS TOKEN>"
export GITLAB_REGISTRATION_TOKEN="<GITLAB TOKEN FOR REGISTERING CI RUNNERS>"

If you would like to change the Grove environment's name, set the following in addition to the previous exports:

export GROVE_ENVIRONMENT="<YOUR ENVIRONMENT>"

Do not include grove as a prefix to your variables as it is automatically added by the terraform scripts. For example, setting GROVE_ENVIRONMENT="digitalocean-staging will create a grove-digitalocean-staging EC2 instance.

Initialize terraform

Before the first usage, terraform must be initialize. To initialize terraform, run:

# Change directory to the appropriate directory
cd ./gitlab-ci/aws-runners

# Initialize terraform
./scripts/terraform.sh init

Creating runners

To create GitLab runners on AWS, run the following within the gitlab-ci directory:

# Check the plan output before applying it
./scripts/terraform.sh plan

# Apply the plan if you find everything correct
./scripts/terraform.sh apply

Warning

There is an existing bug in the runner where the first run will fail with the error below. If encountered, run the terraform plan and apply again.

 Error: Error putting IAM role policy grove-kgaws-gitlab-runners-logging: NoSuchEntity: The role with name grove-name-gitlab-runners-instance cannot be found.
│       status code: 404, request id: c11ac2f9-5bef-41d8-96cc-97adff59ecf5
│
│   with module.gitlab-runner.aws_iam_role_policy.instance[0],
│   on .terraform/modules/gitlab-runner/logging.tf line 1, in resource "aws_iam_role_policy" "instance":
│    1: resource "aws_iam_role_policy" "instance" {

Destroying runners

To destroy runners, simple run the following within the gitlab-ci directory:

./scripts/terraform.sh destroy

Accessing runners

To access a runner for debugging purposes, you can use AWS Session Manager.