From be14e13037e76e2b3c4e8078607b8f6525a3f327 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 8 Jun 2026 12:18:32 +0000 Subject: [PATCH 1/3] docs: sync ADP transcript permissions from cloudv2 Document the dedicated transcript permissions and the TranscriptReader built-in role introduced in cloudv2 (transcript reads are no longer bundled into the Writer/Reader defaults). - Add a Transcript permissions section and TranscriptReader role to the roles and permissions reference. - Add the dataplane_adp_transcript_* family and TranscriptReader to the permissions overview. - Update the transcripts page prerequisite and troubleshooting to require the TranscriptReader role. --- .../control/pages/permissions-overview.adoc | 9 +++-- .../control/pages/permissions-reference.adoc | 35 ++++++++++++++++++- modules/monitor/pages/transcripts.adoc | 5 ++- 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/modules/control/pages/permissions-overview.adoc b/modules/control/pages/permissions-overview.adoc index 986a21a..cd7a981 100644 --- a/modules/control/pages/permissions-overview.adoc +++ b/modules/control/pages/permissions-overview.adoc @@ -7,6 +7,7 @@ :learning-objective-3: Identify which built-in role grants the permissions a user or service account needs // Source: `cloudv2` `pkg/permissions/permissions_constants.go`, `apps/aigw/internal/llm/authz.go`, `apps/aigw/internal/mcp/authz.go`, and `apps/ai-agent/internal/agent/authorization.go` on origin/main, verified 2026-05-18. +// Transcript permissions and the TranscriptReader role verified against cloudv2 commit 6dfd3b3 (PR #26829), 2026-06-08. // TODO: confirm screenshots of the role-binding flow in the Cloud UI once UX-790 (Console-side fine-grained authZ) ships. The Agentic Data Plane uses Redpanda's role-based access control (RBAC) to gate every API call. Each LLM provider, MCP server, agent, pipeline, knowledge base, and governance endpoint enforces a specific permission, and you assign permissions to users and service accounts by binding them to a role. This page explains the three-layer model so you can pick the right built-in role for a workload, or compose your own. @@ -34,6 +35,7 @@ ADP permissions live in the following families, named by the namespace prefix: * `dataplane_adp_mcpserver_*`: Manage and call MCP servers (CRUD plus runtime operations like `tools_call` and `resources_read`). * `dataplane_adp_llmprovider_*`: Manage LLM providers and proxy LLM requests through AI Gateway. The `_invoke` permission is what your applications need at runtime. * `dataplane_adp_agent_*` and `dataplane_adp_agent_credential_*`: Manage declarative AI agents and the OIDC credentials issued to them. +* `dataplane_adp_transcript_*`: Read agent conversation transcripts. Granted only by the dedicated TranscriptReader role, not by Writer or Reader, because transcripts carry full conversation content. * `dataplane_adp_spending_*`: Read AI spending data for governance and cost reporting. * `dataplane_aiagent_a2a_*`: Invoke agent-to-agent (A2A) operations on running agents. * `dataplane_aigateway_*`: Manage enterprise AI Gateway features (rate limits, spend limits, guardrails, model providers, audit, pricing, IAM). @@ -47,7 +49,7 @@ For the full list of permissions and which built-in role grants each one, see xr == Built-in roles -ADP includes the following built-in roles. Admin, Writer, and Reader are general-purpose. The remaining roles are narrow Invoker roles for runtime-only access. +ADP includes the following built-in roles. Admin, Writer, and Reader are general-purpose. The remaining roles are narrow: a set of Invoker roles for runtime-only access, plus TranscriptReader for reading agent conversation transcripts. [cols="1,3"] |=== @@ -60,7 +62,10 @@ ADP includes the following built-in roles. Admin, Writer, and Reader are general |Full create, read, update, and delete access across every ADP-namespaced API (LLM provider, MCP server, agent, agent credential, AI Gateway, pipeline, knowledge base). Use for developers who need to build and modify ADP resources. |*Reader* -|Read-only access (`_get` and `_list`) across the same APIs, plus MCP runtime read operations such as `resources_list` and `prompts_get`. No create, update, delete, or invoke. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights. +|Read-only access (`_get` and `_list`) across the same APIs, plus MCP runtime read operations such as `resources_list` and `prompts_get`. No create, update, delete, or invoke. Does not grant transcript reads. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights. + +|*TranscriptReader* +|Transcript reads only: `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list`. Transcripts carry full conversation content, so this access is granted through a dedicated role rather than bundled into Reader or Writer. Use for users and service accounts that read agent conversation transcripts. Provisioned for organizations with an ADP cluster. |*AIAgentInvoker* |A2A runtime only: `message_send`, `message_stream`, and the task lifecycle (`get`, `list`, `cancel`, `subscribe`). Use for service accounts that consume agents over A2A but should not manage them. diff --git a/modules/control/pages/permissions-reference.adoc b/modules/control/pages/permissions-reference.adoc index ae85ff3..d3fcdc4 100644 --- a/modules/control/pages/permissions-reference.adoc +++ b/modules/control/pages/permissions-reference.adoc @@ -7,6 +7,7 @@ :learning-objective-3: Identify the operation each permission gates // Source: `cloudv2` `pkg/permissions/permissions_constants.go` on origin/main, verified 2026-05-18. +// Transcript permissions and the TranscriptReader role verified against cloudv2 commit 6dfd3b3 (PR #26829), 2026-06-08. Every Redpanda ADP API call enforces a single permission. This reference lists every ADP-namespaced permission, the operation it gates, and which built-in role grants it. @@ -28,6 +29,8 @@ Each table column means the same thing across every namespace. The Admin role grants every permission and is omitted from individual rows for brevity. Permissions that only resolve on ADP-enabled clusters carry no separate mark; the gating is automatic. +The transcript namespace adds a TranscriptReader column in place of the Invoker column. Those permissions are granted by a dedicated role, not by the general-purpose Writer and Reader roles. + == MCP server permissions The `dataplane_adp_mcpserver_*` permissions gate both server management (CRUD) and the MCP protocol calls a client makes against a running server. @@ -232,6 +235,33 @@ The `dataplane_adp_agent_credential_*` permissions gate the OIDC client credenti | |=== +[[transcript-permissions]] +== Transcript permissions + +The `dataplane_adp_transcript_*` permissions gate read access to agent conversation transcripts. Because transcripts carry the full content of an agent's conversations (system prompts, user messages, tool arguments, and model output), these permissions stay out of the broad Writer and Reader defaults. Only the dedicated TranscriptReader role and Admin grant them. See xref:monitor:transcripts.adoc[] for what a transcript records. + +[cols="2,2,1,1,1"] +|=== +|Permission |Operation |Writer |Reader |TranscriptReader + +|`dataplane_adp_transcript_get` +|View a single agent conversation transcript +| +| +|✓ + +|`dataplane_adp_transcript_list` +|List agent conversation transcripts +| +| +|✓ +|=== + +[NOTE] +==== +Transcript access is no longer bundled with agent read access. A principal that can view an agent's configuration through `dataplane_adp_agent_get` cannot read that agent's transcripts unless it also holds the TranscriptReader role (or Admin). Grant TranscriptReader to the users and service accounts that need to read conversation content. +==== + == Spending permissions The `dataplane_adp_spending_*` permissions gate the governance APIs that surface AI spend, request counts, and token volume. See xref:control:budgets.adoc[] for what spending data ADP records automatically. @@ -447,7 +477,10 @@ The `dataplane_knowledgebase_*` permissions gate retrieval-augmented generation |Developers who build and modify ADP resources. Grants full CRUD on every ADP-namespaced API plus pipeline and knowledge-base management. |*Reader* -|Auditors and evaluators who need visibility without mutation rights. Grants `_get` and `_list` plus MCP runtime read methods. +|Auditors and evaluators who need visibility without mutation rights. Grants `_get` and `_list` plus MCP runtime read methods. Does not grant transcript reads. + +|*TranscriptReader* +|Users and service accounts that read agent conversation transcripts. Grants `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list`, which stay out of the Writer and Reader roles because transcripts carry full conversation content. Provisioned for organizations with an ADP cluster. |*AIAgentInvoker* |Service accounts that send messages to agents over A2A without managing them. diff --git a/modules/monitor/pages/transcripts.adoc b/modules/monitor/pages/transcripts.adoc index 6c96079..22ac875 100644 --- a/modules/monitor/pages/transcripts.adoc +++ b/modules/monitor/pages/transcripts.adoc @@ -19,7 +19,7 @@ After reading this page, you will be able to: == Prerequisites * xref:connect:create-agent.adoc[Running agent] or xref:connect:create-server.adoc[MCP server] with at least one execution -* Permission to read the `redpanda.otel_traces` glossterm:topic[] that backs the Transcripts view +* The TranscriptReader role (or Admin) to read transcripts. Transcripts carry full conversation content, so the `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list` permissions stay out of the default Reader and Writer roles. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]. == Open the Transcripts view @@ -191,8 +191,7 @@ For long-running conversations, accept some reconstruction; for short conversati === Transcript missing entirely * Confirm the agent or MCP server actually ran: Check its logs and the corresponding session or task topic. -* Confirm your user has read access to `redpanda.otel_traces`. -// TODO: Replace with the standalone-ADP permission model once available. +* Confirm your user holds the TranscriptReader role (or Admin). Transcript reads require the `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list` permissions, which are not part of the default Reader or Writer roles. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]. * Confirm the feature flag enabling Transcripts is on for your environment. == Next steps From 07e23ec8bf60b10e90a726abf7a7674321166f8b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 8 Jun 2026 14:07:10 +0000 Subject: [PATCH 2/3] docs: address PR review on transcript permissions sync - Resolve companion TODO in monitor/concepts.adoc now that the transcript permission model has shipped: read access is governed by the TranscriptReader role, not redpanda.otel_traces topic ACLs. - Tighten the Transcripts prerequisite bullet to a single concise line. - Drop the inline Reader-row caveat in both control pages; the dedicated TranscriptReader row and NOTE already state Writer and Reader are excluded, which removes the Reader/Writer asymmetry. https://claude.ai/code/session_012JpZZiMGnHHKuNFn17TLxP --- modules/control/pages/permissions-overview.adoc | 2 +- modules/control/pages/permissions-reference.adoc | 2 +- modules/monitor/pages/concepts.adoc | 3 ++- modules/monitor/pages/transcripts.adoc | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/modules/control/pages/permissions-overview.adoc b/modules/control/pages/permissions-overview.adoc index cd7a981..6daa81a 100644 --- a/modules/control/pages/permissions-overview.adoc +++ b/modules/control/pages/permissions-overview.adoc @@ -62,7 +62,7 @@ ADP includes the following built-in roles. Admin, Writer, and Reader are general |Full create, read, update, and delete access across every ADP-namespaced API (LLM provider, MCP server, agent, agent credential, AI Gateway, pipeline, knowledge base). Use for developers who need to build and modify ADP resources. |*Reader* -|Read-only access (`_get` and `_list`) across the same APIs, plus MCP runtime read operations such as `resources_list` and `prompts_get`. No create, update, delete, or invoke. Does not grant transcript reads. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights. +|Read-only access (`_get` and `_list`) across the same APIs, plus MCP runtime read operations such as `resources_list` and `prompts_get`. No create, update, delete, or invoke. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights. |*TranscriptReader* |Transcript reads only: `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list`. Transcripts carry full conversation content, so this access is granted through a dedicated role rather than bundled into Reader or Writer. Use for users and service accounts that read agent conversation transcripts. Provisioned for organizations with an ADP cluster. diff --git a/modules/control/pages/permissions-reference.adoc b/modules/control/pages/permissions-reference.adoc index d3fcdc4..544eda6 100644 --- a/modules/control/pages/permissions-reference.adoc +++ b/modules/control/pages/permissions-reference.adoc @@ -477,7 +477,7 @@ The `dataplane_knowledgebase_*` permissions gate retrieval-augmented generation |Developers who build and modify ADP resources. Grants full CRUD on every ADP-namespaced API plus pipeline and knowledge-base management. |*Reader* -|Auditors and evaluators who need visibility without mutation rights. Grants `_get` and `_list` plus MCP runtime read methods. Does not grant transcript reads. +|Auditors and evaluators who need visibility without mutation rights. Grants `_get` and `_list` plus MCP runtime read methods. |*TranscriptReader* |Users and service accounts that read agent conversation transcripts. Grants `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list`, which stay out of the Writer and Reader roles because transcripts carry full conversation content. Provisioned for organizations with an ADP cluster. diff --git a/modules/monitor/pages/concepts.adoc b/modules/monitor/pages/concepts.adoc index ec69f13..0ef4025 100644 --- a/modules/monitor/pages/concepts.adoc +++ b/modules/monitor/pages/concepts.adoc @@ -316,7 +316,8 @@ The `redpanda.otel_traces` topic has a predefined retention policy. Configuratio The topic persists even after all agents and MCP servers are deleted, allowing you to retain historical trace data for analysis. Transcripts may contain sensitive information from your tool inputs and outputs. Review the data in transcripts before sharing or exporting to external systems. -// TODO: Re-add guidance on ACL scoping for `redpanda.otel_traces` once the standalone-ADP permission model lands. Today's wording assumed users manage topic ACLs on their own Redpanda Cloud cluster, which won't apply when ADP is a separate product surface. + +Read access to transcript data is governed by the TranscriptReader role rather than by topic ACLs on `redpanda.otel_traces`. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]. == Transcripts compared to audit logs diff --git a/modules/monitor/pages/transcripts.adoc b/modules/monitor/pages/transcripts.adoc index 22ac875..3ef2d79 100644 --- a/modules/monitor/pages/transcripts.adoc +++ b/modules/monitor/pages/transcripts.adoc @@ -19,7 +19,7 @@ After reading this page, you will be able to: == Prerequisites * xref:connect:create-agent.adoc[Running agent] or xref:connect:create-server.adoc[MCP server] with at least one execution -* The TranscriptReader role (or Admin) to read transcripts. Transcripts carry full conversation content, so the `dataplane_adp_transcript_get` and `dataplane_adp_transcript_list` permissions stay out of the default Reader and Writer roles. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]. +* The xref:control:permissions-reference.adoc#transcript-permissions[TranscriptReader role] (or Admin). Transcript reads are not part of the default Reader or Writer roles. == Open the Transcripts view From 5c31c062f9bd0b6a7b5798a0eeed08a96f010d58 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 8 Jun 2026 08:40:31 -0600 Subject: [PATCH 3/3] docs: include Admin in transcript-permissions grant note (review nit) The transcript-family bullet said transcripts are granted "only by the dedicated TranscriptReader role, not by Writer or Reader," which omitted Admin and contradicted the reference page NOTE ("Only the dedicated TranscriptReader role and Admin grant them"). Add "(and Admin)" for consistency. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/control/pages/permissions-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/control/pages/permissions-overview.adoc b/modules/control/pages/permissions-overview.adoc index 6daa81a..7928212 100644 --- a/modules/control/pages/permissions-overview.adoc +++ b/modules/control/pages/permissions-overview.adoc @@ -35,7 +35,7 @@ ADP permissions live in the following families, named by the namespace prefix: * `dataplane_adp_mcpserver_*`: Manage and call MCP servers (CRUD plus runtime operations like `tools_call` and `resources_read`). * `dataplane_adp_llmprovider_*`: Manage LLM providers and proxy LLM requests through AI Gateway. The `_invoke` permission is what your applications need at runtime. * `dataplane_adp_agent_*` and `dataplane_adp_agent_credential_*`: Manage declarative AI agents and the OIDC credentials issued to them. -* `dataplane_adp_transcript_*`: Read agent conversation transcripts. Granted only by the dedicated TranscriptReader role, not by Writer or Reader, because transcripts carry full conversation content. +* `dataplane_adp_transcript_*`: Read agent conversation transcripts. Granted by the dedicated TranscriptReader role (and Admin), not by Writer or Reader, because transcripts carry full conversation content. * `dataplane_adp_spending_*`: Read AI spending data for governance and cost reporting. * `dataplane_aiagent_a2a_*`: Invoke agent-to-agent (A2A) operations on running agents. * `dataplane_aigateway_*`: Manage enterprise AI Gateway features (rate limits, spend limits, guardrails, model providers, audit, pricing, IAM).