Untitled :: Vector Digital Platforms Documentation

module-base-gitlab-runner-manager

This module creates a GitLab CI Runner Manager. The module will spawn a single EC2 node in a self-healing AutoScaling Group and runners will be spawned by docker-machine using spot instances. Runners will scale automatically based on the configuration. The module also creates by default a S3 cache bucket that is shared across spot instances runners.

Usage examples

Simple example

module "gitlab_runners" {
  source = "git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/compute/module-base-gitlab-runner-manager.git?ref=vX.Y.Z"

  vpc_id      = var.vpc_id
  vpc_subnets = var.vpc_subnets

  runners_name      = "aws-spot-runners"
  gitlab_server_url = "https://gitlab.com"

  gitlab_runner_registration_config = {
    registration_token = "abc123xxx456def"
    tag_list           = "tag1,tag2"
    description        = "AWS AutoScaled Spot GitLab Runners"
    locked_to_project  = "false"
    run_untagged       = "true"
    maximum_timeout    = "3600"
  }

  tags = {
    Project     = "project_name"
    Environment = "environment_name"
  }
}

Complex example

module "gitlab_runners" {
  source = "git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/compute/module-base-gitlab-runner-manager.git?ref=vX.Y.Z"

  vpc_id      = var.vpc_id
  vpc_subnets = var.vpc_subnets

  runners_name      = "aws-spot-runners"
  gitlab_server_url = "https://gitlab.com"

  gitlab_runner_registration_config = {
    registration_token = "abc123xxx456def"
    tag_list           = "tag1,tag2"
    description        = "AWS AutoScaled Spot GitLab Runners"
    locked_to_project  = "false"
    run_untagged       = "true"
    maximum_timeout    = "3600"
  }

  runners_limit: 20
  runners_concurrent: 20
  runners_idle_time: 600
  runners_idle_count: 1

  runners_off_peak_timezone: "Europe/Madrid"
  runners_off_peak_periods: "[\"* * 0-9,17-23 * * mon-fri *\", \"* * * * * sat,sun *\"]"
  runners_off_peak_idle_count: 0
  runners_off_peak_idle_time: 60

  runners_instance_type: "m5.large"
  runners_spot_price_bid: "0.035"
  runners_root_size: 20
  runners_request_concurrency: 20
  runners_output_limit: 524288

  runners_cache_enabled: true
  runners_cache_expiration_days: 7

  tags = {
    Project     = "project_name"
    Environment = "environment_name"
  }
}

Module argument reference

Modules

Name	Source	Version
asg	git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/compute/module-base-asg.git	v0.1.0
sg_manager	git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/networking/module-base-sg.git	v0.2.2
sg_runner	git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/networking/module-base-sg.git	v0.2.2

Name

Source

Version

asg

git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/compute/module-base-asg.git

v0.1.0

sg_manager

git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/networking/module-base-sg.git

v0.2.2

sg_runner

git::https://gitlab.vectoritcgroup.com/vectordigital/iac/terraform/modules/aws/networking/module-base-sg.git

v0.2.2

Resources

Name	Type
aws_cloudwatch_log_group.this	resource
aws_iam_instance_profile.manager	resource
aws_iam_instance_profile.runners	resource
aws_iam_policy.cache	resource
aws_iam_policy.logging	resource
aws_iam_policy.manager	resource
aws_iam_policy.slr	resource
aws_iam_policy.ssm	resource
aws_iam_policy.ssm-param-store	resource
aws_iam_role.manager	resource
aws_iam_role.runners	resource
aws_iam_role_policy_attachment.cache	resource
aws_iam_role_policy_attachment.logging	resource
aws_iam_role_policy_attachment.manager	resource
aws_iam_role_policy_attachment.slr	resource
aws_iam_role_policy_attachment.ssm	resource
aws_iam_role_policy_attachment.ssm-managed	resource
aws_iam_role_policy_attachment.ssm-param-store	resource
aws_kms_key.this	resource
aws_s3_bucket.cache	resource
aws_ssm_parameter.runner_registration_token	resource
aws_ami.manager	data source
aws_ami.runners	data source
aws_caller_identity.current	data source

Name

Type

aws_cloudwatch_log_group.this

resource

aws_iam_instance_profile.manager

resource

aws_iam_instance_profile.runners

resource

aws_iam_policy.cache

resource

aws_iam_policy.logging

resource

aws_iam_policy.manager

resource

aws_iam_policy.slr

resource

aws_iam_policy.ssm

resource

aws_iam_policy.ssm-param-store

resource

aws_iam_role.manager

resource

aws_iam_role.runners

resource

aws_iam_role_policy_attachment.cache

resource

aws_iam_role_policy_attachment.logging

resource

aws_iam_role_policy_attachment.manager

resource

aws_iam_role_policy_attachment.slr

resource

aws_iam_role_policy_attachment.ssm

resource

aws_iam_role_policy_attachment.ssm-managed

resource

aws_iam_role_policy_attachment.ssm-param-store

resource

aws_kms_key.this

resource

aws_s3_bucket.cache

resource

aws_ssm_parameter.runner_registration_token

resource

aws_ami.manager

data source

aws_ami.runners

data source

aws_caller_identity.current

data source

Inputs

Name Description Type Default Required

Name	Description	Type	Default	Required
aws_region	AWS Region name	`string`	n/a	yes
gitlab_runner_registration_config	Configuration used to register the runner. See the README for an example, or reference the examples in the examples directory of this repo.	`map(string)`	`{ "access_level": "", "description": "", "locked_to_project": "", "maximum_timeout": "", "registration_token": "", "run_untagged": "", "tag_list": "" }`	no
gitlab_server_url	URL of the gitlab instance to connect to.	`string`	n/a	yes
manager_docker_machine_options	List of additional options for the docker machine config. Each element of this list must be a key=value pair. E.g. '["amazonec2-zone=a"]'	`list(string)`	`[]`	no
manager_docker_machine_version	Version of the docker-machine package to install in the Gitlab Runner Manager instance	`string`	`"0.16.2"`	no
manager_executor_type	The executor to use in the Gitlab Runner Manager. It can be `docker+machine` or `docker`	`string`	`"docker+machine"`	no
manager_logging_enabled	Boolean used to enable or disable the CloudWatch logging.	`bool`	`true`	no
manager_logging_kms_enabled	Let the module manage a KMS key, logs will be encrypted via KMS. Be-aware of the costs of an custom key.	`bool`	`false`	no
manager_logging_kms_key_id	KMS key id to encrypted the CloudWatch logs. Ensure CloudWatch has access to the provided KMS key.	`string`	`""`	no
manager_logging_kms_rotation_days	Key rotation window, set to 0 for no rotation. Only used when `logging_kms_enabled` is set to `true`.	`number`	`7`	no
manager_logging_retention_days	Retention for cloudwatch logs. Defaults to unlimited	`number`	`0`	no
manager_runner_version	Version of the Gitlab Runner to be installed the Gitlab Runner Manager instance	`string`	`"12.8.0"`	no
manager_userdata_post_install	User-data script snippet to insert after GitLab Runner Manager installation	`string`	`""`	no
manager_userdata_pre_install	User-data script snippet to insert before GitLab Runner Manager installation	`string`	`""`	no
name	The service name	`string`	`"gitlab-runner-manager"`	no
prefix	The prefix to be attached to every resource name	`string`	n/a	yes
runners_additional_volumes	Additional volumes that will be used in the runner config.toml, e.g Docker socket	`list(string)`	`[]`	no
runners_ami_filter	List of maps used to create the AMI filter for the Gitlab Runner AMI	`map(list(string))`	`{ "name": [ "ubuntu/images/hvm-ssd/ubuntu-bionic-18.04-amd64-server-*" ] }`	no
runners_ami_owners	The list of owners used to select the AMI of Gitlab Runner instance.	`list(string)`	`[ "099720109477" ]`	no
runners_cache_enabled	Wether or not to create an S3 bucket for storing Gitlab Runners cache	`bool`	`true`	no
runners_cache_expiration_days	Number of days before the Gitlab Runners cache objects expires	`number`	`1`	no
runners_concurrent	Concurrent value for the runners, will be used in the runner config.toml.	`number`	`10`	no
runners_environment_vars	Environment variables during build execution, e.g. KEY=Value, see runner-public example. Will be used in the runner config.toml	`list(string)`	`[]`	no
runners_executor	The executor to use. Currently supports `docker+machine` or `docker`.	`string`	`"docker+machine"`	no
runners_iam_instance_profile_name	IAM instance profile name of the runners, will be used in the runner config.toml	`string`	`""`	no
runners_idle_count	Idle count of the runners, will be used in the runner config.toml.	`number`	`0`	no
runners_idle_time	Idle time of the runners, will be used in the runner config.toml.	`number`	`1800`	no
runners_image	Image to run builds, will be used in the runner config.toml	`string`	`"docker:19.03.1"`	no
runners_instance_type	Instance type used for the instances hosting docker-machine.	`string`	`"t3.large"`	no
runners_limit	Limit for the runners, will be used in the runner config.toml.	`number`	`0`	no
runners_max_builds	Max builds for each runner after which it will be removed, will be used in the runner config.toml. By default set to 0, no maxBuilds will be set in the configuration.	`number`	`0`	no
runners_name	Name of the runner, will be used in the runner config.toml.	`string`	n/a	yes
runners_off_peak_idle_count	Off peak idle count of the runners, will be used in the runner config.toml.	`number`	`0`	no
runners_off_peak_idle_time	Off peak idle time of the runners, will be used in the runner config.toml.	`number`	`0`	no
runners_off_peak_periods	Off peak periods of the runners, will be used in the runner config.toml.	`string`	`""`	no
runners_off_peak_timezone	Off peak idle time zone of the runners, will be used in the runner config.toml.	`string`	`""`	no
runners_output_limit	Sets the maximum build log size in kilobytes	`number`	`524288`	no
runners_privileged	Runners will run in privileged mode, will be used in the runner config.toml	`bool`	`true`	no
runners_pull_policy	pull_policy for the runners, will be used in the runner config.toml	`string`	`"always"`	no
runners_request_concurrency	Limit number of concurrent requests for new jobs from GitLab	`number`	`20`	no
runners_request_spot_instance	Whether or not to request spot instances via docker-machine	`bool`	`true`	no
runners_root_size	Runner instance root size in GB.	`number`	`16`	no
runners_shm_size	shm_size for the runners, will be used in the runner config.toml	`number`	`0`	no
runners_spot_price_bid	Spot price bid.	`string`	`"0.03"`	no
runners_token	Token for the runner, will be used in the runner config.toml.	`string`	`"REPLACED_BY_USER_DATA"`	no
tags	Specific tags for all module resources	`map(string)`	n/a	yes
vpc_id	The VPC ID of the VPC used to deploy the Gitlab Runner Manager	`string`	n/a	yes
vpc_subnets	A list of subnets where the Gitlab Runner Manager ASG will be deployed	`list(string)`	n/a	yes

aws_region

AWS Region name

string

n/a

yes

gitlab_runner_registration_config

Configuration used to register the runner. See the README for an example, or reference the examples in the examples directory of this repo.

map(string)

{
  "access_level": "",
  "description": "",
  "locked_to_project": "",
  "maximum_timeout": "",
  "registration_token": "",
  "run_untagged": "",
  "tag_list": ""
}

gitlab_server_url

URL of the gitlab instance to connect to.

string

n/a

yes

manager_docker_machine_options

List of additional options for the docker machine config. Each element of this list must be a key=value pair. E.g. '["amazonec2-zone=a"]'

list(string)

[]

manager_docker_machine_version

Version of the docker-machine package to install in the Gitlab Runner Manager instance

string

"0.16.2"

manager_executor_type

The executor to use in the Gitlab Runner Manager. It can be docker+machine or docker

string

"docker+machine"

manager_logging_enabled

Boolean used to enable or disable the CloudWatch logging.

bool

true

manager_logging_kms_enabled

Let the module manage a KMS key, logs will be encrypted via KMS. Be-aware of the costs of an custom key.

bool

false

manager_logging_kms_key_id

KMS key id to encrypted the CloudWatch logs. Ensure CloudWatch has access to the provided KMS key.

string

""

manager_logging_kms_rotation_days

Key rotation window, set to 0 for no rotation. Only used when logging_kms_enabled is set to true.

number

7

manager_logging_retention_days

Retention for cloudwatch logs. Defaults to unlimited

number

0

manager_runner_version

Version of the Gitlab Runner to be installed the Gitlab Runner Manager instance

string

"12.8.0"

manager_userdata_post_install

User-data script snippet to insert after GitLab Runner Manager installation

string

""

manager_userdata_pre_install

User-data script snippet to insert before GitLab Runner Manager installation

string

""

name

The service name

string

"gitlab-runner-manager"

prefix

The prefix to be attached to every resource name

string

n/a

yes

runners_additional_volumes

Additional volumes that will be used in the runner config.toml, e.g Docker socket

list(string)

[]

runners_ami_filter

List of maps used to create the AMI filter for the Gitlab Runner AMI

map(list(string))

{
  "name": [
    "ubuntu/images/hvm-ssd/ubuntu-bionic-18.04-amd64-server-*"
  ]
}

runners_ami_owners

The list of owners used to select the AMI of Gitlab Runner instance.

list(string)

[
  "099720109477"
]

runners_cache_enabled

Wether or not to create an S3 bucket for storing Gitlab Runners cache

bool

true

runners_cache_expiration_days

Number of days before the Gitlab Runners cache objects expires

number

1

runners_concurrent

Concurrent value for the runners, will be used in the runner config.toml.

number

10

runners_environment_vars

Environment variables during build execution, e.g. KEY=Value, see runner-public example. Will be used in the runner config.toml

list(string)

[]

runners_executor

The executor to use. Currently supports docker+machine or docker.

string

"docker+machine"

runners_iam_instance_profile_name

IAM instance profile name of the runners, will be used in the runner config.toml

string

""

runners_idle_count

Idle count of the runners, will be used in the runner config.toml.

number

0

runners_idle_time

Idle time of the runners, will be used in the runner config.toml.

number

1800

runners_image

Image to run builds, will be used in the runner config.toml

string

"docker:19.03.1"

runners_instance_type

Instance type used for the instances hosting docker-machine.

string

"t3.large"

runners_limit

Limit for the runners, will be used in the runner config.toml.

number

0

runners_max_builds

Max builds for each runner after which it will be removed, will be used in the runner config.toml. By default set to 0, no maxBuilds will be set in the configuration.

number

0

runners_name

Name of the runner, will be used in the runner config.toml.

string

n/a

yes

runners_off_peak_idle_count

Off peak idle count of the runners, will be used in the runner config.toml.

number

0

runners_off_peak_idle_time

Off peak idle time of the runners, will be used in the runner config.toml.

number

0

runners_off_peak_periods

Off peak periods of the runners, will be used in the runner config.toml.

string

""

runners_off_peak_timezone

Off peak idle time zone of the runners, will be used in the runner config.toml.

string

""

runners_output_limit

Sets the maximum build log size in kilobytes

number

524288

runners_privileged

Runners will run in privileged mode, will be used in the runner config.toml

bool

true

runners_pull_policy

pull_policy for the runners, will be used in the runner config.toml

string

"always"

runners_request_concurrency

Limit number of concurrent requests for new jobs from GitLab

number

20

runners_request_spot_instance

Whether or not to request spot instances via docker-machine

bool

true

runners_root_size

Runner instance root size in GB.

number

16

runners_shm_size

shm_size for the runners, will be used in the runner config.toml

number

0

runners_spot_price_bid

Spot price bid.

string

"0.03"

runners_token

Token for the runner, will be used in the runner config.toml.

string

"REPLACED_BY_USER_DATA"

Outputs

Name	Description
cache_bucket_arn	The GitLab Runners S3 cache bucket ARN
cache_bucket_name	The GitLab Runners S3 cache bucket name
cloudwatch_log_group_name	The GitLab Runner Manager log group name
manager_asg_arn	The GitLab Runner Manager AutoScaling Group ARN
manager_asg_name	The GitLab Runner Manager AutoScaling Group name
manager_launch_template_arn	The GitLab Runner Manager Launch Template ARN
manager_launch_template_name	The GitLab Runner Manager Launch Template name
manager_security_group_arn	The GitLab Runner Manager security group arn
manager_security_group_id	The GitLab Runner Manager security group id
manager_security_group_name	The GitLab Runner Manager security group name
runner_security_group_arn	The GitLab Runners security group arn
runner_security_group_id	The GitLab Runners security group id
runner_security_group_name	The GitLab Runners security group name

Name

Description

cache_bucket_arn

The GitLab Runners S3 cache bucket ARN

cache_bucket_name

The GitLab Runners S3 cache bucket name

cloudwatch_log_group_name

The GitLab Runner Manager log group name

manager_asg_arn

The GitLab Runner Manager AutoScaling Group ARN

manager_asg_name

The GitLab Runner Manager AutoScaling Group name