Skip to main content
For enhanced security, you can connect to Ona’s management plane and AWS services using AWS PrivateLink VPC endpoints instead of traversing the public internet.
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.

​
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’re 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 VPC Endpoints

Replace <region> with your AWS region when creating these endpoints.

​
Interface Endpoints

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
Elastic Load Balancingcom.amazonaws.<region>.elasticloadbalancing
ACMcom.amazonaws.<region>.acm

​
Gateway Endpoints

ServiceVPC Endpoint Service Name
S3com.amazonaws.<region>.s3
DynamoDBcom.amazonaws.<region>.dynamodb
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

VPC Endpoint Service Settings - Enable Cross Region Support

  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 Cloud Formation template).

VPC Endpoint Network Settings - Enable DNS Names

  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)

​
Verification

After creating the VPC endpoints:
  1. Check endpoint status in the VPC console - all endpoints should show as “Available”
  2. Verify private DNS resolution from an instance in your VPC: 
    # Test resolution of AWS service endpoints
nslookup ec2.<region>.amazonaws.com
    This should resolve to private IP addresses within your VPC CIDR range
  3. Test connectivity by deploying or accessing your runner

​
Troubleshooting

If you encounter issues with VPC endpoints:
  • 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.