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.
58 package ec2rolecreds
59