The Fargate runner requires direct network access from the ECS task to several AWS service endpoints. Unlike EC2-based runners, Fargate tasks cannot rely on instance-level networking. Each task gets its own elastic network interface (ENI) in your VPC subnets, so the subnets must provide a path to these services.
Required AWS service endpoints
The Fargate runner must reach the following AWS services over HTTPS (port 443):
| Service | Endpoint | Purpose |
|---|
| Secrets Manager | secretsmanager.<region>.amazonaws.com | Retrieve runner token and configuration secrets |
| CloudWatch Logs | logs.<region>.amazonaws.com | Ship runner and container logs |
| ECR API | api.ecr.<region>.amazonaws.com | Authenticate and authorize container image pulls |
| ECR Docker | *.dkr.ecr.<region>.amazonaws.com | Pull runner container images |
| S3 | s3.<region>.amazonaws.com | Download ECR image layers |
<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
You can provide access to these endpoints through any of the following methods. Choose the one that fits your network architecture.
VPC endpoints (AWS PrivateLink)
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.
Create the following VPC endpoints in the same VPC and region as your runner:
Interface endpoints:
| Service | VPC Endpoint Service Name |
|---|
| Secrets Manager | com.amazonaws.<region>.secretsmanager |
| CloudWatch Logs | com.amazonaws.<region>.logs |
| ECR API | com.amazonaws.<region>.ecr.api |
| ECR Docker | com.amazonaws.<region>.ecr.dkr |
| Service | VPC Endpoint Service Name | Type |
|---|
| S3 | com.amazonaws.<region>.s3 | Gateway (recommended) or Interface |
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.
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.
Verifying connectivity
The runner automatically checks connectivity to all required endpoints on startup and every 5 minutes. Results are reported to the management plane as a Fargate network readiness status.
Each endpoint check:
- Resolves the hostname via DNS
- Opens a direct TCP connection on port 443
The report classifies each endpoint’s access type:
| Access type | Meaning |
|---|
vpc_endpoint | DNS resolved to private IPs. Traffic stays within the VPC |
nat_gateway | DNS resolved to public IPs, task has no public IP. Traffic routes through NAT |
internet_gateway | DNS resolved to public IPs, task has a public IP. Traffic routes through IGW |
Troubleshooting
Runner fails to start or reports degraded status
-
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).
-
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.
-
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
-
Check public IP assignment (if using internet gateway):
- Verify the
AssignPublicIp CloudFormation parameter is set to true
- Verify the subnet has an internet gateway attached and a route to
0.0.0.0/0 via the IGW
-
DNS resolution: From a test instance in the same subnet, verify interface endpoints resolve correctly:
nslookup secretsmanager.<region>.amazonaws.com
nslookup logs.<region>.amazonaws.com
nslookup api.ecr.<region>.amazonaws.com
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.
