File: README.md
Terraform AWS Provider
The AWS Provider enables Terraform to manage AWS resources.
Please note: We take Terraform's security and our users' trust very seriously. If you believe you have found a security issue in the Terraform AWS Provider, please responsibly disclose it by contacting us at [email protected].
File: docs/index.md
Welcome
The Terraform AWS Provider is the work of thousands of contributors, and is maintained by a small team within HashiCorp. This site contains extensive instructions about how to contribute and how the AWS provider works.
!!! tip
This documentation is intended for Terraform AWS Provider code developers. Typical operators writing and applying Terraform configurations do not need to read or understand this material.
!!! tip
New Resources and Data Sources need to be implemented using aws-sdk-go-v2 and terraform-plugin-framework.
Preferred tooling for the same would be our scaffolding tool, skaff.
Contribute
Please follow the following steps to ensure your contribution goes smoothly.
1. Configure Development Environment
Install Terraform and Go. Clone the repository, compile the provider, and set up testing. Refer to Configure Development Environment.
2. Debug Code
If you are looking to create or enhance code, such as a new resource or adding an argument to an existing resource, skip to the next step.
Finding and fixing errors in the AWS Provider can be difficult. We have a debugging guide to help you get started.
3. Change Code
Follow the guide for your contribution type and refer to the Development Reference materials as needed for additional details about provider design, expected naming conventions, guidance for error handling, etc.
| Contribution Guide | Description |
|---|---|
| Small Changes | Requirements for small additions or bug-fixes on existing resources/data sources |
| Resources | Allow the management of a logical resource within AWS by adding a new resource to the Terraform AWS Provider. |
| Data Source | Let your Terraform configurations use data from resources not under local management by creating ready only data sources. |
| Services | Allow Terraform (via the AWS Provider) to manage an entirely new AWS service by introducing the resources and data sources required to manage configuration of the service. |
| AWS Region | New regions are immediately usable with the provider with the caveat that a configuration workaround is required to skip validation of the region during cli operations. A small set of changes are required to make this workaround necessary. |
| Resource Name Generation | Allow a resource to either fully, or partially, generate its own resource names. This can be useful in cases where the resource name uniquely identifies the resource and it needs to be recreated. It can also be used when a name is required, but the specific name is not important. |
| Tagging Support | Many AWS resources allow assigning metadata via tags. However, frequently AWS services are launched without tagging support so this will often need to be added later. |
| Import Support | Adding import support allows terraform import to be run targeting an existing unmanaged resource and pulling its configuration into Terraform state. Typically import support is added during initial resource implementation but in some cases this will need to be added later. |
| Enhanced Region Support | Most AWS resources are Regional – they are created and exist in a single AWS Region. By default Regional resources have a top-level region argument that allows the Region to be configured. |
| End User Documentation | The provider documentation is displayed on the Terraform Registry and is sourced and refreshed from the provider repository during the release process. |
4. Write Tests
We require all changes to be covered by acceptance tests and/or unit tests, depending on the situation. In the context of the Terraform AWS Provider, acceptance tests are tests of interactions with AWS, such as creating, reading information about, and destroying AWS resources. In contrast, unit tests test functionality wholly within the provider itself, such as function tests.
If you are unable to pay for acceptance tests for your contributions, mention this in your pull request. We will happily accept "best effort" acceptance tests implementations and run them for you on our side. Your PR may take longer to merge, but this is not a blocker for contributions.
5. Continuous Integration
When submitting a pull request, you'll notice that we run several automated processes on your proposed change. Some of these processes are tests to ensure your contribution aligns with our standards. While we strive for accuracy, some users may find these tests confusing. Check out Continuous Integration for additional clarity.
For contributors working on GitHub Actions workflows or experiencing slow CI builds, see GitHub Actions Caching Strategy for details on how caching is optimized for this large codebase.
6. Update the Changelog
HashiCorp's open-source projects have always maintained a user-friendly, readable CHANGELOG.md that allows users to tell at a glance whether a release should have any effect on them, and to gauge the risk of an upgrade. Not all changes require an entry in the changelog, refer to our Changelog Process for details about when and how to create a changelog.
7. Create a Pull Request
When your contribution is ready, Create a Pull Request in the AWS provider repository.
Pull requests are usually triaged within a few days of creation and are prioritized based on community reactions. Our Prioritization Guides provide more details about the process.
Submit an Issue
In addition to contributions, we welcome bug reports and feature requests.
Join the Contributors Slack
For frequent contributors, it's useful to join the contributors Slack channel hosted within the HashiCorp Slack workspace. This Slack channel is used to discuss topics such as general contribution questions, suggestions for improving the contribution process, coordinating on pair programming sessions, etc. The channel is not intended as a place to request status updates on open issues or pull requests. For prioritization questions, instead refer to the prioritization guide.
To request to join, fill out the request form and allow time for the request to be reviewed and processed.
File: docs/README.md
Documentation
This directory contains documentation for the Terraform AWS Provider Contributor Guide. Resource and data source documentation is located in the website directory and available in the Terraform Registry.
Local Development
To serve the contributing guide locally, mkdocs and the mkdocs-material extension must be installed.
Both require Python and pip.
If using Homebrew, install both with
% brew install mkdocs-materialOtherwise, install directly using pip3
% pip3 install mkdocs% pip3 install mkdocs-materialOnce installed, the documentation can be served from the root directory:
% mkdocs serve --live-reload