ec2rolecreds

Documentation

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 int he 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.

Index

• Constants
• type GetMetadataAPIClient
• type Options
• type Provider
  • func New(optFns ...func(*Options)) *Provider
  • func (p *Provider) Retrieve(ctx context.Context) (aws.Credentials, error)

Constants

const ProviderName = "EC2RoleProvider"

ProviderName provides a name of EC2Role provider

Types

type GetMetadataAPIClient

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

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

type Options

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
}

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

type Provider

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

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 Provider.

p := &ec2rolecreds.New(ec2rolecreds.Options{
     Client: imds.New(imds.Options{}),

     // Expire the credentials 10 minutes before IAM states they should.
     // Proactively refreshing the credentials.
     ExpiryWindow: 10 * time.Minute
})

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) 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.