Custom Service Endpoint Configuration

The Terraform AWS Provider configuration can be customized to connect to non-default AWS service endpoints and AWS compatible solutions. This may be useful for environments with specific compliance requirements, such as using AWS FIPS 140-2 endpoints, connecting to AWS Snowball, SC2S, or C2S environments, or local testing.

This guide outlines how to get started with customizing endpoints, the available endpoint configurations, and offers example configurations for working with certain local development and testing solutions.

\~> NOTE: Support for connecting the Terraform AWS Provider with custom endpoints and AWS compatible solutions is offered as best effort. Individual Terraform resources may require compatibility updates to work in certain environments. Integration testing by HashiCorp during provider changes is exclusively done against default AWS endpoints at this time.

• Getting Started with Custom Endpoints
• Available Endpoint Customizations
• Connecting to Local AWS Compatible Solutions
• DynamoDB Local
• LocalStack

Getting Started with Custom Endpoints

To configure the Terraform AWS Provider to use customized endpoints, it can be done within provider declarations using the endpoints configuration block, e.g.,

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.provider.AwsProvider(this, "aws", {
  endpoints: [
    {
      dynamodb: "http://localhost:4569",
      s3: "http://localhost:4572",
    },
  ],
});

If multiple, different Terraform AWS Provider configurations are required, see the Terraform documentation on multiple provider instances for additional information about the alias provider configuration and its usage.

Available Endpoint Customizations

The Terraform AWS Provider allows the following endpoints to be customized.

Note: The Provider allows some service endpoints to be customized despite not supporting those services.

Note: For backward compatibility, some endpoints can be assigned using multiple service "keys" (e.g., dms, databasemigration, or databasemigrationservice). If you use more than one equivalent service key in your configuration, the provider will use the first endpoint value set. For example, in the configuration below we have set the DMS service endpoints using both dms and databasemigration. The provider will set the endpoint to whichever appears first. Subsequent values are ignored.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.provider.AwsProvider(this, "aws", {
  endpoints: [
    {
      databasemigration: "http://this.value.will.be.ignored.com",
      dms: "http://this.value.will.be.used.com",
    },
  ],
});

As a convenience, for compatibility with the Terraform S3 Backend, the following service endpoints can be configured using environment variables:

• DynamoDB: tfAwsDynamodbEndpoint (or Deprecated awsDynamodbEndpoint)
• IAM: tfAwsIamEndpoint (or Deprecated awsIamEndpoint)
• S3: tfAwsS3Endpoint (or Deprecated awsS3Endpoint)
• STS: tfAwsStsEndpoint (or Deprecated awsStsEndpoint)

Connecting to Local AWS Compatible Solutions

\~> NOTE: This information is not intended to be exhaustive for all local AWS compatible solutions or necessarily authoritative configurations for those documented. Check the documentation for each of these solutions for the most up to date information.

DynamoDB Local

The Amazon DynamoDB service offers a downloadable version for writing and testing applications without accessing the DynamoDB web service. For more information about this solution, see the DynamoDB Local documentation in the Amazon DynamoDB Developer Guide.

An example provider configuration:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.provider.AwsProvider(this, "aws", {
  accessKey: "mock_access_key",
  endpoints: [
    {
      dynamodb: "http://localhost:8000",
    },
  ],
  region: "us-east-1",
  secretKey: "mock_secret_key",
  skipCredentialsValidation: true,
  skipMetadataApiCheck: true,
  skipRequestingAccountId: true,
});

LocalStack

LocalStack provides an easy-to-use test/mocking framework for developing Cloud applications.

An example provider configuration:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.provider.AwsProvider(this, "aws", {
  accessKey: "mock_access_key",
  endpoints: [
    {
      apigateway: "http://localhost:4566",
      cloudformation: "http://localhost:4566",
      cloudwatch: "http://localhost:4566",
      dynamodb: "http://localhost:4566",
      es: "http://localhost:4566",
      firehose: "http://localhost:4566",
      iam: "http://localhost:4566",
      kinesis: "http://localhost:4566",
      lambda: "http://localhost:4566",
      redshift: "http://localhost:4566",
      route53: "http://localhost:4566",
      s3: "http://localhost:4566",
      secretsmanager: "http://localhost:4566",
      ses: "http://localhost:4566",
      sns: "http://localhost:4566",
      sqs: "http://localhost:4566",
      ssm: "http://localhost:4566",
      stepfunctions: "http://localhost:4566",
      sts: "http://localhost:4566",
    },
  ],
  region: "us-east-1",
  s3ForcePathStyle: true,
  secretKey: "mock_secret_key",
  skipCredentialsValidation: true,
  skipMetadataApiCheck: true,
  skipRequestingAccountId: true,
});