Skip to content

docs(telemetry): document the IAM roles --telemetry-gcp requires - #3824

Open
AndyFooBlah wants to merge 2 commits into
googleapis:mainfrom
AndyFooBlah:docs/telemetry-gcp-iam
Open

docs(telemetry): document the IAM roles --telemetry-gcp requires#3824
AndyFooBlah wants to merge 2 commits into
googleapis:mainfrom
AndyFooBlah:docs/telemetry-gcp-iam

Conversation

@AndyFooBlah

Copy link
Copy Markdown

Description

Documents the IAM roles --telemetry-gcp requires, 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:

  • with roles/monitoring.metricWriter but not roles/cloudtrace.agent, metrics export normally while every trace export attempt fails with PermissionDenied on cloudtrace.traces.patch;
  • the dashboards look healthy, so the symptom reads as a trace bug rather than a missing role;
  • and the role name appears nowhere except in the export error itself, so the operator learns it by reading the failure.

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:

signal role key permission
Metrics roles/monitoring.metricWriter monitoring.timeSeries.create
Traces roles/cloudtrace.agent cloudtrace.traces.patch

plus the gcloud add-iam-policy-binding commands 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

  • Make sure to open an issue as a bug/issue before writing your code!
  • Ensure you have manually reviewed the entire diff before requesting a review
  • Ensure the tests and linter pass
  • Code coverage does not decrease (if any source code was changed) — no source changes
  • Appropriate docs were updated (if necessary)
  • Make sure to add ! if this involves a breaking change

Issue 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.

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

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants