Docs: Tutorial: Automate runner creation and registration

Problem to solve

The blog https://about.gitlab.com/blog/2023/07/06/how-to-automate-creation-of-runners/ provides useful information about how to automate the creation and registration of runners with authentication tokens. This should be adapted into a tutorial in the docs site so that it is more discoverable by users and to ensure that the information in it is maintained.

Sections/steps

Intro

Intro to provide context and use case. In what scenario would this setup be useful for a user?

  • Flexibility to configure a runner fleet at scale while ensuring that you can still easily understand and manage the fleet in the GitLab Runners view.
  • Replaces legacy runner registration workflow.
  • Provides more security.

Prerequisites

  • GitLab Runner installed on instance.
  • Administrator role.

Steps

  1. Create a personal access token.
  2. Use the access token to create a runner in the GitLab instance.
    • user/runners POST REST endpoint.
    • view the newly created runner configuration in the GitLab UI.
  3. Reuse the runner authentication token to register multiple runners.
  4. View runners in the runners list (runners created with the same token are grouped).
    • Each runner in the group is uniquely identified by their system_id.
  5. Automate runner registration:
    1. Use Terraform infrastructure as code to install the runner application to a virtual machine hosted on GCP.
    2. Use the GCP Terraform provider and specifically the metadata key to automatically add the runner authentication token to the runner configuration file on the newly created GCP virtual machine.
    3. Register the newly installed runner with the target GitLab instance using a cloud-init script populated from the GCP terraform provider. For example:
#!/bin/bash
apt update
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name -H "Metadata-Flavor:Google")
GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/gl_executor -H "Metadata-Flavor:Google")
apt update
apt install -y gitlab-runner
gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com" --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR" --docker-image="alpine:latest"
systemctl restart gitlab-runner

Concepts the user should understand after the tutorial

  • Reusable runner configurations:
    • runners created with the same token will be grouped in the runners list.
    • "For example, if you have to deploy multiple runners at the instance level, each with the same configuration (executor type, tags, etc.), you simply create a runner and configuration once, then register each individual runner with the same authentication token that you retrieved from the first runner creation. Each of these runners is now displayed in the UI in a nested hierarchy."
  • Runner authentication tokens.

Who can address the issue

TW for grouprunner with input from engineering.

Other links/references

#387993 (comment 1495684352)

Edited by Fiona Neill