diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index c2154c8..4a73f27 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -74,6 +74,9 @@ *** xref:gateway:bedrock-setup.adoc[Set Up AWS Bedrock as an LLM Provider] ** xref:gateway:connect-agent.adoc[Connect Your App to AI Gateway] +* xref:cli:index.adoc[Use the ADP CLI] +** xref:cli:gitops.adoc[Manage Resources with GitOps] + * xref:reference:index.adoc[Reference] ** xref:reference:rpk-install.adoc[Install or Update rpk] ** xref:reference:rpk/index.adoc[rpk Command Reference] diff --git a/modules/cli/pages/gitops.adoc b/modules/cli/pages/gitops.adoc new file mode 100644 index 0000000..76b5ac4 --- /dev/null +++ b/modules/cli/pages/gitops.adoc @@ -0,0 +1,225 @@ += Manage Resources with GitOps +:page-beta: true +:description: Keep ADP resources in Git and reconcile them with rpk ai apply and diff: declarative create-or-update, drift detection, and CI gating. +:page-topic-type: how-to +:personas: platform_engineer, agent_builder +:learning-objective-1: Export an ADP resource to a YAML manifest you can commit to Git +:learning-objective-2: Reconcile resources with apply, and preview changes with diff +:learning-objective-3: Gate continuous integration on configuration drift + +// Source: cloudv2 `apps/rpai/internal/gitops/` (engine.go, command.go, manifest.go, doc.go), the per-resource policies in `apps/rpai/internal/cmd/{llm,mcp,oauth,oauthclient,agent}/gitops.go`, `proto/public/cloud/redpanda/api/adp/v1alpha1/llm_provider.proto`, and `rpk ai apply|diff --help`. Console output verified against the engine and `apps/rpai/internal/gitops/engine_test.go`. Verified against origin/main 2026-06-26. + +GitOps keeps the definition of your glossterm:Agentic Data Plane (ADP)[] resources in Git and reconciles the live environment toward those files, instead of running imperative `create`, `update`, and `delete` commands by hand. With the xref:cli:index.adoc[ADP CLI], `rpk ai apply -f` creates what is missing and updates what has drifted, and `rpk ai diff -f` is a read-only dry-run that reports what `apply` would change. In these commands, `` is one of the resource command groups that support GitOps: + +* LLM providers (`rpk ai llm`) +* MCP servers (`rpk ai mcp`) +* OAuth providers (`rpk ai oauth`) +* OAuth clients (`rpk ai oauth-client`) +* Agents (`rpk ai agent`) + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== Prerequisites + +* The xref:cli:index.adoc[ADP CLI installed and connected] to an ADP environment. +* Permission to create and update the resources you manage. The reconcile commands call the same APIs as `create` and `update`. See xref:control:permissions-reference.adoc[Roles and Permissions Reference]. +* Any secrets your manifests reference already created in ADP. Manifests name secrets by reference, for example, `OPENAI_API_KEY`; the CLI does not create secrets. + +== How apply and diff reconcile + +A manifest is plain resource YAML: the same shape a `get -o yaml` dump produces. The CLI compares each manifest against the live resource of the same name and resolves one of three outcomes: + +Create:: +No resource of that name exists, so `apply` creates it. + +Update:: +The resource exists and a field in the manifest differs from the live value, so `apply` updates the differing fields. + +Unchanged:: +The resource exists and every field the manifest names already matches. + +The reconcile rules are deliberate, and they are not the same as a full-object replace: + +Presence drives updates:: +A field that is present in the manifest and differs from the live resource is updated. A field you omit is left untouched. To clear a field, write it explicitly with an empty or zero value. + +Collections replace wholesale:: +Lists, maps, and provider or backend variants are replaced as a unit, not merged element by element. + +Create-only fields are immutable:: +A field that can be set only at creation time, such as an LLM provider's `type`, an MCP server's backend kind, an OAuth provider's `client_id`, or an agent's managed-or-self-managed kind, cannot change on an existing resource. Changing one is an error that tells you to delete and recreate the resource. + +Secrets stay by reference:: +Manifests reference secrets by name, for example, `api_key_ref` and `client_secret_ref`, and never contain secret values, so a manifest is safe to commit to Git. + +The `apply` command does not delete resources that are absent from your manifests; there is no prune. The `diff` command checks only the fields a manifest names, so it does not detect a resource that exists in the environment but is missing from your manifests, nor drift in a field a manifest omits. + +== Export a resource to a manifest + +Start from a live resource so the manifest is complete. Dump it to YAML and redirect it to a file: + +[,bash] +---- +rpk ai llm get openai -o yaml > openai.yaml +---- + +A dumped OpenAI provider looks like this, ready to commit: + +[,yaml] +---- +'@type': type.googleapis.com/redpanda.api.adp.v1alpha1.LLMProvider +created_at: "2026-06-20T10:15:30Z" +display_name: OpenAI +enabled: true +name: openai +openai_config: + api_key_ref: OPENAI_API_KEY +provider_models: +- name: gpt-4o +- name: gpt-4o-mini +type: LLM_PROVIDER_TYPE_OPENAI +updated_at: "2026-06-20T10:15:30Z" +url: https://openai.aigw.d0example1cluster234.clusters.cloud.redpanda.com/openai/v1 +---- + +The `@type` line records the resource kind. It is optional when you apply with a resource command, because `rpk ai llm apply` already implies the kind, but keeping it lets a reader and any validator know what the file describes. + +[NOTE] +==== +The `created_at`, `updated_at`, and `url` fields are server-managed and read-only. The `apply` command ignores them, so you can leave them in the file or strip them. The `api_key_ref` value is a reference to a secret, not the key itself. +==== + +== Preview changes with diff + +Edit the manifest, then preview the effect before you touch the environment. For example, change the display name: + +[,yaml] +---- +display_name: OpenAI (production) +---- + +Run `diff` to see the plan: + +[,bash] +---- +rpk ai llm diff -f openai.yaml +---- + +[,text] +---- +~ openai (update: display_name) +---- + +The `diff` command marks each manifest with one of three symbols and changes nothing: + +[cols="1m,3"] +|=== +|Symbol |Meaning + +|+ +|The `apply` command would create the resource. + +|~ +|The `apply` command would update the resource. The changed fields follow in parentheses. + +|= +|The resource already matches; `apply` would leave it unchanged. +|=== + +The `diff` command exits with a non-zero status when any change is pending, and zero when the environment already matches every manifest. That exit code is what lets continuous integration gate on drift. + +== Apply changes + +Reconcile the environment toward the manifest: + +[,bash] +---- +rpk ai llm apply -f openai.yaml +---- + +The `apply` command prints one line per manifest as it works: + +[,text] +---- +updated openai (display_name) +---- + +A first-time apply of a resource that does not yet exist prints `created openai` instead, and a manifest that already matches the environment prints `unchanged openai`. The CLI plans every manifest before it changes anything, so a malformed manifest aborts the run before any write. If a later write fails, the lines already printed tell you exactly what was applied. + +== Apply many manifests at once + +The `-f` flag is repeatable and accepts a file, a directory, or a stream: + +[,bash] +---- +# A directory of manifests; the CLI reads every .yaml and .yml file, sorted by name. +rpk ai mcp apply -f ./manifests/ + +# Several paths in one run. +rpk ai llm apply -f openai.yaml -f anthropic.yaml + +# Standard input, for piping a manifest from another tool. +rpk ai oauth apply -f - +---- + +A single file can hold more than one manifest. Separate documents with a line containing only `---`. + +== Gate continuous integration on drift + +Because `diff` exits non-zero when the environment differs from your manifests, a continuous-integration job can fail the build whenever the live environment has drifted from Git: + +[,bash] +---- +# Fails the job if an apply would change anything. +rpk ai llm diff -f ./llm/ +rpk ai mcp diff -f ./mcp/ +---- + +A common pipeline runs `diff` on a pull request to preview changes, then runs `apply` after the merge to roll them out: + +[,bash] +---- +# Deploy step, after merge to the main branch. +rpk ai llm apply -f ./llm/ +rpk ai mcp apply -f ./mcp/ +---- + +== Manifests are declarative + +A manifest describes the full intended state, so an omitted field means zero, not the convenience default that `create` fills in. A manifest that omits `enabled` creates a disabled resource, and `diff` then reports no drift, because the disabled state matches the manifest. + +To avoid surprises: + +* Start from a `get -o yaml` dump, which is already complete, rather than hand-writing a manifest from scratch. +* Set `enabled: true` explicitly when you want an active resource. + +One subtlety follows from this: a dump of an already-disabled resource omits `enabled`, because `false` is the field's zero value and the dump omits zero values. Reapplying that dump elsewhere also produces a disabled resource. + +== Troubleshooting + +[cols="2,3"] +|=== +|Symptom |Resolution + +|The `apply` or `diff` command reports that a field is immutable and tells you to delete and recreate the resource. +|You changed a create-only field, such as an LLM provider's `type` or an OAuth provider's `client_id`. Restore the original value, or delete the resource and recreate it from the new manifest. + +|The `apply` or `diff` command fails to decode the manifest and mentions unknown or misspelled fields. +|A key in the manifest is not a field of the resource. The CLI rejects unknown keys rather than dropping them silently. Fix the key. Start from a `get -o yaml` dump to get the exact field names. + +|The `diff` command reports no drift, but you know the environment has extra resources. +|The `diff` and `apply` commands never prune. They act only on the resources your manifests name. Delete unwanted resources with `rpk ai delete`. + +|A field you changed in the environment keeps coming back after `apply`. +|The `apply` command overwrites a field only when the manifest names it and the value differs. If the change is not in your manifest, add it, then reapply. +|=== + +== Next steps + +* xref:cli:index.adoc[] +* xref:gateway:configure-provider.adoc[] +* xref:connect:create-server.adoc[] diff --git a/modules/cli/pages/index.adoc b/modules/cli/pages/index.adoc new file mode 100644 index 0000000..70a8e1b --- /dev/null +++ b/modules/cli/pages/index.adoc @@ -0,0 +1,153 @@ += Use the ADP CLI +:page-beta: true +:description: Manage Agentic Data Plane resources from the terminal with rpk ai. Install the CLI, connect it to an AI Gateway, and script LLM providers, MCP servers, OAuth, and agents. +:page-topic-type: how-to +:personas: platform_engineer, agent_builder +:learning-objective-1: Install the ADP CLI and connect it to an AI Gateway +:learning-objective-2: Manage ADP resources from the terminal: LLM providers, MCP servers, OAuth providers and clients, and agents +:learning-objective-3: Format command output for scripts and pipelines + +// Source: cloudv2 `apps/rpai/README.md`, `apps/rpai/internal/cmd/root.go` (plugin-mode command surface + persistent flags), `apps/rpai/internal/cmd/env/cmd.go`, and `rpk ai --help`, cross-referenced against `modules/gateway/pages/connect-agent.adoc` and `modules/reference/pages/rpk/rpk-ai/`. Connect/auth model reflects cloudv2 PR #27510: rpk ai is self-contained (its own `auth login` device flow + ADP environment selection), not tied to the rpk cloud session. Verified against origin/main 2026-06-29 (cloudv2 PR #27510 merged). + +The ADP command-line interface, `rpk ai`, manages glossterm:Agentic Data Plane (ADP)[] resources from your terminal. It drives the same control surface as the ADP UI: glossterm:large language model (LLM)[] providers, glossterm:Model Context Protocol (MCP)[] servers, OAuth providers and clients, and agents. Because every action is a command, you can script it and run it in continuous integration. + +The ADP CLI, also called the Redpanda AI CLI, runs as an xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk`] plugin, so you install and run it through your existing `rpk` setup. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== Install the CLI + +The ADP CLI is an `rpk` managed plugin. Install `rpk` first (see xref:reference:rpk-install.adoc[Install or Update rpk]), then install the plugin: + +[,bash] +---- +rpk ai install +---- + +Update the plugin later with xref:reference:rpk/rpk-ai/rpk-ai-upgrade.adoc[`rpk ai upgrade`], and remove it with xref:reference:rpk/rpk-ai/rpk-ai-uninstall.adoc[`rpk ai uninstall`]. + +== Connect to an AI Gateway + +The `rpk ai` command is self-contained: it has its own login and its own environment selection, independent of any `rpk cloud` session. You sign in once, choose an ADP environment, and `rpk ai` targets that environment's AI Gateway for every command. + +. Sign in to Redpanda Cloud. This runs an OAuth device-authorization flow in your browser, caches credentials in `~/.rpai/credentials` (readable only by you), then lists the ADP environments in your organization so you can pick one: ++ +[,bash] +---- +rpk ai auth login +---- + +. List the environments available to you, and switch the active one by name or ID: ++ +[,bash] +---- +rpk ai env list +rpk ai env use +---- ++ +In these commands, `` is the name or ID of an ADP environment. `rpk ai env use` repoints the active profile at that environment's AI Gateway in place. Inspect the resolved environment and token state at any time with `rpk ai env show` and `rpk ai auth status`. + +. Verify the connection: ++ +[,bash] +---- +rpk ai llm list +---- + +For the full setup walkthrough, including token expiry behavior and the supported environment variables, see xref:gateway:connect-agent.adoc#authenticate-with-rpk-ai[Use `rpk ai` for local development]. + +To target a different AI Gateway URL for a single command without switching environments, pass `--rpai-endpoint`: + +[,bash] +---- +rpk ai --rpai-endpoint https://aigw..clusters.cloud.redpanda.com llm list +---- + +This overrides the selected environment's AI Gateway URL for that one command; the flag is not bound to an environment variable. For a local or manual gateway you use repeatedly, define it once as an environment with `rpk ai env add`: + +[,bash] +---- +rpk ai env add local --ai-gateway-url http://localhost:8090 --auth-mode none +rpk ai env use local +---- + +== Manage resources + +Each ADP resource has its own command group, and each group supports the standard `create`, `get`, `list`, `update`, and `delete` actions. The model catalog is read-only. + +[cols="1m,2,1a"] +|=== +|Command |Manages |Reference + +|rpk ai llm +|LLM providers (OpenAI, Anthropic, Google, AWS Bedrock, and OpenAI-compatible endpoints) +|xref:reference:rpk/rpk-ai/rpk-ai-llm.adoc[`rpk ai llm`] + +|rpk ai mcp +|MCP servers and their tools +|xref:reference:rpk/rpk-ai/rpk-ai-mcp.adoc[`rpk ai mcp`] + +|rpk ai oauth +|OAuth providers for user-delegated MCP connections +|xref:reference:rpk/rpk-ai/rpk-ai-oauth.adoc[`rpk ai oauth`] + +|rpk ai oauth-client +|OAuth clients that external tools use to reach an MCP server +|xref:reference:rpk/rpk-ai/rpk-ai-oauth-client.adoc[`rpk ai oauth-client`] + +|rpk ai agent +|Agents in the agent registry +|xref:reference:rpk/rpk-ai/rpk-ai-agent.adoc[`rpk ai agent`] + +|rpk ai model +|The model catalog (read-only discovery) +|xref:reference:rpk/rpk-ai/rpk-ai-model.adoc[`rpk ai model`] +|=== + +For example, to create and inspect an LLM provider: + +[,bash] +---- +rpk ai llm create --name openai --type openai --api-key-ref OPENAI_API_KEY +rpk ai llm get openai +---- + +In this command, `--api-key-ref` names a secret already stored in ADP. The CLI never takes a raw API key, so secrets stay out of your shell history and out of any file you commit. + +To create, update, and delete resources declaratively from YAML manifests instead of imperative flags, see xref:cli:gitops.adoc[Manage Resources with GitOps]. + +== Format command output + +Every `list` and `get` command honors `-o` (`--format`): + +[cols="1m,3"] +|=== +|Format |Use + +|table +|Default. Human-readable columns. + +|wide +|Table with extra columns. + +|json +|Machine-readable JSON for scripts and `jq`. + +|yaml +|YAML. A `get -o yaml` dump is a complete manifest you can edit and reapply. + +|markdown +|Pipe-friendly tables for documents. +|=== + +Set a default for the session with the `RPAI_FORMAT` environment variable. The `-o` flag always wins when both are set. + +== Next steps + +* xref:cli:gitops.adoc[] +* xref:gateway:configure-provider.adoc[] +* xref:reference:rpk/rpk-ai/rpk-ai.adoc[] diff --git a/modules/connect/pages/create-server.adoc b/modules/connect/pages/create-server.adoc index ac5d74b..19425f7 100644 --- a/modules/connect/pages/create-server.adoc +++ b/modules/connect/pages/create-server.adoc @@ -204,7 +204,7 @@ rpk ai mcp update github-proxy \ // TODO(rpk-ai): --auth-config does not exist on `rpk ai mcp create` today (verified against cloudv2/apps/rpai/internal/cmd/mcp/cmd.go on 2026-05-05). For non-convenience auth shapes, encode them inside `--managed-config` JSON. Re-add this row if a flag lands later. -The command resolves the gateway URL from your active rpk cloud profile and reads the cached `rpk cloud login` token. +The command targets the AI Gateway of your selected ADP environment, using credentials from `rpk ai auth login`. == Edit, disable, and delete a server diff --git a/modules/connect/pages/test-tools.adoc b/modules/connect/pages/test-tools.adoc index ac366b0..e523497 100644 --- a/modules/connect/pages/test-tools.adoc +++ b/modules/connect/pages/test-tools.adoc @@ -119,7 +119,7 @@ rpk ai mcp tools call --input '{"arg1":"value"}' rpk ai mcp get ---- -The command resolves the gateway URL from your active rpk cloud profile and reads the cached `rpk cloud login` token. See xref:gateway:connect-agent.adoc[Connect your app to AI Gateway] for installation and profile setup. +The command targets the AI Gateway of your selected ADP environment, using credentials from `rpk ai auth login`. See xref:gateway:connect-agent.adoc[Connect your app to AI Gateway] for installation and sign-in. == Next steps diff --git a/modules/gateway/pages/connect-agent.adoc b/modules/gateway/pages/connect-agent.adoc index 0573591..72e407b 100644 --- a/modules/gateway/pages/connect-agent.adoc +++ b/modules/gateway/pages/connect-agent.adoc @@ -4,10 +4,10 @@ :personas: agent_builder :page-aliases: cloud-data-platform:ai-agents:ai-gateway/builders/connect-your-agent.adoc, cloud-data-platform:ai-agents:ai-gateway/connect-agent.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/index.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/cline-admin.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/cline-user.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/continue-admin.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/continue-user.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/cursor-admin.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/cursor-user.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/github-copilot-admin.adoc, cloud-data-platform:ai-agents:ai-gateway/integrations/github-copilot-user.adoc :learning-objective-1: Construct the proxy URL for an LLM provider you have configured -:learning-objective-2: pass:q[Authenticate to AI Gateway with `rpk` for local development or with OIDC client credentials for CI and programmatic clients] +:learning-objective-2: pass:q[Authenticate to AI Gateway with the `rpk ai` CLI for local development or with OIDC client credentials for CI and programmatic clients] :learning-objective-3: Send requests through the proxy URL with the SDK of your choice -This guide shows how to connect your glossterm:AI agent[] or application to the AI Gateway. You construct the proxy URL for a provider you have already created, authenticate (with xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] for local development or with OIDC client credentials for CI and application code), and send your first request with the SDK of your choice. +This guide shows how to connect your glossterm:AI agent[] or application to the AI Gateway. You construct the proxy URL for a provider you have already created, authenticate (with the xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] CLI for local development or with OIDC client credentials for CI and application code), and send your first request with the SDK of your choice. TIP: The provider's *Connect* tab in ADP generates this configuration for you: a gateway-token step, setup instructions for popular clients, and code examples with the provider's proxy URL prefilled. Copy from the tab for a quick start, or follow this page for the full flow. @@ -43,12 +43,12 @@ AI Gateway forwards the request to the upstream provider, attaches the configure TIP: The provider detail page generates ready-to-run snippets pre-filled with the correct proxy URL and paths. When in doubt, copy from the Connect your app section there. -// Updated for PRs #30273 / #30327 / #30360 (rpk ai managed plugin). +// Updated for cloudv2 PR #27510: rpk ai is self-contained (its own auth login + ADP environment selection), no longer tied to the rpk cloud session. [[authenticate-with-rpk-ai]] [[authenticate-with-rpai]] == Use `rpk ai` for local development -The xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] command is the Redpanda AI CLI. Use it to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools from the command line. Authentication for `rpk ai` is owned by `rpk cloud login`. The active AI Gateway URL comes from your active rpk cloud profile. +The xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] command is the Redpanda AI CLI. Use it to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools from the command line. `rpk ai` is self-contained: it has its own login and its own ADP environment selection, independent of any `rpk cloud` session. . xref:reference:rpk/rpk-ai/rpk-ai-install.adoc[Install `rpk ai`]: + @@ -59,25 +59,22 @@ rpk ai install + Update later with xref:reference:rpk/rpk-ai/rpk-ai-upgrade.adoc[`rpk ai upgrade`]; remove with xref:reference:rpk/rpk-ai/rpk-ai-uninstall.adoc[`rpk ai uninstall`]. -. Log in to Redpanda: +. Sign in. This runs an OAuth device-authorization flow in your browser, caches credentials in `~/.rpai/credentials` (readable only by you), then lists the ADP environments in your organization so you can select one: + [source,bash] ---- -rpk cloud login +rpk ai auth login ---- -+ -This caches a cloud token in `~/.config/rpk/rpk.yaml`. On every invocation, `rpk ai` reads the cached token automatically. -. Select a xref:reference:rpk/rpk-profile/rpk-profile.adoc[profile] that points at a cluster with AI Gateway v2 attached. The AI Gateway URL is cached on the profile when you create it. +. Select the ADP environment whose AI Gateway you want to target. The `rpk ai env use` command accepts an environment name or ID and repoints the active profile in place: + [source,bash] ---- -rpk profile use -# or, to switch the cluster the active profile points at: -rpk cloud cluster use +rpk ai env list +rpk ai env use ---- + -See xref:reference:rpk/rpk-cloud/rpk-cloud-cluster.adoc[`rpk cloud cluster`] for switching the active cluster. +Inspect the resolved environment and token state at any time with `rpk ai env show` and `rpk ai auth status`. . Verify the connection: + @@ -86,7 +83,7 @@ See xref:reference:rpk/rpk-cloud/rpk-cloud-cluster.adoc[`rpk cloud cluster`] for rpk ai llm list ---- -If the cached cloud token has expired, `rpk ai` returns a 401 with a hint to rerun `rpk cloud login`. +If the cached token has expired, `rpk ai` returns a 401; rerun `rpk ai auth login` to refresh it. [NOTE] ==== @@ -95,17 +92,21 @@ If the cached cloud token has expired, `rpk ai` returns a 401 with a hint to rer [TIP] ==== -To target a specific gateway URL for a single invocation (for example, when running against a staging gateway without switching profiles), pass `--rpai-endpoint`: +To target a specific AI Gateway URL for a single invocation (for example, a local gateway, or a staging environment the environments list does not include), pass `--rpai-endpoint`: [source,bash] ---- -rpk ai --rpai-endpoint https://aigw..clusters.rdpa.co llm list +rpk ai --rpai-endpoint http://localhost:8090 llm list ---- -You can also export `RPAI_ENDPOINT` to override for the shell session. -==== +This overrides the selected environment's AI Gateway URL for that one command, and the flag is not bound to an environment variable. For a manual or local gateway you use repeatedly, define it once as an environment instead: -// TODO(rpk-ai): rpai suppresses auth/profile subtrees in plugin mode today (cloudv2 apps/rpai/internal/cmd/root.go:127-135). If that changes, document `rpk ai auth` and `rpk ai profile` here. +[source,bash] +---- +rpk ai env add local --ai-gateway-url http://localhost:8090 --auth-mode none +rpk ai env use local +---- +==== === Environment variables @@ -116,13 +117,10 @@ The `rpk ai` command honors the following environment variables: |Variable |Purpose |`RPAI_TOKEN` -|Bearer token for the gateway. Normally injected automatically from your cached `rpk cloud login` token; set explicitly to override. - -|`RPAI_ENDPOINT` -|AI Gateway URL. Normally resolved from your active rpk cloud profile; set explicitly to override. +|Static bearer token for the gateway. `rpk ai` normally manages its own token through `rpk ai auth login`; set this (or pass `--token`) to override, for example in a headless or CI shell. |`RPAI_PROFILE`, `RPAI_CONFIG`, `RPAI_VERBOSE`, `RPAI_FORMAT` -|Map to `--rpai-profile`, `--rpai-config`, `--rpai-verbose`, `--format`. Long flag names are renamed under `rpk ai` to avoid collision with `rpk`'s globals; short flags (`-p`, `-c`, `-v`, `-o`) are unchanged. +|Map to `--rpai-profile`, `--rpai-config`, `--rpai-verbose`, `--format`. Long flag names are renamed under `rpk ai` to avoid collision with `rpk`'s globals; short flags (`-p`, `-c`, `-v`, `-o`) are unchanged. There is no environment variable for the AI Gateway URL override; use the `--rpai-endpoint` flag. |=== [[authenticate-with-oidc-client-credentials]] @@ -453,7 +451,7 @@ AI Gateway returns standard HTTP status codes. The upstream provider's error bod === 401 Unauthorized -* If you're using `rpk ai`: Rerun `rpk cloud login` to refresh the cached cloud token. Token expiry surfaces as a 401 with this hint in the error. +* If you're using `rpk ai`: Rerun `rpk ai auth login` to refresh the credentials. Token expiry surfaces as a 401. * If you're using OIDC client credentials: Check the token hasn't expired and refresh it. Verify the audience is `cloudv2-production.redpanda.cloud` and the `Authorization` header is formatted `Bearer `. * For Gemini: Ensure the token is sent as `x-goog-api-key`, not `Authorization`. * For Anthropic with passthrough: Ensure the client is sending a valid Anthropic `Authorization` header. diff --git a/modules/gateway/pages/overview.adoc b/modules/gateway/pages/overview.adoc index 6492c19..a1a8233 100644 --- a/modules/gateway/pages/overview.adoc +++ b/modules/gateway/pages/overview.adoc @@ -45,7 +45,7 @@ Use the provider's own SDK: OpenAI, Anthropic, Google AI, AWS Bedrock, or any Op === Managed authentication -Applications authenticate to ADP with OIDC service accounts instead of long-lived provider API keys. Service accounts use the same role and audit model as every other ADP resource, and mint short-lived tokens that are easy to revoke. For local command-line workflows, use xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] to authenticate and xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] to talk to the gateway. CI and programmatic clients use the OIDC client-credentials grant directly. See xref:gateway:connect-agent.adoc[Connect your app to AI Gateway]. +Applications authenticate to ADP with OIDC service accounts instead of long-lived provider API keys. Service accounts use the same role and audit model as every other ADP resource, and mint short-lived tokens that are easy to revoke. For local command-line workflows, use xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] to sign in (`rpk ai auth login`) and talk to the gateway. CI and programmatic clients use the OIDC client-credentials grant directly. See xref:gateway:connect-agent.adoc[Connect your app to AI Gateway]. === Per-provider observability diff --git a/modules/reference/pages/rpk/index.adoc b/modules/reference/pages/rpk/index.adoc index a56eb8c..5aa1e73 100644 --- a/modules/reference/pages/rpk/index.adoc +++ b/modules/reference/pages/rpk/index.adoc @@ -4,6 +4,6 @@ This section documents the `rpk` commands you use to manage the Redpanda Agentic Data Plane (ADP) from the command line. -Use `rpk ai` to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools directly from your terminal. Authentication is owned by `rpk cloud login`. The `rpk ai` commands reuse your active `rpk profile` and the cached cloud token. The active AI Gateway URL is resolved from the same profile unless you override it with `--rpai-endpoint`. +Use `rpk ai` to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools directly from your terminal. `rpk ai` is self-contained: it has its own login (`rpk ai auth login`) and its own ADP environment selection (`rpk ai env`), independent of any `rpk cloud` session. The active AI Gateway URL comes from the selected environment unless you override it with `--rpai-endpoint`. For subcommands available after install (`rpk ai llm`, `rpk ai mcp`, `rpk ai oauth`, and more), run `rpk ai --help` from your terminal.