Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Service-specific endpoints

Service-specific endpoint configuration provides the option to use an endpoint of your choosing for API requests and to have that choice persist. These settings provide flexibility to support local endpoints, VPC endpoints, and third-party local Amazon development environments. Different endpoints can be used for testing and production environments. You can specify an endpoint URL for individual Amazon Web Services services.

Configure endpoints using environment variables

To route requests for all services to a custom endpoint URL, set the AWS_ENDPOINT_URL global environment variable.

export AWS_ENDPOINT_URL=http://localhost:4567

To route requests for a specific Amazon Web Services service to a custom endpoint URL, use the AWS_ENDPOINT_URL_<SERVICE> environment variable. Amazon DynamoDB has a serviceId of DynamoDB. For this service, the endpoint URL environment variable is AWS_ENDPOINT_URL_DYNAMODB. This endpoint takes precedence over the global endpoint set in AWS_ENDPOINT_URL for this service.

export AWS_ENDPOINT_URL_DYNAMODB=http://localhost:5678

As another example, Amazon Elastic Beanstalk has a serviceId of Elastic Beanstalk. The Amazon Web Services service identifier is based on the API model’s serviceId by replacing all spaces with underscores and uppercasing all letters. To set the endpoint for this service, the corresponding environment variable is AWS_ENDPOINT_URL_ELASTIC_BEANSTALK. For a list of all service-specific environment variables, see Identifiers for service-specific endpoints.

export AWS_ENDPOINT_URL_ELASTIC_BEANSTALK=http://localhost:5567

Configure endpoints using the shared config file

In the shared config file, endpoint_url is used in different places for different functionality.

The following example uses a services definition to configure a service-specific endpoint URL to be used for Amazon S3 and a custom global endpoint to be used for all other services:

[profile dev-s3-specific-and-global]
endpoint_url = http://localhost:1234
services = s3-specific

[services s3-specific]
s3 = 
  endpoint_url = https://play.min.io:9000

A single profile can configure endpoints for multiple services. This example shows how to set the service-specific endpoint URLs for Amazon S3 and Amazon Elastic Beanstalk in the same profile. Amazon Elastic Beanstalk has a serviceId of Elastic Beanstalk. The Amazon Web Services service identifier is based on the API model’s serviceId by replacing all spaces with underscores and lowercasing all letters. Thus, the service identifier key becomes elastic_beanstalk and settings for this service begin on the line elastic_beanstalk = . For a list of all service identifier keys to use in the services section, see Identifiers for service-specific endpoints.

[services testing-s3-and-eb]
s3 = 
  endpoint_url = http://localhost:4567
elastic_beanstalk = 
  endpoint_url = http://localhost:8000

[profile dev]
services = testing-s3-and-eb

The service configuration section can be used from multiple profiles. For example, two profiles can use the same services definition while altering other profile properties:

[services testing-s3]
s3 = 
  endpoint_url = https://localhost:4567

[profile testing-json]
output = json
services = testing-s3

[profile testing-text]
output = text
services = testing-s3

Configure endpoints in profiles using role-based credentials

If your profile has role-based credentials configured through a source_profile parameter for IAM assume role functionality, the SDK only uses service configurations for the specified profile. It does not use profiles that are role chained to it. For example, using the following shared config file:

[profile A]
credential_source = Ec2InstanceMetadata
endpoint_url = https://profile-a-endpoint.aws/

[profile B]
source_profile = A
role_arn = arn:aws:iam::123456789012:role/roleB
services = profileB

[services profileB]
ec2 = 
  endpoint_url = https://profile-b-ec2-endpoint.aws

If you use profile B and make a call in your code to Amazon EC2, the endpoint resolves as https://profile-b-ec2-endpoint.aws. If your code makes a request to any other service, the endpoint resolution will not follow any custom logic. The endpoint does not resolve to the global endpoint defined in profile A. For a global endpoint to take effect for profile B, you would need to set endpoint_url directly within profile B. For more information on the source_profile setting, see Assume role credential provider.

Precedence of settings

The settings for this feature can be used at the same time but only one value will take priority per service. For API calls made to a given Amazon Web Services service, the following order is used to select a value:

Compatibility with Amazon SDKs

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the Amazon SDK for Java and the Amazon SDK for Kotlin only.