hashicorp / terraform-provider-aws

The AWS Provider enables Terraform to manage AWS resources.
https://registry.terraform.io/providers/hashicorp/aws
Mozilla Public License 2.0
9.86k stars 9.21k forks source link

Prefer jsonencode() Over Heredoc Syntax of JSON in Documentation Examples #17714

Open bflad opened 3 years ago

bflad commented 3 years ago

Community Note

Description

Martin's excellent summary in https://github.com/hashicorp/terraform-provider-aws/pull/16792 explains this best:

The existing examples of inline IAM policy documents tend to show them as "heredoc" strings, which was the required style in Terraform v0.11 and earlier.

However, users seem to frequently start from these simple examples and then later need to insert dynamic elements such as ARNs or lists of ARNs from other resources, and because they started with a multi-line string template they then understandably start experimenting with string templating to produce the dynamic JSON, and run into various issues with incorrect quoting and generation of commas.

When helping users in that case (e.g. in the community forum) we typically suggest that they switch to using the jsonencode function for generating that dynamic JSON, because then they can just use normal Terraform language expression features and let Terraform itself worry about making the result valid JSON syntax.

In an attempt to help users discover that solution themselves, rather than fighting with string templates first, I've changed the examples for the resource types I've most commonly seen questions about in order to show generating the JSON string programmatically using the jsonencode function. Not everyone will necessarily realize right away that they can also use dynamic expressions in there, I hope that this will at least set folks on a better path when they start evaluating possible solutions by making it less likely that string templates will be seen as a viable option.

There are many more heredoc-based IAM policy examples in other resource types -- particularly in various examples that include aws_iam_role helper resources with assume_role_policy arguments -- but I wanted to keep this confined to a frequently-seen subset to start just to avoid this being a huge diff that could be disruptive to merge. Hopefully over time we can update more of these (though there's no particular urgency here), and also maybe write any new examples in this jsonencode style.

The jsonencode style is also typically how Terraform CLI will present the value in the plan diff, in order to potentially produce a structural diff within the JSON data structure, so hopefully this will also help set users up to be less surprised when they encounter that for the first time.

This issue is for tracking and replacing other examples, but does not offer any initial future-proofing enforcement solutions.

Affected Files

Changes to these files should be submitted in batches, to prevent delayed reviews and merge conflicts.

References

mattburgess commented 1 year ago

Given the advice at https://developer.hashicorp.com/terraform/tutorials/aws/aws-iam-policy?in=terraform%2Faws#refactor-your-policy, I'm wondering whether this ticket should skip the middle step of heredoc -> jsonencode() and instead convert all heredocs into aws_iam_policy_documents? I'm happy to tackle this one once we've reached agreement on approach.