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:

   HCL Copy to clipboard

   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
     min_support        = "experimental"
   }

4. Initialize and apply the module:

   Copy to clipboard

   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.

Support levels and the min_support parameter

You must provide a min_support value for all GRIT modules. This parameter specifies the minimum support level that the operator requires for their deployment. GRIT modules are associated with a support designation of none, experimental, beta, or GA. The goal is for all modules to reach the GA status.

none is a special case. Modules with no support guarantees, primarily for testing and development.

experimental, beta, and ga modules conform to the GitLab definitions of development stages.

Shared responsibility model

GRIT operates under a shared responsibility model between Authors (module developers) and Operators (those deploying with GRIT). For details on the specific responsibilities of each role and how support levels are determined, see the Shared responsibility section in the GORP documentation.

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:

   HCL Copy to clipboard

   terraform {
     backend "http" {}
   }

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

   YAML Copy to clipboard

   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

Contributing to GRIT

GRIT welcomes community contributions. Before contributing, review the following resources:

Developer Certificate of Origin and license

All contributions to GRIT are subject to the Developer Certificate of Origin and license. By contributing, you accept and agree to these terms and conditions for your present and future contributions submitted to GitLab Inc.

Code of Conduct

GRIT follows the GitLab Code of Conduct, which is adapted from the Contributor Covenant. The project is committed to making participation a harassment-free experience for everyone, regardless of background or identity.

Contribution guidelines

When contributing to GRIT, follow these guidelines:

• Review the GORP Guidelines for overall architectural design.
• Adhere to Google’s best practices for using Terraform.
• Follow the composable module approach to reduce complexity and repetition.
• Include appropriate Go tests for your contributions.

Testing and linting

GRIT uses several testing and linting tools to ensure quality:

• Integration tests: Uses Terratest to validate Terraform plans.
• End-to-end tests: Available in the e2e directory.
• Terraform linting: Uses tflint, terraform fmt, and terraform validate.
• Go linting: Uses golangci-lint for Go code (primarily tests).
• Documentation: Follows the GitLab documentation style guide and uses vale and markdownlint.

For detailed instructions on setting up your development environment, running tests, and linting, see CONTRIBUTING.md.