Merge branch 'stable-website' into dynamodb_table_item_attribute

coveooss · Aug 8, 2019 · 852efa6 · 852efa6
2 parents 9ef176b + 0f21f59
commit 852efa6
Show file tree

Hide file tree

Showing 566 changed files with 47,425 additions and 9,253 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -24,6 +24,7 @@ ability to merge PRs and respond to issues.
     - [Checklists for Contribution](#checklists-for-contribution)
         - [Documentation Update](#documentation-update)
         - [Enhancement/Bugfix to a Resource](#enhancementbugfix-to-a-resource)
+        - [Adding Resource Import Support](#adding-resource-import-support)
         - [New Resource](#new-resource)
         - [New Service](#new-service)
         - [New Region](#new-region)
@@ -199,6 +200,18 @@ guidelines.
    folder. This is to avoid conflicts as the vendor versions tend to be fast-
    moving targets. We will plan to merge the PR with this change first.
 
+#### Adding Resource Import Support
+
+Adding import support for Terraform resources will allow existing infrastructure to be managed within Terraform. This type of enhancement generally requires a small to moderate amount of code changes.
+
+Comprehensive code examples and information about resource import support can be found in the [Extending Terraform documentation](https://www.terraform.io/docs/extend/resources/import.html).
+
+In addition to the below checklist and the items noted in the Extending Terraform documentation, please see the [Common Review Items](#common-review-items) sections for more specific coding and testing guidelines.
+
+- [ ] _Resource Code Implementation_: In the resource code (e.g. `aws/resource_aws_service_thing.go`), implementation of `Importer` `State` function
+- [ ] _Resource Acceptance Testing Implementation_: In the resource acceptance testing (e.g. `aws/resource_aws_service_thing_test.go`), implementation of `TestStep`s with `ImportState: true`
+- [ ] _Resource Documentation Implementation_: In the resource documentation (e.g. `website/docs/r/service_thing.html.markdown`), addition of `Import` documentation section at the bottom of the page
+
 #### New Resource
 
 Implementing a new resource is a good way to learn more about how Terraform
@@ -216,9 +229,22 @@ guidelines.
    covering their behavior. See [Writing Acceptance
    Tests](#writing-acceptance-tests) below for a detailed guide on how to
    approach these.
- - [ ] __Naming__: Resources should be named `aws_<service>_<name>` where
-   `service` is the AWS short service name and `name` is a short, preferably
-   single word, description of the resource. Use `_` as a separator.
+ - [ ] __Resource Naming__: Resources should be named `aws_<service>_<name>`,
+   using underscores (`_`) as the separator. Resources are namespaced with the
+   service name to allow easier searching of related resources, to align
+   the resource naming with the service for [Customizing Endpoints](https://www.terraform.io/docs/providers/aws/guides/custom-service-endpoints.html#available-endpoint-customizations),
+   and to prevent future conflicts with new AWS services/resources.
+   For reference:
+
+   - `service` is the AWS short service name that matches the entry in
+     `endpointServiceNames` (created via the [New Service](#new-service)
+     section)
+   - `name` represents the conceptual infrastructure represented by the
+     create, read, update, and delete methods of the service API. It should
+     be a singular noun. For example, in an API that has methods such as
+     `CreateThing`, `DeleteThing`, `DescribeThing`, and `ModifyThing` the name
+     of the resource would end in `_thing`.
+
  - [ ] __Arguments_and_Attributes__: The HCL for arguments and attributes should
    mimic the types and structs presented by the AWS API. API arguments should be
    converted from `CamelCase` to `camel_case`.
@@ -358,6 +384,7 @@ The following resource checks need to be addressed before your contribution can
   ```
 
 - [ ] __Uses resource.NotFoundError__: Custom errors for missing resources should use [`resource.NotFoundError`](https://godoc.org/github.com/hashicorp/terraform/helper/resource#NotFoundError).
+- [ ] __Uses resource.UniqueId()__: API fields for concurrency protection such as `CallerReference` and `IdempotencyToken` should use [`resource.UniqueId()`](https://godoc.org/github.com/hashicorp/terraform/helper/resource#UniqueId). The implementation includes a monotonic counter which is safer for concurrent operations than solutions such as `time.Now()`.
 - [ ] __Skips Exists Function__: Implementing a resource `Exists` function is extraneous as it often duplicates resource `Read` functionality. Ensure `d.SetId("")` is used to appropriately trigger resource recreation in the resource `Read` function.
 - [ ] __Skips id Attribute__: The `id` attribute is implicit for all Terraform resources and does not need to be defined in the schema.
 

diff --git a/.github/MAINTAINING.md b/.github/MAINTAINING.md
@@ -0,0 +1,267 @@
+# Maintaining the Terraform AWS Provider
+
+<!-- TOC depthFrom:2 -->
+
+- [Pull Requests](#pull-requests)
+    - [Pull Request Review Process](#pull-request-review-process)
+        - [Dependency Updates](#dependency-updates)
+            - [AWS Go SDK Updates](#aws-go-sdk-updates)
+            - [Terraform Updates](#terraform-updates)
+    - [Pull Request Merge Process](#pull-request-merge-process)
+- [Release Process](#release-process)
+
+<!-- /TOC -->
+
+## Pull Requests
+
+### Pull Request Review Process
+
+Notes for each type of pull request are (or will be) available in subsections below.
+
+- If you plan to be responsible for the pull request through the merge/closure process, assign it to yourself
+- Add `bug`, `enhancement`, `new-data-source`, `new-resource`, or `technical-debt` labels to match expectations from change
+- Perform a quick scan of open issues and ensure they are referenced in the pull request description (e.g. `Closes #1234`, `Relates #5678`). Edit the description yourself and mention this to the author:
+
+```markdown
+This pull request appears to be related to/solve #1234, so I have edited the pull request description to denote the issue reference.
+```
+
+- Review the contents of the pull request and ensure the change follows the relevant section of the [Contributing Guide](https://github.com/terraform-providers/terraform-provider-aws/blob/master/.github/CONTRIBUTING.md#checklists-for-contribution)
+- If the change is not acceptable, leave a long form comment about the reasoning and close the pull request
+- If the change is acceptable with modifications, leave a pull request review marked using the `Request Changes` option (for maintainer pull requests with minor modification requests, giving feedback with the `Approve` option is recommended so they do not need to wait for another round of review)
+- If the author is unresponsive for changes (by default we give two weeks), determine importance and level of effort to finish the pull request yourself including their commits or close the pull request
+- Run relevant acceptance testing ([locally](https://github.com/terraform-providers/terraform-provider-aws/blob/master/.github/CONTRIBUTING.md#running-an-acceptance-test) or in TeamCity) against AWS Commercial and AWS GovCloud (US) to ensure no new failures are being introduced
+- Approve the pull request with a comment outlining what steps you took that ensure the change is acceptable, e.g. acceptance testing output
+
+``````markdown
+Looks good, thanks @username! :rocket:
+
+Output from acceptance testing in AWS Commercial:
+
+```
+--- PASS: TestAcc...
+--- PASS: TestAcc...
+```
+
+Output from acceptance testing in AWS GovCloud (US):
+
+```
+--- PASS: TestAcc...
+--- PASS: TestAcc...
+```
+``````
+
+#### Dependency Updates
+
+##### AWS Go SDK Updates
+
+Almost exclusively, `github.com/aws/aws-sdk-go` updates are additive in nature. It is generally safe to only scan through them before approving and merging. If you have any concerns about any of the service client updates such as suspicious code removals in the update, or deprecations introduced, run the acceptance testing for potentially affected resources before merging.
+
+Authentication changes:
+
+Occassionally, there will be changes listed in the authentication pieces of the AWS Go SDK codebase, e.g. changes to `aws/session`. The AWS Go SDK `CHANGELOG` should include a relevant description of these changes under a heading such as `SDK Enhancements` or `SDK Bug Fixes`. If they seem worthy of a callout in the Terraform AWS Provider `CHANGELOG`, then upon merging we should include a similar message prefixed with the `provider` subsystem, e.g. `* provider: ...`.
+
+Additionally, if a `CHANGELOG` addition seemed appropriate, this dependency and version should also be updated in the Terraform S3 Backend, which currently lives in Terraform Core. An example of this can be found with https://github.com/terraform-providers/terraform-provider-aws/pull/9305 and https://github.com/hashicorp/terraform/pull/22055.
+
+CloudFront changes:
+
+CloudFront service client updates have previously caused an issue when a new field introduced in the SDK was not included with Terraform and caused all requests to error (https://github.com/terraform-providers/terraform-provider-aws/issues/4091). As a precaution, if you see CloudFront updates, run all the CloudFront resource acceptance testing before merging (`TestAccAWSCloudFront`).
+
+New Regions:
+
+These are added to the AWS Go SDK `aws/endpoints/defaults.go` file and generally noted in the AWS Go SDK `CHANGELOG` as `aws/endpoints: Updated Regions`. Since April 2019, new regions added to AWS now require being explicitly enabled before they can be used. Examples of this can be found when `me-south-1` was announced:
+
+- [Terraform AWS Provider issue](https://github.com/terraform-providers/terraform-provider-aws/issues/9545)
+- [Terraform AWS Provider AWS Go SDK update pull request](https://github.com/terraform-providers/terraform-provider-aws/pull/9538)
+- [Terraform AWS Provider data source update pull request](https://github.com/terraform-providers/terraform-provider-aws/pull/9547)
+- [Terraform S3 Backend issue](https://github.com/hashicorp/terraform/issues/22254)
+- [Terraform S3 Backend pull request](https://github.com/hashicorp/terraform/pull/22253)
+
+Typically our process for new regions is as follows:
+
+- Create new (if not existing) Terraform AWS Provider issue: Support Automatic Region Validation for `XX-XXXXX-#` (Location)
+- Create new (if not existing) Terraform S3 Backend issue: backend/s3: Support Automatic Region Validation for `XX-XXXXX-#` (Location)
+- [Enable the new region in an AWS testing account](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable) and verify AWS Go SDK update works with the new region with `export AWS_DEFAULT_REGION=XX-XXXXX-#` with the new region and run the `TestAccDataSourceAwsRegion_` acceptance testing or by building the provider and testing a configuration like the following:
+
+```hcl
+provider "aws" {
+  region = "me-south-1"
+}
+
+data "aws_region" "current" {}
+
+output "region" {
+  value = data.aws_region.current.name
+}
+```
+
+- Merge AWS Go SDK update in Terraform AWS Provider and close issue with the following information:
+
+``````markdown
+Support for automatic validation of this new region has been merged and will release with version <x.y.z> of the Terraform AWS Provider, later this week.
+
+---
+
+Please note that this new region requires [a manual process to enable](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable). Once enabled in the console, it takes a few minutes for everything to work properly.
+
+If the region is not enabled properly, or the enablement process is still in progress, you can receive errors like these:
+
+```console
+$ terraform apply
+
+Error: error validating provider credentials: error calling sts:GetCallerIdentity: InvalidClientTokenId: The security token included in the request is invalid.
+    status code: 403, request id: 142f947b-b2c3-11e9-9959-c11ab17bcc63
+
+  on main.tf line 1, in provider "aws":
+   1: provider "aws" {
+```
+
+---
+
+To use this new region before support has been added to Terraform AWS Provider version in use, you must disable the provider's automatic region validation via:
+
+```hcl
+provider "aws" {
+  # ... potentially other configuration ...
+
+  region                 = "me-south-1"
+  skip_region_validation = true
+}
+```
+``````
+
+- Update the Terraform AWS Provider `CHANGELOG` with the following:
+
+```markdown
+NOTES:
+
+* provider: Region validation now automatically supports the new `XX-XXXXX-#` (Location) region. For AWS operations to work in the new region, the region must be explicitly enabled as outlined in the [AWS Documentation](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable). When the region is not enabled, the Terraform AWS Provider will return errors during credential validation (e.g. `error validating provider credentials: error calling sts:GetCallerIdentity: InvalidClientTokenId: The security token included in the request is invalid`) or AWS operations will throw their own errors (e.g. `data.aws_availability_zones.current: Error fetching Availability Zones: AuthFailure: AWS was not able to validate the provided access credentials`). [GH-####]
+
+ENHANCEMENTS:
+
+* provider: Support automatic region validation for `XX-XXXXX-#` [GH-####]
+```
+
+- Follow the [Contributing Guide](https://github.com/terraform-providers/terraform-provider-aws/blob/master/.github/CONTRIBUTING.md#new-region) to submit updates for various data sources to support the new region
+- Submit the dependency update to the Terraform S3 Backend by running the following:
+
+```shell
+go get github.com/aws/aws-sdk-go@v#.#.#
+go mod tidy
+go mod vendor
+```
+
+- Create a S3 Bucket in the new region and verify AWS Go SDK update works with new region by building the Terraform S3 Backend and testing a configuration like the following:
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "XXX"
+    key    = "test"
+    region = "me-south-1"
+  }
+}
+
+output "test" {
+  value = timestamp()
+}
+```
+
+- After approval, merge AWS Go SDK update in Terraform S3 Backend and close issue with the following information:
+
+``````markdown
+Support for automatic validation of this new region has been merged and will release with the next version of the Terraform.
+
+This was verified on a build of Terraform with the update:
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "XXX"
+    key    = "test"
+    region = "me-south-1"
+  }
+}
+
+output "test" {
+  value = timestamp()
+}
+```
+
+Outputs:
+
+```console
+$ terraform init
+...
+Terraform has been successfully initialized!
+```
+
+---
+
+Please note that this new region requires [a manual process to enable](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable). Once enabled in the console, it takes a few minutes for everything to work properly.
+
+If the region is not enabled properly, or the enablement process is still in progress, you can receive errors like these:
+
+```console
+$ terraform init
+
+Initializing the backend...
+
+Error: error validating provider credentials: error calling sts:GetCallerIdentity: InvalidClientTokenId: The security token included in the request is invalid.
+```
+
+---
+
+To use this new region before this update is released, you must disable the Terraform S3 Backend's automatic region validation via:
+
+```hcl
+terraform {
+  # ... potentially other configuration ...
+
+  backend "s3" {
+    # ... other configuration ...
+
+    region                 = "me-south-1"
+    skip_region_validation = true
+  }
+}
+```
+``````
+
+- Update the Terraform S3 Backend `CHANGELOG` with the following:
+
+```markdown
+NOTES:
+
+* backend/s3: Region validation now automatically supports the new `XX-XXXXX-#` (Location) region. For AWS operations to work in the new region, the region must be explicitly enabled as outlined in the [AWS Documentation](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable). When the region is not enabled, the Terraform S3 Backend will return errors during credential validation (e.g. `error validating provider credentials: error calling sts:GetCallerIdentity: InvalidClientTokenId: The security token included in the request is invalid`). [GH-####]
+
+ENHANCEMENTS:
+
+* backend/s3: Support automatic region validation for `XX-XXXXX-#` [GH-####]
+```
+
+##### Terraform Updates
+
+Run the full acceptance testing suite against the pull request and verify there are no new or unexpected failures.
+
+### Pull Request Merge Process
+
+- Add this pull request to the upcoming release milestone
+- Add any linked issues that will be closed by the pull request to the same upcoming release milestone
+- Merge the pull request
+- Delete the branch (if the branch is on this repository)
+- Update the repository `CHANGELOG.md` by directly committing to the `master` branch. See also the [Extending Terraform documentation](https://www.terraform.io/docs/extend/best-practices/versioning.html) for more information about the expected CHANGELOG format.
+- Leave a comment on any issues closed by the pull request noting that it has been merged and when to expect the release containing it, e.g.
+
+```markdown
+The fix for this has been merged and will release with version X.Y.Z of the Terraform AWS Provider, expected in the XXX timeframe.
+```
+
+## Release Process
+
+- Create a milestone for the next release after this release (generally, the next milestone will be a minor version increase unless previously decided for a major or patch version)
+- Check the existing release milestone for open items and either work through them or move them to the next milestone
+- Run the HashiCorp (non-OSS) TeamCity release job with the `DEPLOYMENT_TARGET_VERSION` matching the expected release milestone and `DEPLOYMENT_NEXT_VERSION` matching the next release milestone
+- Wait for the TeamCity release job and TeamCity website deployment jobs to complete either by watching the build logs or Slack notifications
+- Close the release milestone
+- Create a new GitHub release with the release title exactly matching the tag and milestone (e.g. `v2.22.0`). This will trigger [HashiBot](https://github.com/apps/hashibot) release comments.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,7 +9,8 @@
 
 <!--- Thank you for keeping this note for the community --->
 
-Fixes #0000
+<!--- If your PR fully resolves and should automatically close the linked issue, use Closes. Otherwise, use Relates --->
+Relates OR Closes #0000
 
 Release note for [CHANGELOG](https://github.com/terraform-providers/terraform-provider-aws/blob/master/CHANGELOG.md):
 <!--