- The module
- Prerequisites
- Usage
- Examples
- Contributors ✨
- Requirements
- Providers
- Modules
- Resources
- Inputs
- Outputs
This Terraform modules creates a GitLab CI runner. A blog post describes the original version of the the runner. See the post at 040code. The original setup of the module is based on the blog post: Auto scale GitLab CI runners and save 90% on EC2 costs.
💥 BREAKING CHANGE: Due to various problems of the GitLab docker+machine driver (especially with spot instances), the driver is switched to the version provided by CKI. For more details see PR.
🚚 CHANGE AHEAD: We have decided to move this repository to a dedicated org soon. No user impact expected, current GitHub links and Terraform registry links remain working. After release 6.0.0 we move the repository to https://github.com/cattle-ops/terraform-aws-gitlab-runner.
The runners created by the module use spot instances by default for running the builds using the docker+machine executor.
- Shared cache in S3 with life cycle management to clear objects after x days.
- Logs streamed to CloudWatch.
- Runner agents registered automatically.
The name of the runner agent and runner is set with the overrides variable. Adding an agent runner name tag does not work.
# ...
overrides = {
name_sg = ""
name_runner_agent_instance = "Gitlab Runner Agent"
name_docker_machine_runners = "Gitlab Runner Terraform"
name_iam_objects = "gitlab-runner"
}
//this doesn't work
agent_tags = merge(local.my_tags, map("Name", "Gitlab Runner Agent"))The runner supports 3 main scenarios:
In this scenario the runner agent is running on a single EC2 node and runners are created by docker machine using spot instances. Runners will scale automatically based on the configuration. The module creates a S3 cache by default, which is shared across runners (spot instances).
In this scenario the multiple runner agents can be created with different configuration by instantiating the module multiple times. Runners will scale automatically based on the configuration. The S3 cache can be shared across runners by managing the cache outside of the module.
In this scenario not docker machine is used but docker to schedule the builds. Builds will run on the same EC2 instance as the agent. No auto scaling is supported.
Ensure you have Terraform installed. The modules is based on Terraform 0.11, see .terraform-version for the used version. A handy
tool to mange your Terraform version is tfenv.
On macOS it is simple to install tfenv using brew.
brew install tfenvNext install a Terraform version.
tfenv install <version>Ensure you have setup your AWS credentials. The module requires access to IAM, EC2, CloudWatch, S3 and SSM.
In order to be able to destroy the module, you will need to run from a host with both jq and aws installed and accessible in
the environment.
On macOS it is simple to install them using brew.
brew install jq awscliThe GitLab runner EC2 instance requires the following service linked roles:
- AWSServiceRoleForAutoScaling
- AWSServiceRoleForEC2Spot
By default the EC2 instance is allowed to create the required roles, but this can be disabled by setting the option
allow_iam_service_linked_role_creation to false. If disabled you must ensure the roles exist. You can create them manually or
via Terraform.
resource "aws_iam_service_linked_role" "spot" {
aws_service_name = "spot.amazonaws.com"
}
resource "aws_iam_service_linked_role" "autoscaling" {
aws_service_name = "autoscaling.amazonaws.com"
}If a KMS key is set via kms_key_id, make sure that you also give proper access to the key. Otherwise, you might
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
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 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, not run untagged. Below is an example of the configuration map.
gitlab_runner_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>"
}For migration to the new setup simply add the runner token to the parameter store. Once the runner is started it will lookup the
required values via the parameter store. If the value is null a new runner will be registered and a new token created/stored.
# 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 runners_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.
When enable_schedule=true, the schedule_config variable can be used to scale the Auto Scaling group.
Scaling may be defined with one scale_out scheduled action and/or one scale_in scheduled action.
For example:
module "runner" {
# ...
enable_schedule = true
schedule_config = {
# Configure optional scale_out scheduled action
scale_out_recurrence = "0 8 * * 1-5"
scale_out_count = 1 # Default for min_size, desired_capacity and max_size
# Override using: scale_out_min_size, scale_out_desired_capacity, scale_out_max_size
# Configure optional scale_in scheduled action
scale_in_recurrence = "0 18 * * 1-5"
scale_in_count = 0 # Default for min_size, desired_capacity and max_size
# Override using: scale_out_min_size, scale_out_desired_capacity, scale_out_max_size
}
}The Auto Scaling Group may be configured with a lifecycle hook that executes a provided Lambda function when the runner is terminated to terminate additional instances that were spawned.
The use of the termination lifecycle can be toggled using the asg_termination_lifecycle_hook_create variable.
When using this feature, a builds/ directory relative to the root module will persist that contains the packaged Lambda function.
A few option are provided to access the runner instance:
- Access via the Session Manager (SSM) by setting
enable_runner_ssm_accesstotrue. The policy to allow access via SSM is not very restrictive. - By setting none of the above, no keys or extra policies will be attached to the instance. You can still configure you own
policies by attaching them to
runner_agent_role_arn.
By default the module creates a cache for the runner in S3. Old objects are automatically removed via a configurable life cycle policy on the bucket.
Creation of the bucket can be disabled and managed outside this module. A good use case is for sharing the cache across multiple runners. For this purpose the cache is implemented as a sub module. For more details see the cache module. An example implementation of this use case can be found in the runner-public example.
In case you enable the access logging for the S3 cache bucket, you have to add the following statement to your S3 logging bucket policy.
{
"Sid": "Allow access logging",
"Effect": "Allow",
"Principal": {
"Service": "logging.s3.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": "<s3-arn>/*"
}In case you manage the S3 cache bucket yourself it might be necessary to apply the cache before applying the runner module. A typical error message looks like:
Error: Invalid count argument
on .terraform/modules/gitlab_runner/main.tf line 400, in resource "aws_iam_role_policy_attachment" "docker_machine_cache_instance":
count = var.cache_bucket["create"] || length(lookup(var.cache_bucket, "policy", "")) > 0 ? 1 : 0
The "count" value depends on resource attributes that cannot be determined until apply, so Terraform cannot predict how many
instances will be created. To work around this, use the -target argument to first apply only the resources that the count
depends on.
The workaround is to use a terraform apply -target=module.cache followed by a terraform apply to apply everything else. This is
a one time effort needed at the very beginning.
Update the variables in terraform.tfvars according to your needs and add the following variables. See the previous step for
instructions on how to obtain the token.
runner_name = "NAME_OF_YOUR_RUNNER"
gitlab_url = "GITLAB_URL"
runner_token = "RUNNER_TOKEN"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.
Below is a basic examples of usages of the module. Regarding the dependencies such as a VPC, have a look at the default example.
module "runner" {
# https://registry.terraform.io/modules/npalm/gitlab-runner/aws/
source = "npalm/gitlab-runner/aws"
aws_region = "eu-west-1"
environment = "spot-runners"
vpc_id = module.vpc.vpc_id
subnet_ids_gitlab_runner = module.vpc.private_subnets
subnet_id_runners = element(module.vpc.private_subnets, 0)
runners_name = "docker-default"
runners_gitlab_url = "https://gitlab.com"
gitlab_runner_registration_config = {
registration_token = "my-token"
tag_list = "docker"
description = "runner default"
locked_to_project = "true"
run_untagged = "false"
maximum_timeout = "3600"
}
}As the module creates a number of resources during runtime (key pairs and spot instance requests), it needs a special procedure to remove them.
- Use the AWS Console to set the desired capacity of all auto scaling groups to 0. To find the correct ones use the
var.environmentas search criteria. Setting the desired capacity to 0 prevents AWS from creating new instances which will in turn create new resources. - Kill all agent ec2 instances on the via AWS Console. This triggers a Lambda function in the background which removes all resources created during runtime of the EC2 instances.
- Wait 3 minutes so the Lambda function has enough time to delete the key pairs and spot instance requests.
- Run a
terraform destroyorterraform apply(depends on your setup) to remove the module.
If you don't follow the above procedure key pairs and spot instance requests might survive the removal and might cause additional costs. But I have never seen that. You should also be fine by executing step 4 only.
Name clashes due to multi-region deployments for global AWS resources create by this module (IAM, S3) can be avoided by including a distinguishing region specific prefix via the cache_bucket_prefix string respectively via name_iam_objects in the overrides map. A simple example for this would be to set region-specific-prefix to the AWS region the module is deployed to.
module "runner" {
# https://registry.terraform.io/modules/npalm/gitlab-runner/aws/
source = "npalm/gitlab-runner/aws"
aws_region = "eu-west-1"
environment = "spot-runners"
vpc_id = module.vpc.vpc_id
subnet_ids_gitlab_runner = module.vpc.private_subnets
subnet_id_runners = element(module.vpc.private_subnets, 0)
runners_name = "docker-default"
runners_gitlab_url = "https://gitlab.com"
gitlab_runner_registration_config = {
registration_token = "my-token"
tag_list = "docker"
description = "runner default"
locked_to_project = "true"
run_untagged = "false"
maximum_timeout = "3600"
}
overrides = {
name_iam_objects = "<region-specific-prefix>-gitlab-runner-iam"
}
cache_bucket_prefix = "<region-specific-prefix>"
}A few examples are provided. Use the
following steps to deploy. Ensure your AWS and Terraform environment is set up correctly. All commands below should be
run from the terraform-aws-gitlab-runner/examples/<example-dir> directory. Don't forget to remove the runners
manually from your Gitlab instance as soon as your are done.
The version of Terraform is locked down via tfenv, see the .terraform-version file for the expected versions.
Providers are locked down as well in the providers.tf file.
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 registration token. 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.
registration_token = "MY_TOKEN"Run terraform init to initialize Terraform. Next you can run terraform plan to inspect the resources that will be created.
To create the runner, run:
terraform applyTo destroy the runner, run:
terraform destroyThis project exists thanks to all the people who contribute.
Made with contributors-img.
| Name | Version |
|---|---|
| terraform | >= 1 |
| aws | >= 4 |
| Name | Version |
|---|---|
| aws | 4.49.0 |
| Name | Source | Version |
|---|---|---|
| cache | ./modules/cache | n/a |
| terminate_agent_hook | ./modules/terminate-agent-hook | n/a |
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| agent_tags | Map of tags that will be added to agent EC2 instances. | map(string) |
{} |
no |
| allow_iam_service_linked_role_creation | Boolean used to control attaching the policy to a runner instance to create service linked roles. | bool |
true |
no |
| ami_filter | List of maps used to create the AMI filter for the Gitlab runner agent AMI. Must resolve to an Amazon Linux 1 or 2 image. | map(list(string)) |
{ |
no |
| ami_owners | The list of owners used to select the AMI of Gitlab runner agent instances. | list(string) |
[ |
no |
| arn_format | Deprecated! Calculated automatically by the module. ARN format to be used. May be changed to support deployment in GovCloud/China regions. | string |
null |
no |
| asg_delete_timeout | Timeout when trying to delete the Runner ASG. | string |
"10m" |
no |
| asg_max_instance_lifetime | The seconds before an instance is refreshed in the ASG. | number |
null |
no |
| asg_terminate_lifecycle_hook_create | (Deprecated and always true now) Boolean toggling the creation of the ASG instance terminate lifecycle hook. | bool |
true |
no |
| asg_terminate_lifecycle_hook_heartbeat_timeout | (Deprecated and no longer in use) The amount of time, in seconds, for the instances to remain in wait state. | number |
null |
no |
| asg_terminate_lifecycle_hook_name | Specifies a custom name for the ASG terminate lifecycle hook and related resources. | string |
null |
no |
| asg_terminate_lifecycle_lambda_memory_size | (Deprecated and no longer in use) The memory size in MB to allocate to the terminate-instances Lambda function. | number |
128 |
no |
| asg_terminate_lifecycle_lambda_runtime | (Deprecated and no longer in use) Identifier of the function's runtime. This should be a python3.x runtime. See https://docs.aws.amazon.com/lambda/latest/dg/API_CreateFunction.html#SSS-CreateFunction-request-Runtime for more information. | string |
"python3.8" |
no |
| asg_terminate_lifecycle_lambda_timeout | (Deprecated and no longer in use) Amount of time the terminate-instances Lambda Function has to run in seconds. | number |
30 |
no |
| auth_type_cache_sr | A string that declares the AuthenticationType for [runners.cache.s3]. Can either be 'iam' or 'credentials' | string |
"iam" |
no |
| aws_region | AWS region. | string |
n/a | yes |
| cache_bucket | Configuration to control the creation of the cache bucket. By default the bucket will be created and used as shared cache. To use the same cache across multiple runners disable the creation of the cache and provide a policy and bucket name. See the public runner example for more details. | map(any) |
{ |
no |
| cache_bucket_name_include_account_id | Boolean to add current account ID to cache bucket name. | bool |
true |
no |
| cache_bucket_prefix | Prefix for s3 cache bucket name. | string |
"" |
no |
| cache_bucket_set_random_suffix | Append the cache bucket name with a random string suffix | bool |
false |
no |
| cache_bucket_versioning | Boolean used to enable versioning on the cache bucket, false by default. | bool |
false |
no |
| cache_expiration_days | Number of days before cache objects expires. | number |
1 |
no |
| cache_logging_bucket | S3 Bucket ID where the access logs to the cache bucket are stored. | string |
null |
no |
| cache_logging_bucket_prefix | Prefix within the cache_logging_bucket. |
string |
null |
no |
| cache_shared | Enables cache sharing between runners, false by default. | bool |
false |
no |
| cloudwatch_logging_retention_in_days | Retention for cloudwatch logs. Defaults to unlimited | number |
0 |
no |
| create_runner_iam_role | Whether to create the runner IAM role of the gitlab runner agent EC2 instance. | bool |
true |
no |
| docker_machine_download_url | (Optional) By default the module will use docker_machine_version to download the CKI maintained version (https://gitlab.com/cki-project/docker-machine) of Docker Machine. Alternative you can set this property to download location of the distribution of for the OS. See also https://docs.gitlab.com/runner/executors/docker_machine.html#install |
string |
"" |
no |
| docker_machine_egress_rules | List of egress rules for the docker-machine instance(s). | list(object({ |
[ |
no |
| docker_machine_iam_policy_arns | List of policy ARNs to be added to the instance profile of the docker machine runners. | list(string) |
[] |
no |
| docker_machine_instance_metadata_options | Enable the docker machine instances metadata service. Requires you use GitLab maintained docker machines. | object({ |
{ |
no |
| docker_machine_instance_type | Instance type used for the instances hosting docker-machine. | string |
"m5.large" |
no |
| 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 |
| docker_machine_role_json | Docker machine runner instance override policy, expected to be in JSON format. | string |
"" |
no |
| docker_machine_security_group_description | A description for the docker-machine security group | string |
"A security group containing docker-machine instances" |
no |
| docker_machine_spot_price_bid | Spot price bid. The maximum price willing to pay. By default the price is limited by the current on demand price for the instance type chosen. | string |
"on-demand-price" |
no |
| docker_machine_version | By default docker_machine_download_url is used to set the docker machine version. This version will be ignored once docker_machine_download_url is set. The version number is maintained by the CKI project. Check out at https://gitlab.com/cki-project/docker-machine/-/releases |
string |
"0.16.2-gitlab.19-cki.2" |
no |
| enable_asg_recreation | Enable automatic redeployment of the Runner ASG when the Launch Configs change. | bool |
true |
no |
| enable_cloudwatch_logging | Boolean used to enable or disable the CloudWatch logging. | bool |
true |
no |
| enable_docker_machine_ssm_access | Add IAM policies to the docker-machine instances to connect via the Session Manager. | bool |
false |
no |
| enable_eip | Enable the assignment of an EIP to the gitlab runner instance | bool |
false |
no |
| enable_kms | 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 |
| enable_manage_gitlab_token | (Deprecated) Boolean to enable the management of the GitLab token in SSM. If true the token will be stored in SSM, which means the SSM property is a terraform managed resource. If false the Gitlab token will be stored in the SSM by the user-data script during creation of the the instance. However the SSM parameter is not managed by terraform and will remain in SSM after a terraform destroy. |
bool |
null |
no |
| enable_ping | Allow ICMP Ping to the ec2 instances. | bool |
false |
no |
| enable_runner_ssm_access | Add IAM policies to the runner agent instance to connect via the Session Manager. | bool |
false |
no |
| enable_runner_user_data_trace_log | Enable bash xtrace for the user data script that creates the EC2 instance for the runner agent. Be aware this could log sensitive data such as you GitLab runner token. | bool |
true |
no |
| enable_schedule | Flag used to enable/disable auto scaling group schedule for the runner instance. | bool |
false |
no |
| environment | A name that identifies the environment, used as prefix and for tagging. | string |
n/a | yes |
| extra_security_group_ids_runner_agent | Optional IDs of extra security groups to apply to the runner agent. This will not apply to the runners spun up when using the docker+machine executor, which is the default. | list(string) |
[] |
no |
| gitlab_runner_egress_rules | List of egress rules for the gitlab runner instance. | list(object({ |
[ |
no |
| 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) |
{ |
no |
| gitlab_runner_security_group_description | A description for the gitlab-runner security group | string |
"A security group containing gitlab-runner agent instances" |
no |
| gitlab_runner_security_group_ids | A list of security group ids that are allowed to access the gitlab runner agent | list(string) |
[] |
no |
| gitlab_runner_version | Version of the GitLab runner. | string |
"15.8.2" |
no |
| instance_role_json | Default runner instance override policy, expected to be in JSON format. | string |
"" |
no |
| instance_type | Instance type used for the GitLab runner. | string |
"t3.micro" |
no |
| kms_alias_name | Alias added to the kms_key (if created and not provided by kms_key_id) | string |
"" |
no |
| kms_deletion_window_in_days | Key rotation window, set to 0 for no rotation. Only used when enable_kms is set to true. |
number |
7 |
no |
| kms_key_id | KMS key id to encrypted the resources. Ensure CloudWatch and Runner/Executor have access to the provided KMS key. | string |
"" |
no |
| log_group_name | Option to override the default name (environment) of the log group, requires enable_cloudwatch_logging = true. |
string |
null |
no |
| metrics_autoscaling | A list of metrics to collect. The allowed values are GroupDesiredCapacity, GroupInServiceCapacity, GroupPendingCapacity, GroupMinSize, GroupMaxSize, GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances, GroupStandbyCapacity, GroupTerminatingCapacity, GroupTerminatingInstances, GroupTotalCapacity, GroupTotalInstances. | list(string) |
null |
no |
| overrides | This map provides the possibility to override some defaults. The following attributes are supported: * name_sg set the name prefix and overwrite the Name tag for all security groups created by this module.* name_runner_agent_instance set the name prefix and override the Name tag for the EC2 gitlab runner instances defined in the auto launch configuration.* name_docker_machine_runners override the Name tag of EC2 instances created by the runner agent (used as name prefix for docker_machine_version >= 0.16.2).* name_iam_objects set the name prefix of all AWS IAM resources created by this module. |
map(string) |
{ |
no |
| permissions_boundary | Name of permissions boundary policy to attach to AWS IAM roles | string |
"" |
no |
| prometheus_listen_address | Defines an address (:) the Prometheus metrics HTTP server should listen on. | string |
"" |
no |
| role_tags | Map of tags that will be added to the role created. Useful for tag based authorization. | map(string) |
{} |
no |
| runner_agent_uses_private_address | Restrict the runner agent to the use of a private IP address. If runner_agent_uses_private_address is set to false it will override the runners_use_private_address for the agent. |
bool |
true |
no |
| runner_ami_filter | List of maps used to create the AMI filter for the Gitlab runner docker-machine AMI. | map(list(string)) |
{ |
no |
| runner_ami_owners | The list of owners used to select the AMI of Gitlab runner docker-machine instances. | list(string) |
[ |
no |
| runner_extra_config | Extra commands to run as part of starting the runner | string |
"" |
no |
| runner_iam_policy_arns | List of policy ARNs to be added to the instance profile of the gitlab runner agent ec2 instance. | list(string) |
[] |
no |
| runner_iam_role_name | IAM role name of the gitlab runner agent EC2 instance. If unspecified then {name_iam_objects}-instance is used |
string |
"" |
no |
| runner_instance_ebs_optimized | Enable the GitLab runner instance to be EBS-optimized. | bool |
true |
no |
| runner_instance_enable_monitoring | Enable the GitLab runner instance to have detailed monitoring. | bool |
true |
no |
| runner_instance_metadata_options | Enable the Gitlab runner agent instance metadata service. | object({ |
{ |
no |
| runner_instance_spot_price | By setting a spot price bid price the runner agent will be created via a spot request. Be aware that spot instances can be stopped by AWS. Choose "on-demand-price" to pay up to the current on demand price for the instance type chosen. | string |
null |
no |
| runner_root_block_device | The EC2 instance root block device configuration. Takes the following keys: device_name, delete_on_termination, volume_type, volume_size, encrypted, iops, throughput, kms_key_id |
map(string) |
{} |
no |
| runner_tags | Map of tags that will be added to runner EC2 instances. | map(string) |
{} |
no |
| runner_yum_update | Run a yum update as part of starting the runner | bool |
true |
no |
| runners_add_dind_volumes | Add certificates and docker.sock to the volumes to support docker-in-docker (dind) | bool |
false |
no |
| runners_additional_volumes | Additional volumes that will be used in the runner config.toml, e.g Docker socket | list(any) |
[] |
no |
| runners_ca_certificate | Trusted CA certificate bundle. Example: file("${path.module}/ca.crt") |
string |
"" |
no |
| runners_check_interval | defines the interval length, in seconds, between new jobs check. | number |
3 |
no |
| runners_clone_url | Overwrites the URL for the GitLab instance. Use only if the runner can’t connect to the GitLab URL. | string |
"" |
no |
| runners_concurrent | Concurrent value for the runners, will be used in the runner config.toml. | number |
10 |
no |
| runners_disable_cache | Runners will not use local cache, will be used in the runner config.toml | bool |
false |
no |
| runners_docker_registry_mirror | The docker registry mirror to use to avoid rate limiting by hub.docker.com | string |
"" |
no |
| runners_docker_runtime | docker runtime for runners, will be used in the runner config.toml | string |
"" |
no |
| runners_docker_services | adds runners.docker.services blocks to config.toml. All fields must be set (examine the Dockerfile of the service image for the entrypoint - see ./examples/runner-default/main.tf) |
list(object({ |
[] |
no |
| runners_ebs_optimized | Enable runners to be EBS-optimized. | bool |
true |
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_extra_hosts | Extra hosts that will be used in the runner config.toml, e.g other-host:127.0.0.1 | list(any) |
[] |
no |
| runners_gitlab_certificate | Certificate of the GitLab instance to connect to. Example: file("${path.module}/my-gitlab.crt") |
string |
"" |
no |
| runners_gitlab_url | URL of the GitLab instance to connect to. | string |
n/a | yes |
| runners_helper_image | Overrides the default helper image used to clone repos and upload artifacts, will be used in the runner config.toml | string |
"" |
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 |
600 |
no |
| runners_image | Image to run builds, will be used in the runner config.toml | string |
"docker:18.03.1-ce" |
no |
| runners_install_amazon_ecr_credential_helper | Install amazon-ecr-credential-helper inside userdata_pre_install script |
bool |
false |
no |
| runners_limit | Limit for the runners, will be used in the runner config.toml. | number |
0 |
no |
| runners_machine_autoscaling | Set autoscaling parameters based on periods, see https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersmachine-section | list(object({ |
[] |
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_monitoring | Enable detailed cloudwatch monitoring for spot instances. | bool |
false |
no |
| runners_name | Name of the runner, will be used in the runner config.toml. | string |
n/a | yes |
| runners_output_limit | Sets the maximum build log size in kilobytes, by default set to 4096 (4MB). | number |
4096 |
no |
| runners_post_build_script | Commands to be executed on the Runner just after executing the build, but before executing after_script. | string |
"\"\"" |
no |
| runners_pre_build_script | Script to execute in the pipeline just before the build, will be used in the runner config.toml | string |
"\"\"" |
no |
| runners_pre_clone_script | Commands to be executed on the Runner before cloning the Git repository. this can be used to adjust the Git client configuration first, for example. | string |
"\"\"" |
no |
| runners_privileged | Runners will run in privileged mode, will be used in the runner config.toml | bool |
true |
no |
| runners_pull_policies | pull policies for the runners, will be used in the runner config.toml, for Gitlab Runner >= 13.8, see https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies | list(string) |
[ |
no |
| runners_pull_policy | Deprecated! Use runners_pull_policies instead. pull_policy for the runners, will be used in the runner config.toml | string |
"" |
no |
| runners_request_concurrency | Limit number of concurrent requests for new jobs from GitLab (default 1). | number |
1 |
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_services_volumes_tmpfs | Mount a tmpfs in gitlab service container. https://docs.gitlab.com/runner/executors/docker.html#mounting-a-directory-in-ram | list(object({ |
[] |
no |
| runners_shm_size | shm_size for the runners, will be used in the runner config.toml | number |
0 |
no |
| runners_token | Token for the runner, will be used in the runner config.toml. | string |
"__REPLACED_BY_USER_DATA__" |
no |
| runners_use_private_address | Restrict runners to the use of a private IP address. If runner_agent_uses_private_address is set to true(default), runners_use_private_address will also apply for the agent. |
bool |
true |
no |
| runners_userdata | Cloud-init user data that will be passed to the runner ec2 instance. Available only for docker+machine driver. Should not be base64 encrypted. |
string |
"" |
no |
| runners_volume_type | Runner instance volume type | string |
"gp2" |
no |
| runners_volumes_tmpfs | Mount a tmpfs in runner container. https://docs.gitlab.com/runner/executors/docker.html#mounting-a-directory-in-ram | list(object({ |
[] |
no |
| schedule_config | Map containing the configuration of the ASG scale-out and scale-in for the runner instance. Will only be used if enable_schedule is set to true. | map(any) |
{ |
no |
| secure_parameter_store_runner_sentry_dsn | The Sentry DSN name used to store the Sentry DSN in Secure Parameter Store | string |
"sentry-dsn" |
no |
| secure_parameter_store_runner_token_key | The key name used store the Gitlab runner token in Secure Parameter Store | string |
"runner-token" |
no |
| sentry_dsn | Sentry DSN of the project for the runner to use (uses legacy DSN format) | string |
"__SENTRY_DSN_REPLACED_BY_USER_DATA__" |
no |
| subnet_id | Subnet id used for the runner and executors. Must belong to the VPC specified above. | string |
"" |
no |
| subnet_id_runners | Deprecated! Use subnet_id instead. List of subnets used for hosting the gitlab-runners. | string |
"" |
no |
| subnet_ids_gitlab_runner | Deprecated! Use subnet_id instead. Subnet used for hosting the GitLab runner. | list(string) |
[] |
no |
| suppressed_tags | List of tag keys which are removed from tags, agent_tags and runner_tags and never added as default tag by the module. | list(string) |
[] |
no |
| tags | Map of tags that will be added to created resources. By default resources will be tagged with name and environment. | map(string) |
{} |
no |
| userdata_post_install | User-data script snippet to insert after GitLab runner install | string |
"" |
no |
| userdata_pre_install | User-data script snippet to insert before GitLab runner install | string |
"" |
no |
| vpc_id | The target VPC for the docker-machine and runner instances. | string |
n/a | yes |
| Name | Description |
|---|---|
| runner_agent_role_arn | ARN of the role used for the ec2 instance for the GitLab runner agent. |
| runner_agent_role_name | Name of the role used for the ec2 instance for the GitLab runner agent. |
| runner_agent_sg_id | ID of the security group attached to the GitLab runner agent. |
| runner_as_group_name | Name of the autoscaling group for the gitlab-runner instance |
| runner_cache_bucket_arn | ARN of the S3 for the build cache. |
| runner_cache_bucket_name | Name of the S3 for the build cache. |
| runner_eip | EIP of the Gitlab Runner |
| runner_launch_template_name | The name of the runner's launch template. |
| runner_role_arn | ARN of the role used for the docker machine runners. |
| runner_role_name | Name of the role used for the docker machine runners. |
| runner_sg_id | ID of the security group attached to the docker machine runners. |
| runner_user_data | The user data of the Gitlab Runner Agent's launch template. |