Package: session

import "../ibm-cos-sdk-go/aws/session"

Constants

const ErrCodeSharedConfig = readonly

ErrCodeSharedConfig represents an error that occurs in the shared configuration logic

Value:

"SharedConfigErr"

const ErrCodeLoadCustomCABundle = readonly

ErrCodeLoadCustomCABundle error code for unable to load custom CA bundle.

Value:

"LoadCustomCABundleError"

const ErrCodeLoadClientTLSCert = readonly

ErrCodeLoadClientTLSCert error code for unable to load client TLS certificate or key

Value:

"LoadClientTLSCertError"

const SharedConfigStateFromEnv SharedConfigState = readonly

SharedConfigStateFromEnv does not override any state of the AWS_SDK_LOAD_CONFIG env var. It is the default value of the SharedConfigState type.

Value:

iota

const EnvProviderName = readonly

EnvProviderName provides a name of the provider when config is loaded from environment.

Value:

"EnvConfigCredentials"

const DefaultSharedConfigProfile = readonly

DefaultSharedConfigProfile is the default profile to be used when loading configuration from the config files if another profile name is not provided.

Value:

`default`

Variables

var ErrSharedConfigSourceCollision = writable

ErrSharedConfigSourceCollision will be returned if a section contains both source_profile and credential_source

Value:

awserr.New(ErrCodeSharedConfig, "only one credential type may be specified per profile: source profile, credential source, credential process, web identity token", nil)

var ErrSharedConfigECSContainerEnvVarEmpty = writable

ErrSharedConfigECSContainerEnvVarEmpty will be returned if the environment variables are empty and Environment was set as the credential source

Value:

awserr.New(ErrCodeSharedConfig, "EcsContainer was specified as the credential_source, but 'AWS_CONTAINER_CREDENTIALS_RELATIVE_URI' was not set", nil)

var ErrSharedConfigInvalidCredSource = writable

ErrSharedConfigInvalidCredSource will be returned if an invalid credential source was provided

Value:

awserr.New(ErrCodeSharedConfig, "credential source values must be EcsContainer, Ec2InstanceMetadata, or Environment", nil)

Type Summary collapse

Options struct

Options provides the means to control how a Session is created and what configuration values will be loaded.
Session struct

A Session provides a central location to create service clients from and store configurations and request handlers for those services.
SharedConfigAssumeRoleError struct

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

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

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

Function Summary collapse

func NewSession(cfgs ...*aws.Config) (*Session, error)

NewSession returns a new Session created from SDK defaults, config files, environment, and user provided config files.
func NewSessionWithOptions(opts Options) (*Session, error)

NewSessionWithOptions returns a new Session created from SDK defaults, config files, environment, and user provided config files.

Type Details

Options struct

Options provides the means to control how a Session is created and what configuration values will be loaded.

Structure Fields:

Config aws.Config

Provides config values for the SDK to use when creating service clients and making API requests to services. Any value set in with this field will override the associated value provided by the SDK defaults, environment or config files where relevant.

If not set, configuration values from from SDK defaults, environment, config will be used.

Profile string

Overrides the config profile the Session should be created from. If not set the value of the environment variable will be loaded (AWS_PROFILE, or AWS_DEFAULT_PROFILE if the Shared Config is enabled).

If not set and environment variables are not set the “default” (DefaultSharedConfigProfile) will be used as the profile to load the session config from.

SharedConfigState SharedConfigState

Instructs how the Session will be created based on the AWS_SDK_LOAD_CONFIG environment variable. By default a Session will be created using the value provided by the AWS_SDK_LOAD_CONFIG environment variable.

Setting this value to SharedConfigEnable or SharedConfigDisable will allow you to override the AWS_SDK_LOAD_CONFIG environment variable and enable or disable the shared config functionality.

SharedConfigFiles []string

Ordered list of files the session will load configuration from. It will override environment variable AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE.

AssumeRoleDuration time.Duration

When the SDK's shared config is configured to assume a role this option may be provided to set the expiry duration of the STS credentials. Defaults to 15 minutes if not set as documented in the stscreds.AssumeRoleProvider.

CustomCABundle io.Reader

Reader for a custom Credentials Authority (CA) bundle in PEM format that the SDK will use instead of the default system's root CA bundle. Use this only if you want to replace the CA bundle the SDK uses for TLS requests.

HTTP Client's Transport concrete implementation must be a http.Transport or creating the session will fail.

If the Transport's TLS config is set this option will cause the SDK to overwrite the Transport's TLS config's RootCAs value. If the CA bundle reader contains multiple certificates all of them will be loaded.

Can also be specified via the environment variable:

AWS_CA_BUNDLE=$HOME/ca_bundle

Can also be specified via the shared config field:

ca_bundle = $HOME/ca_bundle

ClientTLSCert io.Reader

Reader for the TLC client certificate that should be used by the SDK's HTTP transport when making requests. The certificate must be paired with a TLS client key file. Will be ignored if both are not provided.

HTTP Client's Transport concrete implementation must be a http.Transport or creating the session will fail.

Can also be specified via the environment variable:

AWS_SDK_GO_CLIENT_TLS_CERT=$HOME/my_client_cert

ClientTLSKey io.Reader

Reader for the TLC client key that should be used by the SDK's HTTP transport when making requests. The key must be paired with a TLS client certificate file. Will be ignored if both are not provided.

HTTP Client's Transport concrete implementation must be a http.Transport or creating the session will fail.

Can also be specified via the environment variable:

AWS_SDK_GO_CLIENT_TLS_KEY=$HOME/my_client_key

Handlers request.Handlers

The handlers that the session and all API clients will be created with. This must be a complete set of handlers. Use the defaults.Handlers() function to initialize this value before changing the handlers to be used by the SDK.

Function Details

func NewSession(cfgs ...aws.Config) (Session, error)

NewSession returns a new Session created from SDK defaults, config files, environment, and user provided config files. Once the Session is created it can be mutated to modify the Config or Handlers. The Session is safe to be read concurrently, but it should not be written to concurrently.

If the AWS_SDK_LOAD_CONFIG environment variable is set to a truthy value the shared config file (~/.aws/config) will also be loaded in addition to the shared credentials file (~/.aws/credentials). Values set in both the shared config, and shared credentials will be taken from the shared credentials file. Enabling the Shared Config will also allow the Session to be built with retrieving credentials with AssumeRole set in the config.

See the NewSessionWithOptions func for information on how to override or control through code how the Session will be created, such as specifying the config profile, and controlling if shared config is enabled or not.

// File 'aws/session/session.go', line 100

func NewSession(cfgs ...*aws.Config) (*Session, error) {
	opts := Options{}
	opts.Config.MergeIn(cfgs...)

	return NewSessionWithOptions(opts)
}

func NewSessionWithOptions(opts Options) (*Session, error)

NewSessionWithOptions returns a new Session created from SDK defaults, config files, environment, and user provided config files. This func uses the Options values to configure how the Session is created.

// Equivalent to session.New
sess := session.Must(session.NewSessionWithOptions(session.Options{}))

// Specify profile to load for the session's config
sess := session.Must(session.NewSessionWithOptions(session.Options{
     Profile: "profile_name",
}))

// Specify profile for config and region for requests
sess := session.Must(session.NewSessionWithOptions(session.Options{
     Config: aws.Config{Region: aws.String("us-east-1")},
     Profile: "profile_name",
}))

// Force enable Shared Config support
sess := session.Must(session.NewSessionWithOptions(session.Options{
    SharedConfigState: session.SharedConfigEnable,
}))

// File 'aws/session/session.go', line 267

func NewSessionWithOptions(opts Options) (*Session, error) {
	var envCfg envConfig
	var err error
	if opts.SharedConfigState == SharedConfigEnable {
		envCfg, err = loadSharedEnvConfig()
		if err != nil {
			return nil, fmt.Errorf("failed to load shared config, %v", err)
		}
	} else {
		envCfg, err = loadEnvConfig()
		if err != nil {
			return nil, fmt.Errorf("failed to load environment config, %v", err)
		}
	}

	if len(opts.Profile) != 0 {
		envCfg.Profile = opts.Profile
	}

	switch opts.SharedConfigState {
	case SharedConfigDisable:
		envCfg.EnableSharedConfig = false
	case SharedConfigEnable:
		envCfg.EnableSharedConfig = true
	}

	return newSession(opts, envCfg, &opts.Config)
}