tessl/golang-github-com--aws--aws-sdk-go-v2

AWS SDK for Go v2 with 130+ service clients, Request/Send pattern, and context support.

Overview

Eval results

Files

Configuration Loading (`aws/external`)

Name: tessl/golang-github-com--aws--aws-sdk-go-v2
Author: tessl

Import: github.com/aws/aws-sdk-go-v2/aws/external

The external package loads AWS configuration from external sources (environment variables and shared config files) into an aws.Config.

Primary Entry Point

func LoadDefaultAWSConfig(configs ...Config) (aws.Config, error)

Reads from these sources in order:

Environment variables (AWS_ACCESS_KEY_ID, AWS_REGION, etc.)
Shared credentials file (~/.aws/credentials)
Shared config file (~/.aws/config)

Optional configs are prepended to the config chain and can override defaults.

Usage Examples

// Basic: load from defaults
cfg, err := external.LoadDefaultAWSConfig()
if err != nil {
    panic(err)
}
cfg.Region = "us-east-1" // Set region if not in environment

// With custom profile
cfg, err := external.LoadDefaultAWSConfig(
    external.WithSharedConfigProfile("production"),
)

// With explicit region
cfg, err := external.LoadDefaultAWSConfig(
    external.WithRegion("eu-central-1"),
)

// With static credentials override
cfg, err := external.LoadDefaultAWSConfig(
    external.WithCredentialsValue(aws.Credentials{
        AccessKeyID:     "AKID",
        SecretAccessKey: "SECRET",
        Source:          "manual",
    }),
)

// With custom CA bundle
caBundle, _ := ioutil.ReadFile("/path/to/ca.pem")
cfg, err := external.LoadDefaultAWSConfig(
    external.WithCustomCABundle(caBundle),
)

// With custom config files
cfg, err := external.LoadDefaultAWSConfig(
    external.WithSharedConfigFiles([]string{"/custom/.aws/credentials", "/custom/.aws/config"}),
)

// With assume role MFA token function
cfg, err := external.LoadDefaultAWSConfig(
    external.WithMFATokenFunc(external.StdinTokenProvider),
)

Config Option Types

These implement the Config interface and can be passed to LoadDefaultAWSConfig.

// Set AWS region
type WithRegion string
func (v WithRegion) GetRegion() (string, error)

// Set static credentials
type WithCredentialsValue aws.Credentials
func (v WithCredentialsValue) GetCredentialsValue() (aws.Credentials, error)

// Set shared config profile name
type WithSharedConfigProfile string
func (c WithSharedConfigProfile) GetSharedConfigProfile() (string, error)

// Set custom shared config file paths
type WithSharedConfigFiles []string
func (c WithSharedConfigFiles) GetSharedConfigFiles() ([]string, error)

// Set credentials endpoint URL
type WithCredentialsEndpoint string
func (p WithCredentialsEndpoint) GetCredentialsEndpoint() (string, error)

// Set container credentials endpoint path
type WithContainerCredentialsEndpointPath string
func (p WithContainerCredentialsEndpointPath) GetContainerCredentialsEndpointPath() (string, error)

// Set custom CA bundle (PEM bytes)
type WithCustomCABundle []byte
func (v WithCustomCABundle) GetCustomCABundle() ([]byte, error)

// Set MFA token provider function
type WithMFATokenFunc func() (string, error)
func (p WithMFATokenFunc) GetMFATokenFunc() (func() (string, error), error)

// Set assume role configuration
type WithAssumeRoleConfig AssumeRoleConfig
func (p WithAssumeRoleConfig) GetAssumeRoleConfig() (AssumeRoleConfig, error)

// Retrieve region from EC2 Metadata service
type WithEC2MetadataRegion struct {
    Client *ec2metadata.EC2Metadata
}
func (p WithEC2MetadataRegion) GetRegion() (string, error)

Environment Variables

const (
    AWSAccessKeyIDEnvVar        = "AWS_ACCESS_KEY_ID"
    AWSAccessKeyEnvVar          = "AWS_ACCESS_KEY"         // alias
    AWSSecreteAccessKeyEnvVar   = "AWS_SECRET_ACCESS_KEY"
    AWSSecreteKeyEnvVar         = "AWS_SECRET_KEY"         // alias
    AWSSessionTokenEnvVar       = "AWS_SESSION_TOKEN"
    AWSCredentialsEndpointEnvVar = "AWS_CONTAINER_CREDENTIALS_FULL_URI"
    AWSContainerCredentialsEndpointPathEnvVar = "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"
    AWSRegionEnvVar             = "AWS_REGION"
    AWSDefaultRegionEnvVar      = "AWS_DEFAULT_REGION"     // alias
    AWSProfileEnvVar            = "AWS_PROFILE"
    AWSDefaultProfileEnvVar     = "AWS_DEFAULT_PROFILE"    // alias
    AWSSharedCredentialsFileEnvVar = "AWS_SHARED_CREDENTIALS_FILE"
    AWSConfigFileEnvVar         = "AWS_CONFIG_FILE"
    AWSCustomCABundleEnvVar     = "AWS_CA_BUNDLE"
    CredentialsSourceName       = "EnvConfigCredentials"
)

Default File Paths

// Linux/Unix: $HOME/.aws/credentials, Windows: %USERPROFILE%\.aws\credentials
func DefaultSharedCredentialsFilename() string

// Linux/Unix: $HOME/.aws/config, Windows: %USERPROFILE%\.aws\config
func DefaultSharedConfigFilename() string

var DefaultSharedConfigFiles = []string{
    DefaultSharedCredentialsFilename(),
    DefaultSharedConfigFilename(),
}

var DefaultSharedConfigProfile = "default"

AssumeRoleConfig

Specifies assume role configuration when using shared config files with role_arn.

type AssumeRoleConfig struct {
    RoleARN         string
    ExternalID      string
    MFASerial       string
    RoleSessionName string
    Source          *SharedConfig
    // unexported fields
}

SharedConfig

Represents values loaded from shared config/credentials files.

type SharedConfig struct {
    // Profile name
    Profile string

    // Credentials
    Credentials aws.Credentials

    // Assume Role config if configured
    AssumeRole AssumeRoleConfig

    // MFA serial number
    MFASerial string

    // Region
    Region string

    // Custom CA bundle path
    CustomCABundle string

    // Has unexported fields
}

Advanced: Config Chain

For advanced configuration, work directly with the config chain.

type Config interface{} // generic config value

type Configs []Config
func (cs Configs) AppendFromLoaders(loaders []ConfigLoader) (Configs, error)
func (cs Configs) ResolveAWSConfig(resolvers []AWSConfigResolver) (aws.Config, error)

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

// Default loaders (environment + shared config)
var DefaultConfigLoaders = []ConfigLoader{
    LoadEnvConfig,
    LoadSharedConfigIgnoreNotExist,
}

// Default resolvers
var DefaultAWSConfigResolvers = []AWSConfigResolver{
    ResolveDefaultAWSConfig,
    ResolveCustomCABundle,
    ResolveRegion,
    ResolveFallbackEC2Credentials,
    ResolveCredentialsValue,
    ResolveEndpointCredentials,
    ResolveContainerEndpointPathCredentials,
    ResolveAssumeRoleCredentials,
}

Individual Loaders

func LoadEnvConfig(cfgs Configs) (Config, error)
func LoadSharedConfig(configs Configs) (Config, error)
func LoadSharedConfigIgnoreNotExist(configs Configs) (Config, error)

Individual Resolvers

func ResolveDefaultAWSConfig(cfg *aws.Config, configs Configs) error
func ResolveCustomCABundle(cfg *aws.Config, configs Configs) error
func ResolveRegion(cfg *aws.Config, configs Configs) error
func ResolveFallbackEC2Credentials(cfg *aws.Config, configs Configs) error
func ResolveCredentialsValue(cfg *aws.Config, configs Configs) error
func ResolveEndpointCredentials(cfg *aws.Config, configs Configs) error
func ResolveContainerEndpointPathCredentials(cfg *aws.Config, configs Configs) error
func ResolveAssumeRoleCredentials(cfg *aws.Config, configs Configs) error

Config Getters

Search a Configs slice for a specific configuration value.

func GetRegion(configs Configs) (string, bool, error)
func GetCredentialsValue(configs Configs) (aws.Credentials, bool, error)
func GetCredentialsEndpoint(configs Configs) (string, bool, error)
func GetContainerCredentialsEndpointPath(configs Configs) (string, bool, error)
func GetSharedConfigFiles(configs Configs) ([]string, bool, error)
func GetSharedConfigProfile(configs Configs) (string, bool, error)
func GetMFATokenFunc(configs Configs) (func() (string, error), bool, error)
func GetCustomCABundle(configs Configs) ([]byte, bool, error)
func GetAssumeRoleConfig(configs Configs) (AssumeRoleConfig, bool, error)

Provider Interfaces

Custom config types should implement the appropriate provider interfaces.

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

type CredentialsValueProvider interface {
    GetCredentialsValue() (aws.Credentials, error)
}

type CredentialsEndpointProvider interface {
    GetCredentialsEndpoint() (string, error)
}

type ContainerCredentialsEndpointPathProvider interface {
    GetContainerCredentialsEndpointPath() (string, error)
}

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

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

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

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

type AssumeRoleConfigProvider interface {
    GetAssumeRoleConfig() (AssumeRoleConfig, error)
}

EnvConfig

Represents environment variable-based configuration values.

type EnvConfig struct {
    // Credentials from environment
    Credentials aws.Credentials
    // Region from environment
    Region string
    // Endpoint URL for container credentials
    CredentialsEndpoint string
    // Relative URI for container credentials
    ContainerCredentialsEndpointPath string
    // Custom CA bundle path
    CustomCABundle string
    // Profile name
    Profile string
    // Shared credentials and config file paths
    SharedCredentialsFile string
    SharedConfigFile      string
}

func NewEnvConfig() (EnvConfig, error)

SharedConfig (Direct Access)

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

Error Types

// Error when shared config files do not exist
type SharedConfigNotExistErrors []error
func (es SharedConfigNotExistErrors) Error() string

// Error when profile is not found in config files
type SharedConfigProfileNotExistError struct {
    Filename string
    Profile  string
    Err      error
}
func (e SharedConfigProfileNotExistError) Error() string
func (e SharedConfigProfileNotExistError) Cause() error

// Error loading shared config file
type SharedConfigFileNotExistError struct {
    Filename string
    Profile  string
    Err      error
}
func (e SharedConfigFileNotExistError) Error() string

// Error loading shared config (general)
type SharedConfigLoadError struct {
    Filename string
    Err      error
}
func (e SharedConfigLoadError) Error() string

// Error with assume role in shared config
type SharedConfigAssumeRoleError struct {
    RoleARN string
    Err     error
}
func (e SharedConfigAssumeRoleError) Error() string

Install with Tessl CLI

npx tessl i tessl/golang-github-com--aws--aws-sdk-go-v2

docs

examples

guides

reference