aws-samples/cdk-graviton2-gh-sh-runner

Building ARM64 Applications on AWS Graviton2 using the AWS CDK and Self-Hosted Runners for GitHub Actions

Stack Components

• ./app.py - The main entry point to the stack requires the $VPC_CIDR environment variable to be set.
• cdk_graviton2_gh_sh_runner/vpc_stack.py – Defines a Virtual Private Cloud (VPC) across two Availability Zones with an IPv4 CIDR block that you set via $VPC_CIDR. A NAT gateway will be created in each public subnet for egress traffic through the VPC’s internet gateway. The private subnet contains the EC2 instance for the self-hosted runner.
• cdk_graviton2_gh_sh_runner/ec2_stack.py – This defines our AMI, the instance type, and configuration. We’ll use Amazon Linux 2 for the operating system on the runner instance. We also create an IAM role, and add the AmazonSSMManagedInstanceCore policy.

Prerequisites

The following steps are based on these instructions for Adding self-hosted runners - GitHub Docs.

1. Navigate to the GitHub organization where you'd like to configure a custom GitHub Action Runner.
2. Under your organization, click Settings.
3. In the left sidebar, click Actions, then click Runners.
4. Under "Runners", click Add runner.
5. Copy the token value under the "Configure" section.

NOTE: this is an automatically-generated time-limited token to authenticate the request.

Next, launch an AWS CloudShell environment, and create the following AWS SSM Parameter Store values in the AWS account where you'll be deploying the AWS CDK stack. The names gh-url and gh-token, and types String and SecureString, respectively, are required for this integration:

aws ssm put-parameter --name gh-token --type SecureString --value ABCDEFGHIJKLMNOPQRSTUVWXYZABC
aws ssm put-parameter --name gh-url --type String --value https://github.com/your/organization

Installation and Deployment

AWS CloudShell is the preferred environment for installation and deployment.

sudo npm install aws-cdk -g
git clone https://github.com/aws-samples/cdk-graviton2-gh-sh-runner.git
cd cdk-graviton2-gh-sh-runner
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export VPC_CIDR="192.168.0.0/24" # Set your CIDR here.
export AWS_ACCOUNT=`aws sts get-caller-identity | jq -r '.Account'`
cdk bootstrap aws://$AWS_ACCOUNT/$AWS_REGION
cdk deploy --all
# Note: Before the EC2 stack deploys you will be prompted for approval
# The message states 'This deployment will make potentially sensitive changes according to your current security approval level (--require-approval broadening).' and prompts for y/n

These steps will deploy an EC2 instance self-hosted runner that is added to your GitHub organization (as specified by the gh-url parameter in the prerequisites).

You can confirm the self-hosted runner has been successfully added to your organization by navigating to the Settings tab for your GitHub organization, selecting the Actions options from the left-hand panel, then selecting Runners.

Troubleshooting

Refer to the instance ID outputted as part of the CDK stack, then use one of the following steps to get console output for the instance: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-console.html#instance-console-console-output Scroll to the GitHub Actions self-hosted runner registration output.

Common issues include:

• The provided GitHub token is not authorized for the provided GitHub URL.
• The provided GitHub URL is incorrect.
• There is a typo in one of the parameter store values.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.