docs: clarify IAM binding authoritative scope is role + condition - #18640
docs: clarify IAM binding authoritative scope is role + condition#18640hsiam261 wants to merge 4 commits into
Conversation
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
|
Googlers: For automatic test runs see go/terraform-auto-test-runs. @melinath, a repository maintainer, has been assigned to review your changes. If you have not received review feedback within 2 business days, please leave a comment on this PR asking them to take a look. You can help make sure that review is quick by doing a self-review and by running impacted tests locally. |
… just role The existing documentation template for IAM resources was ambiguous about the authoritative scope of `_iam_binding` and the drift detection behavior of `_iam_member`. Users expected `_iam_member` to detect out-of-band additions, but it only tracks its own member. Similarly, `_iam_binding` is authoritative per role *and* condition combination, not per role alone.
47c3651 to
153f74f
Compare
|
Hi there, I'm the Modular magician. I've detected the following information about your changes for commit 153f74f: Diff reportYour PR generated the following diffs in downstream repositories:
|
melinath
left a comment
There was a problem hiding this comment.
I see why you're wanting to clarify this.
My main concern is that not all IAM resources support conditions, so including that broadly could be confusing in its own way. (That's why the documentation today splits the information about conditions into separate sections guarded by {{ if $.IamPolicy.IamConditionsRequestType }}.)
Could you try finding a way to only show the conditions information on IAM resources that support conditions?
The role/condition combination language added in the previous commit was unconditional, but not all IAM resources support IAM Conditions. Gate it behind the existing $.IamPolicy.IamConditionsRequestType check so resources without conditions support keep the simpler role-only wording. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Standardize wording across the IAM doc template instead of mixing "role/condition", "role and condition", and "unique combination of role and condition" for the same concept. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… omitted Note this only where the term is first introduced, to avoid repeating the same parenthetical on every subsequent mention in the doc. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Fixes hashicorp/terraform-provider-google#28785
The documentation for all
_iam_bindingresources describes them as "Authoritative for a given role," but the actual authoritative scope is the combination of role + condition (title+description+expression). This is misleading — users expect_iam_memberto detect out-of-band additions, or expect_iam_bindingto be authoritative across all conditions for a role, neither of which is true.Changes to
resource_iam.html.markdown.tmpl_iam_bindingdescription: "Authoritative for a given role" → "Authoritative for a given role and condition combination." Added note that out-of-band members will be detected as drift and removed._iam_memberdescription: Clarified that out-of-band members will not be detected as drift.roleargument: "Only one binding per role" → "Only one binding per role and condition combination." Added note that multiple bindings for the same role are allowed with different conditions.