docs/provider: Split out endpoint customization into a new Custom Service Endpoints Guide

website/aws.erb

@@ -18,6 +18,10 @@
                             <a href="/docs/providers/aws/guides/version-2-upgrade.html">AWS Provider Version 2 Upgrade</a>
                         </li>
 
+                        <li<%= sidebar_current("docs-aws-guide-custom-service-endpoints") %>>
+                            <a href="/docs/providers/aws/guides/custom-service-endpoints.html">Custom Service Endpoints</a>
+                        </li>
+
                         <li<%= sidebar_current("learn-aws-guides") %>>
                             <a href="https://learn.hashicorp.com/terraform/?track=aws#aws">AWS Provider Track on HashiCorp Learn</a>
                         </li>

website/docs/guides/custom-service-endpoints.html.md

@@ -0,0 +1,144 @@
+---
+layout: "aws"
+page_title: "Terraform AWS Provider Custom Service Endpoint Configuration"
+sidebar_current: "docs-aws-guide-custom-service-endpoint"
+description: |-
+  Configuring the Terraform AWS Provider to connect to custom AWS service endpoints and AWS compatible solutions.
+---
+
+# 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](https://aws.amazon.com/compliance/fips/), 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.
+
+<!-- TOC depthFrom:2 -->
+
+- [Getting Started with Custom Endpoints](#getting-started-with-custom-endpoints)
+- [Available Endpoint Customizations](#available-endpoint-customizations)
+- [Connecting to Local AWS Compatible Solutions](#connecting-to-local-aws-compatible-solutions)
+    - [DynamoDB Local](#dynamodb-local)
+    - [LocalStack](#localstack)
+
+<!-- /TOC -->
+
+## 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.
+
+```hcl
+provider "aws" {
+  # ... potentially other provider configuration ...
+
+  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](https://www.terraform.io/docs/configuration/providers.html#alias-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:
+
+- `acm`
+- `apigateway`
+- `autoscaling`
+- `cloudformation`
+- `cloudwatch`
+- `cloudwatchevents`
+- `cloudwatchlogs`
+- `devicefarm`
+- `dynamodb`
+- `ec2`
+- `ecr`
+- `ecs`
+- `efs`
+- `elb`
+- `es`
+- `firehose`
+- `iam`
+- `kinesis_analytics`
+- `kinesis`
+- `kms`
+- `lambda`
+- `r53`
+- `rds`
+- `redshift`
+- `s3`
+- `s3control`
+- `ses`
+- `sns`
+- `sqs`
+- `ssm`
+- `sts`
+
+## 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html).
+
+An example provider configuration:
+
+```hcl
+provider "aws" {
+  access_key                  = "mock_access_key"
+  region                      = "us-east-1"
+  secret_key                  = "mock_secret_key"
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+  skip_requesting_account_id  = true
+
+  endpoints {
+    dynamodb = "http://localhost:8000"
+  }
+}
+```
+
+### LocalStack
+
+[LocalStack](https://localstack.cloud/) provides an easy-to-use test/mocking framework for developing Cloud applications.
+
+An example provider configuration:
+
+```hcl
+provider "aws" {
+  access_key                  = "mock_access_key"
+  region                      = "us-east-1"
+  s3_force_path_style         = true
+  secret_key                  = "mock_secret_key"
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+  skip_requesting_account_id  = true
+
+  endpoints {
+    apigateway     = "http://localhost:4567"
+    cloudformation = "http://localhost:4581"
+    cloudwatch     = "http://localhost:4582"
+    dynamodb       = "http://localhost:4569"
+    es             = "http://localhost:4578"
+    firehose       = "http://localhost:4573"
+    iam            = "http://localhost:4593"
+    kinesis        = "http://localhost:4568"
+    lambda         = "http://localhost:4574"
+    r53            = "http://localhost:4580"
+    redshift       = "http://localhost:4577"
+    s3             = "http://localhost:4572"
+    ses            = "http://localhost:4579"
+    sns            = "http://localhost:4575"
+    sqs            = "http://localhost:4576"
+    ssm            = "http://localhost:4583"
+    sts            = "http://localhost:4592"
+    # Currently unsupported
+    # secretsmanager = "http://localhost:4584"
+    # sfn            = "http://localhost:4585"
+  }
+}
+```

website/docs/index.html.markdown

@@ -171,6 +171,10 @@ In addition to [generic `provider` arguments](https://www.terraform.io/docs/conf
 * `assume_role` - (Optional) An `assume_role` block (documented below). Only one
   `assume_role` block may be in the configuration.
 
+* `endpoints` - (Optional) Configuration block for customizing service endpoints. See the
+[Custom Service Endpoints Guide](/docs/providers/aws/guides/custom-service-endpoints.html)
+for more information about connecting to alternate AWS endpoints or AWS compatible solutions.
+
 * `shared_credentials_file` = (Optional) This is the path to the shared credentials file.
   If this is not set and a profile is specified, `~/.aws/credentials` will be used.
 
@@ -282,128 +286,6 @@ This gives you a way to further restrict the permissions for the resulting tempo
 security credentials. You cannot use the passed policy to grant permissions that are
 in excess of those allowed by the access policy of the role that is being assumed.
 
-Nested `endpoints` block supports the following:
-
-* `acm` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom ACM endpoints.
-
-* `apigateway` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom API Gateway endpoints.
-
-* `cloudformation` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom CloudFormation endpoints.
-
-* `cloudwatch` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom CloudWatch endpoints.
-
-* `cloudwatchevents` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom CloudWatchEvents endpoints.
-
-* `cloudwatchlogs` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom CloudWatchLogs endpoints.
-
-* `devicefarm` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom DeviceFarm endpoints.
-
-* `dynamodb` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  `dynamodb-local`.
-
-* `ec2` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom EC2 endpoints.
-
-* `autoscaling` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom Autoscaling endpoints.
-
-* `ecr` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom ECR endpoints.
-
-* `ecs` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom ECS endpoints.
-
-* `elb` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom ELB endpoints.
-
-* `efs` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom EFS endpoints.
-
-* `es` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`.  It's typically used to connect to
-  custom Elasticsearch endpoints.
-
-* `firehose` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`.  It's typically used to connect to
-  custom Firehose endpoints.
-
-* `iam` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom IAM endpoints.
-
-* `kinesis` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  `kinesalite`.
-
-* `kms` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom KMS endpoints.
-
-* `lambda` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom Lambda endpoints.
-
-* `r53` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom Route53 endpoints.
-
-* `rds` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom RDS endpoints.
-
-* `redshift` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom Redshift endpoints.
-
-* `s3` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom S3 endpoints.
-
-* `s3control` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom S3 Control endpoints (e.g. account-level public access block).
-
-* `ses` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom SNS endpoints.
-
-* `sns` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom SNS endpoints.
-
-* `sqs` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom SQS endpoints.
-
-* `sts` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom STS endpoints.
-
-* `ssm` - (Optional) Use this to override the default endpoint
-  URL constructed from the `region`. It's typically used to connect to
-  custom SSM endpoints.
-
 ## Getting the Account ID
 
 If you use either `allowed_account_ids` or `forbidden_account_ids`,