Update developer guide to include account ID based endpoints (#4446)

boto3/docs/__init__.py

@@ -24,7 +24,7 @@ def generate_docs(root_dir, session):
     text files documenting each service.
 
     :param root_dir: The directory to write the reference files to. Each
-        service's reference documentation is loacated at
+        service's reference documentation is located at
         root_dir/reference/services/service-name.rst
 
     :param session: The boto3 session

docs/source/guide/configuration.rst

@@ -516,3 +516,129 @@ in the ``~/.aws/config`` file.
 .. _IAM Roles for Amazon EC2: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
 .. _Using IAM Roles: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
 .. _Sourcing Credentials with an External Process: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html
+
+
+Using Account ID-Based Endpoints
+--------------------------------
+Boto3 supports account ID-based endpoints, which improve performance and scalability by using your AWS account ID to streamline request routing for services that support this feature. When Boto3 resolves credentials containing an account ID, it automatically constructs an account ID-based endpoint instead of a regional endpoint.
+
+Account ID-based endpoints follow this format:
+
+.. code-block:: shell
+
+    https://<account-id>.myservice.<region>.amazonaws.com
+
+
+* ``<account-id>`` is the AWS account ID sourced from your credentials.
+* ``<region>`` is the AWS region where the request is being made.
+
+
+Supported Credential Providers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Boto3 can automatically construct account ID-based endpoints by sourcing the AWS account ID from the following places:
+
+* Credentials set using the ``boto3.client()`` method
+* Credentials set when creating a ``Session`` object
+* Environment variables
+* Assume role provider
+* Assume role with web identity provider
+* AWS IAM Identity Center credential provider
+* Shared credential file (``~/.aws/credentials``)
+* AWS config file (``~/.aws/config``)
+* Container credential provider
+
+You can read more about these locations in the :ref:`guide_credentials` guide.
+
+
+Configuring Account ID
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can provide an account ID along with your AWS credentials using one of the following:
+
+Passing it as a parameter when creating clients:
+
+.. code-block:: python
+
+    import boto3
+
+    client = boto3.client(
+        'dynamodb',
+        aws_access_key_id=ACCESS_KEY,
+        aws_secret_access_key=SECRET_KEY,
+        aws_account_id=ACCOUNT_ID
+    )
+
+Passing it as a parameter when creating a ``Session`` object:
+
+.. code-block:: python
+
+    import boto3
+
+    session = boto3.Session(
+        aws_access_key_id=ACCESS_KEY,
+        aws_secret_access_key=SECRET_KEY,
+        aws_account_id=ACCOUNT_ID
+    )
+
+Setting an environment variable:
+
+.. code-block:: shell
+
+    export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
+    export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
+    export AWS_ACCOUNT_ID=<ACCOUNT_ID>
+
+Setting it in the shared credentials or config file:
+
+.. code-block:: ini
+
+    [default]
+    aws_access_key_id=foo
+    aws_secret_access_key=bar
+    aws_account_id=baz
+
+
+Configuring Endpoint Routing Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The account ID endpoint mode is a setting that can be used to turn off account ID-based endpoint routing if necessary.
+
+Valid values are:
+
+* ``preferred`` – The endpoint should include account ID if available.
+* ``disabled`` – A resolved endpoint doesn't include account ID.
+* ``required`` – The endpoint must include account ID. If the account ID isn't available, the SDK throws an error.
+
+.. note::
+
+    The default behavior in Boto3 is ``preferred``.
+
+
+You can configure the setting using one of the following:
+
+Setting it in the ``Config`` object when creating clients:
+
+.. code-block:: python
+
+    import boto3
+    from botocore.config import Config
+
+    my_config = Config(
+        account_id_endpoint_mode = 'disabled'
+    )
+
+    client = boto3.client('dynamodb', config=my_config)
+
+Setting an environment variable:
+
+.. code-block:: shell
+
+    export AWS_ACCOUNT_ID_ENDPOINT_MODE=disabled
+
+Setting it in the shared credentials or config file:
+
+.. code-block:: ini
+
+    [default]
+    account_id_endpoint_mode=disabled