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 := ec2imds.New(ec2imds.Options{})

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

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

provider := ec2imds.New(ec2imds.Options{
	// See ec2imds.Options type's documentation for more options available.
	Client: ec2imds.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/ec2imds module for more details on configuring the client, and options available.

Index

• Constants
• type GetMetadataAPIClient
• type Options
• type Provider
  • func New(options Options, 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, *ec2imds.GetMetadataInput, ...func(*ec2imds.Options)) (*ec2imds.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 ec2imds client.
	Client GetMetadataAPIClient

	// ExpiryWindow will allow the credentials to trigger refreshing prior to
	// the credentials actually expiring. This is beneficial so race conditions
	// with expiring credentials do not cause request to fail unexpectedly
	// due to ExpiredTokenException exceptions.
	//
	// So a ExpiryWindow of 10s would cause calls to IsExpired() to return true
	// 10 seconds before the credentials are actually expired.
	//
	// If ExpiryWindow is 0 or less it will be ignored.
	ExpiryWindow time.Duration
}

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: ec2imds.New(ec2imds.Options{}),

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

func New

func New(options Options, 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.