Port Mappings
Expose container ports so load balancers and other containers can reach them.
Port mappings declare which container ports are open. In awsvpc mode the container port is reached directly on the task's own network interface.
Fields
- containerPort — the port your app listens on.
- protocol —
tcp(default) orudp. - name — optional, used by Service Connect.
With EC2 bridge mode you also set hostPort (or 0 for a dynamic port).
Example
{
"portMappings": [
{
"name": "http",
"containerPort": 8080,
"protocol": "tcp"
},
{
"name": "metrics",
"containerPort": 9090,
"protocol": "tcp"
}
]
}When to use it
- A web service exposes container port 8080 in its task definition so the ALB target group can forward HTTP traffic to the running tasks.
- A UDP game server maps container port 7777 with the udp protocol so players can connect directly to the task's ENI IP.
- A developer uses Service Connect port names in port mappings so other ECS services can discover this service by DNS without hardcoding IPs.
More examples
Basic HTTP Port Mapping
Exposes TCP port 80 from the container so an ALB target group can register the task's ENI IP and route HTTP traffic to it.
{
"name": "web",
"image": "nginx:alpine",
"portMappings": [
{
"containerPort": 80,
"protocol": "tcp"
}
]
}Named Port for Service Connect
Adds a port name and application protocol to the mapping so ECS Service Connect can register it as a discoverable endpoint.
{
"name": "api",
"image": "my-api:latest",
"portMappings": [
{
"name": "api-http",
"containerPort": 8080,
"protocol": "tcp",
"appProtocol": "http"
}
]
}UDP Port for Game Server
Maps both a UDP game port and a TCP RCON port, showing that multiple protocols can be exposed from one container definition.
{
"name": "game-server",
"image": "game-srv:latest",
"portMappings": [
{"containerPort": 7777, "protocol": "udp"},
{"containerPort": 27015, "protocol": "tcp"}
]
}
Discussion