Skip to main content
The AWS runner runs as a Fargate service in your VPC. The ECS cluster contains three services: the runner orchestrator, a proxy for routing traffic to environments, and AWS ADOT for metrics export (when configured). Each Fargate task gets its own elastic network interface (ENI) in your subnets, so the subnets must provide a path to the AWS services the runner depends on.

​
Required AWS service endpoints

The runner must reach the following AWS services over HTTPS (port 443):
ServiceEndpointPurpose
Secrets Managersecretsmanager.<region>.amazonaws.comRetrieve runner token and configuration secrets
CloudWatch Logslogs.<region>.amazonaws.comShip runner and container logs
ECR APIapi.ecr.<region>.amazonaws.comAuthenticate and authorize container image pulls
ECR Docker*.dkr.ecr.<region>.amazonaws.comPull runner container images
S3s3.<region>.amazonaws.comDownload ECR image layers
Replace <region> with your AWS region.
These connections must be direct TCP. The runner verifies reachability by dialing each endpoint directly, bypassing any HTTP proxy. If any endpoint is unreachable, the runner reports a degraded network status.

​
Connectivity options

Choose the method that fits your network architecture.

​
NAT gateway

Route traffic from private subnets to AWS service public endpoints via a NAT gateway in a public subnet. When to use: Private subnets that already have a NAT gateway for general internet access. No additional configuration is needed. As long as the Fargate task subnets have a route to a NAT gateway, the runner can reach AWS service endpoints over their public addresses.

​
Internet gateway (with public IP)

Assign a public IP directly to the Fargate task and route traffic through an internet gateway. When to use: Public subnets without NAT gateway, or development/test environments where simplicity is preferred. To enable this, set the Assign Public IP CloudFormation parameter to true when deploying the runner stack. This causes ECS to assign a public IP to each Fargate task ENI.
If your Fargate task subnets use an internet gateway but you do not enable public IP assignment, the tasks will have no outbound connectivity and the runner will fail to start.
Route traffic to AWS services over private IPs within your VPC, without traversing the public internet. When to use: Private subnets with no internet access, or when security policy prohibits public internet egress. See VPC endpoints reference below for the full list of endpoints and creation instructions.
Cost consideration: VPC endpoints incur additional AWS charges (~$7.20/month per endpoint per AZ plus data processing fees). See AWS PrivateLink pricing for details.

​
Transit gateway / VPC peering / VPN

Route traffic to AWS service endpoints through a transit gateway, VPC peering connection, or VPN tunnel to a VPC that has access to the services. When to use: Hub-and-spoke network architectures where AWS service access is centralized in a shared-services VPC. Ensure the route tables on the Fargate task subnets include routes to the AWS service endpoint IP ranges through the transit gateway or peering connection.

​
Automatic connectivity checks

The runner automatically checks connectivity to all required endpoints on startup and every 5 minutes. Results are reported to the management plane as a network readiness status. Each endpoint check:
  1. Resolves the hostname via DNS
  2. Opens a direct TCP connection on port 443
The report classifies each endpoint’s access type:
Access typeMeaning
vpc_endpointDNS resolved to private IPs. Traffic stays within the VPC
nat_gatewayDNS resolved to public IPs, task has no public IP. Traffic routes through NAT
internet_gatewayDNS resolved to public IPs, task has a public IP. Traffic routes through IGW
You can view the readiness status in the runner details on the Ona dashboard.

​
VPC endpoints reference

If your network does not allow public internet egress, create VPC endpoints to give the runner infrastructure private access to AWS services. The table below lists all endpoints required by the runner stack, including those used by the ECS control plane, CloudFormation, environment VMs, and the runner services themselves.

​
Prerequisites

Before creating VPC endpoints, ensure:
  • Your VPC has both DNS hostnames and DNS resolution enabled
  • You have the VPC ID, subnet IDs, and security group IDs ready
  • You are creating endpoints in the same region as your runner deployment
You can enable DNS settings in the VPC Console under Actions > Edit VPC settings.

​
Required interface endpoints

Replace <region> with your AWS region.
ServiceVPC Endpoint Service Name
EC2com.amazonaws.<region>.ec2
ECR APIcom.amazonaws.<region>.ecr.api
ECR Dockercom.amazonaws.<region>.ecr.dkr
SSMcom.amazonaws.<region>.ssm
STScom.amazonaws.<region>.sts
CloudFormationcom.amazonaws.<region>.cloudformation
Secrets Managercom.amazonaws.<region>.secretsmanager
ECScom.amazonaws.<region>.ecs
ECS Agentcom.amazonaws.<region>.ecs-agent
ECS Telemetrycom.amazonaws.<region>.ecs-telemetry
SSM Messagescom.amazonaws.<region>.ssmmessages
EC2 Messagescom.amazonaws.<region>.ec2messages
CloudWatch Logscom.amazonaws.<region>.logs
IAMcom.amazonaws.<region>.iam
Elastic Load Balancingcom.amazonaws.<region>.elasticloadbalancing
ACMcom.amazonaws.<region>.acm
IAM is a global service, but its VPC endpoint is created as a regional interface endpoint. See the AWS documentation on creating an IAM VPC endpoint for setup instructions.

​
Required gateway endpoints

ServiceVPC Endpoint Service Name
S3com.amazonaws.<region>.s3
DynamoDBcom.amazonaws.<region>.dynamodb
We recommend the S3 gateway endpoint because it is free of charge. Gateway endpoints are configured on route tables rather than ENIs. If you need DNS-based private resolution for S3 (e.g. for compliance reasons), use an interface endpoint instead.
Gateway endpoints (S3, DynamoDB) are configured differently than interface endpoints. See the AWS documentation on gateway endpoints for details.

​
Creating VPC endpoints

​
Using AWS CLI

# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
aws ec2 create-vpc-endpoint \
    --vpc-id vpc-xxx \
    --service-name com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2 \
    --vpc-endpoint-type Interface \
    --subnet-ids subnet-xxx subnet-xxx \
    --security-group-ids sg-xxx \
    --private-dns-enabled \
    --service-region us-east-1
For more CLI options and examples, see the AWS CLI reference for create-vpc-endpoint.

​
Using AWS PowerShell

# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
New-EC2VpcEndpoint `
    -VpcId "vpc-xxx" `
    -ServiceName "com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2" `
    -VpcEndpointType "Interface" `
    -SubnetId @("subnet-xxx", "subnet-xxx") `
    -SecurityGroupId @("sg-xxx") `
    -PrivateDnsEnabled $true `
    -ServiceRegion "us-east-1"
For more PowerShell options and examples, see the AWS PowerShell reference for New-EC2VpcEndpoint.

​
Using AWS Management Console

  1. Navigate to VPC Console
  2. Create Endpoint
    • Click “Create endpoint”
    • Name tag (optional): Enter a descriptive name like ona-management-plane
    • Service type: Select “Endpoint services that use NLBs and GWLBs”
  3. Service Settings
    • Service name: Enter com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2
    • Enable Cross Region endpoint: Check this box to connect across regions (Note: For us-east-1 region, leave this unchecked)
    • Region: Select us-east-1 as the region
    • Click “Verify service” to confirm the service is available
AWS VPC endpoint creation showing service name verification and cross-region endpoint settings
  1. Network Settings
    • VPC: Select the same VPC where your runner is deployed
    • Enable DNS name: Check this box to enable private DNS names (this allows app.gitpod.io to resolve to the endpoint)
    • Subnets: Choose private subnets in available AZs (can be the same subnets as your EC2 runner instances)
    • Security groups: Select or create a security group that allows HTTPS traffic (port 443, inbound). Include the runner security group and the security group for environment access (you can find these in the Output section of the Runner CloudFormation template).
AWS VPC endpoint network configuration showing VPC, subnet, and DNS name settings
  1. Create and Verify
    • Click “Create endpoint”
    • Wait for the endpoint status to become “Available”
For detailed instructions on creating and managing VPC endpoints, see the AWS documentation on creating interface endpoints.

​
Key configuration settings

When creating interface endpoints:
  • Enable private DNS names: This allows AWS service hostnames to resolve to your VPC endpoint’s private IP addresses
  • Subnets: Select subnets in multiple availability zones for high availability
  • Security groups: Configure to allow HTTPS (443) traffic from your runner subnets
us-east-1 region specific: When creating VPC endpoints in the us-east-1 region, disable cross-region support. This is due to availability zone mapping differences between AWS accounts that can prevent endpoint creation. The endpoint only needs to exist in one AZ within your VPC. Clients in other AZs can still reach it via DNS.

​
Security group configuration

Your VPC endpoint security group needs these rules: Inbound Rules:
  • Type: HTTPS (443)
  • Source: Your runner subnets CIDR or the security group attached to your runner instances
  • Description: Allow runner access to AWS services
Outbound Rules:
  • Type: All traffic
  • Destination: 0.0.0.0/0 (or keep the default outbound rule)

​
Troubleshooting

​
Runner fails to start or reports degraded status

  1. Check subnet route tables: Verify the subnets assigned to the Fargate service have routes to the required endpoints (via NAT gateway, internet gateway, transit gateway, or VPC endpoints).
  2. Check security groups: The ECS task security group must allow outbound HTTPS (port 443) to the AWS service endpoints. The default AllowAllOutbound rule covers this.
  3. Check VPC endpoint configuration (if using PrivateLink):
    • Ensure private DNS is enabled on interface endpoints
    • Ensure the endpoint security group allows inbound HTTPS from the Fargate task subnets
    • If using an S3 gateway endpoint, ensure it is associated with the correct route tables
  4. Check public IP assignment (if using internet gateway):
  5. DNS resolution: From a test instance in the same subnet, verify endpoints resolve correctly: 
    nslookup secretsmanager.<region>.amazonaws.com
nslookup logs.<region>.amazonaws.com
nslookup api.ecr.<region>.amazonaws.com
    If using VPC interface endpoints, these should resolve to private IPs within your VPC CIDR.
    If using an S3 gateway endpoint (recommended), nslookup s3.<region>.amazonaws.com will still resolve to public IPs. This is expected. Gateway endpoints route traffic via route table entries, not DNS overrides. Verify connectivity by checking that the gateway endpoint is associated with the correct route tables. If using an S3 interface endpoint instead, DNS should resolve to private IPs.

​
VPC endpoint issues

  • DNS resolution fails: Verify DNS hostnames and DNS resolution are enabled on your VPC
  • Connection timeouts: Check security group rules allow HTTPS (443) from runner subnets
  • Endpoint creation fails in us-east-1: Disable cross-region support when creating the endpoint
  • Service unavailable: Ensure the endpoint is in “Available” state and private DNS is enabled
For additional troubleshooting, see the AWS PrivateLink troubleshooting guide.