This repo contains a terraform module and example to run a GitLab CI multi runner on AWS Spot instances. See the blog post at 040code for a detailed description of the setup.

The setup is based on the blog post: Auto scale GitLab CI runners and save 90% on EC2 costs The created runner will have by default a shared cache in S3 and logging is streamed to CloudWatch. The cache in S3 will expire in X days, see configuration. The logging can be disabled.

Ensure you have Terraform installed, see .terraform-version for the used version. A handy tool to mange your terraform version is tfenv.

On mac simple install tfenv using brew.

brew install tfenv

Next install a terraform version.

tfenv install <version>

To run the terraform scripts you need to have AWS keys. Example file:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

The gitlab runner ec2 instance needs the following sercice linked roles:

• AWSServiceRoleForAutoScaling
• AWSServiceRoleForEC2Spot

By default the ec2 instance is allowed to create the roles, by setting the option allow_iam_service_linked_role_creation to false you can deny the creation of roles by the instance. In that case you have to ensure the roles exists. You can create them manually or via terraform.

resource "aws_iam_service_linked_role" "spot" {
  aws_service_name = "spot.amazonaws.com"
}

resource "aws_iam_service_linked_role" "autoscaling" {
  aws_service_name = "autoscaling.amazonaws.com"
}

Currently register a new runner is a manual process. See the GitLab Runner documentation for more details.

docker run -it --rm gitlab/gitlab-runner register

Provide the details in the interactive terminal. Once done the token can be found in the GitLab runners section, choose edit to get the token or see the config.toml file.

Update the variables in terraform.tfvars to your needs and add the following variables, see previous step for how to obtain the token.

runner_name  = "NAME_OF_YOUR_RUNNER"
gitlab_url   = "GIT_LAB_URL"
runner_token  = "RUNNER_TOKEN"

module "gitlab-runner" {
  source = "npalm/gitlab-runner/aws"
  version = "1.0.0"

  aws_region              = "${var.aws_region}"
  environment             = "${var.environment}"
  ssh_public_key          = "${file("${var.ssh_key_file}")}"

  vpc_id                  = "${module.vpc.vpc_id}"
  subnet_id_gitlab_runner = "${element(module.vpc.private_subnets, 0)}"
  subnet_id_runners       = "${element(module.vpc.private_subnets, 0)}"

  runners_name            = "${var.runner_name}"
  runners_gitlab_url      = "${var.gitlab_url}"
  runners_token           = "${var.runner_token}"
}

All variables and defaults:

An example is provided, execute the following steps to run the sample. Ensure your AWS and Terraform environment is set up correctly. All commands below are supposed to be run inside the directory example.

Keys are generated by terraform and stored in a directory generated in the example directory.

Register a new runner:

docker run -it --rm gitlab/gitlab-runner register

Once done, lookup the token in GitLab and update the terraform.tfvars file.

Run terraform init to initialize terraform. Next you can run terraform plan to inspect the resources that will be created.

To create the runner run:

terraform apply

To destroy runner:

terraform destroy