...
▽

Package ec2rolecreds

import "github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds"
Overview
Index

Overview ▾

Package ec2rolecreds provides the credentials provider implementation for retrieving AWS credentials from Amazon EC2 Instance Roles via Amazon EC2 IMDS.

Concurrency and caching

The Provider is not safe to be used concurrently, and does not provide any caching of credentials retrieved. You should wrap the Provider with a `aws.CredentialsCache` to provide concurrency safety, and caching of credentials.

Loading credentials with the SDK's AWS Config

The EC2 Instance role credentials provider will automatically be the resolved credential provider in the credential chain if no other credential provider is resolved first.

To explicitly instruct the SDK's credentials resolving to use the EC2 Instance role for credentials, you specify a `credentials_source` property in the config profile the SDK will load. 

[default]
credential_source = Ec2InstanceMetadata

Loading credentials with the Provider directly

Another way to use the EC2 Instance role credentials provider is to create it directly and assign it as the credentials provider for an API client.

The following example creates a credentials provider for a command, and wraps it with the CredentialsCache before assigning the provider to the Amazon S3 API client's Credentials option. 

provider := imds.New(imds.Options{})

// Create the service client value configured for credentials.
svc := s3.New(s3.Options{
  Credentials: aws.NewCredentialsCache(provider),
})

If you need more control, you can set the configuration options on the credentials provider using the imds.Options type to configure the EC2 IMDS API Client and ExpiryWindow of the retrieved credentials. 

provider := imds.New(imds.Options{
	// See imds.Options type's documentation for more options available.
	Client: imds.New(Options{
		HTTPClient: customHTTPClient,
	}),

	// Modify how soon credentials expire prior to their original expiry time.
	ExpiryWindow: 5 * time.Minute,
})

EC2 IMDS API Client

See the github.com/aws/aws-sdk-go-v2/feature/ec2/imds module for more details on configuring the client, and options available.

Constants

ProviderName provides a name of EC2Role provider 

const ProviderName = "EC2RoleProvider"

type GetMetadataAPIClient

GetMetadataAPIClient provides the interface for an EC2 IMDS API client for the GetMetadata operation. 

type GetMetadataAPIClient interface {
    GetMetadata(context.Context, *imds.GetMetadataInput, ...func(*imds.Options)) (*imds.GetMetadataOutput, error)
}

type Options

Options is a list of user settable options for setting the behavior of the Provider. 

type Options struct {
    // The API client that will be used by the provider to make GetMetadata API
    // calls to EC2 IMDS.
    //
    // If nil, the provider will default to the EC2 IMDS client.
    Client GetMetadataAPIClient
}

type Provider

A Provider retrieves credentials from the EC2 service, and keeps track if those credentials are expired.

The New function must be used to create the with a custom EC2 IMDS client. 

p := &ec2rolecreds.New(func(o *ec2rolecreds.Options{
     o.Client = imds.New(imds.Options{/* custom options */})
})

type Provider struct {
    // contains filtered or unexported fields
}

func New 

func New(optFns ...func(*Options)) *Provider

New returns an initialized Provider value configured to retrieve credentials from EC2 Instance Metadata service.

func (*Provider) AdjustExpiresBy 

func (p *Provider) AdjustExpiresBy(creds aws.Credentials, dur time.Duration) (
    aws.Credentials, error,
)

AdjustExpiresBy will adds the passed in duration to the passed in credential's Expires time, unless the time until Expires is less than 15 minutes. Returns the credentials, even if not updated.

func (*Provider) HandleFailToRefresh 

func (p *Provider) HandleFailToRefresh(ctx context.Context, prevCreds aws.Credentials, err error) (
    aws.Credentials, error,
)

HandleFailToRefresh will extend the credentials Expires time if it it is expired. If the credentials will not expire within the minimum time, they will be returned.

If the credentials cannot expire, the original error will be returned.

func (*Provider) Retrieve 

func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Retrieve retrieves credentials from the EC2 service. Error will be returned if the request fails, or unable to extract the desired credentials.