Package session
Overview ▹
Index ▹
Constants
const ( // DefaultSharedConfigProfile is the default profile to be used when // loading configuration from the config files if another profile name // is not provided. DefaultSharedConfigProfile = `default` )
type AssumeRoleTokenProviderNotSetError ¶
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.
type AssumeRoleTokenProviderNotSetError struct{}
func (AssumeRoleTokenProviderNotSetError) Code ¶
func (e AssumeRoleTokenProviderNotSetError) Code() string
Code is the short id of the error.
func (AssumeRoleTokenProviderNotSetError) Error ¶
func (e AssumeRoleTokenProviderNotSetError) Error() string
Error satisfies the error interface.
func (AssumeRoleTokenProviderNotSetError) Message ¶
func (e AssumeRoleTokenProviderNotSetError) Message() string
Message is the description of the error
func (AssumeRoleTokenProviderNotSetError) OrigErr ¶
func (e AssumeRoleTokenProviderNotSetError) OrigErr() error
OrigErr is the underlying error that caused the failure.
type Options ¶
Options provides the means to control how a Session is created and what configuration values will be loaded.
type Options struct { // 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. Config aws.Config // 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. Profile string // 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. SharedConfigState SharedConfigState // Ordered list of files the session will load configuration from. // It will override environment variable AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE. SharedConfigFiles []string // When the SDK's shared config is configured to assume a role with MFA // this option is required in order to provide the mechanism that will // retrieve the MFA token. There is no default value for this field. If // it is not set an error will be returned when creating the session. // // This token provider will be called when ever the assumed role's // credentials need to be refreshed. Within the context of service clients // all sharing the same session the SDK will ensure calls to the token // provider are atomic. When sharing a token provider across multiple // sessions additional synchronization logic is needed to ensure the // token providers do not introduce race conditions. It is recommend to // share the session where possible. // // stscreds.StdinTokenProvider is a basic implementation that will prompt // from stdin for the MFA token code. // // This field is only used if the shared configuration is enabled, and // the config enables assume role wit MFA via the mfa_serial field. AssumeRoleTokenProvider func() (string, error) // 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. // // 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. If the CA // bundle reader contains multiple certificates all of them will be loaded. // // The Session option CustomCABundle is also available when creating sessions // to also enable this feature. CustomCABundle session option field has priority // over the AWS_CA_BUNDLE environment variable, and will be used if both are set. CustomCABundle io.Reader }
type Session ¶
A Session provides a central location to create service clients from and store configurations and request handlers for those services.
Sessions are safe to create service clients concurrently, but it is not safe to mutate the Session concurrently.
The Session satisfies the service client's client.ClientConfigProvider.
type Session struct { Config *aws.Config Handlers request.Handlers }
func Must ¶
func Must(sess *Session, err error) *Session
Must is a helper function to ensure the Session is valid and there was no error when calling a NewSession function.
This helper is intended to be used in variable initialization to load the Session and configuration at startup. Such as:
var sess = session.Must(session.NewSession())
func New ¶
func New(cfgs ...*aws.Config) *Session
New creates a new instance of the handlers merging in the provided configs on top of the SDK's default configurations. 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 is set to a truthy value, the New method could now encounter an error when loading the configuration. When The environment variable is set, and an error occurs, New will return a session that will fail all requests reporting the error that occurred while loading the session. Use NewSession to get the error when creating the session.
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.
Deprecated: Use NewSession functions to create sessions instead. NewSession has the same functionality as New except an error can be returned when the func is called instead of waiting to receive an error until a request is made.
func NewSession ¶
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.
func NewSessionWithOptions ¶
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.
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.
// 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, }))
func (*Session) ClientConfig ¶
func (s *Session) ClientConfig(serviceName string, cfgs ...*aws.Config) client.Config
ClientConfig satisfies the client.ConfigProvider interface and is used to configure the service client instances. Passing the Session to the service client's constructor (New) will use this method to configure the client.
func (*Session) ClientConfigNoResolveEndpoint ¶
func (s *Session) ClientConfigNoResolveEndpoint(cfgs ...*aws.Config) client.Config
ClientConfigNoResolveEndpoint is the same as ClientConfig with the exception that the EndpointResolver will not be used to resolve the endpoint. The only endpoint set must come from the aws.Config.Endpoint field.
func (*Session) Copy ¶
func (s *Session) Copy(cfgs ...*aws.Config) *Session
Copy creates and returns a copy of the current Session, coping the config and handlers. If any additional configs are provided they will be merged on top of the Session's copied config.
// Create a copy of the current Session, configured for the us-west-2 region. sess.Copy(&aws.Config{Region: aws.String("us-west-2")})
type SharedConfigAssumeRoleError ¶
SharedConfigAssumeRoleError is an error for the shared config when the profile contains assume role information, but that information is invalid or not complete.
type SharedConfigAssumeRoleError struct { RoleARN string }
func (SharedConfigAssumeRoleError) Code ¶
func (e SharedConfigAssumeRoleError) Code() string
Code is the short id of the error.
func (SharedConfigAssumeRoleError) Error ¶
func (e SharedConfigAssumeRoleError) Error() string
Error satisfies the error interface.
func (SharedConfigAssumeRoleError) Message ¶
func (e SharedConfigAssumeRoleError) Message() string
Message is the description of the error
func (SharedConfigAssumeRoleError) OrigErr ¶
func (e SharedConfigAssumeRoleError) OrigErr() error
OrigErr is the underlying error that caused the failure.
type SharedConfigLoadError ¶
SharedConfigLoadError is an error for the shared config file failed to load.
type SharedConfigLoadError struct { Filename string Err error }
func (SharedConfigLoadError) Code ¶
func (e SharedConfigLoadError) Code() string
Code is the short id of the error.
func (SharedConfigLoadError) Error ¶
func (e SharedConfigLoadError) Error() string
Error satisfies the error interface.
func (SharedConfigLoadError) Message ¶
func (e SharedConfigLoadError) Message() string
Message is the description of the error
func (SharedConfigLoadError) OrigErr ¶
func (e SharedConfigLoadError) OrigErr() error
OrigErr is the underlying error that caused the failure.
type SharedConfigProfileNotExistsError ¶
SharedConfigProfileNotExistsError is an error for the shared config when the profile was not find in the config file.
type SharedConfigProfileNotExistsError struct { Profile string Err error }
func (SharedConfigProfileNotExistsError) Code ¶
func (e SharedConfigProfileNotExistsError) Code() string
Code is the short id of the error.
func (SharedConfigProfileNotExistsError) Error ¶
func (e SharedConfigProfileNotExistsError) Error() string
Error satisfies the error interface.
func (SharedConfigProfileNotExistsError) Message ¶
func (e SharedConfigProfileNotExistsError) Message() string
Message is the description of the error
func (SharedConfigProfileNotExistsError) OrigErr ¶
func (e SharedConfigProfileNotExistsError) OrigErr() error
OrigErr is the underlying error that caused the failure.
type SharedConfigState ¶
SharedConfigState provides the ability to optionally override the state of the session's creation based on the shared config being enabled or disabled.
type SharedConfigState int
const ( // SharedConfigStateFromEnv does not override any state of the // AWS_SDK_LOAD_CONFIG env var. It is the default value of the // SharedConfigState type. SharedConfigStateFromEnv SharedConfigState = iota // SharedConfigDisable overrides the AWS_SDK_LOAD_CONFIG env var value // and disables the shared config functionality. SharedConfigDisable // SharedConfigEnable overrides the AWS_SDK_LOAD_CONFIG env var value // and enables the shared config functionality. SharedConfigEnable )