Skip to content

docs: clarify IAM binding authoritative scope is role + condition - #18640

Open
hsiam261 wants to merge 4 commits into
GoogleCloudPlatform:mainfrom
hsiam261:docs/clarify-iam-binding-authoritative-scope
Open

docs: clarify IAM binding authoritative scope is role + condition#18640
hsiam261 wants to merge 4 commits into
GoogleCloudPlatform:mainfrom
hsiam261:docs/clarify-iam-binding-authoritative-scope

Conversation

@hsiam261

Copy link
Copy Markdown

Fixes hashicorp/terraform-provider-google#28785

The documentation for all _iam_binding resources 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_member to detect out-of-band additions, or expect _iam_binding to be authoritative across all conditions for a role, neither of which is true.

Changes to resource_iam.html.markdown.tmpl

  1. _iam_binding description: "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.
  2. _iam_member description: Clarified that out-of-band members will not be detected as drift.
  3. Coexistence note: "same role" → "same role and condition combination."
  4. role argument: "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.
  5. Warning block: Added sentence clarifying the authoritative scope is the unique (role, condition) combination.

@modular-magician modular-magician added the awaiting-approval Pull requests that need reviewer's approval to run presubmit tests label Aug 13, 2026
@google-cla

google-cla Bot commented Aug 13, 2026

Copy link
Copy Markdown

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.

@github-actions

Copy link
Copy Markdown

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.

@github-actions
github-actions Bot requested a review from melinath August 13, 2026 20:25
… 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.
@hsiam261
hsiam261 force-pushed the docs/clarify-iam-binding-authoritative-scope branch from 47c3651 to 153f74f Compare August 13, 2026 20:45
@modular-magician modular-magician added service/terraform and removed awaiting-approval Pull requests that need reviewer's approval to run presubmit tests labels Aug 13, 2026
@modular-magician

Copy link
Copy Markdown
Collaborator

Hi there, I'm the Modular magician. I've detected the following information about your changes for commit 153f74f:

Diff report

Your PR generated the following diffs in downstream repositories:

Repository Diff Link Changes
google provider View Diff 137 files changed, 589 insertions(+), 589 deletions(-)
google-beta provider View Diff 137 files changed, 589 insertions(+), 589 deletions(-)

@melinath melinath left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@modular-magician modular-magician added the awaiting-approval Pull requests that need reviewer's approval to run presubmit tests label Aug 14, 2026
@github-actions
github-actions Bot requested a review from melinath August 14, 2026 15:49
hsiam261 and others added 2 commits August 14, 2026 22:03
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting-approval Pull requests that need reviewer's approval to run presubmit tests service/terraform

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation: IAM binding authoritative scope should clarify role + condition, not just role

3 participants