view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# TROUBLESHOOTING

## Warning: task placed in a public subnet

When running a task you may see:

    [2025/08/05 03:40:58] run-task: subnet-id: [subnet-7c160c37] is in a public subnet...consider running your jobs in a private subnet

This means the task is being scheduled in a subnet that has a
0.0.0.0/0 route to an Internet Gateway (a public subnet).

While not fatal, placing tasks in public subnets is discouraged unless
you have a specific need.

### Why this matters

Running tasks in public subnets can introduce risk and operational
surprises:

- Accidental exposure

    If the task is assigned a public IP and the security group allows
    inbound access, it may be reachable from the internet.

- Unintended dependency

    Public-subnet egress typically relies on a public IP and the Internet
    Gateway. That can bypass intended egress controls, logging, or central
    inspection.

- Narrow security margin

    Safety depends entirely on security groups and NACLs. A small
    misconfiguration can expose services or data.

### Recommended pattern

Use private subnets for most Fargate workloads. Private subnets do not
route directly to the internet.

If the task needs outbound access (for example, to pull images from
ECR or call external APIs), use one of:

- A NAT Gateway (private subnet egress to the internet)
- VPC interface endpoints for ECR (ecr.api and ecr.dkr) and a
gateway endpoint for S3, so image pulls stay inside the VPC with no
public IPs

For public-facing applications, the common pattern is: tasks in
private subnets, fronted by a public Application Load Balancer in
public subnets.

### When is a public subnet acceptable?

Use a public subnet only when the task itself must have a public IP
and terminate client connections directly (uncommon). If you do:

- Set assignPublicIp=ENABLED so the task can reach the internet
via the Internet Gateway
- Keep security groups locked down and monitor egress on TCP 443

### Note on image pulls

To pull from ECR, the task needs a path to ECR API, ECR DKR, and S3:

- Public subnet: requires a public IP (assignPublicIp=ENABLED),
unless you provision VPC endpoints
- Private subnet: works via a NAT Gateway, or entirely private
via VPC endpoints (no public IPs)

## My task fails with this message:

    ResourceInitializationError: unable to pull secrets or registry auth:
    The task cannot pull registry auth from Amazon ECR: There is a
    connection issue between the task and Amazon ECR. Check your task
    network configuration. operation error ECR: GetAuthorizationToken,
    exceeded maximum number of attempts, 3, https response error
    StatusCode: 0, RequestID: , request send failed, Post
    "https://api.ecr.us-east-1.amazonaws.com/": dial tcp 44.213.79.10:443:
    i/o timeout

This error usually occurs when your task is launched in a subnet that
does not have outbound access to the internet. Internet access - or a
properly configured VPC endpoint - is required for Fargate to
authenticate with ECR and pull your container image.

### Common causes

- The task was placed in a public subnet but was not assigned a
public IP.
- The task was placed in a private subnet without access to a
NAT gateway or VPC endpoints.

Even though the subnet may have a route to an Internet Gateway (i.e.,
it is technically a "public" subnet), if the task does not receive a
public IP, it cannot use that route to reach external services like
ECR or Secrets Manager.

### How to fix it

- If using public subnets, ensure the task is assigned a public
IP.
- If using private subnets, ensure a NAT gateway is available
and the subnet has a route to it.
- Alternatively, configure VPC endpoints for ECR, Secrets
Manager, and related services to avoid needing internet access
altogether.

### Note on Subnet Selection

`App::FargateStack` attempts to prevent this situation by analyzing
your VPC configuration during planning. It categorizes subnets as
private or public and evaluates whether they provide the necessary
network access to launch a Fargate task successfully. The framework
warns if you attempt to use a subnet that lacks internet or endpoint
access.

## My task failed to start and the reason is unclear

This is one of the most common and frustrating scenarios when working