1// Package ec2rolecreds provides the credentials provider implementation for
 2// retrieving AWS credentials from Amazon EC2 Instance Roles via Amazon EC2 IMDS.
 3//
 4// # Concurrency and caching
 5//
 6// The Provider is not safe to be used concurrently, and does not provide any
 7// caching of credentials retrieved. You should wrap the Provider with a
 8// `aws.CredentialsCache` to provide concurrency safety, and caching of
 9// credentials.
10//
11// # Loading credentials with the SDK's AWS Config
12//
13// The EC2 Instance role credentials provider will automatically be the resolved
14// credential provider in the credential chain if no other credential provider is
15// resolved first.
16//
17// To explicitly instruct the SDK's credentials resolving to use the EC2 Instance
18// role for credentials, you specify a `credentials_source` property in the config
19// profile the SDK will load.
20//
21//	[default]
22//	credential_source = Ec2InstanceMetadata
23//
24// # Loading credentials with the Provider directly
25//
26// Another way to use the EC2 Instance role credentials provider is to create it
27// directly and assign it as the credentials provider for an API client.
28//
29// The following example creates a credentials provider for a command, and wraps
30// it with the CredentialsCache before assigning the provider to the Amazon S3 API
31// client's Credentials option.
32//
33//	provider := imds.New(imds.Options{})
34//
35//	// Create the service client value configured for credentials.
36//	svc := s3.New(s3.Options{
37//	  Credentials: aws.NewCredentialsCache(provider),
38//	})
39//
40// If you need more control, you can set the configuration options on the
41// credentials provider using the imds.Options type to configure the EC2 IMDS
42// API Client and ExpiryWindow of the retrieved credentials.
43//
44//	provider := imds.New(imds.Options{
45//		// See imds.Options type's documentation for more options available.
46//		Client: imds.New(Options{
47//			HTTPClient: customHTTPClient,
48//		}),
49//
50//		// Modify how soon credentials expire prior to their original expiry time.
51//		ExpiryWindow: 5 * time.Minute,
52//	})
53//
54// # EC2 IMDS API Client
55//
56// See the github.com/aws/aws-sdk-go-v2/feature/ec2/imds module for more details on
57// configuring the client, and options available.
58package ec2rolecreds