This Terraform module provides a reusable infrastructure configuration for deploying GitLab Runner instances on AWS Spot Instances. Using the AWS Fleeting plugin, the Runner instances can be automatically scaled based on the number of jobs in the GitLab CI/CD pipeline. The module supports both ARM64 and AMD64 architectures.
This module use a single GitLab Runner Manager instance to manage multiple GitLab Runner instances. The Runner Manager is responsible for scheduling jobs on the Runner instances and scaling the number of instances based on the number of jobs in the GitLab CI/CD pipeline.
The Runner Manager is deployed as an EC2 instance and the Runner instances are deployed as AWS Spot Instances. The Runner instances are managed by an Auto Scaling Group and are launched using a Launch Template.
Architecture Diagram - See: GitLab Runner Autoscaler documentation for more details
This module is licensed under the Apache License. See the LICENSE file for more details.
Name | Version |
---|---|
terraform | >= 1.3 |
aws | >= 5.11 |
Name | Version |
---|---|
aws | >= 5.11 |
No modules.
Name | Type |
---|---|
aws_autoscaling_group.gitlab_runner_instance | resource |
aws_iam_instance_profile.runner_manager | resource |
aws_iam_role.runner_manager | resource |
aws_iam_role_policy.gitlab_runner_manager | resource |
aws_iam_role_policy.ssm_read_runner_tokens | resource |
aws_instance.runner_manager | resource |
aws_launch_template.gitlab_runner_instance | resource |
aws_security_group.runner | resource |
aws_security_group.runner_manager | resource |
aws_ami.amazon_linux_2 | data source |
aws_caller_identity.current | data source |
aws_region.current | data source |
Name | Description | Type | Default | Required |
---|---|---|---|---|
architectures | The architectures that the Runner will support (e.g., arm64, amd64). Each specified architecture requires its corresponding runner_instance configuration. | list(string) |
n/a | yes |
aws_azs | n/a | list(string) |
[] |
no |
aws_key_name | n/a | string |
"" |
no |
aws_security_group_ids | n/a | list(string) |
[] |
no |
aws_subnet_ids | n/a | list(string) |
n/a | yes |
aws_vpc_id | n/a | string |
n/a | yes |
environment | A name that identifies the environment, used as a prefix for tagging resources | string |
n/a | yes |
fleeting_plugin_aws_version | The version of the AWS Fleeting plugin to install. | string |
n/a | yes |
gitlab_instance_url | The URL of the GitLab instance | string |
"https://gitlab.com" |
no |
gitlab_runner_version | The version of the GitLab Runner to install. | string |
n/a | yes |
runner_autoscaler_options_amd64 | Options added to the [runners.autoscaler] section of config.toml to configure the Runner Autoscaler. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersautoscaler-section capacity_per_instance = The number of jobs that can be executed concurrently by a single instance. max_use_count = The maximum number of times an instance can be used before it is scheduled for removal. max_instances = The maximum number of instances that are allowed, this is regardless of the instance state (pending, running, deleting). Default: 0 (unlimited). The fleeting-plugin-aws is the only supported plugin. Default values if the option is not given: capacity_per_instance = 1 max_use_count = 10 max_instances = 2 |
object({ |
{ |
no |
runner_autoscaler_options_arm64 | Options added to the [runners.autoscaler] section of config.toml to configure the Runner Autoscaler. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersautoscaler-section capacity_per_instance = The number of jobs that can be executed concurrently by a single instance. max_use_count = The maximum number of times an instance can be used before it is scheduled for removal. max_instances = The maximum number of instances that are allowed, this is regardless of the instance state (pending, running, deleting). Default: 0 (unlimited). The fleeting-plugin-aws is the only supported plugin. Default values if the option is not given: capacity_per_instance = 1 max_use_count = 10 max_instances = 2 |
object({ |
{ |
no |
runner_autoscaler_plugin_connector_options_amd64 | Options added to the [runners.autoscaler.connector_config] section of config.toml to configure the Runner Plugin Connector. For details check https://gitlab.com/gitlab-org/fleeting/plugins/aws |
object({ |
{ |
no |
runner_autoscaler_plugin_connector_options_arm64 | Options added to the [runners.autoscaler.connector_config] section of config.toml to configure the Runner Plugin Connector. For details check https://gitlab.com/gitlab-org/fleeting/plugins/aws |
object({ |
{ |
no |
runner_autoscaler_plugin_options_amd64 | Options added to the [runners.autoscaler.plugin_config] section of config.toml to configure the Runner Plugin. For details check https://gitlab.com/gitlab-org/fleeting/plugins/aws auto_scaling_group_name Will be set to the value of the corresponding Arch |
object({ |
{} |
no |
runner_autoscaler_plugin_options_arm64 | Options added to the [runners.autoscaler.plugin_config] section of config.toml to configure the Runner Plugin. For details check https://gitlab.com/gitlab-org/fleeting/plugins/aws auto_scaling_group_name Will be set to the value of the corresponding Arch |
object({ |
{} |
no |
runner_autoscaler_policy_amd64 | Options added to the [runners.autoscaler.policy] section of config.toml to configure the Runner Autoscaler Policy. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersautoscalerpolicy-section Default values if the option is not given: idle_count = 0 idle_time = "30m" |
list(object({ |
[ |
no |
runner_autoscaler_policy_arm64 | Options added to the [runners.autoscaler.policy] section of config.toml to configure the Runner Autoscaler Policy. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersautoscalerpolicy-section Default values if the option is not given: idle_count = 0 idle_time = "30m" |
list(object({ |
[ |
no |
runner_docker_options_amd64 | Options added to the [runners.docker] section of config.toml to configure the Docker container of the Runner Worker. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html Default values if the option is not given: disable_cache = "false" image = "busybox:latest" privileged = "false" pull_policy = "always" shm_size = 0 tls_verify = "false" volumes = "/cache" |
object({ |
{ |
no |
runner_docker_options_arm64 | Options added to the [runners.docker] section of config.toml to configure the Docker container of the Runner Worker. For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html Default values if the option is not given: disable_cache = false image = "busybox:latest" privileged = false pull_policy = "always" shm_size = 0 tls_verify = false volumes = "/cache" |
object({ |
{ |
no |
runner_instance_amd64 | Configuration for the AMD64 GitLab Runner instance. Required when amd64 architecture is specified. | object({ |
null |
no |
runner_instance_arm64 | Configuration for the ARM64 GitLab Runner instance. Required when arm64 architecture is specified. | object({ |
null |
no |
runner_manager | For details check https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section gitlab_check_interval = Number of seconds between checking for available jobs (check_interval) maximum_concurrent_jobs = The maximum number of jobs which can be processed by all Runners at the same time (concurrent). prometheus_listen_address = Defines an address (:) the Prometheus metrics HTTP server should listen on (listen_address). sentry_dsn = Sentry DSN of the project for the Runner Manager to use (uses legacy DSN format) (sentry_dsn) |
object({ |
{} |
no |
runner_ssm_token_amd64 | The SSM parameter that stores the authentication token for the Runner (amd64). Required when amd64 architecture is specified. | object({ |
null |
no |
runner_ssm_token_arm64 | The SSM parameter that stores the authentication token for the Runner (arm64). Required when arm64 architecture is specified. | object({ |
null |
no |
suppressed_tags | List of tag keys which are automatically removed and never added as default tag by the module. | list(string) |
[] |
no |
tags | A map of tags to apply to all resources | map(string) |
{} |
no |
Name | Description |
---|---|
auto_scaling_group_ids | n/a |
launch_template_ids | n/a |
runner_manager_id | n/a |