Setting up AWS runners

Prerequisites

• Admin access to the Gitpod organization.
• AWS account with permissions to deploy the CloudFormation stack.

Create AWS runner

Go to Settings -> Runners, and press Setup an AWS runner:

Choose a name and select the AWS region to deploy the runner into, then press Create. This creates the runner reference in Gitpod. You will now need to run the CloudFormation stack to fully deploy your runner.

Note: runners are regional, and can only launch environments in the AWS region they are deployed in. For a multi-region support we recommend to set up multiple runners in different regions. The region cannot be changed once deployed, but you can deploy multiple runners in different regions.

CloudFormation template

Next, ensure you are signed into the right AWS account in the AWS console, and then press Open AWS CloudFormation to start deploying the runner into your AWS account. This will link you to the AWS console to create the CloudFormation stack:

Most parameters are auto-filled already. For Network Configuration, choose a VPC (e.g. the default VPC) and one or more Availability Zones and subnets. The runner will create environments in the selected network configuration values.

When done with configuring the stack parameters, press Create stack. The stack is relatively simple and includes e.g. an ECS service and DynamoDB.

Wait until the Stack is deployed successfully, and return to Gitpod Desktop.

The CloudFormation stack should deploy between 3-10 minutes.

Once deployed you should see a screen like this:

Infrastructure Prerequisites

Note: By utilizing the default VPC provided by AWS in your account, you can meet the basic networking requirements for the EC2 Runner deployment, as it comes pre-configured with essential components such as internet gateways, route tables, and subnets across multiple Availability Zones.

1. Existing VPC: A pre-configured Virtual Private Cloud (VPC) with the following characteristics:
   • Spanning multiple Availability Zones (AZs) for high availability (2-3 AZs recommended)
   • Configured route tables with internet connectivity
2. Subnets: Multiple subnets within the VPC, distributed across the chosen AZs:
   • Public subnets with internet access for the EC2 (development environments)
   • Sufficient IP address space to accommodate the expected number of EC2 instances (development environments)
3. IAM Permissions: IAM role(s) with permissions to create and manage EC2 instances, ECS tasks, IAM roles, CloudFormation stacks, SSM parameters, S3 buckets, DynamoDB tables, CloudWatch logs, and Secrets Manager secrets.

Networking Requirements

To facilitate secure and efficient communication between components of the EC2 Runner system, as well as to enable proper integration with existing network infrastructure, the following networking configurations are required:

1. Security Groups:

   • Ability to create or use existing security groups
   • Inbound rules allowing SSH access (port 22)
   • Outbound internet access

2. VPC Endpoints (recommended):

   • S3 Gateway Endpoint
   • DynamoDB Gateway Endpoint
   • Interface Endpoints for ECS, ECR, CloudWatch Logs, and SSM (if using private subnets)

AWS Services

EC2 Runners deployment relies on a suite of AWS services that must be configured as below to ensure smooth operation and management of the infrastructure. The following services are essential components of the setup:

• EC2: Enabled and configured to allow launching instances in the specified VPC and subnets.
• ECS: Fargate enabled and configured to run containerized tasks.
• S3: Enabled for storing container images and other artifacts.
• DynamoDB: Available for storing resource information.
• CloudWatch Logs: Configured for logging from ECS tasks and EC2 instances.
• Systems Manager (SSM): Parameter Store enabled for configuration management.
• Secrets Manager: Available for storing sensitive information such as API tokens.

Configuring repository access

Before the runner can be used to launch any environment, it must be configured with a provider that can access your repos (this includes public repositories).

Press Add a provider and select one of the supported providers such as GitHub:

Configure the host, or leave the default if using github.com. If you want to support multiple hosts, you can add a separate provider for each host.

Next, choose at least one of OAuth or Personal Access Token support. You can set up an OAuth app to make it easy for users to sign in quickly. Personal Access Token allows users to provide their own PAT to sign in. Users will be prompted to authenticate when they start a new environment on the runner.

Press Save once done. You can now start environments for repos on the specified host:

Whenever a user starts an environment for the first time for that host, they will get prompted to authenticate first, and get the option to authenticate through the OAuth app or using a PAT token (whichever is configured in the integration). Once authenticated, the token is encrypted and stored to be remembered for the next time the user creates an environment for this host.

When an admin disables OAuth/PAT support in an integration, or deletes an integration entirely for a host, any existing tokens obtained for the host through the disabled/deleted authentication method will get deleted and users might have to re-authenticate before they can create environments again for that host.