Contributing to a Terraform provider

Terraform is a powerful infrastructure as code tool, giving companies a way to manage their cloud infrastructure in a way that is reliable, scalable, and available. Infrastructure as code has several distinct advantages to ClickOps/console management:

• Version control means reviewing and managing changes is possible
• Automation, consistency, and repeatability
• Code itself serves as living documentation
• Testing and validation is easier
• Compliance and security becomes easier to manage

Terraform providers

Many Terraform providers are massive, encompassing many resources and thousands of different properties across them all. When companies release new cloud services or even make updates to existing ones, they often neglect to update documentation (believe it or not).

Terraform providers are written in Go and typically consist of:

• Resources: Manage the lifecycle of infrastructure objects.
• Data Sources: Read existing infrastructure data.

The main entry point is main.go, which initializes the provider plugin.

How to make an update

Step 1: Identify if you actually need to make an update. I’ve made many a pointless PR in my day, and I want to save you time!

Step 2: Fork and clone the repo

Step 3: Set up your dev environment

• Install Go: Ensure you have the required version of Go installed (check the provider's documentation for the specific version).
• Install Terraform: Download and install the latest version of Terraform.
• Configure Your Environment: Set up your GOPATH, GOROOT, and other necessary environment variables.

Step 4: Read contributing.md if there is one

Maintainers are usually looking for small, focused changes in the same style as the provider.

Step 5: Create a branch for your changes

Step 6: Implement your changes

Some changes could be as simple as updating the provider’s data model, while more complex changes could include adding a new resource.

Suppose we want to add a new optional argument instance_initiated_shutdown_behavior to the existing aws_instance resource, allowing users to specify the shutdown behavior for EC2 instances (note that this argument currently exists).

You would navigate to the aws_instance resource file: in your terminal run cd internal/service/ec2

After opening resource_aws_instance.go in your editor, add the new argument to the resource schema

"instance_initiated_shutdown_behavior": {
    Type:     schema.TypeString,
    Optional: true,
    Default:  "stop",
    ValidateFunc: validation.StringInSlice([]string{
        "stop",
        "terminate",
    }, false),
},

Since you are adding new parameters, you would want to update any relevant functions. In this case, in the resourceAwsInstanceCreate and resourceAwsInstanceUpdate functions you would want to retrieve the value from the schema and set it in the EC2 API request:

if v, ok := d.GetOk("instance_initiated_shutdown_behavior"); ok {
    launchTemplateData.InstanceInitiatedShutdownBehavior = aws.String(v.(string))
}

Similarly, you would want to update the resourceAwsInstanceRead function‍

d.Set("instance_initiated_shutdown_behavior", instance.InstanceInitiatedShutdownBehavior)

Step 7: Write tests

We won’t cover tests in detail, but you will want to write unit and acceptance tests.

Step 8: Add documentation

Make sure to update documentation for any new properties or resources that you add.

Step 9: Commit your changes and submit a PR

Real example: updating AWS HSM instance type

Recently, Preston Price on our team found that the AWS provider was missing a HSM type: hsm2m.medium. AWS released this new HSM type on August 20th, but a couple weeks later the new type had not been added to the provider. Preston submitted a PR that was accepted, you can see that here.

This PR both adds the new hsm_type, as well as adds mode as a property to the aws_cloudhsm_v2_cluster, which is a required property if hsm_type=hsm2m.medium. Preston even wrote a new acceptance test for hsm_type that didn’t yet exist. You can follow along with his merged PR for a strong example for how to contribute to Terraform providers.

Terraform providers are open source, for the better

Terraform providers are overwhelmingly open source for a reason: they make working with cloud infrastructure and services safer, easier, and more reliable. However, these providers are at times neglected or not updated in a timely manner.

Contributing to a Terraform provider is a meaningful way to enhance the tool’s IaC functionality and support the community. Your improvements can help engineers worldwide manage infrastructure more effectively.

‍