feat: add option to use a pre-registered Runner (#1115)

## Description

GitLab announced then [Next GitLab Runner Token
Architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/index.html#proposal).
Runners have to be registered manually.

This PR adds a new import parameter
`runner_gitlab.preregistered_runner_token_ssm_parameter_name` holding
the name of a SSM parameter (type: `SecuredString`). This parameter
contains the GitLab Runner token obtained from GitLab. All other
registration methods will still work, but have been marked as deprecated
and will be removed with
[v8.0.0](https://github.com/cattle-ops/terraform-aws-gitlab-runner/milestone/4)
end of the year.

This also solves the problems with Runners removed from GitLab at
shutdown, resulting in new Runners not able to start.

Closes #1074 and #1109 

## Verification

- [x] deployed the module using the new registration version. Runner is
online.
- [x] deployed the module using the old authentication schema. Runner is
online.

Author: kayman-mk

docs/usage.md

@@ -5,27 +5,22 @@ Common pitfalls are documented in [pitfalls.md](pitfalls.md).
 ## Configuration
 
 The examples are configured with defaults that should work in general. The examples are in general configured for the
-region Ireland `eu-west-1`. The only parameter that needs to be provided is the GitLab are the registration token and the
-URL of your GitLab instance. The token can be found in GitLab in the runner section (global, group or repo scope).
-Create a file `terraform.tfvars` and the registration token.
+region Ireland `eu-west-1`. The only parameter that needs to be provided is the name of a SSM parameter holding the Runner
+registration token and the URL of your GitLab instance. The Runner token is created in GitLab during the Runner registration process.
+Create a file `terraform.tfvars` and put the Runner registration token in the SSM parameter.
 
 ```hcl
-registration_token = "MY_TOKEN"
+preregistered_runner_token_ssm_parameter_name = "my-gitlab-runner-token-ssm-parameter-name"
 gitlab_url   = "https://my.gitlab.instance/"
 ```
 
 The base image used to host the GitLab Runner agent is the latest available Amazon Linux 2 HVM EBS AMI. In previous versions of
 this module a hard coded list of AMIs per region was provided. This list has been replaced by a search filter to find the latest
 AMI. Setting the filter to `amzn2-ami-hvm-2.0.20200207.1-x86_64-ebs` will allow you to version lock the target AMI if needed.
 
-> 💥  **If you are using GitLab >= 16.0.0**: `registration_token` will be deprecated!
-
->GitLab >= 16.0.0 has removed the `registration_token` since they are working on a [new token architecture](https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/). This module handle these changes, you need to provide a personal access token with `api` scope for the runner to authenticate itself.
-
->The workflow is as follows ([migration steps](https://github.com/cattle-ops/terraform-aws-gitlab-runner/pull/876)):
->1. The runner make an API call (with the access token) to create a new runner on GitLab depending on its type (`instance`, `group` or `project`).
->2. GitLab answers with a token prefixed by `glrt-` and we put it in SSM.
->3. The runner will get the config from `/etc/gitlab-runner/config.toml` and will listen for new jobs from your GitLab instance.
+The Runner uses a token to register with GitLab. This token is stored in the AWS SSM parameter store. The token has to be created
+manually in GitLab and stored in the SSM parameter store. All other registration methods are deprecated and will be removed in
+v8.0.0.
 
 ## Install the module
 
@@ -45,40 +40,7 @@ terraform destroy
 
 ## Scenarios
 
-### Scenario: Basic usage on GitLab **< 16.0.0**
-
-Below is a basic examples of usages of the module. Regarding the dependencies such as a VPC, have a look at the [default example](https://github.com/cattle-ops/terraform-aws-gitlab-runner/tree/main/examples/runner-default).
-
-```hcl
-module "runner" {
-  # https://registry.terraform.io/modules/cattle-ops/gitlab-runner/aws/
-  source  = "cattle-ops/gitlab-runner/aws"
-
-  environment = "basic"
-
-  vpc_id    = module.vpc.vpc_id
-  subnet_id = element(module.vpc.private_subnets, 0)
-
-  runner_gitlab = {
-    url = "https://gitlab.com"
-  }
-
-  runner_gitlab_registration_config = {
-    registration_token = "my-token"
-    tag_list           = "docker"
-    description        = "runner default"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
-  }
-
-  runner_worker_docker_machine_instance = {
-    subnet_ids = module.vpc.private_subnets
-  }
-}
-```
-
-### Scenario: Basic usage on GitLab **>= 16.0.0**
+### Scenario: Basic usage
 
 Below is a basic examples of usages of the module if your GitLab instance version is >= 16.0.0.
 
@@ -99,20 +61,9 @@ module "runner" {
    
   runner_gitlab = {
     url = "https://gitlab.com"
-    access_token_secure_parameter_store_name = "gitlab_access_token_ssm_name"
+     
+    preregistered_runner_token_ssm_parameter_name = "my-gitlab-runner-token-ssm-parameter-name"
   }
-   
-  runner_gitlab_registration_config = {
-    type               = "instance" # or "group" or "project"
-    # group_id           = 1234 # for "group"
-    # project_id         = 5678 # for "project"
-    tag_list           = "docker"
-    description        = "runner default"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
-  }
-
 }
 ```
 
@@ -135,15 +86,8 @@ module "runner" {
    
   runner_gitlab = {
     url = "https://gitlab.com"
-  }
-   
-  runner_gitlab_registration_config = {
-    registration_token = "my-token"
-    tag_list           = "docker"
-    description        = "runner default"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
+
+    preregistered_runner_token_ssm_parameter_name = "my-gitlab-runner-token-ssm-parameter-name"
   }
    
    runner_worker_cache = {
@@ -181,16 +125,9 @@ module "runner" {
 
   runner_gitlab = {
     url = "https://gitlab.com"
- }
 
-  runner_gitlab_registration_config = {
-    registration_token = "my-token"
-    tag_list           = "docker"
-    description        = "runner default"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
-  }
+    preregistered_runner_token_ssm_parameter_name = "my-gitlab-runner-token-ssm-parameter-name"
+ }
 
   runner_worker = {
     type = "docker+machine"
@@ -243,52 +180,6 @@ If a KMS key is set via `kms_key_id`, make sure that you also give proper access
 get errors, e.g. the build cache can't be decrypted or logging via CloudWatch is not possible. For a CloudWatch
 example checkout [kms-policy.json](https://github.com/cattle-ops/terraform-aws-gitlab-runner/blob/main/policies/kms-policy.json)
 
-### GitLab runner token configuration
-
-By default, the runner is registered on initial deployment. In previous versions of this module this was a manual process. The
-manual process is still supported but will be removed in future releases. The runner token will be stored in the AWS SSM parameter
-store. See [example](../examples/runner-pre-registered) for more details.
-
-To register the runner automatically set the variable `gitlab_runner_registration_config["registration_token"]`. This token value
-can be found in your GitLab project, group, or global settings. For a generic runner you can find the token in the admin section.
-By default, the runner will be locked to the target project and not run untagged jobs. Below is an example of the configuration map.
-
-```hcl
-runner_gitlab_registration_config = {
-  registration_token = "<registration token>"
-  tag_list           = "<your tags, comma separated>"
-  description        = "<some description>"
-  locked_to_project  = "true"
-  run_untagged       = "false"
-  maximum_timeout    = "3600"
-  # ref_protected runner will only run on pipelines triggered on protected branches. Defaults to not_protected
-  access_level       = "<not_protected OR ref_protected>"
-}
-```
-
-The registration token can also be read in via SSM parameter store. If no registration token is passed in, the module
-will look up the token in the SSM parameter store at the location specified by
-`runner_gitlab_registration_token_secure_parameter_store_name`.
-
-For migration to the new setup simply add the runner token to the parameter store. Once the runner is started it will look up the
-required values via the parameter store. If the value is `null` a new runner will be registered and a new token created/stored.
-
-```sh
-# set the following variables, look up the variables in your Terraform config.
-# see your Terraform variables to fill in the vars below.
-aws-region=<${var.aws_region}>
-token=<runner-token-see-your-gitlab-runner>
-parameter-name=<${var.environment}>-<${var.secure_parameter_store_runner_token_key}>
-
-aws ssm put-parameter --overwrite --type SecureString  --name "${parameter-name}" --value ${token} --region "${aws-region}"
-```
-
-Once you have created the parameter, you must remove the variable `runner_gitlab.registration_token` from your config. The next
-time your GitLab runner instance is created it will look up the token from the SSM parameter store.
-
-Finally, the runner still supports the manual runner creation. No changes are required. Please keep in mind that this setup will be
-removed in future releases.
-
 ### Auto Scaling Group
 
 #### Scheduled scaling

examples/runner-certificates/main.tf

@@ -42,6 +42,7 @@ module "vpc_endpoints" {
   }
 }
 
+
 module "runner" {
   source = "../../"
 
@@ -57,7 +58,9 @@ module "runner" {
   # Public cert of my company's gitlab instance
   # Other public certs relating to my company.
   runner_gitlab = {
-    url            = var.gitlab_url
+    url                                           = var.gitlab_url
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
+
     certificate    = file("${path.module}/my_gitlab_instance_cert.crt")
     ca_certificate = file("${path.module}/my_company_ca_cert_bundle.crt")
   }
@@ -74,18 +77,6 @@ module "runner" {
     ]
   }
 
-  ###############################################
-  # Registration
-  ###############################################
-  runner_gitlab_registration_config = {
-    registration_token = var.registration_token
-    tag_list           = "docker_runner"
-    description        = "runner docker - auto"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
-  }
-
   ###############################################
   # Network
   ###############################################

examples/runner-certificates/variables.tf

@@ -22,8 +22,7 @@ variable "gitlab_url" {
   default     = "https://gitlab.com"
 }
 
-variable "registration_token" {
-  description = "Gitlab runner registration token"
+variable "preregistered_runner_token_ssm_parameter_name" {
+  description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
   type        = string
-  default     = "something"
-}
+}

examples/runner-default/main.tf

@@ -67,15 +67,8 @@ module "runner" {
 
   runner_gitlab = {
     url = var.gitlab_url
-  }
 
-  runner_gitlab_registration_config = {
-    registration_token = var.registration_token
-    tag_list           = "docker_spot_runner"
-    description        = "runner default - auto"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
   }
 
   runner_worker_gitlab_pipeline = {

examples/runner-default/variables.tf

@@ -22,8 +22,8 @@ variable "gitlab_url" {
   default     = "https://gitlab.com"
 }
 
-variable "registration_token" {
-  description = "Registration token for the runner."
+variable "preregistered_runner_token_ssm_parameter_name" {
+  description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
   type        = string
 }
 

examples/runner-docker/main.tf

@@ -56,15 +56,8 @@ module "runner" {
 
   runner_gitlab = {
     url = var.gitlab_url
-  }
 
-  runner_gitlab_registration_config = {
-    registration_token = var.registration_token
-    tag_list           = "docker_runner"
-    description        = "runner docker - auto"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
   }
 
   runner_worker = {

examples/runner-docker/variables.tf

@@ -22,7 +22,7 @@ variable "gitlab_url" {
   default     = "https://gitlab.com"
 }
 
-variable "registration_token" {
-  description = "Registration token for the runner."
+variable "preregistered_runner_token_ssm_parameter_name" {
+  description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
   type        = string
 }

examples/runner-pre-registered/main.tf

@@ -54,8 +54,9 @@ module "runner" {
   }
 
   runner_gitlab = {
-    url                = var.gitlab_url
-    registration_token = var.runner_token
+    url = var.gitlab_url
+
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
   }
 
   # working 9 to 5 :)

examples/runner-pre-registered/variables.tf

@@ -20,8 +20,8 @@ variable "gitlab_url" {
   type        = string
 }
 
-variable "runner_token" {
-  description = "Token for the runner, will be used in the runner config.toml"
+variable "preregistered_runner_token_ssm_parameter_name" {
+  description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
   type        = string
 }
 

examples/runner-public/main.tf

@@ -42,16 +42,8 @@ module "runner" {
 
   runner_gitlab = {
     url = var.gitlab_url
-  }
 
-  runner_gitlab_registration_config = {
-    registration_token = var.registration_token
-    tag_list           = "docker_spot_runner"
-    description        = "runner public - auto"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
-    access_level       = "ref_protected"
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
   }
 
   runner_worker = {
@@ -89,15 +81,8 @@ module "runner2" {
 
   runner_gitlab = {
     url = var.gitlab_url
-  }
 
-  runner_gitlab_registration_config = {
-    registration_token = var.registration_token
-    tag_list           = "docker_spot_runner_2"
-    description        = "runner public - auto"
-    locked_to_project  = "true"
-    run_untagged       = "false"
-    maximum_timeout    = "3600"
+    preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
   }
 
   runner_worker_cache = {

examples/runner-public/variables.tf

@@ -22,7 +22,7 @@ variable "gitlab_url" {
   default     = "https://gitlab.com"
 }
 
-variable "registration_token" {
-  description = "Registration token for the runner."
+variable "preregistered_runner_token_ssm_parameter_name" {
+  description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
   type        = string
 }

main.tf

@@ -59,6 +59,7 @@ locals {
       post_install                                                 = var.runner_install.post_install_script
       runners_gitlab_url                                           = var.runner_gitlab.url
       runners_token                                                = var.runner_gitlab.registration_token
+      preregistered_runner_token_ssm_parameter_name                = var.runner_gitlab.preregistered_runner_token_ssm_parameter_name
       secure_parameter_store_gitlab_runner_registration_token_name = var.runner_gitlab_registration_token_secure_parameter_store_name
       secure_parameter_store_runner_token_key                      = local.secure_parameter_store_runner_token_key
       secure_parameter_store_runner_sentry_dsn                     = local.secure_parameter_store_runner_sentry_dsn