refactor!: group variables for better overview (#810)

Groups variables into objects to
- reduce the number of variables (currently 118)
- to gain a better overview of all configuration settings

Creates new groups of variables:
- `runner_manager` in case it configures the "main" process which sets
the defaults for all runners
- `runner` in case it configures the runner created by the runner
manager
- `runner_worker` in case it configures the docker/docker+machine or
leave it as it is, if it is a global scope, e.g. common tags, the
environment, ...

Yes and a script is provided to do that. It covers 98% of all migrations
(see migrations/migrate-to-7-0-0.sh)

Please mention the examples you have verified.

---------

Co-authored-by: Tyrone Meijn <[email protected]>

Author: kayman-mk

.cspell.json

@@ -18,9 +18,13 @@
     "codeowners",
     "companys",
     "concat",
+    "cpu",
+    "cpus",
+    "cpuset",
     "devskim",
     "dind",
     "endfor",
+    "filesha",
     "formatlist",
     "gitter",
     "glrunners",
@@ -45,6 +49,8 @@
     "stretchr",
     "subkey",
     "substr",
+    "sysctl",
+    "sysctls",
     "templatefile",
     "terrascan",
     "terratest",
@@ -58,7 +64,9 @@
     "trivy",
     "typecheck",
     "userdata",
-    "xanzy"
+    "userns",
+    "xanzy",
+    "xvda"
   ],
   "flagWords": []
 }

.github/workflows/ci.yml

@@ -137,7 +137,8 @@ jobs:
         run: tflint --init
 
       - name: Run TFLint
-        run: tflint --var 'enable_kms=true'
+        # assign necessary variables to avoid errors
+        run: "tflint --var 'enable_kms=true' --var='runner_instance={\"name_prefix\": \"a\", \"name\": \"b\"}'"
 
   tfsec:
     name: tfsec PR commenter

.mega-linter.yml

@@ -4,6 +4,8 @@ DISABLE_LINTERS:
   - TERRAFORM_TFLINT
   # Super slow linter, but useful. We disable it here and run it in parallel to Megalinter saves some minutes.
   - REPOSITORY_KICS
+  # has issues with the Terraform code `optional` variable definitions: https://github.com/tenable/terrascan/issues/1532
+  - TERRAFORM_TERRASCAN
   # Nice linter to report CVEs and other cool stuff. But it reports problems with the Terraform code which can't be disabled by
   # configuration.
   - REPOSITORY_TRIVY

README.md

@@ -386,13 +386,12 @@ module "runner" {
 
 Since spot instances can be taken over by AWS depending on the instance type and AZ you are using, you may want multiple instances
 types in multiple AZs. This is where spot fleets come in, when there is no capacity on one instance type and one AZ, AWS will take
-the next instance type and so on. This update has been possible since the [fork](https://gitlab.com/cki-project/docker-machine/-/tree/v0.16.2-gitlab.19-cki.2)
-of docker-machine supports spot fleets.
+the next instance type and so on. This update has been possible since the
+[fork](https://gitlab.com/cki-project/docker-machine/-/tree/v0.16.2-gitlab.19-cki.2) of docker-machine supports spot fleets.
 
 We have seen that the [fork](https://gitlab.com/cki-project/docker-machine/-/tree/v0.16.2-gitlab.19-cki.2) of docker-machine this
-module is using consume more RAM using spot fleets.
-For comparison, if you launch 50 machines in the same time, it consumes ~1.2GB of RAM. In our case, we had to change the
-`instance_type` of the runner from `t3.micro` to `t3.small`.
+module is using consume more RAM using spot fleets. For comparison, if you launch 50 machines in the same time, it consumes
+~1.2GB of RAM. In our case, we had to change the `instance_type` of the runner from `t3.micro` to `t3.small`.
 
 #### Configuration example
 

examples/runner-certificates/README.md

@@ -32,20 +32,24 @@ Create a PEM-encoded `.crt` file containing the public certificate of your Gitla
 
 ```hcl
 module {
-  ...
+  # ...
   # Public cert of my companys gitlab instance
-  runners_gitlab_certificate = file("${path.module}/my_gitlab_instance_cert.crt")
-  ...
+  runner_gitlab = {
+    certificate = file("${path.module}/my_gitlab_instance_cert.crt")
+  }  
+  # ...
 }
 ```
 
 Add your CA and intermediary certs to a second PEM-encoded `.crt` file.
 ```hcl
 module {
-  ...
+  # ...
   # Other public certs relating to my company.
-  runners_ca_certificate = file("${path.module}/my_company_ca_cert_bundle.crt")
-  ...
+  runner_gitlab = {
+    ca_certificate = file("${path.module}/my_company_ca_cert_bundle.crt")
+  }
+  # ...
 }
 ```
 
@@ -58,15 +62,17 @@ For **user images**, you must:
     The runner module can be configured to do this step. Configure the module like so:
 
     ```terraform
-    module {
+    module "runner" {
       # ...
       
       # Mount EC2 host certs in docker so all user docker images can reference them.
-      runners_additional_volumes = ["/etc/gitlab-runner/certs/:/etc/gitlab-runner/certs:ro"]
-      
-        # ...
+      runner_worker_docker_options = {
+        volumes = ["/etc/gitlab-runner/certs/:/etc/gitlab-runner/certs:ro"]
       }
-      ```
+      
+      # ...
+    }
+    ```
       
 2. Trust the certificates from within the user image.
   
@@ -107,17 +113,18 @@ For **user images**, you must:
     This avoids maintaining the script in each pipeline file, but expects that all user images use the same OS.
     
     ```terraform
-    module {
+    module "runner" {
       # ...
     
-      runners_pre_build_script = <<EOT
-      '''
-      apt-get install -y ca-certificates
-      cp /etc/gitlab-runner/certs/* /usr/local/share/ca-certificates/
-      update-ca-certificates
-      '''
-      EOT
-    
+      runner_worker_gitlab_pipeline = {
+        pre_build_script = <<EOT
+        '''
+        apt-get install -y ca-certificates
+        cp /etc/gitlab-runner/certs/* /usr/local/share/ca-certificates/
+        update-ca-certificates
+        '''
+        EOT
+      }
       # ...
     }
     ```

examples/runner-certificates/main.tf

@@ -27,31 +27,26 @@ module "runner" {
   ###############################################
   # General
   ###############################################
-
-  runners_name       = var.runner_name
-  runners_gitlab_url = var.gitlab_url
-
-  runners_executor = "docker"
-
-  aws_region  = var.aws_region
   environment = var.environment
 
   ###############################################
   # Certificates
   ###############################################
 
   # Public cert of my companys gitlab instance
-  runners_gitlab_certificate = file("${path.module}/my_gitlab_instance_cert.crt")
-
   # Other public certs relating to my company.
-  runners_ca_certificate = file("${path.module}/my_company_ca_cert_bundle.crt")
+  runner_gitlab = {
+    url            = var.gitlab_url
+    certificate    = file("${path.module}/my_gitlab_instance_cert.crt")
+    ca_certificate = file("${path.module}/my_company_ca_cert_bundle.crt")
+  }
 
   # Mount EC2 host certs in docker so all user docker images can reference them.
   # Each user image will need to do:
   # cp /etc/gitlab-runner/certs/* /usr/local/share/ca-certificates/
   # update-ca-certificates
   # Or similar OS-dependent commands. The above are an example for Ubuntu.
-  runners_docker_options = {
+  runner_worker_docker_options = {
     volumes = [
       "/cache",
       "/etc/gitlab-runner/certs/:/etc/gitlab-runner/certs:ro"
@@ -61,8 +56,7 @@ module "runner" {
   ###############################################
   # Registration
   ###############################################
-
-  gitlab_runner_registration_config = {
+  runner_gitlab_registration_config = {
     registration_token = var.registration_token
     tag_list           = "docker_runner"
     description        = "runner docker - auto"
@@ -76,5 +70,11 @@ module "runner" {
   ###############################################
   vpc_id    = module.vpc.vpc_id
   subnet_id = element(module.vpc.public_subnets, 0)
+  runner_instance = {
+    name = var.runner_name
+  }
 
+  runner_worker = {
+    type = "docker"
+  }
 }

examples/runner-default/main.tf

@@ -50,22 +50,26 @@ module "vpc_endpoints" {
 module "runner" {
   source = "../../"
 
-  aws_region  = var.aws_region
   environment = var.environment
 
-  vpc_id              = module.vpc.vpc_id
-  subnet_id           = element(module.vpc.private_subnets, 0)
-  metrics_autoscaling = ["GroupDesiredCapacity", "GroupInServiceCapacity"]
+  vpc_id    = module.vpc.vpc_id
+  subnet_id = element(module.vpc.private_subnets, 0)
 
-  runners_name             = var.runner_name
-  runners_gitlab_url       = var.gitlab_url
-  enable_runner_ssm_access = true
+  runner_instance = {
+    collect_autoscaling_metrics = ["GroupDesiredCapacity", "GroupInServiceCapacity"]
+    name                        = var.runner_name
+    ssm_access                  = true
+  }
 
-  gitlab_runner_security_group_ids = [data.aws_security_group.default.id]
+  runner_networking = {
+    allow_incoming_ping_security_group_ids = [data.aws_security_group.default.id]
+  }
 
-  docker_machine_spot_price_bid = "on-demand-price"
+  runner_gitlab = {
+    url = var.gitlab_url
+  }
 
-  gitlab_runner_registration_config = {
+  runner_gitlab_registration_config = {
     registration_token = var.registration_token
     tag_list           = "docker_spot_runner"
     description        = "runner default - auto"
@@ -74,27 +78,37 @@ module "runner" {
     maximum_timeout    = "3600"
   }
 
-  tags = {
-    "tf-aws-gitlab-runner:example"           = "runner-default"
-    "tf-aws-gitlab-runner:instancelifecycle" = "spot:yes"
+  runner_worker_gitlab_pipeline = {
+    pre_build_script  = <<EOT
+        '''
+        echo 'multiline 1'
+        echo 'multiline 2'
+        '''
+        EOT
+    post_build_script = "\"echo 'single line'\""
   }
 
-  runners_volumes_tmpfs = [
+  runner_worker_docker_options = {
+    privileged = "true"
+    volumes    = ["/cache", "/certs/client"]
+  }
+
+  runner_worker_docker_volumes_tmpfs = [
     {
       volume  = "/var/opt/cache",
       options = "rw,noexec"
     }
   ]
 
-  runners_services_volumes_tmpfs = [
+  runner_worker_docker_services_volumes_tmpfs = [
     {
       volume  = "/var/lib/mysql",
       options = "rw,noexec"
     }
   ]
 
-  # working 9 to 5 :)
-  runners_machine_autoscaling_options = [
+  runner_worker_docker_machine_autoscaling_options = [
+    # working 9 to 5 :)
     {
       periods    = ["* * 0-9,17-23 * * mon-fri *", "* * * * * sat,sun *"]
       idle_count = 0
@@ -103,20 +117,11 @@ module "runner" {
     }
   ]
 
-  runners_docker_options = {
-    privileged = "true"
-    volumes    = ["/cache", "/certs/client"]
+  tags = {
+    "tf-aws-gitlab-runner:example"           = "runner-default"
+    "tf-aws-gitlab-runner:instancelifecycle" = "spot:yes"
   }
 
-  runners_pre_build_script = <<EOT
-  '''
-  echo 'multiline 1'
-  echo 'multiline 2'
-  '''
-  EOT
-
-  runners_post_build_script = "\"echo 'single line'\""
-
   # Uncomment the HCL code below to configure a docker service so that registry mirror is used in auto-devops jobs
   # See https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27171 and https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#the-service-in-the-gitlab-runner-configuration-file
   # You can check this works with a CI job like:
@@ -141,7 +146,7 @@ module "runner" {
   #
   # If not using an official docker image for your job, you may need to specify `DOCKER_HOST: tcp://docker:2375`
   ## UNCOMMENT 6 LINES BELOW
-  # runners_docker_services = [{
+  # runner_worker_docker_services = [{
   #   name       = "docker:20.10.16-dind"
   #   alias      = "docker"
   #   command    = ["--registry-mirror", "https://mirror.gcr.io"]
@@ -151,7 +156,8 @@ module "runner" {
 
   # Example how to configure runners, to utilize EC2 user-data feature
   # example template, creates (configurable) swap file for the runner
-  # runners_userdata = templatefile("${path.module}/../../templates/swap.tpl", {
-  #   swap_size = "512"
-  # })
+  # runner_worker_docker_machine_instance = {
+  #   start_script = templatefile("${path.module}/../../templates/swap.tpl", {
+  # swap_size = "512"
+  # }
 }

examples/runner-docker/main.tf

@@ -41,28 +41,39 @@ module "vpc_endpoints" {
 module "runner" {
   source = "../../"
 
-  aws_region  = var.aws_region
+  vpc_id      = module.vpc.vpc_id
+  subnet_id   = element(module.vpc.public_subnets, 0)
   environment = var.environment
 
-  runners_use_private_address = false
-  enable_eip                  = true
-
-  docker_machine_security_group_description = "Custom description for docker-machine"
-  gitlab_runner_security_group_description  = "Custom description for gitlab-runner"
+  runner_instance = {
+    runner_use_eip = true
+    name           = var.runner_name
+  }
 
-  vpc_id    = module.vpc.vpc_id
-  subnet_id = element(module.vpc.public_subnets, 0)
+  runner_networking = {
+    security_group_description = "Custom description for gitlab-runner"
+  }
 
-  runners_executor   = "docker"
-  runners_name       = var.runner_name
-  runners_gitlab_url = var.gitlab_url
+  runner_gitlab = {
+    url = var.gitlab_url
+  }
 
-  gitlab_runner_registration_config = {
+  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"
   }
+
+  runner_worker = {
+    type = "docker"
+  }
+
+  runner_worker_docker_machine_instance = {
+    private_address_only = false
+  }
+
+  runner_worker_docker_machine_security_group_description = "Custom description for docker-machine"
 }