Project Structure

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• infrastructure/repository/labels-workflow.tf
• internal/generate/listpages/main.go
• internal/service/amplify/README.md
• internal/service/codebuild/project.go
• providerlint/vendor/golang.org/x/sys/unix/README.md

The Terraform AWS Provider is a plugin for Terraform that enables the full lifecycle management of AWS resources. The project's structure is organized to support a large number of contributors and the vast surface area of AWS. It features a modular design, separating each AWS service into its own package, and utilizes code generation to automate repetitive tasks. The repository itself is managed using Terraform, demonstrating an "infrastructure-as-code" approach to its own development and maintenance workflows.

The core logic is written in Go, with a clear separation between the main provider framework and the implementation of resources and data sources for each AWS service. This structure is designed for maintainability and scalability, with dedicated areas for service implementations, code generation tooling, and repository infrastructure management. Contributor-focused documentation and tooling, such as custom linters, are also integral parts of the project structure.

Sources: README.md, internal/service/amplify/README.md, infrastructure/repository/labels-workflow.tf

Key Directories

The project is organized into several key directories, each with a distinct purpose.

Directory	Purpose
internal/	Contains the core Go source code for the provider.
internal/service/	Houses individual packages for each supported AWS service (e.g., ec2, s3, codebuild).
internal/generate/	Includes tooling for code generation, such as creating paginated list functions.
infrastructure/	Defines the repository's own infrastructure, such as GitHub labels, using Terraform.
docs/	Contains developer and contributor documentation, including contribution guidelines and FAQs.
providerlint/	Contains custom linters and static analysis tools to enforce coding standards.

Sources: README.md:29, internal/generate/listpages/main.go, infrastructure/repository/labels-workflow.tf, internal/service/amplify/README.md, providerlint/vendor/golang.org/x/sys/unix/README.md

The following diagram illustrates the high-level directory structure.

internal/service - Service Packages

The internal/service/ directory contains a subdirectory for each AWS service supported by the provider. Each of these packages is intended for provider contributors and maintainers and contains the resource and data source implementations for that specific service.

For example, internal/service/codebuild/ contains the logic for aws_codebuild_project. Each service-specific README.md file provides handy links to contribution guides, Terraform Registry documentation, and the AWS SDK for Go documentation for that service.

Sources: internal/service/amplify/README.md:2-11, internal/service/codebuild/project.go

Resource Implementation

Within each service package, files like project.go for aws_codebuild_project define the resource's schema and CRUD (Create, Read, Update, Delete) operations.

A typical resource file includes:

• A Resource...() function that returns a schema.Resource.
• The resource Schema definition, which maps Terraform configuration attributes to their types, validation rules, and other properties.
• CRUD functions (resource...Create, resource...Read, resource...Update, resource...Delete).
• "Expander" functions (e.g., expandProjectEnvironment) that convert Terraform state data into AWS SDK input structures.
• "Flattener" functions (e.g., flattenProjectEnvironment) that convert AWS SDK output structures into a format that can be saved in the Terraform state.

The following diagram shows the lifecycle of an aws_codebuild_project resource as managed by the provider.

internal/generate - Code Generation

The project uses code generation to reduce boilerplate and ensure consistency. The internal/generate/listpages tool is a prime example. It is used to generate helper functions for handling paginated List* API calls from the AWS SDK.

The generator is invoked with a go:generate directive. It parses the AWS SDK for Go source package, finds a specified function, and generates a corresponding ...Pages and ...PagesWithContext function. These generated functions loop through the paginated results of an AWS API call until the last page is reached.

Sources: [internal/generate/listpages/main.go:1-30]

listpages Generator

The listpages generator is configured via command-line flags.

Flag	Description
-ListOps	A comma-separated list of AWS SDK list operations to generate paginators for.
-Paginator	The name of the pagination token field in the API response, e.g., NextToken.
-Export	A boolean to control whether the generated functions are exported.

Sources: [internal/generate/listpages/main.go:20-24]

The generation process is as follows:

The tool uses a map of service names to find the correct AWS SDK package and its capitalization.

// internal/generate/listpages/main.go:303-305
func awsServiceName(s string) (string, error) {
	s = strings.ToLower(s)
//...

Sources: [internal/generate/listpages/main.go:303-305]

infrastructure/ - Repository as Code

The project uses Terraform to manage its own GitHub repository settings. The file infrastructure/repository/labels-workflow.tf defines the set of issue labels used in the repository's workflow.

This demonstrates a commitment to "dogfooding" the tools the project helps build. The labels are defined in a variable "workflow_labels" and then created using the github_issue_label resource.

Sources: [infrastructure/repository/labels-workflow.tf]

Workflow Labels

The labels provide a structured way to categorize issues and pull requests, aiding maintainers and contributors.

Label	Color	Description
bug	ec585d	Addresses a defect in current functionality.
enhancement	844fba	Requests to existing resources that expand the functionality or scope.
documentation	f4ecff	Introduces or discusses updates to documentation.
new-resource	8040c9	Introduces a new resource.
new-data-source	ac72f0	Introduces a new data source.
good first issue	63d0ff	Call to action for new contributors looking for a place to start.
needs-triage	dc477d	Waiting for first response or review from a maintainer.
dependencies	1c7ada	Used to indicate dependency changes.

Sources: [infrastructure/repository/labels-workflow.tf:2-179]

Dependency Management and Build System

The project includes vendored dependencies, and some of these dependencies have their own complex build systems. For instance, the golang.org/x/sys/unix package, found within the providerlint/vendor directory, has a detailed build process for generating Go files from C header files.

This process involves:

• Build Systems: A legacy system that relies on local C header files and a newer, reproducible system that uses Docker containers.
• Component Files: A collection of scripts and Go programs (mksysnum, mksyscall.go, etc.) that parse system headers and generate Go constants, types, and syscall wrappers.
• Generated Files: The output files, such as zerrors_${GOOS}_${GOARCH}.go and zsyscall_${GOOS}_${GOARCH}.go, which contain the platform-specific generated code.

While this is part of a dependency, its presence highlights the complexity involved in maintaining a low-level provider that interfaces with system libraries.

Sources: [providerlint/vendor/golang.org/x/sys/unix/README.md:1-170]