Boto3 looks at various configuration locations until it finds configuration values. Boto3 adheres to the following lookup order when searching through sources for configuration values:
Config
object that's created and passed as the config
parameter when creating a client~/.aws/config
fileNote
Configurations are not wholly atomic. This means configuration values set in your AWS config file can be singularly overwritten by setting a specific environment variable or through the use of a Config
object.
For details about credential configuration, see the Credentials guide.
This option is for configuring client-specific configurations that affect the behavior of your specific client object only. As described earlier, there are options used here that will supersede those found in other configuration locations:
region_name
(string) - The AWS Region used in instantiating the client. If used, this takes precedence over environment variable and configuration file values. But it doesn't overwrite a region_name
value explicitly passed to individual service methods.signature_version
(string) - The signature version used when signing requests. Note that the default version is Signature Version 4. If you're using a presigned URL with an expiry of greater than 7 days, you should specify Signature Version 2.s3
(related configurations; dictionary) - Amazon S3 service-specific configurations. For more information, see the Botocore config reference.proxies
(dictionary) - Each entry maps a protocol name to the proxy server Boto3 should use to communicate using that protocol. See Specifying proxy servers for more information.proxies_config
(dictionary) - Additional proxy configuration settings. For more information, see Configuring proxies.retries
(dictionary) - Client retry behavior configuration options that include retry mode and maximum retry attempts. For more information, see the Retries guide.For more information about additional options, or for a complete list of options, see the Config reference.
To set these configuration options, create a Config
object with the options you want, and then pass them into your client.
import boto3
from botocore.config import Config
my_config = Config(
region_name = 'us-west-2',
signature_version = 'v4',
retries = {
'max_attempts': 10,
'mode': 'standard'
}
)
client = boto3.client('kinesis', config=my_config)
With Boto3, you can use proxies as intermediaries between your code and AWS. Proxies can provide functions such as filtering, security, firewalls, and privacy assurance.
You can specify proxy servers to be used for connections when using specific protocols. The proxies
option in the Config
object is a dictionary in which each entry maps a protocol to the address and port number of the proxy server for that protocol.
In the following example, a proxy list is set up to use proxy.amazon.com
, port 6502 as the proxy for all HTTP requests by default. HTTPS requests use port 2010 on proxy.amazon.org
instead.
import boto3
from botocore.config import Config
proxy_definitions = {
'http': 'http://proxy.amazon.com:6502',
'https': 'https://proxy.amazon.org:2010'
}
my_config = Config(
region_name='us-east-2',
signature_version='v4',
proxies=proxy_definitions
)
client = boto3.client('kinesis', config=my_config)
Alternatively, you can use the HTTP_PROXY
and HTTPS_PROXY
environment variables to specify proxy servers. Proxy servers specified using the proxies
option in the Config
object will override proxy servers specified using environment variables.
You can configure how Boto3 uses proxies by specifying the proxies_config
option, which is a dictionary that specifies the values of several proxy options by name. There are three keys in this dictionary: proxy_ca_bundle
, proxy_client_cert
, and proxy_use_forwarding_for_https
. For more information about these keys, see the Botocore config reference.
import boto3
from botocore.config import Config
proxy_definitions = {
'http': 'http://proxy.amazon.com:6502',
'https': 'https://proxy.amazon.org:2010'
}
my_config = Config(
region_name='us-east-2',
signature_version='v4',
proxies=proxy_definitions,
proxies_config={
'proxy_client_cert': '/path/of/certificate'
}
)
client = boto3.client('kinesis', config=my_config)
With the addition of the proxies_config
option shown here, the proxy will use the specified certificate file for authentication when using the HTTPS proxy.
You can set configuration settings using system-wide environment variables. These configurations are global and will affect all clients created unless you override them with a Config
object.
Note
Only the configuration settings listed below can be set using environment variables.
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
AWS_SECURITY_TOKEN
environment variable can also be used, but is only supported
for backward-compatibility purposes. AWS_SESSION_TOKEN
is
supported by multiple AWS SDKs in addition to Boto3.AWS_DEFAULT_REGION
us-west-1
or us-west-2
.AWS_PROFILE
default
profile.AWS_CONFIG_FILE
~/.aws/config
. You only need to set this variable if
you want to change this location.AWS_SHARED_CREDENTIALS_FILE
~/.aws/credentials
. You only need to set this variable if
you want to change this location.BOTO_CONFIG
/etc/boto.cfg
or ~/.boto
.AWS_CA_BUNDLE
AWS_METADATA_SERVICE_TIMEOUT
AWS_METADATA_SERVICE_NUM_ATTEMPTS
AWS_DATA_PATH
<botocoreroot>/data/
and ~/.aws/models
. Setting this
environment variable indicates additional directories to check first before
falling back to the built-in search paths. Multiple entries should be
separated with the os.pathsep
character, which is :
on Linux and
;
on Windows.AWS_STS_REGIONAL_ENDPOINTS
sts_regional_endpoints
configuration file section for more information on how to use this.AWS_MAX_ATTEMPTS
max_attempts
configuration file section.AWS_RETRY_MODE
retry_mode
configuration file section.Boto3 will also search the ~/.aws/config
file when looking for
configuration values. You can change the location of this file by
setting the AWS_CONFIG_FILE
environment variable.
This file is an INI-formatted file that contains at least one
section: [default]
. You can create multiple profiles (logical
groups of configuration) by creating sections named [profile profile-name]
.
If your profile name has spaces, you need to surround this value with quotation marks:
[profile "my profile name"]
. The following are all the config variables supported
in the ~/.aws/config
file.
api_versions
Specifies the API version to use for a particular AWS service.
The api_versions
settings are nested configuration values that require special
formatting in the AWS configuration file. If the values are set by the
AWS CLI or programmatically by an SDK, the formatting is handled
automatically. If you set them by manually editing the AWS configuration
file, the following is the required format. Notice the indentation of each
value.
[default]
region = us-east-1
api_versions =
ec2 = 2015-03-01
cloudfront = 2015-09-17
aws_access_key_id
aws_secret_access_key
aws_session_token
aws_security_token
is supported for
backward compatibility.ca_bundle
AWS_CA_BUNDLE
environment variable.credential_process
credential_source
To invoke an AWS service from an Amazon EC2 instance, you can use
an IAM role attached to either an EC2 instance profile or an Amazon ECS
container. In such a scenario, use the credential_source
setting to
specify where to find the credentials.
The credential_source
and source_profile
settings are mutually
exclusive.
The following values are supported.
Ec2InstanceMetadata
- Use the IAM role attached to the Amazon EC2 instance profile.
EcsContainer
- Use the IAM role attached to the Amazon ECS container.
Environment
- Retrieve the credentials from environment variables.
duration_seconds
external_id
AssumeRole
calls.metadata_service_timeout
AWS_METADATA_SERVICE_TIMEOUT
.metadata_service_num_attempts
AWS_METADATA_SERVICE_NUM_ATTEMPTS
.mfa_serial
parameter_validation
true
or false
. Whenever you make an
API call using a client, the parameters you provide are run through
a set of validation checks, including (but not limited to) required
parameters provided, type checking, no unknown parameters,
minimum length checks, and so on. Typically, you should leave parameter
validation enabled.region
us-west-1
or us-west-2
. When
specifying a Region inline during client initialization, this property
is named region_name
.role_arn
role_session_name
web_identity_token_file
WebIdentityToken
argument to
the AssumeRoleWithWebIdentity
operation.s3
Set Amazon S3-specific configuration data. Typically, these values do not need to be set.
The s3
settings are nested configuration values that require special
formatting in the AWS configuration file. If the values are set by the
AWS CLI or programmatically by an SDK, the formatting is handled
automatically. If you set them manually by editing the AWS configuration
file, the following is the required format. Notice the indentation of each
value.
[default]
region = us-east-1
s3 =
addressing_style = path
signature_version = s3v4
addressing_style
: The S3 addressing style. When necessary, Boto
automatically switches the addressing style to an appropriate value.
The following values are supported.
auto
(Default) Attempts to use
virtual
, but falls back topath
if necessary.path
Bucket name is included in the URI path.
virtual
Bucket name is included in the hostname.
payload_signing_enabled
: Specifies whether to include an SHA-256
checksum with Amazon Signature Version 4 payloads. Valid settings are
true
or false
.
For streaming uploads (UploadPart
and PutObject
) that use HTTPS
and include a content-md5
header, this setting is disabled by default.
signature_version
: The AWS signature version to use when signing
requests. When necessary, Boto automatically switches the signature
version to an appropriate value. The following values are recognized.
s3v4
(Default) Signature Version 4
s3
(Deprecated) Signature Version 2
use_accelerate_endpoint
: Specifies whether to use the Amazon S3 Accelerate
endpoint. The bucket must be enabled to use S3 Accelerate. Valid settings
are true
or false
. Default: false
Either use_accelerate_endpoint
or use_dualstack_endpoint
can be
enabled, but not both.
use_dualstack_endpoint
: Specifies whether to direct all Amazon S3
requests to the dual IPv4/IPv6 endpoint for the configured Region. Valid
settings are true
or false
. Default: false
Either use_accelerate_endpoint
or use_dualstack_endpoint
can be
enabled, but not both.
source_profile
The profile name that contains credentials to use for the initial
AssumeRole
call.
The credential_source
and source_profile
settings are mutually
exclusive.
sts_regional_endpoints
Sets AWS STS endpoint resolution logic. This configuration can also be set
using the environment variable AWS_STS_REGIONAL_ENDPOINTS
. By default,
this configuration option is set to legacy
. Valid values are the following:
regional
Uses the STS endpoint that corresponds to the configured Region. For
example, if the client is configured to use us-west-2
, all calls
to STS will be made to the sts.us-west-2.amazonaws.com
regional
endpoint instead of the global sts.amazonaws.com
endpoint.
legacy
Uses the global STS endpoint, sts.amazonaws.com
, for the following
configured Regions:
ap-northeast-1
ap-south-1
ap-southeast-1
ap-southeast-2
aws-global
ca-central-1
eu-central-1
eu-north-1
eu-west-1
eu-west-2
eu-west-3
sa-east-1
us-east-1
us-east-2
us-west-1
us-west-2
All other Regions will use their respective regional endpoint.
tcp_keepalive
false
; TCP Keepalive will not be used
when creating connections. To enable TCP Keepalive with the system default configurations,
set this value to true
.max_attempts
legacy
retry mode,
and 3 in the standard
and adaptive
retry modes.retry_mode
A string representing the type of retries Boto3 will perform. Valid values are the following:
legacy
- The preexisting retry behavior. This is the default value if no retry mode is provided.standard
- A standardized set of retry rules across the AWS SDKs. This includes a standard set of errors that are retried and support for retry quotas, which limit the number of unsuccessful retries an SDK can make. This mode will default the maximum number of attempts to 3 unless amax_attempts
is explicitly provided.adaptive
- An experimental retry mode that includes all the functionality ofstandard
mode with automatic client-side throttling. This is a provisional mode whose behavior might change.