autoscaled-gitlab-runner

GitLab Runner fleet on AWS using the GitLab Runner and AWS Autoscaling services.

For more details, refer to the Solution Overview.

The terraform stack includes the following components:

• GitLab Job Webhook:
  • Triggers the Step Functions workflow whenever new CI/CD jobs are added to the queue.
• Amazon DynamoDB:
  • Used for state management and lock acquisition.
  • Ensures that scaling operations are not duplicated or run concurrently.
• AWS Step Function:
  • Manages workflow to process incoming requests from Gitlab Job Webhook and execute scaling action if required.
• Auto Scaling Group (ASG):
  • Dynamically adjusts the number of GitLab Runner instances based on job demand.
• CloudWatch:
  • Monitors metrics from the runner to analyze servers load and performance
• IAM Roles:
  • Secures interactions between services.

Prerequisites

Before using this stack, ensure you have the following AMI must be available in the target region: gitlab-runner-amazon.

AMI can be built using the following command:

ansible-playbook ami_build.yml -e @aws_vars.yml

Before building the AMI you need the following secrets to be configured:

• gl_runner_token secret string stored in AWS Parameters Store, path: /gitlab_tokens

This secret is used to register new gitlab-runner instances in Gitlab on EC2 instance startup during execution of user-metadata scripts.

• gitlab_secret_token secret stored in secrets or specified explicitly as terraform variable

This secret is used to secure API calls from Gitlab Webhook to AWS API Gateway triggering Step Function to scale AWS Autoscaling Group on demand.

Requirements

Name	Version
terraform	>= 1.0
aws	~> 5.21

Providers

Name	Version
aws	5.84.0

Modules

No modules.

Resources

Name	Type
aws_api_gateway_account.api_gateway_account	resource
aws_api_gateway_deployment.api_deployment	resource
aws_api_gateway_integration.post_integration	resource
aws_api_gateway_integration_response.post_integration_response	resource
aws_api_gateway_method.post_method	resource
aws_api_gateway_method_response.post_method_response	resource
aws_api_gateway_method_settings.api_method_settings	resource
aws_api_gateway_resource.webhook_resource	resource
aws_api_gateway_rest_api.gitlab_webhook_api	resource
aws_api_gateway_stage.api_stage	resource
aws_autoscaling_group.gitlab_runners	resource
aws_autoscaling_lifecycle_hook.gitlab_runners_start	resource
aws_autoscaling_lifecycle_hook.gitlab_runners_stop	resource
aws_cloudwatch_log_group.api_gw_logs	resource
aws_cloudwatch_log_group.step_functions_log_group	resource
aws_dynamodb_table.lock_table	resource
aws_iam_instance_profile.gitlab_runner	resource
aws_iam_policy.api_gateway_logs_policy	resource
aws_iam_policy.api_gateway_policy	resource
aws_iam_policy.gitlab_cache_policy	resource
aws_iam_policy.step_functions_policy	resource
aws_iam_role.api_gateway_role	resource
aws_iam_role.step_functions_role	resource
aws_iam_role_policy_attachment.api_gateway_logs_policy_attachment	resource
aws_iam_role_policy_attachment.api_gateway_role_policy_attachment	resource
aws_iam_role_policy_attachment.gitlab_policy_attachment	resource
aws_iam_role_policy_attachment.step_functions_role_policy_attachment	resource
aws_launch_template.gitlab_runner	resource
aws_s3_bucket.gitlab_cache	resource
aws_security_group.gitlab_runner	resource
aws_sfn_state_machine.state_machine	resource
aws_vpc_security_group_egress_rule.allow_all_traffic_ipv4	resource
aws_vpc_security_group_egress_rule.runner_to_https	resource
aws_vpc_security_group_egress_rule.runner_to_ssh	resource
aws_vpc_security_group_ingress_rule.runner_ssh	resource
aws_ami.gitlab_runner	data source
aws_default_tags.tags	data source
aws_iam_policy_document.gitlab_assume_role_policy	data source
aws_iam_policy_document.gitlab_cache	data source

Inputs

Name	Description	Type	Default	Required
ami_user	The user to use for the AMI.	string	"ec2-user"	no
api_gateway_stage_name	Name of the API Gateway deployment stage	string	"dev"	no
aws_region	The AWS region to use.	string	n/a	yes
bastion_security_group_id	The ID of the bastion security group.	string	"sg-0a1b2c3d4e5f6g7h8"	no
capacity_per_instance	The number of concurrent jobs per instance.	number	null	no
desired_size	The desired number of instances in the autoscaling group.	number	0	no
environment_name	The name of the environment.	string	n/a	yes
fleet_instance_types	The instance types to use.	list(string)	[ "m5a.large", "m5.large", "m6a.large", "m6i.large", "m7a.large", "c5.large", "c5a.large", "c6a.large", "c6i.large", "c7i.large", "c7a.large", "m7i.large", "m7i-flex.large" ]	no
gitlab_api_url	Target GitLab base API endpoint in the form of https://my.gitlab.server/api/v4/.	string	"https://gitlab.com/api/v4/"	no
gitlab_secret_token	Secret token configured in GitLab webhook for validation	string	"h&s8BdSbinDQ7h"	no
gl_cache_path	The IAM role to use for the instances.	string	"cache"	no
gl_runner_tags	The tags to apply to the GitLab Runner.	list(string)	null	no
group_id	The GitLab group ID.	number	1347	no
iam_role	The IAM role to use for the instances.	string	"gitlab-runner"	no
idle_threshold	The number of seconds before a runner is considered idle.	number	null	no
image_id	If unset or false (default), use the data lookup for the image	string	null	no
image_name	The 'service_name' of the image to lookup	string	"gitlab-runner-amazon"	no
key_name	The name of the key pair to use.	string	"gitlab-runner-key"	no
max_size	The maximum number of instances in the autoscaling group.	number	10	no
min_size	The minimum number of instances in the autoscaling group.	number	0	no
private_subnet_ids	List of subnet IDs to launch resources in.	list(string)	[ "subnet-0a1b2c3d4e5f6g7h8" ]	no
root_disk_size	The size of the root disk in GB.	number	30	no
volume_delete_on_termination	Whether to delete the root volume on instance termination.	bool	true	no
vpc_cidr	The CIDR block for the VPC.	string	"172.31.0.0/16"	no
vpc_id	The ID of the VPC.	string	n/a	yes

Outputs

Name	Description
api_gateway_invoke_url	n/a