v1.17.11 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 5, 2024 License: Apache-2.0 Imports: 15 Imported by: 18



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.

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,


See the module for more details on configuring the client, and options available.



View Source
const ProviderName = "EC2RoleProvider"

ProviderName provides a name of EC2Role provider


This section is empty.


This section is empty.


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 with a custom EC2 IMDS client.

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

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 added in v1.11.0

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 added in v1.11.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL