From c8ef4c0750ca4faabbf2a3ea602cbe598cd0b108 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Thu, 11 Feb 2021 11:30:26 -0500 Subject: [PATCH] docs/contributing: Add Data Sources section to Provider Design page (#17546) This quick section is designed to explain the "in words" design methodology behind singular versus plural data sources. --- docs/contributing/provider-design.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/contributing/provider-design.md b/docs/contributing/provider-design.md index 9585d265768..17d62a6a31e 100644 --- a/docs/contributing/provider-design.md +++ b/docs/contributing/provider-design.md @@ -9,6 +9,9 @@ The Terraform AWS Provider follows the guidelines established in the [HashiCorp - [Resource Type Considerations](#resource-type-considerations) - [Authorization and Acceptance Resources](#authorization-and-acceptance-resources) - [Cross-Service Functionality](#cross-service-functionality) + - [Data Sources](#data-sources) + - [Plural Data Sources](#plural-data-sources) + - [Singular Data Sources](#singular-data-sources) - [IAM Resource-Based Policy Resources](#iam-resource-based-policy-resources) - [Managing Resource Running State](#managing-resource-running-state) - [Task Execution and Waiter Resources](#task-execution-and-waiter-resources) @@ -81,6 +84,20 @@ The rationale behind this design decision includes the following: A poignant real-world example of the last point involved a Lambda resource. The resource helped clean up extra resources (ENIs) due to a common misconfiguration. Practitioners found the functionality helpful since the issue was hard to diagnose. Years later, AWS updated the Lambda API. Immediately, practitioners reported that Terraform executions were failing. Downgrading the provider was not possible since many configurations depended on recent releases. For environments running many versions behind, forcing an upgrade with the fix would likely cause unrelated and unexpected changes. In the end, HashiCorp and AWS performed a large-scale outreach to help upgrade and fixing the misconfigurations. Provider maintainers and practitioners lost considerable time. +### Data Sources + +A separate class of Terraform resource types are [data sources](https://www.terraform.io/docs/language/data-sources/). These are typically intended as a configuration method to lookup or fetch data in a read-only manner. Data sources should not have side effects on the remote system. + +When discussing data sources, they are typically classified by the intended number of return objects or data. Singular data sources represent a one-to-one lookup or data operation. Plural data sources represent a one-to-many operation. + +#### Plural Data Sources + +These data sources are intended to return zero, one, or many results, usually associated with a managed resource type. Typically results are a set unless ordering guarantees are provided by the remote system. These should be named with a plural suffix (e.g. `s` or `es`) and should not include any specific attribute in the naming (e.g. prefer `aws_ec2_transit_gateways` instead of `aws_ec2_transit_gateway_ids`). + +#### Singular Data Sources + +These data sources are intended to return one result or an error. These should not include any specific attribute in the naming (e.g. prefer `aws_ec2_transit_gateway` instead of `aws_ec2_transit_gateway_id`). + ### IAM Resource-Based Policy Resources For some AWS components, the AWS API allows specifying an [IAM resource-based policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html), the IAM policy to associate with a component. Some examples include: