diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index db1ff0a..39cd54a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -67,6 +67,8 @@ *** xref:governance:guardrails/cost-tracking.adoc[Cost Tracking] ** xref:governance:budgets.adoc[Token Budgets and Limits] ** xref:governance:kill-switch.adoc[Kill Switch] +** xref:governance:permissions-overview.adoc[About ADP Permissions] +** xref:governance:permissions-reference.adoc[ADP Permissions Reference] * xref:observability:index.adoc[Observability] ** xref:observability:concepts.adoc[Concepts] ** xref:observability:transcripts.adoc[Read a Transcript] diff --git a/modules/agents/pages/byoa-register.adoc b/modules/agents/pages/byoa-register.adoc index 81a2dd3..4e57e29 100644 --- a/modules/agents/pages/byoa-register.adoc +++ b/modules/agents/pages/byoa-register.adoc @@ -68,7 +68,7 @@ Before you register a BYOA agent, make sure you have: * An agent running in your own infrastructure with a reachable HTTPS endpoint. * The ability to add an HTTPS route at `/.well-known/agent-card.json` (or equivalent) on that endpoint. See <>. * The agent instrumented with OpenTelemetry, emitting the minimum required spans contract. See xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)]. -* The right permission to create agents (`dataplane_adp_agent_create`). +* The `dataplane_adp_agent_create` permission, granted by the Writer built-in role. See xref:governance:permissions-reference.adoc#agent-management-permissions[Agent management permissions]. * A name for the agent that follows DNS-1123 conventions (1–63 characters, lowercase letters / numbers / hyphens, starting with a letter). The name is immutable once the agent is registered. [[a2a-endpoint-contract]] diff --git a/modules/ai-gateway/pages/configure-provider.adoc b/modules/ai-gateway/pages/configure-provider.adoc index 225a87b..9ad7d56 100644 --- a/modules/ai-gateway/pages/configure-provider.adoc +++ b/modules/ai-gateway/pages/configure-provider.adoc @@ -358,9 +358,7 @@ The spend chart footer summarizes the selected view by cost bucket, including to |Gemini uses the `x-goog-api-key` header, not `Authorization`. If you're seeing 401s on Gemini, check that the client is sending the correct header. See xref:ai-gateway:connect-agent.adoc[Connect your agent]. |Provider list empty or 403 -|Confirm your account has the `dataplane_adp_llmprovider_*` permissions in ADP. -+ -// TODO: confirm the exact role/permission model once the standalone ADP UI launches. +|Confirm your account has the `dataplane_adp_llmprovider_*` permissions in ADP. The Reader built-in role is the minimum required to list providers. The Writer role is required to create one. See xref:governance:permissions-reference.adoc#llm-provider-permissions[LLM provider permissions]. |=== // TODO: add screenshots of common error toasts once captured from the live environment. diff --git a/modules/ai-gateway/pages/connect-agent.adoc b/modules/ai-gateway/pages/connect-agent.adoc index 88ba5b2..9b5022b 100644 --- a/modules/ai-gateway/pages/connect-agent.adoc +++ b/modules/ai-gateway/pages/connect-agent.adoc @@ -439,7 +439,7 @@ AI Gateway returns standard HTTP status codes. The upstream provider's error bod === 403 Forbidden -* The service account may lack the required roles. Ask an admin to grant `dataplane_adp_llmprovider_get` at minimum. +* The service account may lack the required roles. Ask an admin to grant `dataplane_adp_llmprovider_get` at minimum to read provider config, and `dataplane_adp_llmprovider_invoke` to proxy LLM requests through AI Gateway. See xref:governance:permissions-reference.adoc#llm-provider-permissions[LLM provider permissions] or assign the LLMProviderInvoker built-in role for runtime-only access. * The provider may be disabled. Check the *Status* field on its *Connection* card. === Connection timeout or reset diff --git a/modules/governance/pages/dashboard/overview.adoc b/modules/governance/pages/dashboard/overview.adoc index 762f872..ef734f9 100644 --- a/modules/governance/pages/dashboard/overview.adoc +++ b/modules/governance/pages/dashboard/overview.adoc @@ -20,7 +20,7 @@ Use this guide to: == Prerequisites * Access to the Agentic Data Plane -* The `dataplane_adp_spending_get` permission to read spend, request, and token data +* The `dataplane_adp_spending_get` permission to read spend, request, and token data, granted by both the Writer and Reader built-in roles. See xref:governance:permissions-reference.adoc#spending-permissions[Spending permissions]. * At least one LLM provider or agent if you want non-empty charts and tables == Open the dashboard diff --git a/modules/governance/pages/permissions-overview.adoc b/modules/governance/pages/permissions-overview.adoc new file mode 100644 index 0000000..0e85dda --- /dev/null +++ b/modules/governance/pages/permissions-overview.adoc @@ -0,0 +1,97 @@ += About ADP Permissions +:description: Understand how ADP permissions, built-in roles, and role bindings fit together to control access to AI Gateway, MCP, agents, pipelines, and governance APIs. +:page-topic-type: concept +:personas: platform_admin, evaluator, app_developer +:learning-objective-1: Explain how ADP permissions, roles, and role bindings fit together +:learning-objective-2: Differentiate between the Admin, Writer, Reader, and Invoker built-in roles +: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. +// 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 Cloud'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. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== The three-layer model + +ADP authorization composes three pieces. Each layer answers a different question. + +* *Permission*: What action is allowed? A permission is a string like `dataplane_adp_llmprovider_invoke` that names exactly one operation on one resource type. The gRPC service that handles an API call checks the caller's permission set before executing. +* *Role*: Which permissions go together? A role is a named bundle of permissions. ADP ships built-in roles for common access patterns (Admin, Writer, Reader, and a set of Invoker sub-roles), and you can define custom roles for more specific needs. +* *Role binding*: Who gets the role, and where? A role binding attaches a role to a principal (user or service account) at a scope. Scopes range from the entire organization down to a single resource group or dataplane, so the same principal can have different permissions in different parts of your deployment. + +A successful API call requires all three: the caller must hold a role binding whose role contains the permission the endpoint enforces, at a scope that covers the resource being acted on. + +== ADP-namespaced permissions + +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_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, routing rules, guardrails, model providers, audit, pricing, IAM). + +Two more families belong to Redpanda Connect resources that ADP uses: + +* `dataplane_pipeline_*`: Manage and invoke Redpanda Connect pipelines. +* `dataplane_knowledgebase_*`: Manage retrieval-augmented generation knowledge bases. + +These permissions only resolve on clusters that have ADP enabled. Granting them to a principal on a non-ADP cluster has no effect. + +For the full list of permissions and which built-in role grants each one, see xref:governance:permissions-reference.adoc[ADP Permissions Reference]. + +== 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. + +[cols="1,3"] +|=== +|Role |What it grants + +|*Admin* +|Every permission, on every resource. Use for cluster operators who configure providers, agents, MCP servers, and pricing. + +|*Writer* +|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. + +|*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. + +|*MCPInvoker* +|MCP runtime only: `initialize`, `ping`, the `resources_*` read methods, the `prompts_*` read methods, and `tools_list` / `tools_call`. No CRUD. Use for service accounts that call MCP tools without managing the servers themselves. + +|*LLMProviderInvoker* +|A single permission: `dataplane_adp_llmprovider_invoke`. Use for applications that proxy LLM requests through AI Gateway but should not see or modify provider configuration. + +|*PipelineInvoker* +|Runtime pipeline invocation only: `gateway_invoke`, `otlp_grpc_invoke`, `otlp_http_invoke`. Use for clients that produce telemetry or send data into Connect pipelines without managing them. +|=== + +Pick the narrowest role that covers a workload. For example, an application that only needs to call an LLM through AI Gateway should hold the LLMProviderInvoker role, not the Writer role. + +== Identity and impersonation + +ADP API calls authenticate as one of two identity types: + +* *User identity (OIDC)*: A human user signed in through Redpanda Cloud's OIDC provider. The Cloud UI uses this identity when an admin manages ADP resources interactively. +* *Service account*: A non-human identity backed by OIDC client credentials. Applications, CI jobs, and `rpk ai` use service accounts. + +Account impersonation, which lets Redpanda Cloud's Console reuse a user's identity for Kafka API and Schema Registry calls, applies to those two subsystems only. ADP endpoints continue to authenticate clients directly through their OIDC tokens, regardless of how account impersonation is configured at the cluster level. See xref:redpanda-cloud:security:cloud-authentication.adoc#account-impersonation[Account impersonation] for the Kafka and Schema Registry flow. + +== Where ADP fits in Cloud RBAC + +ADP permissions are part of the same Cloud RBAC system that gates control-plane resources such as resource groups, networks, and clusters. The Admin, Writer, and Reader built-in roles each cover control-plane permissions, dataplane Kafka permissions, and ADP dataplane permissions in a single bundle, so a single role binding on the Writer role at the organization scope grants a developer access to every layer. + +== Related topics + +* xref:governance:permissions-reference.adoc[ADP Permissions Reference] diff --git a/modules/governance/pages/permissions-reference.adoc b/modules/governance/pages/permissions-reference.adoc new file mode 100644 index 0000000..192cf28 --- /dev/null +++ b/modules/governance/pages/permissions-reference.adoc @@ -0,0 +1,433 @@ += ADP Permissions Reference +:description: Look up the permissions ADP enforces across LLM providers, MCP servers, agents, pipelines, knowledge bases, and governance APIs, and the built-in roles that grant them. +:page-topic-type: reference +:personas: platform_admin +:learning-objective-1: Look up an ADP permission by namespace +:learning-objective-2: Find which built-in role grants a specific permission +:learning-objective-3: Identify the operation each permission gates + +// Source: `cloudv2` `pkg/permissions/permissions_constants.go` on origin/main, verified 2026-05-18. + +Every 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. + +Use this reference to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +For an explanation of how permissions, roles, and role bindings fit together, see xref:governance:permissions-overview.adoc[About ADP Permissions]. + +== How to read this reference + +Each table column means the same thing across every namespace. + +* The Permission column is the exact string the API enforces. Use it in custom-role definitions and role bindings. +* The Operation column is the user-facing action this permission gates. +* The Writer, Reader, and Invoker columns indicate whether the built-in role grants this permission, marked with a check mark. The Invoker column also names which Invoker sub-role (when applicable) grants the permission. + +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. + +== 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. + +[cols="2,2,1,1,1"] +|=== +|Permission |Operation |Writer |Reader |Invoker + +|`dataplane_adp_mcpserver_create` +|Register a new MCP server +|✓ +| +| + +|`dataplane_adp_mcpserver_update` +|Modify an existing MCP server's configuration +|✓ +| +| + +|`dataplane_adp_mcpserver_delete` +|Delete an MCP server +|✓ +| +| + +|`dataplane_adp_mcpserver_get` +|View one MCP server's configuration +|✓ +|✓ +| + +|`dataplane_adp_mcpserver_list` +|List MCP servers +|✓ +|✓ +| + +|`dataplane_adp_mcpserver_initialize` +|Initialize an MCP session against a server +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_ping` +|Health-check an MCP server +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_resources_list` +|List resources a server exposes +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_resources_templates_list` +|List resource templates a server exposes +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_resources_read` +|Read a resource from a server +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_prompts_list` +|List prompts a server exposes +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_prompts_get` +|Retrieve a prompt from a server +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_tools_list` +|List tools a server exposes +|✓ +|✓ +|MCPInvoker + +|`dataplane_adp_mcpserver_tools_call` +|Invoke a tool on an MCP server +|✓ +| +|MCPInvoker + +|`dataplane_adp_mcpserver_logging_set_level` +|Adjust an MCP server's log level +|✓ +| +| +|=== + +A legacy `dataplane_mcpserver_*` namespace mirrors these permissions and is still enforced by older proto versions. The Writer and Reader built-in roles include both namespaces, so existing role bindings continue to work without modification. + +== LLM provider permissions + +The `dataplane_adp_llmprovider_*` permissions gate AI Gateway provider configuration and the runtime proxy that forwards LLM requests upstream. + +[cols="2,2,1,1,1"] +|=== +|Permission |Operation |Writer |Reader |Invoker + +|`dataplane_adp_llmprovider_create` +|Create an LLM provider +|✓ +| +| + +|`dataplane_adp_llmprovider_get` +|View one LLM provider's configuration +|✓ +|✓ +| + +|`dataplane_adp_llmprovider_list` +|List LLM providers +|✓ +|✓ +| + +|`dataplane_adp_llmprovider_update` +|Modify an LLM provider's configuration +|✓ +| +| + +|`dataplane_adp_llmprovider_delete` +|Delete an LLM provider +|✓ +| +| + +|`dataplane_adp_llmprovider_invoke` +|Proxy LLM requests through AI Gateway at runtime +|✓ +| +|LLMProviderInvoker +|=== + +== Agent management permissions + +The `dataplane_adp_agent_*` permissions gate declarative agent configuration. + +[cols="2,2,1,1"] +|=== +|Permission |Operation |Writer |Reader + +|`dataplane_adp_agent_create` +|Create a declarative agent +|✓ +| + +|`dataplane_adp_agent_get` +|View one agent's configuration +|✓ +|✓ + +|`dataplane_adp_agent_list` +|List agents +|✓ +|✓ + +|`dataplane_adp_agent_update` +|Modify an agent's configuration +|✓ +| + +|`dataplane_adp_agent_delete` +|Delete an agent +|✓ +| +|=== + +== Agent credential permissions + +The `dataplane_adp_agent_credential_*` permissions gate the OIDC client credentials an agent uses for outbound calls. + +[cols="2,2,1,1"] +|=== +|Permission |Operation |Writer |Reader + +|`dataplane_adp_agent_credential_create` +|Issue a new OIDC client credential for an agent +|✓ +| + +|`dataplane_adp_agent_credential_list` +|List an agent's credentials +|✓ +|✓ + +|`dataplane_adp_agent_credential_delete` +|Revoke an agent credential +|✓ +| +|=== + +== Spending permissions + +The `dataplane_adp_spending_*` permissions gate the governance APIs that surface AI spend, request counts, and token volume. See xref:governance:budgets.adoc[Token Budgets and Limits] for what spending data ADP records automatically. + +[cols="2,2,1,1"] +|=== +|Permission |Operation |Writer |Reader + +|`dataplane_adp_spending_get` +|Read AI spending data for governance and cost reports +|✓ +|✓ +|=== + +== A2A runtime permissions + +The `dataplane_aiagent_a2a_*` permissions gate agent-to-agent (A2A) runtime traffic. The AIAgentInvoker built-in role grants every permission in this namespace. + +[cols="2,2,1,1,1"] +|=== +|Permission |Operation |Writer |Reader |Invoker + +|`dataplane_aiagent_a2a_message_send` +|Send a message to an agent +|✓ +| +|AIAgentInvoker + +|`dataplane_aiagent_a2a_message_stream` +|Open a streaming message connection to an agent +|✓ +| +|AIAgentInvoker + +|`dataplane_aiagent_a2a_tasks_get` +|Read one A2A task +|✓ +|✓ +|AIAgentInvoker + +|`dataplane_aiagent_a2a_tasks_list` +|List A2A tasks +|✓ +|✓ +|AIAgentInvoker + +|`dataplane_aiagent_a2a_tasks_cancel` +|Cancel an A2A task +|✓ +| +|AIAgentInvoker + +|`dataplane_aiagent_a2a_tasks_subscribe` +|Subscribe to A2A task events +|✓ +| +|AIAgentInvoker + +|`dataplane_aiagent_a2a_get_extended_agent_card` +|Read an agent's extended agent card +|✓ +|✓ +|AIAgentInvoker +|=== + +== Pipeline permissions + +The `dataplane_pipeline_*` permissions gate Redpanda Connect pipelines used by ADP for ingestion and transformation. The PipelineInvoker role grants only the runtime invocation permissions. + +[cols="2,2,1,1,1"] +|=== +|Permission |Operation |Writer |Reader |Invoker + +|`dataplane_pipeline_create` +|Create a pipeline +|✓ +| +| + +|`dataplane_pipeline_get` +|View one pipeline's configuration +|✓ +|✓ +| + +|`dataplane_pipeline_list` +|List pipelines +|✓ +|✓ +| + +|`dataplane_pipeline_update` +|Modify a pipeline's configuration +|✓ +| +| + +|`dataplane_pipeline_delete` +|Delete a pipeline +|✓ +| +| + +|`dataplane_pipeline_start` +|Start a stopped pipeline +|✓ +| +| + +|`dataplane_pipeline_stop` +|Stop a running pipeline +|✓ +| +| + +|`dataplane_pipeline_gateway_invoke` +|Invoke a pipeline through the gateway endpoint +|✓ +| +|PipelineInvoker + +|`dataplane_pipeline_otlp_grpc_invoke` +|Send OTLP traces to a pipeline over gRPC +|✓ +| +|PipelineInvoker + +|`dataplane_pipeline_otlp_http_invoke` +|Send OTLP traces to a pipeline over HTTP +|✓ +| +|PipelineInvoker +|=== + +== Knowledge base permissions + +The `dataplane_knowledgebase_*` permissions gate retrieval-augmented generation (RAG) knowledge bases. + +[cols="2,2,1,1"] +|=== +|Permission |Operation |Writer |Reader + +|`dataplane_knowledgebase_create` +|Create a knowledge base +|✓ +| + +|`dataplane_knowledgebase_get` +|View one knowledge base's configuration +|✓ +|✓ + +|`dataplane_knowledgebase_list` +|List knowledge bases +|✓ +|✓ + +|`dataplane_knowledgebase_update` +|Modify a knowledge base's configuration +|✓ +| + +|`dataplane_knowledgebase_delete` +|Delete a knowledge base +|✓ +| +|=== + +== Built-in roles summary + +[cols="1,3"] +|=== +|Role |Use case + +|*Admin* +|Cluster operators who configure providers, agents, MCP servers, pricing, and IAM. Grants every permission. + +|*Writer* +|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. + +|*AIAgentInvoker* +|Service accounts that send messages to agents over A2A without managing them. + +|*MCPInvoker* +|Service accounts that call MCP tools and read MCP resources without managing the servers. + +|*LLMProviderInvoker* +|Applications that proxy LLM requests through AI Gateway. Grants only `dataplane_adp_llmprovider_invoke`. + +|*PipelineInvoker* +|Clients that produce telemetry or send data into Connect pipelines without managing them. +|=== + +== Related topics + +* xref:governance:permissions-overview.adoc[About ADP Permissions]