# `IMDS.Providers.AWS`

AWS EC2 Instance Metadata Service, version 2 (IMDSv2).

The provider asks for a session token with `PUT /latest/api/token` and sends
the token in the `x-aws-ec2-metadata-token` header of the metadata requests
of one operation. A request that answers with HTTP 401 asks for a new token
one time.

IMDSv1 is used when the token request answers with HTTP 403, 404 or 405 and
the `:aws_imds_v1_fallback` option is not `false`. The fallback is enabled
by default.

The region comes from `/latest/dynamic/instance-identity/document` when that
document is available. The fallback derives the region from the availability
zone, including local zones such as `us-west-2-lax-1a` and partitions such as
`us-iso-east-1a`. A failed document request other than HTTP 404 does not
start the fallback: a timeout stays a timeout.

The identity document also gives the instance type and the account ID, which
the identity map returns as `instance_type` and `scope_id`. The fallback
reads the instance type from `/latest/meta-data/instance-type` and leaves
`scope_id` empty.

# `region_from_zone`

```elixir
@spec region_from_zone(binary() | nil) :: binary() | nil
```

Derive the region from an availability zone name.

The identity document has an authoritative region. Use this function only
when that document does not give the region.

## Examples

    iex> IMDS.Providers.AWS.region_from_zone("us-west-2a")
    "us-west-2"

    iex> IMDS.Providers.AWS.region_from_zone("us-west-2-lax-1a")
    "us-west-2"

    iex> IMDS.Providers.AWS.region_from_zone("us-iso-east-1a")
    "us-iso-east-1"

    iex> IMDS.Providers.AWS.region_from_zone(nil)
    nil

---

*Consult [api-reference.md](api-reference.md) for complete listing*