### Initialize and Apply Terraform Setup Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/permissions-boundary Run these commands to initialize and apply the Terraform configuration in the setup directory. ```bash cd setup terraform init terraform apply cd .. ``` -------------------------------- ### Install Dependencies Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer Navigate to the runner binaries syncer lambda directory and install dependencies using yarn. ```bash cd lambdas/runners yarn install ``` -------------------------------- ### Lambda Configuration Example Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners An example of a JSON object for Lambda configuration, showing an empty config object. ```json { "config": {} } ``` -------------------------------- ### Install Lambda Dependencies Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/webhook Navigate to the webhook Lambda directory and install its Node.js dependencies using yarn. ```bash cd lambdas/webhook yarn install ``` -------------------------------- ### Configure AMI Housekeeper Module Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/ami-housekeeper Example of how to configure and enable the AMI Housekeeper module in your Terraform setup. This includes setting cleanup criteria like minimum age, SSM parameter names to exclude, and tag filters. The `dryRun` option is useful for testing. ```terraform module "ami_housekeeper" { source = "path to module" prefix = "my-prefix" ami_cleanup_config = { ssmParameterNames = ["*/ami-id"] minimumDaysOld = 30 filters = [ { Name = "tag:Packer" Values = ["true"] } ] dryRun = true } log_level = "debug" } ``` -------------------------------- ### Install Lambda Dependencies Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/ami-housekeeper Installs the necessary Node.js dependencies for the Lambda function using yarn. Ensure you are in the `lambdas` directory. ```bash cd lambdas yarn install ``` -------------------------------- ### Example Log Message Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration An example log message from the scale-up function, showing the structure and keys included in log output. ```json { "level": "INFO", "message": "Received event", "service": "runners-scale-up", "timestamp": "2023-03-20T08:15:27.448Z", "xray_trace_id": "1-6418161e-08825c2f575213ef760531bf", "module": "scale-up", "region": "eu-west-1", "environment": "my-linux-x64", "aws-request-id": "eef1efb7-4c07-555f-9a67-b3255448ee60", "function-name": "my-linux-x64-scale-up", "runner": { "type": "Repo", "owner": "test-runners/multi-runner" }, "github": { "event": "workflow_job", "workflow_job_id": "1234" } } ``` -------------------------------- ### Initialize, Validate, and Build Packer Image Source: https://github-aws-runners.github.io/terraform-aws-github-runner/ami-examples Commands to initialize Packer, validate the configuration, and build a custom Linux AL2023 AMI for GitHub runners. Ensure you have Packer installed and AWS credentials configured. ```bash packer init . packer validate . packer build github_agent.linux.pkr.hcl ``` -------------------------------- ### Build Lambda Functions Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/termination-watcher Build the lambda functions locally using yarn. Ensure you have Node.js and yarn installed. ```bash cd lambdas yarn install && yarn dist ``` -------------------------------- ### Log Example for Spot Notifications Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration This JSON structure represents a log message generated by the termination watcher or handler for spot instance warnings or terminations. It includes details like environment, instance ID, type, launch time, and tags. ```json { "level": "INFO", "message": "Received spot notification for ${metricName}", "environment": "default", "instanceId": "i-0039b8826b3dcea55", "instanceType": "c5.large", "instanceLaunchTime": "2024-03-15T08:10:34.000Z", "instanceRunningTimeInSeconds": 68, "tags": [ { "Key": "ghr:environment", "Value": "default" } ... all tags ... ] } ``` -------------------------------- ### Configure Multi Runner Deployment Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner Define multiple runner configurations with specific label matchers and runner settings for different operating systems and architectures. This example shows configurations for 'linux-arm' and 'linux-x64' runners. ```terraform module "multi-runner" { prefix = "multi-runner" github_app = { # app details } multi_runner_config = { "linux-arm" = { matcherConfig : { labelMatchers = [["self-hosted", "linux", "arm64", "arm"]] exactMatch = true } runner_config = { runner_os = "linux" runner_architecture = "arm64" runner_extra_labels = "arm" enable_ssm_on_runners = true instance_types = ["t4g.large", "c6g.large"] ... } ... }, "linux-x64" = { matcherConfig : { labelMatchers = [["self-hosted", "linux", "x64"]] exactMatch = false } runner_config = { runner_os = "linux" runner_architecture = "x64" instance_types = ["m5ad.large", "m5a.large"] enable_ephemeral_runners = true delay_webhook_event = 0 ... } ... } } } ``` -------------------------------- ### Configure Runners with Custom AMI Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/prebuilt Configure the runners module to use a custom AMI by specifying the ami_filter and ami_owners. This example assumes you have built a 'linux-al2023' image. ```hcl module "runners" { ... # set the name of the ami to use ami_filter = { name = ["github-runner-al2023-x86_64-2023*"], state = ["available"] } # provide the owner id of ami_owners = [""] enable_userdata = false ... } ``` -------------------------------- ### Configure Idle Runners Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Specify a configuration to keep a certain number of runners active based on a cron schedule and timezone. This is useful for reducing cold start times, especially for Windows runners. The eviction strategy can be set to 'oldest_first' (default) or 'newest_first'. ```hcl idle_config = [{ cron = "* * 9-17 * * 1-5" timeZone = "Europe/Amsterdam" idleCount = 2 # Defaults to 'oldest_first' evictionStrategy = "oldest_first" }] ``` -------------------------------- ### Create SSM Parameters using AWS CLI Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/external-managed-ssm-secrets Use the AWS CLI to create secure string SSM parameters for your GitHub App ID, private key, and installation ID. Ensure these parameters are created before running Terraform. ```bash # GitHub App ID aws ssm put-parameter \ --name "/github-action-runners/app/github_app_id" \ --value "YOUR_APP_ID" \ --type "SecureString" # GitHub App Private Key aws ssm put-parameter \ --name "/github-action-runners/app/github_app_key_base64" \ --value "YOUR_PRIVATE_KEY" \ --type "SecureString" # GitHub App Installation ID aws ssm put-parameter \ --name "/github-action-runners/app/github_app_webhook_secret" \ --value "YOUR_INSTALLATION_ID" \ --type "SecureString" ``` -------------------------------- ### Initialize and Apply Lambda Downloads Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/external-managed-ssm-secrets Download and apply the necessary Lambda releases for the GitHub runner. Ensure you replace `` with the desired GitHub release version. This step is crucial if you are not building the lambdas locally. ```bash cd ../lambdas-download terraform init terraform apply -var=module_version= cd - ``` -------------------------------- ### Initialize and Apply Lambdas Download Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/ephemeral Run these commands to initialize and apply the Terraform configuration for the lambda downloads. Ensure the version in `lambdas-download/main.tf` is set to a valid GitHub release version. ```bash cd lambdas-download terraform init terraform apply cd .. ``` -------------------------------- ### Initialize and Apply Terraform Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/termination-watcher Initialize the Terraform working directory and apply the configuration to set up the termination watcher. ```bash terraform init terraform apply ``` -------------------------------- ### Initialize and Apply Terraform Module Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/lambda-download Initialize Terraform and apply the module, specifying the desired module version. This process downloads the necessary Lambda distributions. ```bash terraform init terraform apply -var=module_version= ``` -------------------------------- ### Initialize and Apply Lambdas Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/prebuilt Initialize and apply Terraform for downloading or building Lambda functions. Ensure you replace with the appropriate GitHub release version. ```bash cd ../lambdas-download terraform init terraform apply -var=module_version= cd - ``` -------------------------------- ### Initialize and Apply Terraform Deployment Source: https://github-aws-runners.github.io/terraform-aws-github-runner/examples/prebuilt Initialize and apply the Terraform configuration to deploy the GitHub runners. ```bash terraform init terraform apply ``` -------------------------------- ### Terraform Module for IAM Setup Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/setup-iam-permissions Use this Terraform code to configure an IAM role for deploying the root module, optionally with permission boundaries. Ensure you have the correct AWS account ID and desired namespaces defined. ```terraform module "iam" { source = "../../" environment = "default" account_id = "123456789" namespaces = { boundary_namespace = "boundaries" role_namespace = "runners" policy_namespace = "runners" instance_profile_namespace = "runners" } } output "role" { value = module.iam.role } output "boundary" { value = module.iam.boundary } ``` -------------------------------- ### Configure Instance Termination Watcher Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners Set up the spot instance termination watcher, including enabling/disabling features, memory limits, and lambda function details. ```terraform object({ enable = optional(bool, false) features = optional(object({ enable_spot_termination_handler = optional(bool, true) enable_spot_termination_notification_watcher = optional(bool, true) }), {}) memory_size = optional(number, null) s3_key = optional(string, null) s3_object_version = optional(string, null) timeout = optional(number, null) zip = optional(string, null) }) ``` -------------------------------- ### Extend EventBridge Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Disable the default EventBridge mode and configure custom EventBridge rules and targets. This example shows how to disable the default EventBridge behavior and set up a custom CloudWatch Event Rule to capture all GitHub events, routing them to a specified ARN. ```terraform module "runners" { source = "github-aws-runners/github-runners/aws" ... eventbridge = { enable = false } ... } locals { event_bus_name = module.runners.webhook.eventbridge.event_bus.name } resource "aws_cloudwatch_event_rule" "example" { name = "${local.prefix}-github-events-all" description = "Caputure all GitHub events" event_bus_name = local.event_bus_name event_pattern = < event_bus_name = local.event_bus_name role_arn = aws_iam_role.event_rule_firehose_role.arn } data "aws_iam_policy_document" "event_rule_firehose_role" { statement { actions = ["sts:AssumeRole"] principals { type = "Service" identifiers = ["events.amazonaws.com"] } } } resource "aws_iam_role" "event_rule_role" { name = "${local.prefix}-eventbridge-github-rule" assume_role_policy = data.aws_iam_policy_document.event_rule_firehose_role.json } data aws_iam_policy_document firehose_stream { statement { INSER_YOUR_POIICY_HERE_TO_ACCESS_THE_TARGET } } resource "aws_iam_role_policy" "event_rule_firehose_role" { name = "target-event-rule-firehose" role = aws_iam_role.event_rule_firehose_role.name policy = data.aws_iam_policy_document.firehose_stream.json } ``` -------------------------------- ### Run Tests Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer Execute tests for the runner binaries syncer lambda using vitest. AWS and GitHub calls are mocked. ```bash yarn run test ``` -------------------------------- ### Configure SSM Housekeeper Lambda Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/multi-runner Sets up the SSM housekeeper lambda for managing runner tokens and JIT configurations. Allows customization of schedule, memory, timeout, and configuration path. ```terraform object({ schedule_expression = optional(string, "rate(1 day)") enabled = optional(bool, true) lambda_memory_size = optional(number, 512) lambda_timeout = optional(number, 60) config = object({ tokenPath = optional(string) minimumDaysOld = optional(number, 1) dryRun = optional(bool, false) }) }) ``` ```json { "config": {} } ``` -------------------------------- ### Configure AMI using SSM Parameter Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Provide an SSM parameter ARN in the `ami` object for the module to use a specific AMI ID. The module grants necessary Lambda access. ```hcl ami = { id_ssm_parameter_arn = "arn:aws:ssm:region:account:parameter/path/to/ami/parameter" } ``` -------------------------------- ### Configure AMI using Filters Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Use the `ami` object with `filter` and `owners` to dynamically select an AMI. The module stores the AMI ID in an SSM parameter. ```hcl ami = { filter = { name = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-*"] state = ["available"] } owners = ["amazon"] } ``` -------------------------------- ### Enable Metrics in GitHub Runner Module Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Set `metrics.enable = true` to activate all module-managed metrics. Individual metrics can be configured via the `metrics` object. Metrics are created in the 'GitHub Runners' namespace. ```hcl metrics { enable = true } ``` -------------------------------- ### Configure GitHub Runner Terraform Module Source: https://github-aws-runners.github.io/terraform-aws-github-runner/getting-started Instantiate the GitHub runner module with AWS region, VPC, subnet IDs, and GitHub App credentials. Ensure the private key is base64 encoded. ```hcl module "github-runner" { source = "github-aws-runners/github-runner/aws" version = "REPLACE_WITH_VERSION" aws_region = "eu-west-1" vpc_id = "vpc-123" subnet_ids = ["subnet-123", "subnet-456"] prefix = "gh-ci" github_app = { key_base64 = "base64string" id = "1" webhook_secret = "webhook_secret" } webhook_lambda_zip = "lambdas-download/webhook.zip" runner_binaries_syncer_lambda_zip = "lambdas-download/runner-binaries-syncer.zip" runners_lambda_zip = "lambdas-download/runners.zip" enable_organization_runners = true } ``` -------------------------------- ### Enable Termination Watcher Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Set `instance_termination_watcher.enable = true` to activate the termination watcher feature, which monitors for spot instance terminations. This feature is experimental and disabled by default. ```hcl instance_termination_watcher { enable = true } ``` -------------------------------- ### Cron Expression Syntax Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Illustrates the syntax for cron expressions used in scheduling pool adjustments and idle runner configurations. Supports seconds, minutes, hours, day of month, month, and day of week. ```text * * * * * * ┬ ┬ ┬ ┬ ┬ ┬ │ │ │ │ │ | │ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun) │ │ │ │ └───── month (1 - 12) │ │ │ └────────── day of month (1 - 31) │ │ └─────────────── hour (0 - 23) │ └──────────────────── minute (0 - 59) └───────────────────────── second (0 - 59, optional) ``` -------------------------------- ### SSM Paths Configuration Object Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners Defines the structure for SSM paths, specifying root, tokens, and config paths. ```hcl object({ root = string tokens = string config = string }) ``` -------------------------------- ### Configure EC2 Runner Metadata Options Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners Define metadata options for EC2 runner instances. Disable instance metadata tags only when using custom scripts for runner bootstrapping. ```HCL { "http_endpoint": "enabled", "http_put_response_hop_limit": 1, "http_tokens": "required", "instance_metadata_tags": "enabled" } ``` -------------------------------- ### SQS Build Queue Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners Defines the SQS queue for consuming accepted build events. Requires the ARN and URL of the SQS queue. ```terraform object({ arn = string url = string }) ``` -------------------------------- ### Package Lambda Function Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runner-binaries-syncer Compile TypeScript/JavaScript sources into a single file using ncc for the runner binaries syncer lambda. ```bash yarn run dist ``` -------------------------------- ### Download Lambda Artifacts with Terraform Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/public/download-lambda Use this module to download specified Lambda artifacts by providing a list of Lambda names and their corresponding tags. Ensure your Terraform and AWS provider versions meet the module's requirements. ```terraform module "lambdas" { source = "" lambdas = [ { name = "webhook" tag = "v0.15.0" }, { name = "runners" tag = "v0.15.0" }, { name = "runner-binaries-syncer" tag = "v0.15.0" } ] } ``` -------------------------------- ### GitHub App Parameters Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/ssm Defines the structure for GitHub app parameters, including options for providing keys, IDs, and webhook secrets directly or via SSM parameters. Use SSM parameters for sensitive information. ```terraform object({ key_base64 = optional(string) key_base64_ssm = optional(object({ arn = string name = string })) id = optional(string) id_ssm = optional(object({ arn = string name = string })) webhook_secret = optional(string) webhook_secret_ssm = optional(object({ arn = string name = string })) }) ``` -------------------------------- ### Configure Metrics for GitHub Runners Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners Enables and configures metrics for the GitHub Runners module. By default, metrics are disabled to prevent additional costs. All metrics are created unless explicitly configured otherwise. ```terraform object({ enable = optional(bool, false) namespace = optional(string, "GitHub Runners") metric = optional(object({ enable_github_app_rate_limit = optional(bool, true) enable_job_retry = optional(bool, true) enable_spot_termination_warning = optional(bool, true) }), {}) ``` -------------------------------- ### Lambda Configuration Object Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners Defines the configuration structure for the Lambda function, including schedule, state, memory, timeout, and nested config parameters like token path and dry run. ```hcl object({ schedule_expression = optional(string, "rate(1 day)") state = optional(string, "ENABLED") lambda_memory_size = optional(number, 512) lambda_timeout = optional(number, 60) config = object({ tokenPath = optional(string) minimumDaysOld = optional(number, 1) dryRun = optional(bool, false) }) }) ``` -------------------------------- ### S3 Runner Binaries Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/internal/runners Specifies the S3 bucket details for cached GitHub runner binaries. Requires ARN, ID, and key of the S3 bucket. ```terraform object({ arn = string id = string key = string }) ``` -------------------------------- ### Enable Tracing Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Enable tracing for Lambda functions by providing the `tracing_config` option. This generates timelines for function lifecycle, GitHub API calls, and AWS SDK calls. ```hcl tracing_config { # Optional: capture_http_requests = true } ``` -------------------------------- ### Configure SSM Paths Source: https://github-aws-runners.github.io/terraform-aws-github-runner/modules/runners Define the root path structure for storing configuration and secrets in SSM. Customize the root, app, runners, webhook paths, and whether to use a prefix. ```HCL object({ root = optional(string, "github-action-runners") app = optional(string, "app") runners = optional(string, "runners") webhook = optional(string, "webhook") use_prefix = optional(bool, true) }) ``` -------------------------------- ### Ephemeral Runner Configuration Source: https://github-aws-runners.github.io/terraform-aws-github-runner/configuration Configure runners to be ephemeral, used for a single job. This involves setting `delay_webhook_event` to 0 for immediate processing and optionally enabling `enable_job_queued_check` to prevent unnecessary runner creation. Adjust SQS retention and redrive settings for error handling. ```hcl # Example configuration for ephemeral runners (commented out in source) # minimum_running_time_in_minutes = 10 # delay_webhook_event = 0 # enable_job_queued_check = true # job_queue_retention_in_seconds = 3600 # redrive_build_queue = true ```