Prerequisites

Three gates before you start: a recent AWS CLI, a Region with ECS Gateway, and credentials that can create the networking, IAM, ECS, and load balancer resources the lab touches.

AWS CLI2.38.3 or newer (v2 only)

Region

Any commercial · lab uses ap-southeast-6

AccessVPC · IAM · ECS · ELB in that Region

AWS CLI and Region

You need AWS CLI 2.38.3 or later. That is the first v2 release with create-gateway and the other ECS Gateway commands. CLI v1 never includes these commands.

macOS
Linux

brew install awscli
# already installed: brew upgrade awscli

Install unzip and curl first if needed (sudo apt install -y unzip curl or sudo dnf install -y unzip curl).

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install --update

ARM:

curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install --update

aws --version
aws sts get-caller-identity >/dev/null
aws ecs create-gateway help

aws --version must show aws-cli/2.38.3 or newer. If help says the command is invalid, the CLI is too old. get-caller-identity only checks that you are signed in; redirect keeps account details out of the terminal scrollback you might copy.

ECS Gateway is available in all commercial Regions. Credentials must be able to call ECS, EC2, IAM, and ELB in the Region where you run the lab. The lab uses ap-southeast-6 (Asia Pacific — New Zealand). Opt in that Region on the account if it is not already enabled.

Permissions

Your credentials need enough access across four services:

NetworkingVPC, subnets, internet gateway, route tables

IAM

Create roles, attach managed policies, iam:PassRole for the infra and task execution roles

ECS + Gateway

Clusters, task definitions, services, and the gateway APIs (CreateGateway, associate, list/describe routes, delete)

Load balancingELB access so ECS can provision the ALB path on your behalf

Shell variables

Keep one shell for the whole lab. Later pages reuse these names.

export AWS_PAGER=""
export AWS_REGION=ap-southeast-6
export AWS_DEFAULT_REGION="$AWS_REGION"
export NAME=ecs-gw-lab

aws sts get-caller-identity >/dev/null
echo "Authenticated. region=$AWS_REGION NAME=$NAME"

Confirm you are signed in. Do not paste account IDs, ARNs, or other identity output into issues, PRs, or docs.

Lab path

1Shared setup

VPC + infra roles

2Choose a pathEC2 or Fargate — own cluster + gateway each

3Tear downthe path you ran, then the shared VPC

Create VPC