feat(DOC-1970): add missing rpk connect reference pages#1608
Conversation
Adds documentation for three rpk connect commands missing from the reference: - rpk connect agent (+ agent init, agent run subcommands) — EXPERIMENTAL - rpk connect dry-run - rpk connect plugin (+ plugin init subcommand) — EXPERIMENTAL Updates nav.adoc to include the new pages in alphabetical order. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis pull request adds documentation for new rpk connect subcommands, introducing six new AsciiDoc documentation pages for agent, agent-init, agent-run, dry-run, plugin, and plugin-init commands. The navigation structure in nav.adoc is updated to include these new command entries under a reorganized hierarchy. Previous mcp-server entries are removed from the navigation. Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc (1)
17-17: Use empty brackets in xref to auto-pull the target page title.The xref link includes hard-coded link text
[init]. Per repository conventions, use empty brackets[]to automatically pull the title from the referenced document.📝 Suggested change
-* xref:rpk/rpk-connect/rpk-connect-plugin-init.adoc[init]: Create the boilerplate for a custom component plugin. +* xref:rpk/rpk-connect/rpk-connect-plugin-init.adoc[]: Create the boilerplate for a custom component plugin.Based on learnings: "AsciiDoc linking: prefer using xref links with empty brackets (e.g., xref:section/target.adoc[]) because the title is pulled from the referenced document automatically."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc` at line 17, Replace the hard-coded xref text `[init]` with empty brackets `[]` so the link auto-pulls the target page title; update the xref in the rpk-connect-plugin.adoc line referencing rpk-connect-plugin-init.adoc (xref:rpk/rpk-connect/rpk-connect-plugin-init.adoc[]).modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc (2)
17-18: Use empty brackets in xrefs to auto-pull target page titles.The xref links include hard-coded link text. Per repository conventions, use empty brackets
[]to automatically pull titles from the referenced documents.📝 Suggested change
-* xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[init]: Initialize a Redpanda Connect agent. -* xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[run]: Execute a Redpanda Connect agent as part of a pipeline with MCP tool access. +* xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[]: Initialize a Redpanda Connect agent. +* xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[]: Execute a Redpanda Connect agent as part of a pipeline with MCP tool access.Based on learnings: "AsciiDoc linking: prefer using xref links with empty brackets (e.g., xref:section/target.adoc[]) because the title is pulled from the referenced document automatically."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc` around lines 17 - 18, Replace the hard-coded xref link text in rpk-connect-agent.adoc so titles are auto-pulled: change xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[init] to xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[] and xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[run] to xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[] (update the two xref usages shown in the diff).
1-29: Consider updating the parent page to list subcommands.The parent page
rpk-connect.adoc(referenced in context) lacks a "Subcommands" or "Commands" section that would enumerate available subcommands likeagent,dry-run, andplugin. While navigation provides access, including a subcommands section on the parent page would improve discoverability for users.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc` around lines 1 - 29, Parent page rpk-connect.adoc is missing a "Subcommands" section to list available subcommands (agent, dry-run, plugin); add a Subcommands or Commands section to rpk-connect.adoc that enumerates each subcommand with short descriptions and xref links (e.g., xref:rpk/rpk-connect/rpk-connect-agent.adoc[rpk connect agent], xref:rpk/rpk-connect/rpk-connect-dry-run.adoc[rpk connect dry-run], xref:rpk/rpk-connect/rpk-connect-plugin.adoc[rpk connect plugin]) so users can discover and navigate to the specific pages directly from the parent page.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc`:
- Around line 17-18: Replace the hard-coded xref link text in
rpk-connect-agent.adoc so titles are auto-pulled: change
xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[init] to
xref:rpk/rpk-connect/rpk-connect-agent-init.adoc[] and
xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[run] to
xref:rpk/rpk-connect/rpk-connect-agent-run.adoc[] (update the two xref usages
shown in the diff).
- Around line 1-29: Parent page rpk-connect.adoc is missing a "Subcommands"
section to list available subcommands (agent, dry-run, plugin); add a
Subcommands or Commands section to rpk-connect.adoc that enumerates each
subcommand with short descriptions and xref links (e.g.,
xref:rpk/rpk-connect/rpk-connect-agent.adoc[rpk connect agent],
xref:rpk/rpk-connect/rpk-connect-dry-run.adoc[rpk connect dry-run],
xref:rpk/rpk-connect/rpk-connect-plugin.adoc[rpk connect plugin]) so users can
discover and navigate to the specific pages directly from the parent page.
In `@modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc`:
- Line 17: Replace the hard-coded xref text `[init]` with empty brackets `[]` so
the link auto-pulls the target page title; update the xref in the
rpk-connect-plugin.adoc line referencing rpk-connect-plugin-init.adoc
(xref:rpk/rpk-connect/rpk-connect-plugin-init.adoc[]).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 12e93d25-7268-40ea-a8ff-661e4098ed7e
📒 Files selected for processing (7)
modules/ROOT/nav.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-agent-init.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-agent-run.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-dry-run.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-plugin-init.adocmodules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc
|
lgtm |
…le-plugin Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
@mmatczuk — gentle nudge on this one when you have a chance. Adds the missing |
kbatuigas
left a comment
kbatuigas
left a comment
There was a problem hiding this comment.
Changes required to xrefs
| | --help, -h | ||
| | Show help for the command. | ||
|
|
||
| 4+h| Linux only |
There was a problem hiding this comment.
Please double check what this is for, it's currently not being rendered: https://deploy-preview-1608--redpanda-docs-preview.netlify.app/current/reference/rpk/rpk-connect/rpk-connect-agent-run/#options If it's meant to indicate that the following options are for Linux only, we should just indicate that in the individual description cells and remove this row altogether.
…ence pages - Add reference: module prefix to xrefs in agent and plugin pages - Add :page-topic-type: reference to all new pages - Rephrase rpk connect agent run description per review suggestion - Remove non-rendering 4+h| Linux only header row; add (Linux only) qualifier inline to --chroot and --chroot-passthrough descriptions - Rename --secrets option cell from --secrets env: to --secrets - Add --secrets none: usage example to agent run and dry-run - Rename foo.yaml to pipeline.yaml in dry-run example - Lowercase "license" in --redpanda-license description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add subcommand names [init] and [run] to xref links for better clarity - Improve description clarity in rpk-connect-agent-run.adoc Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add learning objectives metadata to all pages - Add learning objectives display sections - Fix passive voice in dry-run and plugin-init pages - Rename Options to Flags for consistency with other rpk connect pages - Fix MCP acronym order (spell out first, then acronym) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
mfernest is no longer at the company; @Feediver1 (Joyce) is taking over to land this PR. Two outstanding items from the prior review pass: 1. Add --resources, -r to rpk-connect-streams.adoc flag table. Ben Barkhouse's original Slack report (cited in DOC-1970) called out this missing flag specifically. Sibling pages rpk-connect-lint.adoc and rpk-connect-run.adoc both already document --resources, -r; the flag is supported on streams mode too. Inserted in alphabetical order between --prefix-stream-endpoints and --help, -h, with the imperative-voice wording that matches the rest of the streams flag table. This closes Ben's first reported gap (the -o flag, his second concern, was already fixed in PR #598). 2. Restore the word 'first' to the rpk-connect-agent-run.adoc description, per @kbatuigas's suggestion in the original review. The 'first ... then' pair makes the sequence (read resource definitions, then run the agent) explicit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
PR Review: feat(DOC-1970): add missing rpk connect reference pages (#1608)
Files reviewed: 7 files (278 additions / 3 deletions) + follow-up commit 194db353 for review feedback (3 additions / 1 deletion across 2 files)
Overall assessment: Closes the bulk of the DOC-1970 audit (three previously-missing top-level commands). Ben Barkhouse's specific --resources, -r complaint on Streams mode is now also addressed in the follow-up commit. All of @kbatuigas's earlier review concerns appear to be in the current state. Ready to land after @kbatuigas refreshes her stale CHANGES_REQUESTED and @mmatczuk confirms the new flag on streams (see Critical #1 below).
Note: mfernest is no longer at the company. @Feediver1 (Joyce) has taken over to land the open items from the prior review pass — commit
194db353carries the follow-up changes.
What this PR does
Adds reference pages for three rpk connect commands that were missing from the docs:
rpk connect agent+agent init+agent runsubcommands — marked experimental (3 pages, 137 lines).rpk connect dry-run— parses configs and tests connections (1 page, 52 lines).rpk connect plugin+plugin initsubcommand — marked experimental (2 pages, 80 lines).
Plus the nav.adoc updates to surface the six new entries alphabetically alongside existing rpk connect entries.
The follow-up commit 194db353 also:
- Adds
--resources, -rtorpk-connect-streams.adoc(fixes Ben's specific complaint from the DOC-1970 ticket). - Restores the word "first" to the
rpk-connect-agent-run.adocdescription (per @kbatuigas's earlier suggestion).
Jira ticket alignment
Ticket: DOC-1970 — rpk connect reference is missing some flags (Support escalation, originally reported by Ben Barkhouse in Slack).
Breakdown of the ticket's three asks against the current PR state:
| Ticket item | Status |
|---|---|
"Missing -r flag for resource file in Streams mode" (Ben's specific report) |
✅ Fixed in commit 194db353. --resources, -r row added to rpk-connect-streams.adoc:48. |
"Missing -o flag for observability file" (Ben's specific report) |
✅ Already fixed in an earlier PR (#598 / commit 12df4eeb). --observability, -o is present at rpk-connect-streams.adoc:44. |
| "Missing a lot more than just the reported flags … revisit the rpk connect reference" (broader scope) | ✅ Adds three previously-missing top-level commands (agent, dry-run, plugin) plus three subcommands. |
DOC-1970 is now substantively closed.
Suggestions (should consider)
None of substance. The two minor items I'd have raised (the "first" word in agent-run description; the --resources flag I just added) are now in the follow-up commit.
Impact on other files
modules/ROOT/nav.adoc✓ — six new entries added under therpk connectgroup; verified alphabetical placement.- No What's New entry needed — backfilling reference documentation, not a user-visible feature.
- Cross-references verified: All xrefs in the new pages (the
agentandpluginparents linking to theirinit/runchildren) resolve to sibling files within this PR. - No cross-repo / single-source impact — all changes are in
modules/reference/pages/rpk/and the nav, neither single-sourced into cloud-docs.
Outstanding review activity — status
-
@mmatczuk APPROVED on 2026-03-20. ✓ (Note: that approval predates the streams.adoc flag addition in
194db353— see Critical #1 above.) -
@kbatuigas CHANGES_REQUESTED on 2026-03-20 with 13 inline suggestions. I cross-checked every one against the current PR-branch content — all 13 are addressed:
@kbatuigas suggestion Resolution Add :page-topic-type: referenceto new pages✓ All six new pages have it Rephrase agent-run description for clarity ✓ Reworded close to her version; 194db353restores "first" per her exact wordingRemove non-rendering Linux-only chroot header row ✓ Removed; "(Linux only)" inlined into each affected flag's description (Linux only) Chroot into…and(Linux only) Specify additional files…wording✓ Both match her suggestions exactly Bracketed link text for subcommand xrefs ( [init],[run])✓ Match exactly Rename the fooyaml to descriptive name✓ Now pipeline.yamlAdd explicit --secrets none:usage example✓ Added to agent-run.adocanddry-run.adocTighten --redpanda-licensedescription✓ Matches her suggested wording Plugin-init xref link text ✓ Matches @kbatuigas — would you take another look and dismiss/refresh given everything's been addressed?
-
@JakeSCahill APPROVED on 2026-03-31. ✓
CodeRabbit findings worth considering
CodeRabbit posted a "Nitpick (3)" review on 2026-03-16. The only substantive item suggested empty [] xref brackets to auto-pull target page titles. @kbatuigas's review then preferred explicit bracketed text ([init], [run]), which is now applied throughout. The team convention favors explicit subcommand text for these short references, and that's the convention this PR follows. No CodeRabbit findings to incorporate.
What works well
- Closes the bulk of the audit. Three previously-missing top-level commands (
agent,dry-run,plugin) now have reference pages — a real, durable improvement to the rpk connect documentation surface. - Strong response to review. @kbatuigas left 13 specific inline suggestions; mfernest landed essentially all of them in follow-up commits. The cross-check above is one-to-one. Two minor remaining items are in
194db353. :page-topic-type: referenceon every new page. @kbatuigas flagged this as a small tech-debt cleanup the team's been wanting — these six pages now set the right example.- IMPORTANT admonitions for experimental commands. Both
agentandpluginare marked experimental on their parent and child pages — that's the right pattern for in-flight features. Readers won't accidentally build production workflows on top of unstable surface area. - Worked examples include the disable-secret-lookup case for
agent runanddry-run(@kbatuigas's suggestion). Concrete, non-obvious example readers actually want. - Consistent table styling (
[cols="1m,2a"]) and consistent| Option | Descriptionheader across all six new pages. - Two SME approvals (@mmatczuk engineer, @JakeSCahill docs) plus follow-up review feedback addressed.
- CI fully green on the pre-
194db353state; the new commit's CI will run shortly.
Final-pass review via /docs-team-standards:pr-review. Critical fix and the Kat-suggested "first" addition are in commit 194db353 (pushed to this branch).
The PR branch was opened against main when main was at version 25.3.
Since then, main has bumped to version 26.1 and the team has cut a
separate v/25.3 branch to hold frozen 25.3 documentation. The PR
branch had not been brought current with main's antora.yml, so it
still declared version: 25.3 — colliding with the v/25.3 branch.
Antora's playbook saw two ROOT components both claiming version 25.3
and produced a fatal duplicate-nav error:
FATAL (antora): Duplicate nav in 25.3@ROOT: modules/ROOT/nav.adoc
1: /opt/build/repo/modules/ROOT/nav.adoc in /opt/build/repo (branch: HEAD <worktree>)
2: modules/ROOT/nav.adoc in https://github.com/redpanda-data/docs (branch: v/25.3)
Take main's antora.yml verbatim (this PR doesn't intentionally edit
antora.yml). The PR's other changes — six new rpk-connect reference
pages, nav.adoc updates, and the recent --resources/--first follow-ups
— are version-neutral and apply correctly under 26.1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 participants
Fixes https://redpandadata.atlassian.net/browse/DOC-1970
Summary
Adds documentation for three
rpk connectcommands missing from the reference:rpk connect agent(+agent init,agent runsubcommands) — marked EXPERIMENTALrpk connect dry-runrpk connect plugin(+plugin initsubcommand) — marked EXPERIMENTALUpdates
nav.adocto include the new pages in alphabetical order alongside existingrpk connectentries.Test plan
rpk connect🤖 Generated with Claude Code