Struct Client

pub struct Client { /* private fields */ }

IMDSv2 Client

Client for IMDSv2. This client handles fetching tokens, retrying on failure, and token caching according to the specified token TTL.

Note: This client ONLY supports IMDSv2. It will not fallback to IMDSv1. See transitioning to IMDSv2 for more information.

Note: When running in a Docker container, all network requests will incur an additional hop. When combined with the default IMDS hop limit of 1, this will cause requests to IMDS to timeout! To fix this issue, you’ll need to set the following instance metadata settings :

amazonec2-metadata-token=required
amazonec2-metadata-token-response-hop-limit=2

On an instance that is already running, these can be set with ModifyInstanceMetadataOptions. On a new instance, these can be set with the MetadataOptions field on RunInstances.

For more information about IMDSv2 vs. IMDSv1 see this guide

Client Configuration

The IMDS client can load configuration explicitly, via environment variables, or via ~/.aws/config. It will first attempt to resolve an endpoint override. If no endpoint override exists, it will attempt to resolve an EndpointMode. If no EndpointMode override exists, it will fallback to IpV4. An exhaustive list is below:

Endpoint configuration list

1. Explicit configuration of Endpoint via the builder:

use aws_config::imds::client::Client;
let client = Client::builder()
  .endpoint("http://customidms:456/").expect("valid URI")
  .build();

2. The AWS_EC2_METADATA_SERVICE_ENDPOINT environment variable. Note: If this environment variable is set, it MUST contain to a valid URI or client construction will fail.

3. The ec2_metadata_service_endpoint field in ~/.aws/config:

[default]
# ... other configuration
ec2_metadata_service_endpoint = http://my-custom-endpoint:444

4. An explicitly set endpoint mode:

use aws_config::imds::client::{Client, EndpointMode};
let client = Client::builder().endpoint_mode(EndpointMode::IpV6).build();

5. An endpoint mode loaded from the AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE environment variable. Valid values: IPv4, IPv6

6. An endpoint mode loaded from the ec2_metadata_service_endpoint_mode field in ~/.aws/config:

[default]
# ... other configuration
ec2_metadata_service_endpoint_mode = IPv4

7. The default value of http://169.254.169.254 will be used.

Implementations

impl Client

pub fn builder() -> Builder

IMDS client builder

pub async fn get( &self, path: impl Into<String>, ) -> Result<SensitiveString, ImdsError>

Retrieve information from IMDS

This method will handle loading and caching a session token, combining the path with the configured IMDS endpoint, and retrying potential errors.

For more information about IMDSv2 methods and functionality, see Instance metadata and user data

Examples

use aws_config::imds::client::Client;
let client = Client::builder().build();
let ami_id = client
  .get("/latest/meta-data/ami-id")
  .await
  .expect("failure communicating with IMDS");

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.