From 35506be12496f27c36fe1c07ebf1b056e8b68543 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 4 Feb 2026 15:38:05 -0300 Subject: [PATCH 1/4] adp: add authorization docs --- modules/ai-agents/pages/agents/concepts.adoc | 2 + .../ai-agents/pages/agents/create-agent.adoc | 6 +- .../ai-agents/pages/agents/quickstart.adoc | 2 + .../ai-agents/pages/mcp/remote/concepts.adoc | 2 + .../pages/mcp/remote/quickstart.adoc | 7 +-- .../service-account-authorization.adoc | 61 +++++++++++++++++++ 6 files changed, 71 insertions(+), 9 deletions(-) create mode 100644 modules/ai-agents/partials/service-account-authorization.adoc diff --git a/modules/ai-agents/pages/agents/concepts.adoc b/modules/ai-agents/pages/agents/concepts.adoc index 0ddb068f9..b43384a3f 100644 --- a/modules/ai-agents/pages/agents/concepts.adoc +++ b/modules/ai-agents/pages/agents/concepts.adoc @@ -140,6 +140,8 @@ When context exceeds the limit, the oldest tool results get truncated, the agent Design workflows to complete within context limits. Avoid unbounded tool chaining. +include::partial$service-account-authorization.adoc[] + == Next steps * xref:ai-agents:agents/architecture-patterns.adoc[] diff --git a/modules/ai-agents/pages/agents/create-agent.adoc b/modules/ai-agents/pages/agents/create-agent.adoc index 60b95ecf9..f09baaa78 100644 --- a/modules/ai-agents/pages/agents/create-agent.adoc +++ b/modules/ai-agents/pages/agents/create-agent.adoc @@ -210,9 +210,9 @@ The updated metadata appears immediately at `\https://your-agent-url/.well-known . Configure the service account name (optional): + -* Default pattern: `--agent--sa` -* Custom name: 3-128 characters, cannot contain `<` or `>` characters -* This service account authenticates the agent with cluster resources +A service account is automatically created to authenticate your agent with cluster resources. The default name follows the pattern `cluster--agent--sa`. You can customize this name (3-128 characters, cannot contain `<` or `>` characters). ++ +For details about default permissions and how to manage service accounts, see xref:ai-agents:agents/concepts.adoc#service-account-authorization[Service account authorization]. . Click *Create Agent*. diff --git a/modules/ai-agents/pages/agents/quickstart.adoc b/modules/ai-agents/pages/agents/quickstart.adoc index 0be1a183b..6c7c51825 100644 --- a/modules/ai-agents/pages/agents/quickstart.adoc +++ b/modules/ai-agents/pages/agents/quickstart.adoc @@ -104,6 +104,8 @@ Response format: * *Max Iterations*: `30` (allows multiple tool calls per request) . Review your configuration and click *Create Agent*. ++ +TIP: A service account is automatically created to authenticate your agent with cluster resources. For details about default permissions and how to manage service accounts, see xref:ai-agents:agents/concepts.adoc#service-account-authorization[Service account authorization]. . Wait for the agent status to change from *Starting* to *Running*. diff --git a/modules/ai-agents/pages/mcp/remote/concepts.adoc b/modules/ai-agents/pages/mcp/remote/concepts.adoc index db7f22ada..eb31010c6 100644 --- a/modules/ai-agents/pages/mcp/remote/concepts.adoc +++ b/modules/ai-agents/pages/mcp/remote/concepts.adoc @@ -37,6 +37,8 @@ MCP servers automatically emit OpenTelemetry traces for monitoring and debugging To monitor MCP server activity, consume traces, and debug failures, see xref:ai-agents:mcp/remote/monitor-mcp-servers.adoc[]. +include::partial$service-account-authorization.adoc[] + == Next steps * xref:ai-agents:mcp/remote/create-tool.adoc[] diff --git a/modules/ai-agents/pages/mcp/remote/quickstart.adoc b/modules/ai-agents/pages/mcp/remote/quickstart.adoc index 92ee94aeb..1a649d4dd 100644 --- a/modules/ai-agents/pages/mcp/remote/quickstart.adoc +++ b/modules/ai-agents/pages/mcp/remote/quickstart.adoc @@ -191,12 +191,7 @@ This page shows a list of existing servers. * *Description*: Explain what the server does. For example, `Generates fake user event data and publishes it to Redpanda topics`. * *Tags*: Add key/value tags such as `owner=platform` or `env=demo`. The tag names `service_account_id` and `secret_id` are reserved and cannot be used. * *Resources*: Choose a size (XSmall / Small / Medium / Large / XLarge). Larger sizes allow more concurrent requests and faster processing, but cost more. You can change this later. -* *Service Account*: A service account is automatically created for authenticating the MCP server to your cluster. The name is pre-filled. You can customize this name or keep the default. -+ -[NOTE] -==== -Service accounts authenticate MCP server requests to your Redpanda cluster. The service account has editor permissions to the cluster, allowing it to perform operations like reading and writing data, managing topics, and accessing cluster resources. Service account credentials are stored in the xref:develop:connect/configuration/secret-management.adoc[Secrets Store] with the ID `SERVICE_ACCOUNT_` and scope set to *MCP server*. -==== +* *Service Account*: A service account is automatically created for authenticating the MCP server to your cluster. The name is pre-filled but you can customize it. For details about default permissions and how to manage service accounts, see xref:ai-agents:mcp/remote/concepts.adoc#service-account-authorization[Service account authorization]. . Click *Next* to define tools. + diff --git a/modules/ai-agents/partials/service-account-authorization.adoc b/modules/ai-agents/partials/service-account-authorization.adoc new file mode 100644 index 000000000..6091757ff --- /dev/null +++ b/modules/ai-agents/partials/service-account-authorization.adoc @@ -0,0 +1,61 @@ +[[service-account-authorization]] +== Service account authorization + +When you create an MCP server or AI agent, Redpanda Cloud automatically creates a service account to authenticate requests to your cluster. + +=== Default configuration + +The service account is created with: + +* **Name**: Pre-filled as `cluster----sa`, where `sa` stands for service account. For example: +** MCP server: `cluster-d5tp5kntujt599ksadgg-mcp-my-test-server-sa` +** AI agent: `cluster-d5tp5kntujt599ksadgg-agent-my-agent-sa` ++ +You can customize this name during creation. + +* **Role binding**: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage topics, and access cluster resources. + +=== Manage service accounts + +You can view and manage service accounts created for MCP servers and AI agents in *Organization* > *IAM* > *Service accounts*. + +The Organization IAM page shows additional details not visible during creation: + +[cols="1,2"] +|=== +|Field |Description + +|Client ID +|Unique identifier for OAuth2 authentication + +|Description +|Optional description of the service account + +|Created at +|Timestamp when the service account was created + +|Updated at +|Timestamp of the last modification +|=== + +From this page you can: + +* Edit the service account name or description +* View and manage role bindings +* Rotate credentials +* Delete the service account + +[NOTE] +==== +Deleting a service account removes authentication for the associated MCP server or AI agent. The resource will no longer be able to access cluster data. +==== + +=== Customize role bindings + +The default Writer role provides broad access suitable for most use cases. If you need more restrictive permissions: + +. Navigate to *Organization* > *IAM* > *Service accounts*. +. Find the service account for your resource. +. Edit the role bindings to use a more restrictive role or scope. + +For more about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[]. From dd09b6526cfefdd099b8436dd692ffe208d42b8a Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 4 Feb 2026 15:46:26 -0300 Subject: [PATCH 2/4] adjust to standards --- .../partials/service-account-authorization.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ai-agents/partials/service-account-authorization.adoc b/modules/ai-agents/partials/service-account-authorization.adoc index 6091757ff..e5bb1594d 100644 --- a/modules/ai-agents/partials/service-account-authorization.adoc +++ b/modules/ai-agents/partials/service-account-authorization.adoc @@ -7,13 +7,13 @@ When you create an MCP server or AI agent, Redpanda Cloud automatically creates The service account is created with: -* **Name**: Pre-filled as `cluster----sa`, where `sa` stands for service account. For example: +* *Name*: Pre-filled as `cluster----sa`, where `sa` stands for service account. For example: ** MCP server: `cluster-d5tp5kntujt599ksadgg-mcp-my-test-server-sa` ** AI agent: `cluster-d5tp5kntujt599ksadgg-agent-my-agent-sa` + You can customize this name during creation. -* **Role binding**: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage topics, and access cluster resources. +* *Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage topics, and access cluster resources. === Manage service accounts @@ -21,7 +21,7 @@ You can view and manage service accounts created for MCP servers and AI agents i The Organization IAM page shows additional details not visible during creation: -[cols="1,2"] +[cols="1,2", options="header"] |=== |Field |Description @@ -47,7 +47,7 @@ From this page you can: [NOTE] ==== -Deleting a service account removes authentication for the associated MCP server or AI agent. The resource will no longer be able to access cluster data. +Deleting a service account removes authentication for the associated MCP server or AI agent. The resource can no longer access cluster data. ==== === Customize role bindings @@ -58,4 +58,4 @@ The default Writer role provides broad access suitable for most use cases. If yo . Find the service account for your resource. . Edit the role bindings to use a more restrictive role or scope. -For more about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[]. +For more about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[Role-based access control]. From 469fb467e7dadd60416b3c61df44708f8905dcc9 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 4 Feb 2026 16:37:05 -0300 Subject: [PATCH 3/4] Update modules/ai-agents/partials/service-account-authorization.adoc --- modules/ai-agents/partials/service-account-authorization.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ai-agents/partials/service-account-authorization.adoc b/modules/ai-agents/partials/service-account-authorization.adoc index e5bb1594d..6e621480d 100644 --- a/modules/ai-agents/partials/service-account-authorization.adoc +++ b/modules/ai-agents/partials/service-account-authorization.adoc @@ -54,7 +54,7 @@ Deleting a service account removes authentication for the associated MCP server The default Writer role provides broad access suitable for most use cases. If you need more restrictive permissions: -. Navigate to *Organization* > *IAM* > *Service accounts*. +. Exit the cluster. Navigate to *Organization IAM * > *Service accounts*. . Find the service account for your resource. . Edit the role bindings to use a more restrictive role or scope. From b23a05b94b4794856b879b90773721ff11f76b22 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 4 Feb 2026 19:41:56 -0300 Subject: [PATCH 4/4] use glossterms --- modules/ai-agents/partials/service-account-authorization.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ai-agents/partials/service-account-authorization.adoc b/modules/ai-agents/partials/service-account-authorization.adoc index 6e621480d..ff1eb27b8 100644 --- a/modules/ai-agents/partials/service-account-authorization.adoc +++ b/modules/ai-agents/partials/service-account-authorization.adoc @@ -1,7 +1,7 @@ [[service-account-authorization]] == Service account authorization -When you create an MCP server or AI agent, Redpanda Cloud automatically creates a service account to authenticate requests to your cluster. +When you create a glossterm:mcp-server[] or glossterm:ai-agent[], Redpanda Cloud automatically creates a glossterm:service-account[] to glossterm:authentication[authenticate] requests to your glossterm:cluster[]. === Default configuration @@ -13,7 +13,7 @@ The service account is created with: + You can customize this name during creation. -* *Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage topics, and access cluster resources. +* *Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage glossterm:topic[,topics], and access cluster resources. === Manage service accounts