external

type AWSConfigResolver ¶

type AWSConfigResolver func(cfg *aws.Config, configs Configs) error

An AWSConfigResolver will extract configuration data from the Configs slice using the provider interfaces to extract specific functionality. The extracted configuration values will be written to the AWS Config value.

The resolver should return an error if it it fails to extract the data, the data is malformed, or incomplete.

type AssumeRoleConfig ¶

type AssumeRoleConfig struct{}

AssumeRoleConfig provides the values defining the configuration for an IAM assume role.

type AssumeRoleCredentialProviderOptions ¶ added in v0.20.0

type AssumeRoleCredentialProviderOptions interface {
	GetAssumeRoleCredentialProviderOptions() (func(*stscreds.AssumeRoleProviderOptions), bool, error)
}

AssumeRoleCredentialProviderOptions is an interface for retrieving a function for setting the stscreds.AssumeRoleProviderOptions.

type AssumeRoleTokenProviderNotSetError ¶ added in v0.20.0

type AssumeRoleTokenProviderNotSetError struct{}

AssumeRoleTokenProviderNotSetError is an error returned when creating a session when the MFAToken option is not set when shared config is configured load assume a role with an MFA token.

func (e AssumeRoleTokenProviderNotSetError) Code() string

func (e AssumeRoleTokenProviderNotSetError) Error() string

func (e AssumeRoleTokenProviderNotSetError) Message() string

func (e AssumeRoleTokenProviderNotSetError) OrigErr() error

type Config ¶

type Config interface{}

A Config represents a generic configuration value or set of values. This type will be used by the AWSConfigResolvers to extract

General the Config type will use type assertion against the Provider interfaces to extract specific data from the Config.

func LoadEnvConfig(cfgs Configs) (Config, error)

func LoadSharedConfig(configs Configs) (Config, error)

func LoadSharedConfigIgnoreNotExist(configs Configs) (Config, error)

type ConfigLoader ¶

type ConfigLoader func(Configs) (Config, error)

A ConfigLoader is used to load external configuration data and returns it as a generic Config type.

The loader should return an error if it fails to load the external configuration or the configuration data is malformed, or required components missing.

type Configs ¶

type Configs []Config

Configs is a slice of Config values. These values will be used by the AWSConfigResolvers to extract external configuration values to populate the AWS Config type.

Use AppendFromLoaders to add additional external Config values that are loaded from external sources.

Use ResolveAWSConfig after external Config values have been added or loaded to extract the loaded configuration values into the AWS Config.

func (cs Configs) AppendFromLoaders(loaders []ConfigLoader) (Configs, error)

func (cs Configs) ResolveAWSConfig(resolvers []AWSConfigResolver) (aws.Config, error)

func (cs Configs) ResolveConfig(f func(configs []interface{}) error) error

type CredentialRequiresARNError ¶ added in v0.20.0

type CredentialRequiresARNError struct {
	// type of credentials that were configured.
	Type string

	// Profile name the credentials were in.
	Profile string
}

CredentialRequiresARNError provides the error for shared config credentials that are incorrectly configured in the shared config or credentials file.

func (e CredentialRequiresARNError) Code() string

func (e CredentialRequiresARNError) Error() string

func (e CredentialRequiresARNError) Message() string

func (e CredentialRequiresARNError) OrigErr() error

type CredentialsProviderProvider ¶ added in v0.20.0

type CredentialsProviderProvider interface {
	GetCredentialsProvider() (aws.CredentialsProvider, bool, error)
}

CredentialsProviderProvider provides access to the credentials external configuration value.

type CustomCABundleProvider ¶

type CustomCABundleProvider interface {
	GetCustomCABundle() ([]byte, error)
}

CustomCABundleProvider provides access to the custom CA bundle PEM bytes.

type DefaultRegionProvider ¶ added in v0.21.0

type DefaultRegionProvider interface {
	GetDefaultRegion() (string, bool, error)
}

DefaultRegionProvider is an interface for retrieving a default region if a region was not resolved from other sources

type EC2RoleCredentialProviderOptions ¶ added in v0.20.0

type EC2RoleCredentialProviderOptions interface {
	GetEC2RoleCredentialProviderOptions() (func(*ec2rolecreds.ProviderOptions), bool, error)
}

EC2RoleCredentialProviderOptions is an interface for retrieving a function for setting the ec2rolecreds.Provider options.

type EnableEndpointDiscoveryProvider ¶ added in v0.20.0

type EnableEndpointDiscoveryProvider interface {
	GetEnableEndpointDiscovery() (value, found bool, err error)
}

EnableEndpointDiscoveryProvider provides access to the

type EndpointCredentialProviderOptions ¶ added in v0.20.0

type EndpointCredentialProviderOptions interface {
	GetEndpointCredentialProviderOptions() (func(*endpointcreds.ProviderOptions), bool, error)
}

EndpointCredentialProviderOptions is an interface for retrieving a function for setting the endpointcreds.ProviderOptions.

type EndpointResolverFunc ¶ added in v0.20.0

type EndpointResolverFunc func(aws.EndpointResolver) aws.EndpointResolver

EndpointResolverFunc is a function that is given the default EndpointResolver and returns an aws.EndpointResolver that will be used

func GetEndpointResolverFunc(configs Configs) (f EndpointResolverFunc, found bool, err error)

type EndpointResolverFuncProvider ¶ added in v0.20.0

type EndpointResolverFuncProvider interface {
	GetEndpointResolverFunc() (EndpointResolverFunc, bool, error)
}

EndpointResolverFuncProvider is an interface for retrieving an aws.EndpointResolver from a configuration source

type EnvConfig ¶

type EnvConfig struct {
	// Environment configuration values. If set both Access Key ID and Secret Access
	// Key must be provided. Session Token and optionally also be provided, but is
	// not required.
	//
	//	# Access Key ID
	//	AWS_ACCESS_KEY_ID=AKID
	//	AWS_ACCESS_KEY=AKID # only read if AWS_ACCESS_KEY_ID is not set.
	//
	//	# Secret Access Key
	//	AWS_SECRET_ACCESS_KEY=SECRET
	//	AWS_SECRET_KEY=SECRET # only read if AWS_SECRET_ACCESS_KEY is not set.
	//
	//	# Session Token
	//	AWS_SESSION_TOKEN=TOKEN
	Credentials aws.Credentials

	// ContainerCredentialsEndpoint value is the HTTP enabled endpoint to retrieve credentials
	// using the endpointcreds.Provider
	ContainerCredentialsEndpoint string

	// ContainerCredentialsRelativePath is the relative URI path that will be used when attempting to retrieve
	// credentials from the container endpoint.
	ContainerCredentialsRelativePath string

	// ContainerAuthorizationToken is the authorization token that will be included in the HTTP Authorization
	// header when attempting to retrieve credentials from the container credentials endpoint.
	ContainerAuthorizationToken string

	// Region value will instruct the SDK where to make service API requests to. If is
	// not provided in the environment the region must be provided before a service
	// client request is made.
	//
	//	AWS_REGION=us-west-2
	//	AWS_DEFAULT_REGION=us-west-2
	Region string

	// Profile name the SDK should load use when loading shared configuration from the
	// shared configuration files. If not provided "default" will be used as the
	// profile name.
	//
	//	AWS_PROFILE=my_profile
	//	AWS_DEFAULT_PROFILE=my_profile
	SharedConfigProfile string

	// Shared credentials file path can be set to instruct the SDK to use an alternate
	// file for the shared credentials. If not set the file will be loaded from
	// $HOME/.aws/credentials on Linux/Unix based systems, and
	// %USERPROFILE%\.aws\credentials on Windows.
	//
	//	AWS_SHARED_CREDENTIALS_FILE=$HOME/my_shared_credentials
	SharedCredentialsFile string

	// Shared config file path can be set to instruct the SDK to use an alternate
	// file for the shared config. If not set the file will be loaded from
	// $HOME/.aws/config on Linux/Unix based systems, and
	// %USERPROFILE%\.aws\config on Windows.
	//
	//	AWS_CONFIG_FILE=$HOME/my_shared_config
	SharedConfigFile string

	// Sets the path to a custom Credentials Authroity (CA) Bundle PEM file
	// that the SDK will use instead of the system's root CA bundle.
	// Only use this if you want to configure the SDK to use a custom set
	// of CAs.
	//
	// Enabling this option will attempt to merge the Transport
	// into the SDK's HTTP client. If the client's Transport is
	// not a http.Transport an error will be returned. If the
	// Transport's TLS config is set this option will cause the
	// SDK to overwrite the Transport's TLS config's  RootCAs value.
	//
	// Setting a custom HTTPClient in the aws.Config options will override this setting.
	// To use this option and custom HTTP client, the HTTP client needs to be provided
	// when creating the config. Not the service client.
	//
	//  AWS_CA_BUNDLE=$HOME/my_custom_ca_bundle
	CustomCABundle string

	// Enables endpoint discovery via environment variables.
	//
	//	AWS_ENABLE_ENDPOINT_DISCOVERY=true
	EnableEndpointDiscovery *bool

	// Specifies the WebIdentity token the SDK should use to assume a role
	// with.
	//
	//  AWS_WEB_IDENTITY_TOKEN_FILE=file_path
	WebIdentityTokenFilePath string

	// Specifies the IAM role arn to use when assuming an role.
	//
	//  AWS_ROLE_ARN=role_arn
	RoleARN string

	// Specifies the IAM role session name to use when assuming a role.
	//
	//  AWS_ROLE_SESSION_NAME=session_name
	RoleSessionName string

	// Specifies if the S3 service should allow ARNs to direct the region
	// the client's requests are sent to.
	//
	// AWS_S3_USE_ARN_REGION=true
	S3UseARNRegion *bool
}

EnvConfig is a collection of environment values the SDK will read setup config from. All environment values are optional. But some values such as credentials require multiple values to be complete or the values will be ignored.

func NewEnvConfig() (EnvConfig, error)

func (c EnvConfig) GetCustomCABundle() ([]byte, error)

func (c EnvConfig) GetEnableEndpointDiscovery() (value, ok bool, err error)

func (c EnvConfig) GetRegion() (string, error)

func (c EnvConfig) GetS3UseARNRegion() (value, ok bool, err error)

func (c EnvConfig) GetSharedConfigFiles() ([]string, error)

func (c EnvConfig) GetSharedConfigProfile() (string, error)

type HandlersFunc ¶ added in v0.20.0

type HandlersFunc func(aws.Handlers) aws.Handlers

HandlersFunc is a function pointer that takes a list of handlers and returns the modified set of handlers to use

func GetHandlersFunc(configs Configs) (f HandlersFunc, found bool, err error)

type HandlersFuncProvider ¶ added in v0.20.0

type HandlersFuncProvider interface {
	GetHandlersFunc() (HandlersFunc, bool, error)
}

HandlersFuncProvider provides access to the configuration handlers

type MFATokenFuncProvider ¶

type MFATokenFuncProvider interface {
	GetMFATokenFunc() (func() (string, error), error)
}

MFATokenFuncProvider provides access to the MFA token function needed for Assume Role with MFA.

type ProcessCredentialProviderOptions ¶ added in v0.20.0

type ProcessCredentialProviderOptions interface {
	GetProcessCredentialProviderOptions() (func(*processcreds.ProviderOptions), bool, error)
}

ProcessCredentialProviderOptions is an interface for retrieving a function for setting the processcreds.ProviderOptions.

type RegionProvider ¶

type RegionProvider interface {
	GetRegion() (string, error)
}

RegionProvider provides access to the region external configuration value.

type SharedConfig ¶

type SharedConfig struct {
	Profile string

	// Credentials values from the config file. Both aws_access_key_id
	// and aws_secret_access_key must be provided together in the same file
	// to be considered valid. The values will be ignored if not a complete group.
	// aws_session_token is an optional field that can be provided if both of the
	// other two fields are also provided.
	//
	//	aws_access_key_id
	//	aws_secret_access_key
	//	aws_session_token
	Credentials aws.Credentials

	CredentialSource     string
	CredentialProcess    string
	WebIdentityTokenFile string

	RoleARN             string
	ExternalID          string
	MFASerial           string
	RoleSessionName     string
	RoleDurationSeconds *time.Duration

	SourceProfileName string
	Source            *SharedConfig

	// Region is the region the SDK should use for looking up AWS service endpoints
	// and signing requests.
	//
	//	region
	Region string

	// EnableEndpointDiscovery can be enabled in the shared config by setting
	// endpoint_discovery_enabled to true
	//
	//	endpoint_discovery_enabled = true
	EnableEndpointDiscovery *bool

	// Specifies if the S3 service should allow ARNs to direct the region
	// the client's requests are sent to.
	//
	// s3_use_arn_region=true
	S3UseARNRegion *bool
}

SharedConfig represents the configuration fields of the SDK config files.

func NewSharedConfig(profile string, filenames []string) (SharedConfig, error)

func (c SharedConfig) GetCredentialsProvider() (aws.Credentials, error)

func (c *SharedConfig) GetEnableEndpointDiscovery() (value, ok bool, err error)

func (c SharedConfig) GetRegion() (string, error)

func (c *SharedConfig) GetS3UseARNRegion() (value, ok bool, err error)

type SharedConfigAssumeRoleError ¶

type SharedConfigAssumeRoleError struct {
	Profile string
	RoleARN string
	Err     error
}

SharedConfigAssumeRoleError is an error for the shared config when the profile contains assume role information, but that information is invalid or not complete.

func (e SharedConfigAssumeRoleError) Error() string

type SharedConfigFileNotExistError ¶

type SharedConfigFileNotExistError struct {
	Filename string
	Profile  string
	Err      error
}

SharedConfigFileNotExistError is an error for the shared config when the filename does not exist.

func (e SharedConfigFileNotExistError) Cause() error

func (e SharedConfigFileNotExistError) Error() string

type SharedConfigFilesProvider ¶

type SharedConfigFilesProvider interface {
	GetSharedConfigFiles() ([]string, error)
}

SharedConfigFilesProvider provides access to the shared config filesnames external configuration value.

type SharedConfigLoadError ¶

type SharedConfigLoadError struct {
	Filename string
	Err      error
}

SharedConfigLoadError is an error for the shared config file failed to load.

func (e SharedConfigLoadError) Cause() error

func (e SharedConfigLoadError) Error() string

type SharedConfigNotExistErrors ¶

type SharedConfigNotExistErrors []error

SharedConfigNotExistErrors provides an error type for failure to load shared config because resources do not exist.

func (es SharedConfigNotExistErrors) Error() string

type SharedConfigProfileNotExistError ¶

type SharedConfigProfileNotExistError struct {
	Filename string
	Profile  string
	Err      error
}

SharedConfigProfileNotExistError is an error for the shared config when the profile was not find in the config file.

func (e SharedConfigProfileNotExistError) Cause() error

func (e SharedConfigProfileNotExistError) Error() string

type SharedConfigProfileProvider ¶

type SharedConfigProfileProvider interface {
	GetSharedConfigProfile() (string, error)
}

SharedConfigProfileProvider provides access to the shared config profile name external configuration value.

type WebIdentityCredentialProviderOptions ¶ added in v0.20.0

type WebIdentityCredentialProviderOptions interface {
	GetWebIdentityCredentialProviderOptions() (func(*stscreds.WebIdentityRoleProviderOptions), bool, error)
}

WebIdentityCredentialProviderOptions is an interface for retrieving a function for setting the stscreds.WebIdentityCredentialProviderOptions.

type WithAssumeRoleCredentialProviderOptions ¶ added in v0.20.0

type WithAssumeRoleCredentialProviderOptions func(*stscreds.AssumeRoleProviderOptions)

WithAssumeRoleCredentialProviderOptions wraps a function and satisfies the EC2RoleCredentialProviderOptions interface

func (w WithAssumeRoleCredentialProviderOptions) GetAssumeRoleCredentialProviderOptions() (func(*stscreds.AssumeRoleProviderOptions), bool, error)

type WithAssumeRoleDuration ¶ added in v0.20.0

type WithAssumeRoleDuration time.Duration

WithAssumeRoleDuration provides a wrapping type of a time.Duration to satisfy

func (w WithAssumeRoleDuration) GetAssumeRoleDuration() (time.Duration, bool, error)

type WithCredentialsProvider ¶ added in v0.20.0

type WithCredentialsProvider struct {
	aws.CredentialsProvider
}

WithCredentialsProvider provides wrapping of a credentials Value to satisfy the CredentialsProviderProvider interface.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/aws/external"
)

func main() {
	cfg, err := external.LoadDefaultAWSConfig(
		// Hard coded credentials.
		external.WithCredentialsProvider{
			CredentialsProvider: aws.StaticCredentialsProvider{
				Value: aws.Credentials{
					AccessKeyID: "AKID", SecretAccessKey: "SECRET", SessionToken: "SESSION",
					Source: "example hard coded credentials",
				},
			},
		},
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to load config, %v", err)
		os.Exit(1)
	}

	// Credentials retrieve will be called automatically internally to the SDK
	// service clients created with the cfg value.
	creds, err := cfg.Credentials.Retrieve(context.Background())
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to get credentials, %v", err)
		os.Exit(1)
	}

	fmt.Println("Credentials Source:", creds.Source)

}

Output:

Credentials Source: example hard coded credentials

func (v WithCredentialsProvider) GetCredentialsProvider() (aws.CredentialsProvider, bool, error)

type WithCustomCABundle ¶

type WithCustomCABundle []byte

WithCustomCABundle provides wrapping of a region string to satisfy the CustomCABundleProvider interface.

func (v WithCustomCABundle) GetCustomCABundle() ([]byte, error)

type WithDefaultRegion ¶ added in v0.21.0

type WithDefaultRegion string

WithDefaultRegion wraps a string and satisfies the DefaultRegionProvider interface

func (w WithDefaultRegion) GetDefaultRegion() (string, bool, error)

type WithEC2MetadataRegion ¶

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

WithEC2MetadataRegion provides a RegionProvider that retrieves the region from the EC2 Metadata service.

TODO add this provider to the default config loading?

func NewWithEC2MetadataRegion(ctx context.Context, client *ec2metadata.Client) WithEC2MetadataRegion

external.NewWithEC2MetadataRegion(ctx, ec2metaClient),

func (p WithEC2MetadataRegion) GetRegion() (string, error)

type WithEC2RoleCredentialProviderOptions ¶ added in v0.20.0

type WithEC2RoleCredentialProviderOptions func(*ec2rolecreds.ProviderOptions)

WithEC2RoleCredentialProviderOptions wraps a function and satisfies the EC2RoleCredentialProviderOptions interface

func (w WithEC2RoleCredentialProviderOptions) GetEC2RoleCredentialProviderOptions() (func(*ec2rolecreds.ProviderOptions), bool, error)

type WithEnableEndpointDiscovery ¶ added in v0.20.0

type WithEnableEndpointDiscovery bool

WithEnableEndpointDiscovery provides a wrapping type of a bool to satisfy the EnableEndpointDiscoveryProvider interface.

func (w WithEnableEndpointDiscovery) GetEnableEndpointDiscovery() (value, found bool, err error)

type WithEndpointCredentialProviderOptions ¶ added in v0.20.0

type WithEndpointCredentialProviderOptions func(*endpointcreds.ProviderOptions)

WithEndpointCredentialProviderOptions wraps a function and satisfies the EC2RoleCredentialProviderOptions interface

func (w WithEndpointCredentialProviderOptions) GetEndpointCredentialProviderOptions() (func(*endpointcreds.ProviderOptions), bool, error)

type WithEndpointResolverFunc ¶ added in v0.20.0

type WithEndpointResolverFunc EndpointResolverFunc

WithEndpointResolverFunc wraps a aws.EndpointResolver value to satisfy the EndpointResolverFuncProvider interface

func (w WithEndpointResolverFunc) GetEndpointResolverFunc() (EndpointResolverFunc, bool, error)

type WithHandlersFunc ¶ added in v0.20.0

type WithHandlersFunc HandlersFunc

WithHandlersFunc implements the HandlersFuncProvider and delegates to the wrapped function

func (w WithHandlersFunc) GetHandlersFunc() (HandlersFunc, bool, error)

type WithMFATokenFunc ¶

type WithMFATokenFunc func() (string, error)

WithMFATokenFunc provides wrapping of a string to satisfy the MFATokenFuncProvider interface.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/aws/aws-sdk-go-v2/aws/external"
	"github.com/aws/aws-sdk-go-v2/aws/stscreds"
)

func main() {
	cfg, err := external.LoadDefaultAWSConfig(
		// Set the provider function for the MFA token.
		external.WithMFATokenFunc(stscreds.StdinTokenProvider),

		// Optionally, specify the shared configuration profile to load.
		external.WithSharedConfigProfile("exampleProfile"),
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to load config, %v", err)
		os.Exit(1)
	}

	// If assume role credentials with MFA enabled are specified in the shared
	// 	configuration the MFA token provider function will be called to retrieve
	// the MFA token for the assume role API call.
	fmt.Println(cfg.Credentials.Retrieve(context.Background()))
}

Output:

func (p WithMFATokenFunc) GetMFATokenFunc() (func() (string, error), error)

type WithProcessCredentialProviderOptions ¶ added in v0.20.0

type WithProcessCredentialProviderOptions func(*processcreds.ProviderOptions)

WithProcessCredentialProviderOptions wraps a function and satisfies the EC2RoleCredentialProviderOptions interface

func (w WithProcessCredentialProviderOptions) GetProcessCredentialProviderOptions() (func(*processcreds.ProviderOptions), bool, error)

type WithRegion ¶

type WithRegion string

WithRegion provides wrapping of a region string to satisfy the RegionProvider interface.

func (v WithRegion) GetRegion() (string, error)

type WithSharedConfigFiles ¶

type WithSharedConfigFiles []string

WithSharedConfigFiles wraps a slice of strings to satisfy the SharedConfigFilesProvider interface so a slice of custom shared config files ared used when loading the SharedConfig.

func (c WithSharedConfigFiles) GetSharedConfigFiles() ([]string, error)

type WithSharedConfigProfile ¶

type WithSharedConfigProfile string

WithSharedConfigProfile wraps a strings to satisfy the SharedConfigProfileProvider interface so a slice of custom shared config files ared used when loading the SharedConfig.

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/aws/aws-sdk-go-v2/aws/external"
)

func main() {
	cfg, err := external.LoadDefaultAWSConfig(
		// Specify the shared configuration profile to load.
		external.WithSharedConfigProfile("exampleProfile"),

		// Optionally specify the specific shared configuraiton
		// files to load the profile from.
		external.WithSharedConfigFiles([]string{
			filepath.Join("testdata", "shared_config"),
		}),
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to load config, %v", err)
		os.Exit(1)
	}

	// Region loaded from credentials file.
	fmt.Println("Region:", cfg.Region)

}

Output:

Region: us-west-2

func (c WithSharedConfigProfile) GetSharedConfigProfile() (string, error)

type WithWebIdentityCredentialProviderOptions ¶ added in v0.20.0

type WithWebIdentityCredentialProviderOptions func(*stscreds.WebIdentityRoleProviderOptions)

WithWebIdentityCredentialProviderOptions wraps a function and satisfies the EC2RoleCredentialProviderOptions interface

func (w WithWebIdentityCredentialProviderOptions) GetWebIdentityCredentialProviderOptions() (func(*stscreds.WebIdentityRoleProviderOptions), bool, error)