Component: `github-runners`

This component is responsible for provisioning EC2 instances for GitHub runners.

Usage

Stack Level: Regional

Here's an example snippet for how to use this component.

components:
  terraform:
    github-runners:
      vars:
        cpu_utilization_high_threshold_percent: 5
        cpu_utilization_low_threshold_percent: 1
        default_cooldown: 300
        github_scope: company
        instance_type: "t3.small"
        max_size: 10
        min_size: 1
        runner_group: default
        scale_down_cooldown_seconds: 2700
        wait_for_capacity_timeout: 10m
        mixed_instances_policy:
          instances_distribution:
            on_demand_allocation_strategy: "prioritized"
            on_demand_base_capacity: 1
            on_demand_percentage_above_base_capacity: 0
            spot_allocation_strategy: "capacity-optimized"
            spot_instance_pools: null
            spot_max_price: null
          override:
            - instance_type: "t4g.large"
              weighted_capacity: null
            - instance_type: "m5.large"
              weighted_capacity: null
            - instance_type: "m5a.large"
              weighted_capacity: null
            - instance_type: "m5n.large"
              weighted_capacity: null
            - instance_type: "m5zn.large"
              weighted_capacity: null
            - instance_type: "m4.large"
              weighted_capacity: null
            - instance_type: "c5.large"
              weighted_capacity: null
            - instance_type: "c5a.large"
              weighted_capacity: null
            - instance_type: "c5n.large"
              weighted_capacity: null
            - instance_type: "c4.large"
              weighted_capacity: null

Configuration

API Token

Prior to deployment, the API Token must exist in SSM.

To generate the token, please follow these instructions. Once generated, write the API token to the SSM key store at the following location within the same AWS account and region where the GitHub Actions runner pool will reside.

assume-role <automation-admin role>
chamber write github/runners/<github-org> registration-token ghp_secretstring

Requirements

Name	Version
terraform	>= 1.0.0
aws	>= 4.9.0
cloudinit	>= 2.2

Providers

Name	Version
aws	>= 4.9.0
cloudinit	>= 2.2

Modules

Name	Source	Version
account_map	cloudposse/stack-config/yaml//modules/remote-state	1.4.1
autoscale_group	cloudposse/ec2-autoscale-group/aws	0.30.1
graceful_scale_in	./modules/graceful_scale_in	n/a
iam_roles	../account-map/modules/iam-roles	n/a
sg	cloudposse/security-group/aws	1.0.1
this	cloudposse/label/null	0.25.0
vpc	cloudposse/stack-config/yaml//modules/remote-state	1.4.1

Resources

Name	Type
aws_iam_instance_profile.github_action_runner	resource
aws_iam_policy.github_action_runner	resource
aws_iam_role.github_action_runner	resource
aws_ami.runner	data source
aws_iam_policy_document.github_action_runner	data source
aws_iam_policy_document.instance_assume_role_policy	data source
aws_partition.current	data source
aws_ssm_parameter.github_token	data source
cloudinit_config.config	data source

Inputs

Name	Description	Type	Default	Required
account_map_environment_name	The name of the environment where `account_map` is provisioned	`string`	`"gbl"`	no
account_map_stage_name	The name of the stage where `account_map` is provisioned	`string`	`"root"`	no
account_map_tenant_name	The name of the tenant where `account_map` is provisioned. If the `tenant` label is not used, leave this as `null`.	`string`	`null`	no
additional_tag_map	Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`. This is for some rare cases where resources want additional configuration of tags and therefore take a list of maps with tag key, value, and additional configuration.	`map(string)`	`{}`	no
ami_filter	Map of lists used to look up the AMI which will be used for the GitHub Actions Runner.	`map(list(string))`	`{ "name": [ "amzn2-ami-hvm-2.*-x86_64-ebs" ] }`	no
ami_owners	The list of owners used to select the AMI of action runner instances.	`list(string)`	`[ "amazon" ]`	no
attributes	ID element. Additional attributes (e.g. `workers` or `cluster`) to add to `id`, in the order they appear in the list. New attributes are appended to the end of the list. The elements of the list are joined by the `delimiter` and treated as a single ID element.	`list(string)`	`[]`	no
block_device_mappings	Specify volumes to attach to the instance besides the volumes specified by the AMI	`list(object({ device_name = string no_device = bool virtual_name = string ebs = object({ delete_on_termination = bool encrypted = bool iops = number kms_key_id = string snapshot_id = string volume_size = number volume_type = string }) }))`	`[]`	no
context	Single object for setting entire context at once. See description of individual variables for details. Leave string and numeric variables as `null` to use default value. Individual variable settings (non-null) override settings in context object, except for attributes, tags, and additional_tag_map, which are merged.	`any`	`{ "additional_tag_map": {}, "attributes": [], "delimiter": null, "descriptor_formats": {}, "enabled": true, "environment": null, "id_length_limit": null, "label_key_case": null, "label_order": [], "label_value_case": null, "labels_as_tags": [ "unset" ], "name": null, "namespace": null, "regex_replace_chars": null, "stage": null, "tags": {}, "tenant": null }`	no
cpu_utilization_high_evaluation_periods	The number of periods over which data is compared to the specified threshold	`number`	`2`	no
cpu_utilization_high_period_seconds	The period in seconds over which the specified statistic is applied	`number`	`300`	no
cpu_utilization_high_threshold_percent	The value against which the specified statistic is compared	`number`	`90`	no
cpu_utilization_low_evaluation_periods	The number of periods over which data is compared to the specified threshold	`number`	`2`	no
cpu_utilization_low_period_seconds	The period in seconds over which the specified statistic is applied	`number`	`300`	no
cpu_utilization_low_threshold_percent	The value against which the specified statistic is compared	`number`	`10`	no
default_cooldown	The amount of time, in seconds, after a scaling activity completes before another scaling activity can start	`number`	`300`	no
delimiter	Delimiter to be used between ID elements. Defaults to `-` (hyphen). Set to `""` to use no delimiter at all.	`string`	`null`	no
descriptor_formats	Describe additional descriptors to be output in the `descriptors` output map. Map of maps. Keys are names of descriptors. Values are maps of the form `{<br/> format = string<br/> labels = list(string)<br/>}` (Type is `any` so the map values can later be enhanced to provide additional options.) `format` is a Terraform format string to be passed to the `format()` function. `labels` is a list of labels, in order, to pass to `format()` function. Label values will be normalized before being passed to `format()` so they will be identical to how they appear in `id`. Default is `{}` (`descriptors` output will be empty).	`any`	`{}`	no
docker_compose_version	The version of docker-compose to install	`string`	`"1.29.2"`	no
enabled	Set to false to prevent the module from creating any resources	`bool`	`null`	no
environment	ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'	`string`	`null`	no
github_scope	Scope of the runner (e.g. `cloudposse/example` for repo or `cloudposse` for org)	`string`	n/a	yes
id_length_limit	Limit `id` to this many characters (minimum 6). Set to `0` for unlimited length. Set to `null` for keep the existing setting, which defaults to `0`. Does not affect `id_full`.	`number`	`null`	no
import_profile_name	AWS Profile name to use when importing a resource	`string`	`null`	no
import_role_arn	IAM Role ARN to use when importing a resource	`string`	`null`	no
instance_type	Default instance type for the action runner.	`string`	`"m5.large"`	no
label_key_case	Controls the letter case of the `tags` keys (label names) for tags generated by this module. Does not affect keys of tags passed in via the `tags` input. Possible values: `lower`, `title`, `upper`. Default value: `title`.	`string`	`null`	no
label_order	The order in which the labels (ID elements) appear in the `id`. Defaults to ["namespace", "environment", "stage", "name", "attributes"]. You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.	`list(string)`	`null`	no
label_value_case	Controls the letter case of ID elements (labels) as included in `id`, set as tag values, and output by this module individually. Does not affect values of tags passed in via the `tags` input. Possible values: `lower`, `title`, `upper` and `none` (no transformation). Set this to `title` and set `delimiter` to `""` to yield Pascal Case IDs. Default value: `lower`.	`string`	`null`	no
labels_as_tags	Set of labels (ID elements) to include as tags in the `tags` output. Default is to include all labels. Tags with empty values will not be included in the `tags` output. Set to `[]` to suppress all generated tags. Notes: The value of the `name` tag, if included, will be the `id`, not the `name`. Unlike other `null-label` inputs, the initial setting of `labels_as_tags` cannot be changed in later chained modules. Attempts to change it will be silently ignored.	`set(string)`	`[ "default" ]`	no
max_instance_lifetime	The maximum amount of time, in seconds, that an instance can be in service, values must be either equal to 0 or between 604800 and 31536000 seconds	`number`	`null`	no
max_size	The maximum size of the autoscale group	`number`	n/a	yes
min_size	The minimum size of the autoscale group	`number`	n/a	yes
mixed_instances_policy	Policy to use a mixed group of on-demand/spot of differing types. Launch template is automatically generated. https://www.terraform.io/docs/providers/aws/r/autoscaling_group.html#mixed_instances_policy-1	`object({ instances_distribution = object({ on_demand_allocation_strategy = string on_demand_base_capacity = number on_demand_percentage_above_base_capacity = number spot_allocation_strategy = string spot_instance_pools = number spot_max_price = string }) override = list(object({ instance_type = string weighted_capacity = number })) })`	`null`	no
name	ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'. This is the only ID element not also included as a `tag`. The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input.	`string`	`null`	no
namespace	ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique	`string`	`null`	no
regex_replace_chars	Terraform regular expression (regex) string. Characters matching the regex will be removed from the ID elements. If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits.	`string`	`null`	no
region	AWS Region	`string`	n/a	yes
runner_group	GitHub runner group	`string`	`"default"`	no
runner_labels	List of labels to add to the GitHub Runner (e.g. 'Amazon Linux 2').	`list(string)`	`[]`	no
runner_role_additional_policy_arns	List of policy ARNs that will be attached to the runners' default role on creation in addition to the defaults	`list(string)`	`[]`	no
runner_version	GitHub runner release version	`string`	`"2.288.1"`	no
scale_down_cooldown_seconds	The amount of time, in seconds, after a scaling activity completes and before the next scaling activity can start	`number`	`300`	no
ssm_parameter_name_format	SSM parameter name format	`string`	`"/%s/%s"`	no
ssm_path	GitHub token SSM path	`string`	`"github"`	no
ssm_path_key	GitHub token SSM path key	`string`	`"registration-token"`	no
stage	ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'	`string`	`null`	no
tags	Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`). Neither the tag keys nor the tag values will be modified by this module.	`map(string)`	`{}`	no
tenant	ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for	`string`	`null`	no
userdata_post_install	Shell script to run post installation of github action runner	`string`	`""`	no
userdata_pre_install	Shell script to run before installation of github action runner	`string`	`""`	no
wait_for_capacity_timeout	A maximum duration that Terraform should wait for ASG instances to be healthy before timing out. (See also Waiting for Capacity below.) Setting this to '0' causes Terraform to skip all Capacity Waiting behavior	`string`	`"10m"`	no

Outputs

Name	Description
autoscaling_group_arn	The Amazon Resource Name (ARN) of the Auto Scaling Group.
autoscaling_group_name	The name of the Auto Scaling Group.
autoscaling_lifecycle_hook_name	The name of the Lifecycle Hook for the Auto Scaling Group.
eventbridge_rule_arn	The ARN of the Eventbridge rule for the EC2 lifecycle transition.
eventbridge_target_arn	The ARN of the Eventbridge target corresponding to the Eventbridge rule for the EC2 lifecycle transition.
iam_role_arn	The ARN of the IAM role associated with the Autoscaling Group
ssm_document_arn	The ARN of the SSM document.

References

cloudposse/terraform-aws-components - Cloud Posse's upstream component

Component: github-runners

Usage​

Configuration​

API Token​

Requirements​

Providers​

Modules​

Resources​

Inputs​

Outputs​

References​