diff options
Diffstat (limited to 'vendor/github.com/aws/aws-sdk-go/aws/session/doc.go')
-rw-r--r-- | vendor/github.com/aws/aws-sdk-go/aws/session/doc.go | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/vendor/github.com/aws/aws-sdk-go/aws/session/doc.go b/vendor/github.com/aws/aws-sdk-go/aws/session/doc.go new file mode 100644 index 0000000..ea7b886 --- /dev/null +++ b/vendor/github.com/aws/aws-sdk-go/aws/session/doc.go | |||
@@ -0,0 +1,273 @@ | |||
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.Println("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 arfrom 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 stscrds.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 | ||