Hashicorp

Contributing to the Terraform Provider AWS, a beginner guide.

Jeremy Chauvet

Dec 15, 2023 — 5 min read

Terraform is a powerful tool designed to track the state of resources. It integrate a myriad of plugins and providers, allowing users to interact with a vast ecosystem of services and APIs.

Most of these providers are open-source, inviting contributions from anyone to introduce new services, add features, or resolve bugs. In this article, we will address commonly asked questions.

How can I find an easy issue to start?

The Terraform provider AWS code is hosted on Github. The maintainers are using GitHub issues to prioritize bugs and features.

Once an issue is created on the project, the maintainers will proceed to a pre-filtering, closing duplicate issues or adding labels to help project and release management.

The maintainers sometimes add a label "good first issue" to issue requiring a low level of knowledge on the code, or the provider itself. However, a minimal understanding of the AWS service related to the issue is needed.

You can filter issues by labels, allowing to easily find the first good issues

For a first contribution, I will suggest starting with:

An AWS service you use frequently: familiarity with the service's logic will enhance your understanding of the impact of any change you make.
A service easy to test: some services are more complex than others: for example, S3 is a service of relatively limited complexity, making it easy to test and debug. In contrast, services like Redshift, DMS, or DirectConnect are requiring a deeper understanding of the service it-self and are costly to test.

What is the minimal setup to start working on an issue?

Working on the provider requires softwares and tools to be installed on your computer. Here's the list.

Go

As the provider is coded in Go, this programming language must be installed. It will be required to build and test the provider.

A GitHub account

Will be used to fork the repository and create a Pull Request.

Optional - An AWS account

Will be used to provision the resources during the acceptance test. This is not mandatory, you can open a Pull Request without having executed acceptances test (please mention it while submitting it), but changes must at least be covered by acceptances tests (existing or to be created).

An IDE

Depending on your preferences or your budget, two IDE can fit the need:

Visual Studio Code - https://code.visualstudio.com/
The polyvalent IDE from Microsoft. Install the official Google Go extension from the store
GoLand, by Jetbrains - https://www.jetbrains.com/go

Tools

Make - To automate actions such a run acceptance tests.
Git - To clone the repository on your computer and track changes.
AWS CLI - To authenticate to AWS via the command line (optional).
Once the provider code is clone on your computer, and Make installed, you can use the command `make tools` to install the provider required tools.

You are now ready to go!

How can I test my feature/fix?

Launching an acceptance test is a single line command. Let's see it in action in multiple context.

Skeleton

The following command will run any test related to DMS service. Please note the underscore at the end of the value of TESTS . This can be considered as a prefix wildcard.

make testacc TESTS=TestAccDMSReplicationTask_ PKG=dms

Keep in mind running a test will provision resources in an AWS account, which can be costly depending on the test you are executing. As no profile is set, the default profile will be used.

Executing a specific test

The following command can be used to execute to target a specific test:

make testacc TESTS=TestAccDMSReplicationTask_basic PKG=dms

Increase test log level

Tests will provision resources in an AWS account, using Terraform (obviously..). You can increase the log level using a Terraform CLI parameter:

TF_LOG=debug make testacc TESTS=TestAccDMSReplicationTask_basic PKG=dms

Use a specific AWS account

You can choose the target AWS account by using `AWS_PROFILE` parameter:

AWS_PROFILE=acme TF_LOG=debug make testacc TESTS=TestAccDMSReplicationTask_basic PKG=dms

What's required to open a Pull Request?

Before opening a Pull Request, there are several important steps to follow. Firstly, check if your change is covered by an acceptance test. Double check your code on GitHub, and clean your code from debug traces and undesired files (eg: .DS_Store files from macOS)

If you're adding a new parameter in a resource / a datasource, you must also update the associated documentation, used by the website. You can find the documentation about resources here and datasources here (inside website folder on your computer).

Every new version of the provider should include a release note that describe what's new / fixed or enhanced.
Therefore, you need to add a changelog to your Pull Request. A new txt file must be created in .archive/changelog folder (Note the folder can be hidden if you're using Ubuntu, Debian, and other Linux distributions).
The file name should be the ID number of your Pull Request. To do this, first create the Pull Request with your changes and obtain the ID number, then add a new commit with the changelog.

Finally, don't forget to mention the issue you are solving or relating in the description of the Pull Request. This helps closing related issues once the Pull Request is merged.

This marks the conclusion of our introductory course on contributing to the Terraform AWS provider. Remember, all contributions are welcomed and appreciated!