| /* |
| Package session provides configuration for the SDK's service clients. Sessions |
| can be shared across service clients that share the same base configuration. |
| |
| Sessions are safe to use concurrently as long as the Session is not being |
| modified. Sessions should be cached when possible, because creating a new |
| Session will load all configuration values from the environment, and config |
| files each time the Session is created. Sharing the Session value across all of |
| your service clients will ensure the configuration is loaded the fewest number |
| of times possible. |
| |
| Sessions options from Shared Config |
| |
| By default NewSession will only load credentials from the shared credentials |
| file (~/.aws/credentials). If the AWS_SDK_LOAD_CONFIG environment variable is |
| set to a truthy value the Session will be created from the configuration |
| values from the shared config (~/.aws/config) and shared credentials |
| (~/.aws/credentials) files. Using the NewSessionWithOptions with |
| SharedConfigState set to SharedConfigEnable will create the session as if the |
| AWS_SDK_LOAD_CONFIG environment variable was set. |
| |
| Credential and config loading order |
| |
| The Session will attempt to load configuration and credentials from the |
| environment, configuration files, and other credential sources. The order |
| configuration is loaded in is: |
| |
| * Environment Variables |
| * Shared Credentials file |
| * Shared Configuration file (if SharedConfig is enabled) |
| * EC2 Instance Metadata (credentials only) |
| |
| The Environment variables for credentials will have precedence over shared |
| config even if SharedConfig is enabled. To override this behavior, and use |
| shared config credentials instead specify the session.Options.Profile, (e.g. |
| when using credential_source=Environment to assume a role). |
| |
| sess, err := session.NewSessionWithOptions(session.Options{ |
| Profile: "myProfile", |
| }) |
| |
| Creating Sessions |
| |
| Creating a Session without additional options will load credentials region, and |
| profile loaded from the environment and shared config automatically. See, |
| "Environment Variables" section for information on environment variables used |
| by Session. |
| |
| // Create Session |
| sess, err := session.NewSession() |
| |
| |
| When creating Sessions optional aws.Config values can be passed in that will |
| override the default, or loaded, config values the Session is being created |
| with. This allows you to provide additional, or case based, configuration |
| as needed. |
| |
| // Create a Session with a custom region |
| sess, err := session.NewSession(&aws.Config{ |
| Region: aws.String("us-west-2"), |
| }) |
| |
| Use NewSessionWithOptions to provide additional configuration driving how the |
| Session's configuration will be loaded. Such as, specifying shared config |
| profile, or override the shared config state, (AWS_SDK_LOAD_CONFIG). |
| |
| // Equivalent to session.NewSession() |
| sess, err := session.NewSessionWithOptions(session.Options{ |
| // Options |
| }) |
| |
| sess, err := session.NewSessionWithOptions(session.Options{ |
| // Specify profile to load for the session's config |
| Profile: "profile_name", |
| |
| // Provide SDK Config options, such as Region. |
| Config: aws.Config{ |
| Region: aws.String("us-west-2"), |
| }, |
| |
| // Force enable Shared Config support |
| SharedConfigState: session.SharedConfigEnable, |
| }) |
| |
| Adding Handlers |
| |
| You can add handlers to a session to decorate API operation, (e.g. adding HTTP |
| headers). All clients that use the Session receive a copy of the Session's |
| handlers. For example, the following request handler added to the Session logs |
| every requests made. |
| |
| // Create a session, and add additional handlers for all service |
| // clients created with the Session to inherit. Adds logging handler. |
| sess := session.Must(session.NewSession()) |
| |
| sess.Handlers.Send.PushFront(func(r *request.Request) { |
| // Log every request made and its payload |
| logger.Printf("Request: %s/%s, Params: %s", |
| r.ClientInfo.ServiceName, r.Operation, r.Params) |
| }) |
| |
| Shared Config Fields |
| |
| By default the SDK will only load the shared credentials file's |
| (~/.aws/credentials) credentials values, and all other config is provided by |
| the environment variables, SDK defaults, and user provided aws.Config values. |
| |
| If the AWS_SDK_LOAD_CONFIG environment variable is set, or SharedConfigEnable |
| option is used to create the Session the full shared config values will be |
| loaded. This includes credentials, region, and support for assume role. In |
| addition the Session will load its configuration from both the shared config |
| file (~/.aws/config) and shared credentials file (~/.aws/credentials). Both |
| files have the same format. |
| |
| If both config files are present the configuration from both files will be |
| read. The Session will be created from configuration values from the shared |
| credentials file (~/.aws/credentials) over those in the shared config file |
| (~/.aws/config). |
| |
| Credentials are the values the SDK uses to authenticating requests with AWS |
| Services. When specified in a file, both aws_access_key_id and |
| aws_secret_access_key must be provided together in the same file to be |
| considered valid. They will be ignored if both are not present. |
| aws_session_token is an optional field that can be provided in addition to the |
| other two fields. |
| |
| aws_access_key_id = AKID |
| aws_secret_access_key = SECRET |
| aws_session_token = TOKEN |
| |
| ; region only supported if SharedConfigEnabled. |
| region = us-east-1 |
| |
| Assume Role configuration |
| |
| The role_arn field allows you to configure the SDK to assume an IAM role using |
| a set of credentials from another source. Such as when paired with static |
| credentials, "profile_source", "credential_process", or "credential_source" |
| fields. If "role_arn" is provided, a source of credentials must also be |
| specified, such as "source_profile", "credential_source", or |
| "credential_process". |
| |
| role_arn = arn:aws:iam::<account_number>:role/<role_name> |
| source_profile = profile_with_creds |
| external_id = 1234 |
| mfa_serial = <serial or mfa arn> |
| role_session_name = session_name |
| |
| |
| The SDK supports assuming a role with MFA token. If "mfa_serial" is set, you |
| must also set the Session Option.AssumeRoleTokenProvider. The Session will fail |
| to load if the AssumeRoleTokenProvider is not specified. |
| |
| sess := session.Must(session.NewSessionWithOptions(session.Options{ |
| AssumeRoleTokenProvider: stscreds.StdinTokenProvider, |
| })) |
| |
| To setup Assume Role outside of a session see the stscreds.AssumeRoleProvider |
| documentation. |
| |
| Environment Variables |
| |
| When a Session is created several environment variables can be set to adjust |
| how the SDK functions, and what configuration data it loads when creating |
| Sessions. All environment values are optional, but some values like credentials |
| require multiple of the values to set or the partial values will be ignored. |
| All environment variable values are strings unless otherwise noted. |
| |
| 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=SECRET # only read if AWS_SECRET_ACCESS_KEY is not set. |
| |
| # Session Token |
| AWS_SESSION_TOKEN=TOKEN |
| |
| 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-east-1 |
| |
| # AWS_DEFAULT_REGION is only read if AWS_SDK_LOAD_CONFIG is also set, |
| # and AWS_REGION is not also set. |
| AWS_DEFAULT_REGION=us-east-1 |
| |
| Profile name the SDK should load use when loading shared config from the |
| configuration files. If not provided "default" will be used as the profile name. |
| |
| AWS_PROFILE=my_profile |
| |
| # AWS_DEFAULT_PROFILE is only read if AWS_SDK_LOAD_CONFIG is also set, |
| # and AWS_PROFILE is not also set. |
| AWS_DEFAULT_PROFILE=my_profile |
| |
| SDK load config instructs the SDK to load the shared config in addition to |
| shared credentials. This also expands the configuration loaded so the shared |
| credentials will have parity with the shared config file. This also enables |
| Region and Profile support for the AWS_DEFAULT_REGION and AWS_DEFAULT_PROFILE |
| env values as well. |
| |
| AWS_SDK_LOAD_CONFIG=1 |
| |
| Shared credentials file path can be set to instruct the SDK to use an alternative |
| 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 |
| |
| Shared config file path can be set to instruct the SDK to use an alternative |
| 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 |
| |
| Path to a custom Credentials Authority (CA) bundle PEM file 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. |
| |
| AWS_CA_BUNDLE=$HOME/my_custom_ca_bundle |
| |
| 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 file |
| 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. |
| |
| 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 session. Not the service client. |
| */ |
| package session |