Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Terraform AWS provider is a plugin for Terraform that enables the full lifecycle management of AWS resources. Maintained by the HashiCorp AWS Provider team, its architecture is designed for scalability, maintainability, and community contribution. The provider's structure is highly modular, with a clear separation of concerns for each AWS service it supports.
This overview details the provider's high-level structure, its service-oriented package design, the development and testing workflows, and its strategic direction as outlined in public roadmaps. The architecture facilitates the continuous addition of new resources and enhancements while maintaining a stable and reliable core.
Sources: README.md:13-14
Service-Oriented Package Structure
A core architectural principle of the provider is its modular design, where code is organized into distinct packages for each AWS service. This is evident within the internal/service/ directory, which contains subdirectories for services such as Amplify, AppMesh, Cloud9, CodeCommit, DMS, DocDB, FMS, Glue, MWAA, Neptune, Schemas, and WAF.
Each service-specific package is intended for provider contributors and maintainers, encapsulating the logic for that service's resources and data sources. This approach isolates service-specific implementations, simplifying maintenance and making it easier for contributors to focus on a particular area of the provider without needing to understand the entire codebase.
Sources: internal/service/amplify/README.md:2, internal/service/appmesh/README.md:2, internal/service/cloud9/README.md:2, internal/service/dms/README.md:2, internal/service/docdb/README.md:2, internal/service/fms/README.md:2, internal/service/glue/README.md:2, internal/service/mwaa/README.md:2, internal/service/neptune/README.md:2, internal/service/schemas/README.md:2, internal/service/waf/README.md:2
The following diagram illustrates this modular package structure.
Development and Contribution Workflow
The project's architecture extends to its development and contribution processes, which are managed and automated to ensure consistency and clarity.
Issue and Pull Request Management
The repository uses a well-defined set of GitHub issue labels to categorize and manage work. These labels are defined as code using Terraform in the infrastructure/repository/labels-workflow.tf file. This system provides a clear workflow for triaging issues, identifying work for new contributors, and tracking the size and type of changes.
The diagram below shows a simplified flow of how an issue or PR is processed using these labels.
Key workflow labels include:
| Label | Description |
|---|---|
bug | Addresses a defect in current functionality. |
enhancement | Requests to existing resources that expand the functionality or scope. |
new-data-source | Introduces a new data source. |
new-resource | Introduces a new resource. |
breaking-change | Introduces a breaking change in current functionality; usually deferred to the next major release. |
good first issue | Call to action for new contributors looking for a place to start. |
needs-triage | Waiting for first response or review from a maintainer. |
technical-debt | Addresses areas of the codebase that need refactoring or redesign. |
Sources: infrastructure/repository/labels-workflow.tf:12-121
Strategic Planning and Roadmap
The project's direction is guided by a quarterly roadmap that highlights areas of focus. This roadmap is informed by top community issues, core service requirements, and internal priorities. It outlines planned new services, enhancements to existing services, and long-term research topics. This structured planning ensures that development efforts are aligned with user needs and strategic goals.
Sources: ROADMAP.md:3-7
Testing Architecture
The provider employs a robust testing strategy centered on acceptance tests. These tests are written in Go and leverage the terraform-plugin-sdk/v2 framework to perform full lifecycle actions (Create, Read, Update, Delete) against real AWS infrastructure.
Acceptance Test Structure
An acceptance test is defined using a resource.TestCase. The structure from internal/service/codecommit/approval_rule_template_test.go serves as a representative example.
Key components of a TestCase include:
PreCheck: A function to verify prerequisites before running the test (e.g., credentials are set).Providers: A map of the providers to be used in the test.CheckDestroy: A function that runs after the resource is destroyed by Terraform to verify it no longer exists in the target environment.Steps: A series ofTestStepobjects, each defining a Terraform configuration (Config) and aCheckfunction to validate the resulting state.
Sources: internal/service/codecommit/approval_rule_template_test.go:25-39
The following sequence diagram illustrates the lifecycle of a typical acceptance test step.
Future Architectural Direction
The project's roadmap includes research into architectural changes that will improve the developer experience and maintainer workflow. A key research topic is the creation of a scaffolding tool.
Scaffolding for New Components
The team is researching a command-line tool to automate the generation of boilerplate code for new resources, data sources, and their associated test files. This tool would ensure consistency, reduce repetitive work, and speed up the contribution process for both new and experienced developers. It would automatically generate the necessary files and add required code references, such as registering the new resource in the provider's main configuration.
Sources: ROADMAP.md:104-108