terraform-aws-arc-github-runner ¶

Overview¶

SourceFuse AWS Reference Architecture (ARC) Terraform module for managing GitHub Runner.

This module will create the following resources in a specified AWS Account: * S3 bucket: used for storing the generated docker-compose.yml * EC2 instance: Used for running the runner container on * SSH Key Pair: Used for decrypting EC2 password * SSM Documents: Used for installing dependencies and updating the SSM Agent * IAM Policies: For accessing created resources * SSM Parameter: For storing the runner token

This module utilizes different local-exec provisioners to execute scripts for obtaining the needed GitHub Runner token and remove the runner from the organization when the resources are destroyed. See Pre-Requisites for information on the needed permissions these scripts will require.

Pre-Requisites¶

You will need to have a GitHub Personal Access Token (PAT) with admin:org permissions in order to manage GitHub runners for the Organization. If you do not have sufficient permissions to GitHub, the runner will not register.

Once you've obtained a PAT, you will need to set it so Terraform can access it. The recommended approach to this is to save it in Systems Manager Parameter Store with the Parameter name of: /<namespace>/<environment>/github/token You can reference this parameter via a data lookup:

data "aws_ssm_parameter" "github_token" {
  name = "/${var.namespace}/${var.environment}/github/token"
}

Usage¶

At this time, this module only supports Debian / Ubuntu AMIs. When choosing an AMI, please be sure to select either Ubuntu or Debian.

To see a full example, check out the main.tf file in the example folder.

module "runner" {
  source  = "sourcefuse/arc-github-runner/aws"
  version = "0.2.6"
  namespace     = var.namespace
  environment   = var.environment
  region        = var.region
  subnet_id     = local.private_subnet_ids[0]
  vpc_id        = data.aws_vpc.this.id
  instance_type = "t2.micro"
  github_token  = data.aws_ssm_parameter.github_token.value
  runner_labels = "example,${var.namespace},${var.environment}"

  tags = module.tags.tags
}

Requirements¶

Name	Version
terraform	~> 1.3, < 2.0.0
aws	>= 4.0
null	>= 3.0
random	>= 3.0

Providers¶

Name	Version
aws	4.50.0
null	3.2.1
random	3.4.3

Modules¶

Name	Source	Version
runner	git::https://github.com/cloudposse/terraform-aws-ec2-instance	0.45.2
ssh_key_pair	git::https://github.com/cloudposse/terraform-aws-key-pair	0.18.3

Resources¶

Name	Type
aws_iam_policy.runner_bucket_access	resource
aws_iam_role_policy_attachment.runner	resource
aws_iam_role_policy_attachment.runner_bucket_access	resource
aws_s3_bucket.runner	resource
aws_s3_bucket_acl.runner	resource
aws_s3_bucket_logging.runner	resource
aws_s3_bucket_public_access_block.runner	resource
aws_s3_bucket_server_side_encryption_configuration.runner	resource
aws_s3_bucket_versioning.runner	resource
aws_s3_object.docker_compose	resource
aws_ssm_association.dependencies	resource
aws_ssm_association.runner_compose	resource
aws_ssm_document.dependencies	resource
aws_ssm_document.runner_compose	resource
null_resource.cleanup	resource
null_resource.prepare	resource
random_string.runner	resource
aws_caller_identity.this	data source
aws_ssm_parameter.runner_token	data source

Inputs¶

Name	Description	Type	Default	Required
ami	AMI information for the EC2 instance	object({ id = string owner_id = string })	{ "id": "ami-04505e74c0741db8d", "owner_id": "099720109477" }	no
associate_public_ip_address	Associate a public IP address with the instance	`bool`	`false`	no
ec2_runner_iam_role_policy_arns	IAM role policies to attach to the Runner instance	`list(string)`	[ "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore", "arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM" ]	no
environment	Name of the environment, i.e. dev, stage, prod	`string`	n/a	yes
github_owner	GitHub Owner the runner belongs to. If you are adding a repo, the format will be `owner/repo`	`string`	`"sourcefuse"`	no
github_token	GitHub Personal Access Token with `admin:org` permission scope. This is used to obtain a Runner Token used for registering the runner. For more information, see Create a registration token for an organization.	`string`	n/a	yes
instance_type	The instance type for the EC2 instance. Default is t3a.medium.	`string`	`"t3a.medium"`	no
monitoring_enabled	Launched EC2 instance will have detailed monitoring enabled	`bool`	`true`	no
namespace	Namespace of the project, i.e. refarch	`string`	n/a	yes
region	AWS region	`string`	n/a	yes
repos_or_orgs	Whether the API will register / deregister the runner in repos or orgs. Options are `orgs` and `repos`	`string`	`"orgs"`	no
root_block_device_encrypted	Whether to encrypt the root block device	`bool`	`true`	no
root_block_device_kms_key_id	KMS key ID used to encrypt EBS volume. When specifying root_block_device_kms_key_id, root_block_device_encrypted needs to be set to true	`string`	`null`	no
root_volume_size	Size of the root volume in gigabytes	`string`	`"80"`	no
root_volume_type	Type of root volume. Can be standard, gp2, gp3, io1 or io2	`string`	`"gp2"`	no
runner_image	Name of the image to use for the Actions Runner.	`string`	`"sourcefuse/github-runner:0.3.0"`	no
runner_labels	Labels to assign the GitHub Runner. If no values are given, the default labels will be: - `self-hosted` - Base OS, i.e. `Linux` - Architecture, i.e. `X64` These labels cannot be overridden. Separate labels via comma, i.e. `dev,docker,another_label`	`string`	`""`	no
runner_name	Name to assign the GitHub Runner. If no value is given, it will use the ec2 instance name.	`string`	`null`	no
runner_user	Name of the user to run the container as.	`string`	`"runner"`	no
security_group_rules	Security group rules for the EC2 instance running the GitHub Runner	list(object({ type = string from_port = number to_port = number protocol = string cidr_blocks = list(string) }))	[ { "cidr_blocks": [ "0.0.0.0/0" ], "from_port": 0, "protocol": "-1", "to_port": 65535, "type": "egress" } ]	no
ssm_patch_manager_enabled	Whether to enable SSM Patch manager	`bool`	`true`	no
subnet_id	Subnet ID for the EC2 instance to be assigned to	`string`	n/a	yes
tags	Default tags to apply to every resource	`map(string)`	`{}`	no
volume_tags_enabled	Whether or not to copy instance tags to root and EBS volumes	`bool`	`true`	no
vpc_id	VPC ID for EC2 instance to reside in	`string`	n/a	yes

Outputs¶

Name	Description
ec2_runner_instance_id	Instance ID of the EC2 Runner
ec2_runner_instance_name	Instance Name of the EC2 Runner
ec2_runner_role	Instance role name
ec2_runner_role_arn	Instance role ARN

Development¶

Prerequisites¶

Configurations¶

Configure pre-commit hooks
1
pre-commit install

Git commits¶

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

git commit -m "your commit message #major"

By specifying this , it will bump the version and if you dont specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests¶

Tests are available in test directory

Configure the dependencies

cd test/
go mod init github.com/sourcefuse/terraform-aws-refarch-github-runner
go get github.com/gruntwork-io/terratest/modules/terraform

Now execute the test
1
go test -timeout 30m

Authors¶

This project is authored by: - SourceFuse ARC Team

terraform-aws-arc-github-runner¶