docs(telemetry): document the IAM roles --telemetry-gcp requires - #3824
Open
AndyFooBlah wants to merge 2 commits into
Open
docs(telemetry): document the IAM roles --telemetry-gcp requires#3824AndyFooBlah wants to merge 2 commits into
AndyFooBlah wants to merge 2 commits into
Conversation
The Google Cloud Exporter section listed the APIs to enable but not the roles the running identity needs. Metrics and traces are authorized separately, so a partial grant fails partially: with roles/monitoring.metricWriter but not roles/cloudtrace.agent, metrics export normally while every trace export fails with PermissionDenied on cloudtrace.traces.patch — which is the state a least-privilege deployment lands in first, and the role name only appears in the export error. Adds both roles with their key permissions, the gcloud commands to grant them, and a tip naming the partial-grant symptom. The flags section cross-references the exporter section rather than repeating it. Assisted by Claude. Part of googleapis#3638
1 task
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the telemetry documentation to clarify that metrics and traces are authorized separately, detailing the required IAM roles and providing gcloud commands to configure them. It also adds a troubleshooting tip for partial authorization failures and links to the Google Cloud Exporter section. The reviewer suggested a minor grammatical improvement to enhance readability, which has been kept as it provides a clear code suggestion.
Comment on lines
+348
to
+350
| authorized separately. The identity Toolbox runs as — the attached service | ||
| account on Cloud Run, GCE, or GKE, or your own credentials when running | ||
| locally — needs **both** of these roles on the telemetry project: |
Contributor
There was a problem hiding this comment.
For improved grammatical flow and readability, consider adding 'that' to clarify the noun clause.
Suggested change
| authorized separately. The identity Toolbox runs as — the attached service | |
| account on Cloud Run, GCE, or GKE, or your own credentials when running | |
| locally — needs **both** of these roles on the telemetry project: | |
| authorized separately. The identity that Toolbox runs as — the attached service | |
| account on Cloud Run, GCE, or GKE, or your own credentials when running | |
| locally — needs **both** of these roles on the telemetry project: |
Applies review feedback on googleapis#3824. Assisted by Claude.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents the IAM roles
--telemetry-gcprequires, which @averikitsch asked for in #3638.The Google Cloud Exporter section already lists the APIs to enable, but not the roles the identity Toolbox runs as needs. That matters because metrics and traces are exported as two independent signals and authorized separately, so a partial grant fails partially:
roles/monitoring.metricWriterbut notroles/cloudtrace.agent, metrics export normally while every trace export attempt fails withPermissionDeniedoncloudtrace.traces.patch;This is the first state a least-privilege deployment lands in, which is how we hit it on Cloud Run.
Adds to the Google Cloud Exporter section:
roles/monitoring.metricWritermonitoring.timeSeries.createroles/cloudtrace.agentcloudtrace.traces.patchplus the
gcloud add-iam-policy-bindingcommands to grant them, and a tip naming the partial-grant symptom so the trace-only failure is searchable. The flags section gets a cross-reference to the exporter section rather than a second copy of the requirements.Docs only; no behavior change.
PR Checklist
!if this involves a breaking changeIssue Reference
Part of #3638 🦕 — this is the documentation half that @averikitsch offered to accept. The behavior half of that issue (failing fast at startup on a permanent authorization failure, rather than retrying the export indefinitely) is still open for discussion there, so this PR doesn't close it.