docs: add Use the ADP CLI section with GitOps how-to#112
Merged
Conversation
The rpk ai CLI can manage every ADP resource declaratively from YAML manifests, but the docs only shipped the autogenerated command reference. Operators automating ADP in Git and CI had no guide for the apply/diff workflow, its reconcile semantics, or drift gating. Add a top-level "Use the ADP CLI" section (beta) with two pages: - index.adoc: what rpk ai is, install, connect (reuses rpk cloud login and the active profile), the resource command surface, and output formats. Links to the existing connect-agent setup walkthrough rather than duplicating it. - gitops.adoc: export with get -o yaml, preview with diff, reconcile with apply, directory/stdin/multi-document inputs, CI drift gating, the declarative omitted-means-zero caveat, and troubleshooting. Covers llm, mcp, oauth, oauth-client, and agent. Wire both into the nav between Routing & LLM Settings and Reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
👷 Deploy request for redpanda-agentic-data-plane pending review.Visit the deploys page to approve it
|
rpai no longer rides the rpk cloud session. It signs in with its own device-flow login and selects an ADP environment, not a streaming cluster. The docs still described the old coupling everywhere rpk ai was mentioned. Rewrite the CLI overview connect section and the connect-agent rpk ai walkthrough around `rpk ai auth login` and `rpk ai env`, drop the false RPAI_ENDPOINT env override (the only endpoint override is the --rpai-endpoint flag, deliberately not env-bound), and move the GitOps page's connection-target wording from "cluster" to "environment". Fix the same stale "authentication is owned by rpk cloud login" claim in the rpk reference index, the gateway overview, and the Connect test-tools/create-server pages. Tracks cloudv2 PR #27510.
Contributor
Author
|
@micheleRP this is now ready for review |
- gitops: convert the reconcile-outcomes list to a description list and trim the page description under the 155-char limit - cli overview: set page-topic-type to how-to to match its procedural content and skill-level learning objectives - align "independent of any rpk cloud session" phrasing across the cli, connect-agent, and rpk reference pages - refresh the cli index source comment to origin/main (cloudv2 PR #27510 merged) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
micheleRP
approved these changes
Jun 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add a top-level Use the ADP CLI section (beta) with two pages, wire them into the nav, and bring every
rpk aimention in the docs in line with the self-contained CLI auth model:modules/cli/pages/index.adoc) — whatrpk aiis, how to install it, how to sign in and select an ADP environment, the resource command surface, and output formats.modules/cli/pages/gitops.adoc) — therpk ai <resource> apply/diffworkflow.It also corrects the existing
gateway:connect-agent.adocrpk aiwalkthrough and the stray "authentication is owned byrpk cloud login" claims in the gateway overview, the rpk reference index, and the Connect test-tools/create-server pages.Why
The
rpk aiCLI can manage every ADP resource declaratively from YAML manifests, but the docs only shipped the autogenerated command reference. Operators automating ADP in Git and CI had no guide for the apply/diff workflow, its reconcile semantics, or drift gating. GitOps is a first-class CLI workflow and belongs in a guide section distinct from the command reference.cloudv2 PR #27510 also changed how the CLI authenticates.
rpk aiis now self-contained: it signs in with its own OAuth device flow (rpk ai auth login) and selects an ADP environment (rpk ai env), independent of therpk cloudsession. The docs described the old coupling ("reuses the rpk cloud login token") and a non-existentRPAI_ENDPOINTenv override, both of which are now wrong.Implementation details
New module
modules/cli, both pages marked:page-beta:because the ADP CLI and GitOps are beta.rpk ai install) and connect:rpk ai auth loginruns the device flow and caches credentials in~/.rpai/credentials, thenrpk ai env list/use/showselects an ADP environment whose AI Gateway becomes the active target.--rpai-endpointis the one-off endpoint override; it is deliberately not bound to an environment variable.diffexits non-zero on drift for CI gating. It coversllm,mcp,oauth,oauth-client, andagent, with an exported manifest example, a worked apply/diff cycle, and troubleshooting.connect-agent.adoc,gateway/overview.adoc,reference/rpk/index.adoc,connect/test-tools.adoc, andconnect/create-server.adocdrop therpk cloud logincoupling and point atrpk ai auth login.nav.adoc: the section sits between Routing & LLM Settings and Reference.Preview pages
References
rpk aicommand reference:reference:rpk/rpk-ai/rpk-ai.adocgateway:connect-agent.adoc