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:
Note
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:
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)
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.
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.
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
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.
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 to path 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.
The profile name that contains credentials to use for the initial AssumeRole call.
The credential_source and source_profile settings are mutually exclusive.
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:
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.
Uses the global STS endpoint, sts.amazonaws.com, for the following configured Regions:
All other Regions will use their respective regional endpoint.
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 a max_attempts is explicitly provided.
- adaptive - An experimental retry mode that includes all the functionality of standard mode with automatic client-side throttling. This is a provisional mode whose behavior might change.