aws / aws/containers-roadmap

[ECS Fargate] [request]: Document (and confirm stability of) AvailabilityZoneID in ECS task metadata v4 response

Open
#2,850 0 comments 1 reaction 0 assignees View on GitHub
ECS
Dominant language
Shell
Stars
5.4k
Forks
334
PR merge metrics
No merged PRs in 30d

Description

### Community Note

* Please vote on this issue by adding a 👍 [reaction](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) to the original issue to help the community and maintainers prioritize this request
* Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
* If you are interested in working on this issue or have submitted a pull request, please leave a comment

**Tell us about your request**

Please document the `AvailabilityZoneID` field in the ECS task metadata v4 response for **Fargate** (https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-fargate-response.html), and confirm whether it is officially supported and safe to depend on for Fargate tasks.

Today the docs list only `AvailabilityZone` (the AZ **name**, e.g. `us-east-1a`), but the `GET ${ECS_CONTAINER_METADATA_URI_V4}/task` response on Fargate is **also returning `AvailabilityZoneID`** (the zonal **ID**, e.g. `use1-az4`) — undocumented.

**Which service(s) is this request for?**

Fargate (Amazon ECS)

**Tell us about the problem you're trying to solve. What are you trying to do, and why is it hard?**

We run Kafka consumers on ECS Fargate and want to set the consumer's `client.rack` to the task's Availability Zone **ID** to enable rack-aware (same-AZ) fetching from Amazon MSK, which reduces cross-AZ data-transfer cost and latency. Kafka/MSK rack awareness keys on the AZ **ID** (e.g. `use1-az4`), not the AZ **name** (`us-east-1a`), and the name→ID mapping is account-specific — so deriving the ID from the documented `AvailabilityZone` field would require an extra `DescribeAvailabilityZones` call per account/region.

We observe that on **Fargate platform version 1.4.0** the task metadata v4 endpoint already returns `AvailabilityZoneID` directly, which is exactly what we need. But because it isn't documented for Fargate, we can't tell whether it's safe to rely on:

- Is `AvailabilityZoneID` officially supported on Fargate (all PV 1.4.x and later), or is it incidental/subject to change?
- Is it covered by the v4 metadata stability guarantee (existing fields will not be removed or renamed)?
- When will it be added to the Fargate v4 response documentation?

For context, it looks like an intentional addition on the agent side: it's a named field (`AvailabilityZoneID`) in the shared TMDS v4 response struct (`ecs-agent/tmds/handlers/v4/state/response.go`), added in aws/amazon-ecs-agent#4848 ("support AZ ID in TMDS", CHANGELOG: "Enhancement - Support AZ ID for TMDS"). That PR populates the value from EC2 IMDS for the **EC2** launch type; this request is specifically about the **Fargate** launch type, where the field also appears but is undocumented.

**Are you currently working around this issue?**

Yes — we read `AvailabilityZoneID` from the task metadata defensively and fall back to a sentinel value when it's absent, so we don't hard-depend on it. We'd prefer to consume it as a documented, supported contract.

**Additional context**

- Endpoint: `GET ${ECS_CONTAINER_METADATA_URI_V4}/task` on Fargate platform version **1.4.0**
- Observed: `"AvailabilityZoneID": ""` returned alongside the documented `"AvailabilityZone": ""`
- Docs page to update: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-fargate-response.html
- Related agent change: https://github.com/aws/amazon-ecs-agent/pull/4848

Contributor guide

Open the contributing guide

Research direction

Start with the ECS task metadata v4 Fargate response documentation page and compare its listed fields with the observed response on Fargate platform version 1.4.0. Review the linked ECS agent change for context, then confirm whether AvailabilityZoneID is supported and covered by the metadata stability guarantee. Done means the documentation is updated with the field and its support status.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
cloud, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.