vendor/github.com/aws/aws-sdk-go/aws/session/doc.go

   1 /*
   2 Package session provides configuration for the SDK's service clients.
   3
   4 Sessions can be shared across all service clients that share the same base
   5 configuration.  The Session is built from the SDK's default configuration and
   6 request handlers.
   7
   8 Sessions should be cached when possible, because creating a new Session will
   9 load all configuration values from the environment, and config files each time
  10 the Session is created. Sharing the Session value across all of your service
  11 clients will ensure the configuration is loaded the fewest number of times possible.
  12
  13 Concurrency
  14
  15 Sessions are safe to use concurrently as long as the Session is not being
  16 modified. The SDK will not modify the Session once the Session has been created.
  17 Creating service clients concurrently from a shared Session is safe.
  18
  19 Sessions from Shared Config
  20
  21 Sessions can be created using the method above that will only load the
  22 additional config if the AWS_SDK_LOAD_CONFIG environment variable is set.
  23 Alternatively you can explicitly create a Session with shared config enabled.
  24 To do this you can use NewSessionWithOptions to configure how the Session will
  25 be created. Using the NewSessionWithOptions with SharedConfigState set to
  26 SharedConfigEnable will create the session as if the AWS_SDK_LOAD_CONFIG
  27 environment variable was set.
  28
  29 Creating Sessions
  30
  31 When creating Sessions optional aws.Config values can be passed in that will
  32 override the default, or loaded config values the Session is being created
  33 with. This allows you to provide additional, or case based, configuration
  34 as needed.
  35
  36 By default NewSession will only load credentials from the shared credentials
  37 file (~/.aws/credentials). If the AWS_SDK_LOAD_CONFIG environment variable is
  38 set to a truthy value the Session will be created from the configuration
  39 values from the shared config (~/.aws/config) and shared credentials
  40 (~/.aws/credentials) files. See the section Sessions from Shared Config for
  41 more information.
  42
  43 Create a Session with the default config and request handlers. With credentials
  44 region, and profile loaded from the environment and shared config automatically.
  45 Requires the AWS_PROFILE to be set, or "default" is used.
  46
  47         // Create Session
  48         sess := session.Must(session.NewSession())
  49
  50         // Create a Session with a custom region
  51         sess := session.Must(session.NewSession(&aws.Config{
  52                 Region: aws.String("us-east-1"),
  53         }))
  54
  55         // Create a S3 client instance from a session
  56         sess := session.Must(session.NewSession())
  57
  58         svc := s3.New(sess)
  59
  60 Create Session With Option Overrides
  61
  62 In addition to NewSession, Sessions can be created using NewSessionWithOptions.
  63 This func allows you to control and override how the Session will be created
  64 through code instead of being driven by environment variables only.
  65
  66 Use NewSessionWithOptions when you want to provide the config profile, or
  67 override the shared config state (AWS_SDK_LOAD_CONFIG).
  68
  69         // Equivalent to session.NewSession()
  70         sess := session.Must(session.NewSessionWithOptions(session.Options{
  71                 // Options
  72         }))
  73
  74         // Specify profile to load for the session's config
  75         sess := session.Must(session.NewSessionWithOptions(session.Options{
  76                  Profile: "profile_name",
  77         }))
  78
  79         // Specify profile for config and region for requests
  80         sess := session.Must(session.NewSessionWithOptions(session.Options{
  81                  Config: aws.Config{Region: aws.String("us-east-1")},
  82                  Profile: "profile_name",
  83         }))
  84
  85         // Force enable Shared Config support
  86         sess := session.Must(session.NewSessionWithOptions(session.Options{
  87                 SharedConfigState: session.SharedConfigEnable,
  88         }))
  89
  90 Adding Handlers
  91
  92 You can add handlers to a session for processing HTTP requests. All service
  93 clients that use the session inherit the handlers. For example, the following
  94 handler logs every request and its payload made by a service client:
  95
  96         // Create a session, and add additional handlers for all service
  97         // clients created with the Session to inherit. Adds logging handler.
  98         sess := session.Must(session.NewSession())
  99
 100         sess.Handlers.Send.PushFront(func(r *request.Request) {
 101                 // Log every request made and its payload
 102                 logger.Printf("Request: %s/%s, Payload: %s",
 103                         r.ClientInfo.ServiceName, r.Operation, r.Params)
 104         })
 105
 106 Deprecated "New" function
 107
 108 The New session function has been deprecated because it does not provide good
 109 way to return errors that occur when loading the configuration files and values.
 110 Because of this, NewSession was created so errors can be retrieved when
 111 creating a session fails.
 112
 113 Shared Config Fields
 114
 115 By default the SDK will only load the shared credentials file's (~/.aws/credentials)
 116 credentials values, and all other config is provided by the environment variables,
 117 SDK defaults, and user provided aws.Config values.
 118
 119 If the AWS_SDK_LOAD_CONFIG environment variable is set, or SharedConfigEnable
 120 option is used to create the Session the full shared config values will be
 121 loaded. This includes credentials, region, and support for assume role. In
 122 addition the Session will load its configuration from both the shared config
 123 file (~/.aws/config) and shared credentials file (~/.aws/credentials). Both
 124 files have the same format.
 125
 126 If both config files are present the configuration from both files will be
 127 read. The Session will be created from configuration values from the shared
 128 credentials file (~/.aws/credentials) over those in the shared config file (~/.aws/config).
 129
 130 Credentials are the values the SDK should use for authenticating requests with
 131 AWS Services. They are from a configuration file will need to include both
 132 aws_access_key_id and aws_secret_access_key must be provided together in the
 133 same file to be considered valid. The values will be ignored if not a complete
 134 group. aws_session_token is an optional field that can be provided if both of
 135 the other two fields are also provided.
 136
 137         aws_access_key_id = AKID
 138         aws_secret_access_key = SECRET
 139         aws_session_token = TOKEN
 140
 141 Assume Role values allow you to configure the SDK to assume an IAM role using
 142 a set of credentials provided in a config file via the source_profile field.
 143 Both "role_arn" and "source_profile" are required. The SDK supports assuming
 144 a role with MFA token if the session option AssumeRoleTokenProvider
 145 is set.
 146
 147         role_arn = arn:aws:iam::<account_number>:role/<role_name>
 148         source_profile = profile_with_creds
 149         external_id = 1234
 150         mfa_serial = <serial or mfa arn>
 151         role_session_name = session_name
 152
 153 Region is the region the SDK should use for looking up AWS service endpoints
 154 and signing requests.
 155
 156         region = us-east-1
 157
 158 Assume Role with MFA token
 159
 160 To create a session with support for assuming an IAM role with MFA set the
 161 session option AssumeRoleTokenProvider to a function that will prompt for the
 162 MFA token code when the SDK assumes the role and refreshes the role's credentials.
 163 This allows you to configure the SDK via the shared config to assumea role
 164 with MFA tokens.
 165
 166 In order for the SDK to assume a role with MFA the SharedConfigState
 167 session option must be set to SharedConfigEnable, or AWS_SDK_LOAD_CONFIG
 168 environment variable set.
 169
 170 The shared configuration instructs the SDK to assume an IAM role with MFA
 171 when the mfa_serial configuration field is set in the shared config
 172 (~/.aws/config) or shared credentials (~/.aws/credentials) file.
 173
 174 If mfa_serial is set in the configuration, the SDK will assume the role, and
 175 the AssumeRoleTokenProvider session option is not set an an error will
 176 be returned when creating the session.
 177
 178     sess := session.Must(session.NewSessionWithOptions(session.Options{
 179         AssumeRoleTokenProvider: stscreds.StdinTokenProvider,
 180     }))
 181
 182     // Create service client value configured for credentials
 183     // from assumed role.
 184     svc := s3.New(sess)
 185
 186 To setup assume role outside of a session see the stscreds.AssumeRoleProvider
 187 documentation.
 188
 189 Environment Variables
 190
 191 When a Session is created several environment variables can be set to adjust
 192 how the SDK functions, and what configuration data it loads when creating
 193 Sessions. All environment values are optional, but some values like credentials
 194 require multiple of the values to set or the partial values will be ignored.
 195 All environment variable values are strings unless otherwise noted.
 196
 197 Environment configuration values. If set both Access Key ID and Secret Access
 198 Key must be provided. Session Token and optionally also be provided, but is
 199 not required.
 200
 201         # Access Key ID
 202         AWS_ACCESS_KEY_ID=AKID
 203         AWS_ACCESS_KEY=AKID # only read if AWS_ACCESS_KEY_ID is not set.
 204
 205         # Secret Access Key
 206         AWS_SECRET_ACCESS_KEY=SECRET
 207         AWS_SECRET_KEY=SECRET=SECRET # only read if AWS_SECRET_ACCESS_KEY is not set.
 208
 209         # Session Token
 210         AWS_SESSION_TOKEN=TOKEN
 211
 212 Region value will instruct the SDK where to make service API requests to. If is
 213 not provided in the environment the region must be provided before a service
 214 client request is made.
 215
 216         AWS_REGION=us-east-1
 217
 218         # AWS_DEFAULT_REGION is only read if AWS_SDK_LOAD_CONFIG is also set,
 219         # and AWS_REGION is not also set.
 220         AWS_DEFAULT_REGION=us-east-1
 221
 222 Profile name the SDK should load use when loading shared config from the
 223 configuration files. If not provided "default" will be used as the profile name.
 224
 225         AWS_PROFILE=my_profile
 226
 227         # AWS_DEFAULT_PROFILE is only read if AWS_SDK_LOAD_CONFIG is also set,
 228         # and AWS_PROFILE is not also set.
 229         AWS_DEFAULT_PROFILE=my_profile
 230
 231 SDK load config instructs the SDK to load the shared config in addition to
 232 shared credentials. This also expands the configuration loaded so the shared
 233 credentials will have parity with the shared config file. This also enables
 234 Region and Profile support for the AWS_DEFAULT_REGION and AWS_DEFAULT_PROFILE
 235 env values as well.
 236
 237         AWS_SDK_LOAD_CONFIG=1
 238
 239 Shared credentials file path can be set to instruct the SDK to use an alternative
 240 file for the shared credentials. If not set the file will be loaded from
 241 $HOME/.aws/credentials on Linux/Unix based systems, and
 242 %USERPROFILE%\.aws\credentials on Windows.
 243
 244         AWS_SHARED_CREDENTIALS_FILE=$HOME/my_shared_credentials
 245
 246 Shared config file path can be set to instruct the SDK to use an alternative
 247 file for the shared config. If not set the file will be loaded from
 248 $HOME/.aws/config on Linux/Unix based systems, and
 249 %USERPROFILE%\.aws\config on Windows.
 250
 251         AWS_CONFIG_FILE=$HOME/my_shared_config
 252
 253 Path to a custom Credentials Authority (CA) bundle PEM file that the SDK
 254 will use instead of the default system's root CA bundle. Use this only
 255 if you want to replace the CA bundle the SDK uses for TLS requests.
 256
 257         AWS_CA_BUNDLE=$HOME/my_custom_ca_bundle
 258
 259 Enabling this option will attempt to merge the Transport into the SDK's HTTP
 260 client. If the client's Transport is not a http.Transport an error will be
 261 returned. If the Transport's TLS config is set this option will cause the SDK
 262 to overwrite the Transport's TLS config's  RootCAs value. If the CA bundle file
 263 contains multiple certificates all of them will be loaded.
 264
 265 The Session option CustomCABundle is also available when creating sessions
 266 to also enable this feature. CustomCABundle session option field has priority
 267 over the AWS_CA_BUNDLE environment variable, and will be used if both are set.
 268
 269 Setting a custom HTTPClient in the aws.Config options will override this setting.
 270 To use this option and custom HTTP client, the HTTP client needs to be provided
 271 when creating the session. Not the service client.
 272 */
 273 package session