docs/design-decisions/relationship-resource-design-standards.md
Summary: Align on design standards for relationship management resources in the Terraform AWS Provider.
Created: 2022-07-11
The goal of this document is to assess the design of existing "relationship" resources in the Terraform AWS Provider and determine if a consistent set of rules can be defined for implementing them. For the purpose of this document, a "relationship" resource is defined as a resource which manages either a direct relationship between two standalone resources ("one-to-one", ie. aws_ssoadmin_permission_boundary_attachment), or a variable number of child relationships to a parent resource ("one-to-many", ie. aws_iam_role_policy_attachment). Resources and AWS APIs with this function will often contain suffixes like "attachment", "assignment", "registration", or "rule".
A documented standard for implementing relationship-styled resources will inform how new resources are written, and provide guidelines to refer back to when the community requests features which may not align with internal best practices.
The first form of relationship resources ("one-to-one") typically have a straightforward, singular API design and provider implementation given only a single relationship exists. The second form of resources ("one-to-many") often has to balance two provider design principles:
In these cases, the smallest possible piece of infrastructure may be a single parent-child relationship, while the AWS APIs may accept and return lists of parent-child relationships. The first principle would favor a resource representing a single relationship, while the second principle suggests a resource should manage a variable number of relationships. Additionally, practitioners coming from the AWS CLI or SDK might also have expectations about how resource schemas should be shaped compared to CLI flags or SDK inputs.
An analysis of existing resources can inform which of these principles maintainers have given precedence to up to this point. The table below documents existing relationship resources in the AWS provider. This table should not be considered exhaustive1, but covers a large majority of the resources implementing the patterns discussed above.
Of the 44 resources documented above, 29 are of the "one-to-many" form and 17 have "plural" AWS APIs (ie. accept a list of child resources to be attached to a single parent). Of these 17, 13 resources (76%) use a "singular" Terraform implementation, where a list with one item is sent to the Create/Read/Update API, rather than allowing a single resource to manage multiple relationships. Of the remaining 4 with "plural" Terraform implementations, 2 do so to exclusively manage child relationships (aws_security_group Ingress/Egress variants), and one requires a "plural" implementation simply because of API limitations.
These metrics indicate a strong historical preference for representing a single API object over aligning the schema to the underlying AWS API. The primary exceptions to this are when exclusive management of all child resources is desired, such as security group ingress/egress rules, or IAM policy attachments.
The best practice for net-new "one-to-many" relationship resources should be to implement singular versions. Feature requests related to changing the singular nature of an existing relationship resource should be avoided unless necessary for the underlying API to function properly.
Variation from this pattern should only be done when:
Given a fictional "plural" API AttachChildren with a request body like:
{
"ParentId": "string",
"Children": [
{
"ChildId: "string"
}
]
}
The corresponding Terraform resource would only represent a single parent/child relationship with a configuration like:
resource "aws_parent" "example" {
name = "foo"
}
resource "aws_child" "example" {
name = "bar"
}
resource "aws_child_attachment" "example" {
parent_id = aws_parent.example.id
child_id = aws_child.example.id
}
Due to the volume of resources with "rule" in the name (~70), only the prominent security group rule resources were included in the analysis above. While "rule" resources often follow the same relationship-style design, the ~40 examples above provided enough initial data to inform design standards. ↩
The structure of this API precludes it from being implemented in a singular fashion. ↩
Creates exclusive attachments. ↩