diff --git a/.github/workflows/update-rpk-docs.yml b/.github/workflows/update-rpk-docs.yml new file mode 100644 index 0000000000..689b283422 --- /dev/null +++ b/.github/workflows/update-rpk-docs.yml @@ -0,0 +1,279 @@ +name: Update rpk Documentation + +on: + workflow_dispatch: + inputs: + version: + description: 'rpk version tag (e.g., v26.2.0, v26.2.0-rc1) or "dev" for latest dev branch. RC versions target beta branch.' + required: true + default: 'dev' + diff_version: + description: 'Previous version for diff (optional, e.g., v26.1.9)' + required: false + draft_missing: + description: 'Generate draft pages for new commands' + required: false + default: 'true' + type: boolean + repository_dispatch: + types: [update-rpk-docs] + +permissions: + contents: write + pull-requests: write + +jobs: + update-rpk-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout docs repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Setup Go + uses: actions/setup-go@v5 + with: + # Must match or exceed the version in redpanda/src/go/rpk/go.mod + # Check with: curl -s https://raw.githubusercontent.com/redpanda-data/redpanda/dev/src/go/rpk/go.mod | grep "^go " + go-version: 'stable' + + - name: Determine version parameters + id: params + env: + EVENT_NAME: ${{ github.event_name }} + DISPATCH_VERSION: ${{ github.event.client_payload.version }} + DISPATCH_DIFF_VERSION: ${{ github.event.client_payload.diff_version }} + DISPATCH_DRAFT_MISSING: ${{ github.event.client_payload.draft_missing }} + INPUT_VERSION: ${{ github.event.inputs.version }} + INPUT_DIFF_VERSION: ${{ github.event.inputs.diff_version }} + INPUT_DRAFT_MISSING: ${{ github.event.inputs.draft_missing }} + run: | + # Handle workflow_dispatch vs repository_dispatch + if [ "$EVENT_NAME" = "repository_dispatch" ]; then + VERSION="${DISPATCH_VERSION:-dev}" + DIFF_VERSION="${DISPATCH_DIFF_VERSION}" + DRAFT_MISSING="${DISPATCH_DRAFT_MISSING:-false}" + else + VERSION="${INPUT_VERSION}" + DIFF_VERSION="${INPUT_DIFF_VERSION}" + DRAFT_MISSING="${INPUT_DRAFT_MISSING}" + fi + + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "diff_version=$DIFF_VERSION" >> $GITHUB_OUTPUT + echo "draft_missing=$DRAFT_MISSING" >> $GITHUB_OUTPUT + + # Detect RC versions (e.g., v26.2.0-rc1, 26.2.0-rc2) + if [[ "$VERSION" =~ -rc[0-9]+$ ]]; then + echo "is_rc=true" >> $GITHUB_OUTPUT + echo "base_branch=beta" >> $GITHUB_OUTPUT + else + echo "is_rc=false" >> $GITHUB_OUTPUT + echo "base_branch=main" >> $GITHUB_OUTPUT + fi + + # Determine branch name + if [ "$VERSION" = "dev" ]; then + echo "branch_name=rpk-docs-dev-$(date +%Y%m%d)" >> $GITHUB_OUTPUT + else + echo "branch_name=rpk-docs-$VERSION" >> $GITHUB_OUTPUT + fi + + - name: Validate RC version against beta branch + if: steps.params.outputs.is_rc == 'true' + run: | + VERSION="${{ steps.params.outputs.version }}" + + # Extract major.minor from version (e.g., v26.2.0-rc1 -> 26.2) + VERSION_MAJOR_MINOR=$(echo "$VERSION" | sed -E 's/^v?([0-9]+\.[0-9]+).*/\1/') + + # Get version from beta branch antora.yml + BETA_VERSION=$(git show origin/beta:antora.yml | grep "^version:" | sed -E "s/^version:[[:space:]]*['\"]?([0-9]+\.[0-9]+)['\"]?.*/\1/") + + echo "RC version major.minor: $VERSION_MAJOR_MINOR" + echo "Beta branch version: $BETA_VERSION" + + if [ "$VERSION_MAJOR_MINOR" != "$BETA_VERSION" ]; then + echo "::error::RC version $VERSION does not match beta branch version $BETA_VERSION" + echo "RC releases must target the current beta version." + exit 1 + fi + + echo "✓ RC version $VERSION matches beta branch version $BETA_VERSION" + + - name: Checkout target branch + run: | + BASE_BRANCH="${{ steps.params.outputs.base_branch }}" + if [ "$BASE_BRANCH" != "main" ]; then + echo "Checking out $BASE_BRANCH branch for RC release" + git checkout "$BASE_BRANCH" + fi + + - name: Build rpk-docs command + id: command + run: | + # Build command - builds rpk from source using Go + CMD="npx doc-tools generate rpk-docs" + + VERSION="${{ steps.params.outputs.version }}" + CMD="$CMD --ref $VERSION" + + DIFF_VERSION="${{ steps.params.outputs.diff_version }}" + if [ -n "$DIFF_VERSION" ]; then + CMD="$CMD --diff $DIFF_VERSION" + fi + + DRAFT_MISSING="${{ steps.params.outputs.draft_missing }}" + if [ "$DRAFT_MISSING" = "true" ]; then + CMD="$CMD --draft-missing" + fi + + # Update what's-new if doing a diff + if [ -n "$DIFF_VERSION" ]; then + CMD="$CMD --update-whats-new" + fi + + CMD="$CMD --output-dir modules/reference/pages/rpk" + echo "cmd=$CMD" >> $GITHUB_OUTPUT + + - name: Run rpk-docs generator + id: generate + run: | + echo "Running: ${{ steps.command.outputs.cmd }}" + ${{ steps.command.outputs.cmd }} 2>&1 | tee generation-output.txt + + # Extract summary for PR description + DIFF_FILE=$(ls -t docs-data/rpk-diff-*.json 2>/dev/null | head -1) + if [ -n "$DIFF_FILE" ]; then + echo "diff_file=$DIFF_FILE" >> $GITHUB_OUTPUT + fi + + - name: Check for changes + id: changes + run: | + git add -A + if git diff --staged --quiet; then + echo "has_changes=false" >> $GITHUB_OUTPUT + else + echo "has_changes=true" >> $GITHUB_OUTPUT + echo "Changed files:" + git diff --staged --name-only | head -20 + fi + + - name: Generate PR description + if: steps.changes.outputs.has_changes == 'true' + id: pr_body + run: | + VERSION="${{ steps.params.outputs.version }}" + DIFF_VERSION="${{ steps.params.outputs.diff_version }}" + + # Start building PR body + cat > pr-body.md << 'HEADER' + ## Summary + + Automated update of rpk CLI documentation. + + HEADER + + # Add version info + if [ "$VERSION" = "dev" ]; then + echo "**Source**: \`dev\` branch (pre-release)" >> pr-body.md + else + echo "**Version**: \`$VERSION\`" >> pr-body.md + fi + + if [ -n "$DIFF_VERSION" ]; then + echo "**Diff against**: \`$DIFF_VERSION\`" >> pr-body.md + fi + + echo "" >> pr-body.md + + # Add diff summary if available + DIFF_FILE="${{ steps.generate.outputs.diff_file }}" + if [ -n "$DIFF_FILE" ] && [ -f "$DIFF_FILE" ]; then + echo "## Changes detected" >> pr-body.md + echo "" >> pr-body.md + + # Extract counts from diff JSON + NEW_CMDS=$(jq -r '.summary.newCommands // 0' "$DIFF_FILE") + REMOVED_CMDS=$(jq -r '.summary.removedCommands // 0' "$DIFF_FILE") + NEW_FLAGS=$(jq -r '.summary.newFlags // 0' "$DIFF_FILE") + REMOVED_FLAGS=$(jq -r '.summary.removedFlags // 0' "$DIFF_FILE") + CHANGED_DEFAULTS=$(jq -r '.summary.changedDefaults // 0' "$DIFF_FILE") + + if [ "$NEW_CMDS" -gt 0 ]; then + echo "- **New commands**: $NEW_CMDS" >> pr-body.md + echo "" >> pr-body.md + jq -r '.details.newCommands[]? | " - \`\(.path)\`"' "$DIFF_FILE" >> pr-body.md 2>/dev/null || true + echo "" >> pr-body.md + fi + + if [ "$REMOVED_CMDS" -gt 0 ]; then + echo "- **Removed commands**: $REMOVED_CMDS" >> pr-body.md + echo "" >> pr-body.md + jq -r '.details.removedCommands[]? | " - \`\(.path)\`"' "$DIFF_FILE" >> pr-body.md 2>/dev/null || true + echo "" >> pr-body.md + fi + + if [ "$NEW_FLAGS" -gt 0 ]; then + echo "- **New flags**: $NEW_FLAGS" >> pr-body.md + fi + + if [ "$REMOVED_FLAGS" -gt 0 ]; then + echo "- **Removed flags**: $REMOVED_FLAGS" >> pr-body.md + fi + + if [ "$CHANGED_DEFAULTS" -gt 0 ]; then + echo "- **Changed defaults**: $CHANGED_DEFAULTS" >> pr-body.md + fi + + echo "" >> pr-body.md + fi + + # Add file change summary + echo "## Files changed" >> pr-body.md + echo "" >> pr-body.md + echo "\`\`\`" >> pr-body.md + git diff --staged --stat | tail -20 >> pr-body.md + echo "\`\`\`" >> pr-body.md + echo "" >> pr-body.md + + # Add footer + cat >> pr-body.md << 'FOOTER' + ## Automation + + Generated by [rpk-docs automation](https://github.com/redpanda-data/docs-extensions-and-macros/tree/main/tools/rpk-docs). + + Review the changes and merge when ready. + FOOTER + + - name: Create Pull Request + if: steps.changes.outputs.has_changes == 'true' + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: ${{ steps.params.outputs.branch_name }} + base: ${{ steps.params.outputs.base_branch }} + title: "docs: update rpk CLI documentation (${{ steps.params.outputs.version }})" + body-path: pr-body.md + commit-message: "docs: update rpk CLI documentation for ${{ steps.params.outputs.version }}" + delete-branch: true + labels: | + documentation + automated + + - name: No changes detected + if: steps.changes.outputs.has_changes == 'false' + run: | + echo "No documentation changes detected for version ${{ steps.params.outputs.version }}" diff --git a/.github/workflows/validate-docs-data.yml b/.github/workflows/validate-docs-data.yml new file mode 100644 index 0000000000..ad8da5c7d7 --- /dev/null +++ b/.github/workflows/validate-docs-data.yml @@ -0,0 +1,71 @@ +--- +name: Validate docs-data files +on: + pull_request: + paths: + - 'docs-data/rpk-overrides.json' + - 'docs-data/rpk-overrides.schema.json' + - 'docs-data/property-overrides.json' + push: + branches: [main] + paths: + - 'docs-data/rpk-overrides.json' + - 'docs-data/rpk-overrides.schema.json' + - 'docs-data/property-overrides.json' + +jobs: + validate-rpk-overrides: + name: Validate rpk-overrides.json + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install AJV CLI + run: npm install -g ajv-cli ajv-formats + + - name: Validate rpk-overrides.json against schema + run: | + echo "Validating docs-data/rpk-overrides.json against docs-data/rpk-overrides.schema.json..." + ajv validate \ + --spec=draft2020 \ + -s docs-data/rpk-overrides.schema.json \ + -d docs-data/rpk-overrides.json \ + -c ajv-formats \ + --strict=false \ + --all-errors + + - name: Schema validation passed + if: success() + run: echo "rpk-overrides.json validates successfully against the schema." + + validate-property-overrides: + name: Validate property-overrides.json + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate property-overrides.json syntax + run: | + echo "Checking docs-data/property-overrides.json is valid JSON..." + if jq empty docs-data/property-overrides.json 2>/dev/null; then + echo "property-overrides.json is valid JSON." + else + echo "::error::property-overrides.json contains invalid JSON syntax" + exit 1 + fi + + - name: Check for required fields + run: | + echo "Checking property-overrides.json structure..." + # Verify it's an object with expected top-level keys + if jq -e 'type == "object"' docs-data/property-overrides.json > /dev/null; then + echo "property-overrides.json has correct structure." + else + echo "::error::property-overrides.json must be a JSON object" + exit 1 + fi diff --git a/docs-data/README.adoc b/docs-data/README.adoc new file mode 100644 index 0000000000..77921ba0ab --- /dev/null +++ b/docs-data/README.adoc @@ -0,0 +1,145 @@ += docs-data directory +:description: Reference for data files used by documentation generation tools, including rpk-overrides.json for rpk command customization and property-overrides.json for configuration property enhancements. +:page-topic-type: reference + +The docs-data directory stores data files that documentation generation tools use to create `rpk` command reference pages and configuration property documentation. Use this reference to identify which files you can edit and which files the tools generate automatically. + +== `rpk` command documentation + +The `rpk` command documentation uses both manually created override files and automatically generated JSON files. You edit override files to add examples, warnings, and editorial enhancements. Generated files track command structures across versions. + +=== Writer-editable files + +[cols="1m,2a"] +|=== +| File | Purpose + +| rpk-overrides.json +| Manual editorial enhancements for `rpk` command documentation. Add examples, warnings, notes, concept sections, and other editorial content. See link:RPK_OVERRIDES_GUIDE.adoc[]. Validated against `rpk-overrides.schema.json` automatically during generation. + +| rpk-overrides.schema.json +| JSON Schema that validates rpk-overrides.json structure. Provides autocomplete and validation in VS Code and other editors. + +| RPK_OVERRIDES_GUIDE.adoc +| Complete guide for using rpk-overrides.json. Documents all content types with examples (sections, examples, admonitions), position reference, and best practices. +|=== + +=== Generated files + +Do not edit these files manually. The documentation tools regenerate them automatically. + +[cols="1m,2a"] +|=== +| File | Purpose + +| rpk-v.json +| Complete `rpk` command tree with overrides applied. Generated by `npx doc-tools generate rpk-docs --tag `. Used for version tracking and diffing between releases. Examples: `rpk-v26.2.0.json`, `rpk-vlocal.json` (local dev builds). + +| rpk-diff-_to_.json +| Detailed diff between two `rpk` versions. Generated with `--diff` flag during generation. Shows new commands, removed commands, and flag changes. Used for creating release notes. +|=== + +== Redpanda property documentation + +=== Writer-editable files + +[cols="1m,2a"] +|=== +| File | Purpose + +| property-overrides.json +| Manual enhancements for Redpanda configuration property descriptions. Replaces auto-generated descriptions with clearer explanations. Adds examples, valid values, and usage notes. Uses `$ref` syntax for reusable property descriptions. +|=== + +=== Generated files + +Do not edit these files manually. The documentation tools regenerate them automatically. + +[cols="1m,2a"] +|=== +| File | Purpose + +| cluster-properties-.json +| All cluster-level configuration properties for a Redpanda version. Extracted from Redpanda C++ source code. + +| topic-properties-.json +| All topic-level configuration properties for a Redpanda version. Extracted from Redpanda C++ source code. + +| redpanda-property-changes--to-.json +| Diff showing property changes between Redpanda versions. Lists new properties, removed properties, and changed defaults. Used for release notes and upgrade guides. +|=== + +== Usage + +=== Generate `rpk` documentation + +Generate documentation for a released version: + +[,bash] +---- +npx doc-tools generate rpk-docs --tag v26.2.0 --fetch-binary +---- + +Generate documentation with diff for release notes: + +[,bash] +---- +npx doc-tools generate rpk-docs --tag v26.2.0 --fetch-binary --diff v26.1.9 +---- + +=== Edit `rpk` editorial content + +. Edit `rpk-overrides.json` to add or modify content. +. Run the generator to validate and regenerate docs: ++ +[,bash] +---- +npx doc-tools generate rpk-docs +---- + +For detailed instructions, see the link:RPK_OVERRIDES_GUIDE.adoc[RPK Overrides Guide]. + +=== Generate property documentation + +Generate documentation for a released version: + +[,bash] +---- +npx doc-tools generate property-docs --tag v26.2.0 +---- + +Generate with AsciiDoc partials for the docs build: + +[,bash] +---- +npx doc-tools generate property-docs --tag v26.2.0 --generate-partials +---- + +=== Edit property descriptions + +. Edit `property-overrides.json` to improve descriptions. +. Use `$ref` syntax to reuse descriptions across properties. +. Regenerate the docs: ++ +[,bash] +---- +npx doc-tools generate property-docs --tag --generate-partials +---- + +The property-overrides.json file uses this structure: + +[,json] +---- +{ + "definitions": { + "reusable-description": "This description can be referenced..." + }, + "overrides": { + "cluster": { + "some_property": { + "description": { "$ref": "#/definitions/reusable-description" } + } + } + } +} +---- diff --git a/docs-data/RPK_OVERRIDES_GUIDE.adoc b/docs-data/RPK_OVERRIDES_GUIDE.adoc new file mode 100644 index 0000000000..9cc4c046ad --- /dev/null +++ b/docs-data/RPK_OVERRIDES_GUIDE.adoc @@ -0,0 +1,515 @@ += Overrides Guide for Redpanda CLI (rpk) +:description: Customize auto-generated rpk command documentation using rpk-overrides.json to add examples, warnings, editorial enhancements, and fix auto-generated content. +:page-topic-type: how-to +:toc: +:toclevels: 3 + +Use `rpk-overrides.json` to customize auto-generated `rpk` documentation. Add examples, warnings, notes, and other editorial enhancements without modifying source code. + +The `rpk` documentation is generated automatically from `rpk --print-tree` command output. The overrides file lets you enhance, customize, and fix auto-generated content. + +== File location + +The overrides file is located at: + +---- +docs-data/rpk-overrides.json +---- + +== Basic structure + +[,json] +---- +{ + "definitions": { + // Reusable content blocks + }, + "textTransformations": { + // Global text transformations + }, + "commands": { + "rpk ": { + // Command-specific overrides + } + } +} +---- + +== Command overrides + +Customize each command by adding an entry under the `commands` key using the full command path (for example, `"rpk topic create"`). + +=== Override description + +Replace the auto-generated description: + +[,json] +---- +"rpk topic create": { + "description": "Create one or more topics.\n\nThis command creates topics with the specified configuration." +} +---- + +=== Append to description + +Add content to the end of the auto-generated description: + +[,json] +---- +"rpk topic create": { + "appendToDescription": "For more details, see the topic configuration guide." +} +---- + +=== Override flag descriptions + +Improve individual flag descriptions: + +[,json] +---- +"rpk topic create": { + "flags": { + "partitions": { + "description": "Number of partitions for the topic. More partitions allow higher throughput but use more resources." + }, + "replication-factor": { + "description": "Number of replicas for each partition. Higher values provide better fault tolerance.", + "introducedInVersion": "v24.1.0" + } + } +} +---- + +Flag override properties: + +* `description` - Replace the flag description +* `type` - Override the flag type +* `default` - Document the default value +* `deprecated` - Mark the flag as deprecated (boolean) +* `deprecatedMessage` - Explain the deprecation +* `introducedInVersion` - Document when the flag was added +* `cloudOnly` - Mark as only available in Redpanda Cloud +* `selfHostedOnly` - Mark as only available in self-hosted deployments + +=== Exclude flags + +Remove flags from documentation: + +[,json] +---- +"rpk topic create": { + "excludeFlags": ["internal-flag", "debug-mode"] +} +---- + +=== Exclude examples + +Filter out specific examples from the source EXAMPLES section. Use regex patterns that match against example descriptions or commands: + +[,json] +---- +"rpk topic trim-prefix": { + "excludeExamples": ["JSON file", "--from-file"] +} +---- + +This filters out any example whose description or command matches any of the patterns (case-insensitive). + +== Content array + +The `content` array provides a flexible way to add various types of content at specific positions in the documentation. + +=== Position options + +Place content at these positions: + +* `after_header` - After the page title +* `after_description` - After the description paragraph +* `after_usage` - After the Usage section +* `after_aliases` - After the Aliases section +* `after_flags` - After the Flags section +* `after_modifiers` - After format modifier sections +* `after_examples` - After the Examples section +* `before_see_also` - Before the See Also section +* `end` - At the end of the page + +=== Include partials + +Include an AsciiDoc partial file: + +[,json] +---- +"rpk topic delete": { + "content": [ + { + "type": "include", + "position": "after_header", + "path": "shared:partial$warning-delete-records.adoc" + } + ] +} +---- + +=== Add notes, warnings, tips + +Add admonitions: + +[,json] +---- +"rpk cluster config set": { + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Changes take effect immediately without requiring a restart." + }, + { + "type": "warning", + "position": "after_flags", + "content": "Modifying cluster configuration can affect all brokers." + } + ] +} +---- + +Supported admonition types: `note`, `warning`, `tip`, `caution`, `important` + +=== Add custom sections + +Add a custom section with AsciiDoc content: + +[,json] +---- +"rpk cluster partitions balancer-status": { + "content": [ + { + "type": "section", + "id": "balancer-status", + "title": "Balancer Status", + "position": "after_flags", + "headingLevel": 2, + "content": "[cols=\"1m,1a\"]\n|===\n|Value |Description\n\n|off |The balancer is disabled.\n|ready |The balancer is active but there is nothing to do.\n|===\n" + } + ] +} +---- + +Section properties: + +* `id` - Unique identifier for the section +* `title` - Section heading text +* `position` - Where to place the section +* `headingLevel` - Heading level (2 = `==`, 3 = `===`) +* `content` - AsciiDoc content + +=== Replace source sections + +To replace content from a source section (like FIELDS, EXAMPLES, NOTES), use a section with the matching `id` and provide new `content`: + +[,json] +---- +"rpk cluster partitions balancer-status": { + "content": [ + { + "type": "section", + "id": "FIELDS", + "content": "Custom replacement content for the FIELDS section." + } + ] +} +---- + +This replaces the auto-generated FIELDS section content with your custom content. + +=== Exclude source sections + +To completely remove a source section: + +[,json] +---- +"rpk some-command": { + "content": [ + { + "type": "section", + "id": "EXAMPLES", + "exclude": true + } + ] +} +---- + +=== Add structured examples + +Add examples with proper formatting: + +[,json] +---- +"rpk topic create": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "items": [ + { + "description": "Create a topic with 3 partitions", + "code": "rpk topic create my-topic -p 3" + }, + { + "description": "Create a topic with custom configuration", + "code": "rpk topic create my-topic -c retention.ms=86400000" + } + ] + } + ] +} +---- + +=== Add examples with output + +Include expected output in examples: + +[,json] +---- +"rpk cluster status": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "items": [ + { + "description": "Check cluster status", + "code": "rpk cluster status", + "output": "CLUSTER\n=======\nredpanda.abc123\n\nBROKERS\n=======\nID HOST PORT\n0* localhost 9092", + "outputLanguage": "bash" + } + ] + } + ] +} +---- + +The `output` field creates a separate code block labeled "Output:" with the `.no-wrap` class for proper formatting. + +=== Add subsections + +Nest content within sections: + +[,json] +---- +"rpk cluster partitions move": { + "content": [ + { + "type": "section", + "id": "partition-format", + "title": "Partition Format", + "position": "after_flags", + "subsections": [ + { + "title": "Basic Format", + "content": "The basic format is `topic/partition:replica1,replica2,replica3`." + }, + { + "title": "With Core Assignment", + "content": "Add core IDs using `broker-core` format: `topic/0:1-0,2-1,3-0`." + } + ] + } + ] +} +---- + +== Platform restrictions + +Mark commands as platform-specific: + +[,json] +---- +"rpk redpanda tune": { + "platforms": ["linux"] +} +---- + +Valid platforms: `linux`, `darwin`, `windows` + +== Deprecation + +Mark commands as deprecated: + +[,json] +---- +"rpk old-command": { + "deprecated": true, + "deprecatedMessage": "Use 'rpk new-command' instead.", + "deprecatedInVersion": "v24.1.0", + "removedInVersion": "v25.1.0", + "replacement": "xref:rpk-new-command.adoc[rpk new-command]" +} +---- + +== Version information + +Document when features were introduced: + +[,json] +---- +"rpk connect run": { + "introducedInVersion": "v23.1.0" +} +---- + +== See also links + +Add cross-references to related pages: + +[,json] +---- +"rpk topic create": { + "seeAlso": [ + "xref:reference:rpk/rpk-topic/rpk-topic-delete.adoc[rpk topic delete]", + "xref:manage:cluster-maintenance/manage-topics.adoc[Manage Topics]" + ] +} +---- + +== Reusable definitions + +Define reusable content blocks: + +[,json] +---- +{ + "definitions": { + "tls-flags": { + "tls-enabled": { + "description": "Enable TLS for connections." + }, + "tls-cert": { + "description": "Path to the TLS certificate file." + } + } + }, + "commands": { + "rpk topic create": { + "$refs": ["#/definitions/tls-flags"] + } + } +} +---- + +== Text transformations + +Define global text transformations: + +[,json] +---- +{ + "textTransformations": { + "inlineCode": [ + { + "pattern": "(? `cmd -f rest`)", + "pattern": "`([^`\\n]+)\\s+`(-[a-zA-Z])`\\s+([^`\\n]+)`", + "replacement": "`$1 $2 $3`", + "flags": "g" + }, + { + "description": "Merge broken inline code spans with embedded long flags (e.g., `cmd `--flag` rest` -> `cmd --flag rest`)", + "pattern": "`([^`\\n]+)\\s+`(--[a-z][-a-z0-9]*)`\\s+([^`\\n]+)`", + "replacement": "`$1 $2 $3`", + "flags": "g" + }, + { + "description": "Convert double-quoted rpk commands (with arguments and flags) to inline code", + "pattern": "\"(rpk\\s+[^\"]+)\"", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Convert shell comment headers (# Word:) to bold text to prevent AsciiDoc header interpretation", + "pattern": "^# ([A-Za-z]+):$", + "replacement": "**$1:**", + "flags": "gm" + }, + { + "description": "Convert 'Note:' to 'NOTE:' (admonition)", + "pattern": "(^|\\n\\s*)Note:\\s", + "replacement": "$1NOTE: ", + "flags": "g" + }, + { + "description": "Convert 'Tip:' to 'TIP:' (admonition)", + "pattern": "(^|\\n\\s*)Tip:\\s", + "replacement": "$1TIP: ", + "flags": "g" + }, + { + "description": "Convert 'Important:' to 'IMPORTANT:' (admonition)", + "pattern": "(^|\\n\\s*)Important:\\s", + "replacement": "$1IMPORTANT: ", + "flags": "g" + }, + { + "description": "Convert 'Warning:' to 'WARNING:' (admonition)", + "pattern": "(^|\\n\\s*)Warning:\\s", + "replacement": "$1WARNING: ", + "flags": "g" + }, + { + "description": "Convert 'Caution:' to 'CAUTION:' (admonition)", + "pattern": "(^|\\n\\s*)Caution:\\s", + "replacement": "$1CAUTION: ", + "flags": "g" + }, + { + "description": "Fix duplicate NOTE admonition prefix from source", + "pattern": "NOTE: NOTE: ", + "replacement": "NOTE: ", + "flags": "g" + }, + { + "description": "Fix duplicate WARNING admonition prefix from source", + "pattern": "WARNING: WARNING: ", + "replacement": "WARNING: ", + "flags": "g" + }, + { + "description": "Convert single-quoted file paths to backticks", + "pattern": "'(\\/[^']+\\.(?:yaml|license|json|conf|log|txt))'", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Convert single-quoted rpk commands to backticks", + "pattern": "'(rpk\\s+[^']+)'", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Fix already-backticked rpk inside quotes", + "pattern": "'`rpk`\\s+([^']+)'", + "replacement": "`rpk $1`", + "flags": "g" + }, + { + "description": "Convert single-quoted short flags to backticks", + "pattern": "'(-[A-Za-z](?:\\s+\\w+)?)'", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Convert single-quoted long flags to backticks", + "pattern": "'(--[a-z][-a-z0-9]*(?:\\s+\\w+)?)'", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Wrap rpk command before [args] in backticks", + "pattern": "(?", + "pattern": "\\[([A-Z][-A-Z0-9]*(?:\\.\\.\\.)?)\\]", + "replacement": "<$1>", + "flags": "g" + }, + { + "description": "Remove redundant double quotes around backticked content", + "pattern": "\"`([^`\"]+)`\"", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Convert double-quoted subcommand names to backticks (1-3 word commands only)", + "pattern": "\"([a-z][-a-z0-9]+(?: [a-z][-a-z0-9]+){0,2})\"", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Wrap single option in parens with backticks", + "pattern": "\\(([a-z][a-z0-9_-]*)\\)", + "replacement": "(`$1`)", + "flags": "g" + }, + { + "description": "Wrap first option in comma-separated list with backticks", + "pattern": "\\(([a-z][a-z0-9_-]*)(?=,)", + "replacement": "(`$1`", + "flags": "g" + }, + { + "description": "Wrap middle options in comma-separated list with backticks", + "pattern": "(?<=,)([a-z][a-z0-9_-]*)(?=,)", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Wrap last option in comma-separated list with backticks", + "pattern": "(?<=,)([a-z][a-z0-9_-]*)(?=\\))", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Ensure blank line before bullet lists", + "pattern": "([^\n])\n([-*] )", + "replacement": "$1\n\n$2", + "flags": "g" + }, + { + "description": "Wrap simple lowercase list items in backticks", + "pattern": "^([-*] )([a-z][a-z0-9_-]+)$", + "replacement": "$1`$2`", + "flags": "gm" + }, + { + "description": "Wrap rpk commands in xref link text with backticks", + "pattern": "\\[(rpk [^\\]]+)\\]", + "replacement": "[`$1`]", + "flags": "g" + }, + { + "description": "Convert double-quoted commands to backticks", + "pattern": "\"(type [^\"]+)\"", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Convert double-quoted shell commands to backticks", + "pattern": "\"((?:source|echo|command|type) [^\"]+)\"", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Wrap .rpk- plugin names in backticks", + "pattern": "(?][a-z0-9-<>]*)", + "replacement": "`$1`", + "flags": "g" + }, + { + "description": "Wrap standalone .rpk- prefix in backticks", + "pattern": "(?iIqQc.$]} |The unpack modifier has a further internal specification, similar to timestamps above.\n|===\n\nUnpacking text can allow translating binary input into readable output. If a value is a big-endian uint32, `%v` prints the raw four bytes, while `%v{unpack[>I]}` prints the number as ASCII. If unpacking exhausts the input before something is unpacked fully, an error message is appended to the output." + }, + { + "type": "section", + "id": "headers", + "title": "Headers", + "position": "after_usage", + "parent": "usage", + "headingLevel": 3, + "content": "Headers are formatted with percent encoding inside of the modifier:\n\n[,bash]\n----\n%h{%k=%v{hex}}\n----\n\nThis prints all headers with a space before the key and after the value, an equals sign between the key and value, and with the value hex encoded. Header formatting actually just parses the internal format as a record format, so all of the above rules about `%K`, `%V`, text, and numbers apply." + }, + { + "type": "section", + "id": "values", + "title": "Values", + "position": "after_usage", + "parent": "usage", + "headingLevel": 3, + "content": "Values for consumed records can be omitted by using the `--meta-only` flag.\n\nTombstone records (records with a `null` value) have their value omitted from the JSON output by default. All other records, including those with an empty-string value (`\"\"`), have their values printed." + }, + { + "type": "section", + "id": "offsets", + "title": "Offsets", + "position": "after_usage", + "parent": "usage", + "headingLevel": 3, + "content": "The `--offset` flag allows for specifying where to begin consuming, and optionally, where to stop consuming. The literal words `start` and `end` specify consuming from the start and the end.\n\n[cols=\"1m,2a\"]\n|===\n|Offset |Description\n\n|start |Consume from the beginning\n|end |Consume from the end\n|:end |Consume until the current end\n|+oo |Consume oo after the current start offset\n|-oo |Consume oo before the current end offset\n|oo |Consume after an exact offset\n|oo: |Alias for oo\n|:oo |Consume until an exact offset\n|o1:o2 |Consume from exact offset o1 until exact offset o2\n|@t |Consume starting from a given timestamp\n|@t: |Alias for @t\n|@:t |Consume until a given timestamp\n|@t1:t2 |Consume from timestamp t1 until timestamp t2\n|===\n\nEach timestamp option is evaluated until one succeeds.\n\n[cols=\"1m,2a\"]\n|===\n|Timestamp |Description\n\n|13 digits |Parsed as a unix millisecond\n|9 digits |Parsed as a unix second\n|YYYY-MM-DD |Parsed as a day, UTC\n|YYYY-MM-DDTHH:MM:SSZ |Parsed as RFC3339, UTC; fractional seconds optional (.MMM)\n|-dur |Duration; from now (as t1) or from t1 (as t2)\n|dur |For t2 in @t1:t2, relative duration from t1\n|end |For t2 in @t1:t2, the current end of the partition\n|===\n\nDurations are parsed simply:\n\n[,bash]\n----\n3ms three milliseconds\n10s ten seconds\n9m nine minutes\n1h one hour\n1m3ms one minute and three milliseconds\n----" + }, + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Format examples", + "items": [ + { + "description": "A key and value, separated by a space and ending in newline", + "code": "rpk topic consume my-topic -f '%k %v\\n'" + }, + { + "description": "A key length as four big endian bytes and the key as hex", + "code": "rpk topic consume my-topic -f '%K{big32}%k{hex}'" + }, + { + "description": "A little endian uint32 and a string unpacked from a value", + "code": "rpk topic consume my-topic -f '%v{unpack[is$]}'" + } + ] + }, + { + "title": "Offset examples", + "items": [ + { + "description": "Consume 1 hour of data on Valentine's Day 2022", + "code": "rpk topic consume my-topic -o @2022-02-14:1h" + }, + { + "description": "Consume from 2 days ago to 1 day ago", + "code": "rpk topic consume my-topic -o @-48h:-24h" + }, + { + "description": "Consume from 1 minute ago until now", + "code": "rpk topic consume my-topic -o @-1m:end" + }, + { + "description": "Consume from the start until an hour ago", + "code": "rpk topic consume my-topic -o @:-1hr" + } + ] + } + ] + } + ] + }, + "rpk cluster": { + "description": "Manage and inspect Redpanda cluster configuration, health, and maintenance operations.", + "$refs": [ + "#/definitions/common-admin-flags" + ] + }, + "rpk cluster config": { + "description": "View and modify cluster-wide configuration properties. Changes take effect across all brokers.", + "$refs": [ + "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "Cluster properties are Redpanda settings that apply to all brokers in\nthe cluster." + }, + { + "type": "self-hosted", + "position": "after_description", + "content": "Cluster properties are Redpanda settings that apply to all brokers in\nthe cluster. These are separate from broker properties, which apply to only that broker and are set with\n`rpk redpanda config`.\n\nUse the `edit` subcommand to interactively modify the cluster configuration, or\n`export` and `import` to write the configuration to a file that can be edited and\nread back later.\n\nThese commands take an optional `--all` flag to include all properties such as\nlow-level tunables (for example, internal buffer sizes) that do not usually need\nto be changed during normal operations. These properties generally require\nsome expertise to set safely, so if in doubt, avoid using `--all`." + } + ] + }, + "rpk cluster storage": { + "description": "Manage cluster storage, including mounting and unmounting topics from Tiered Storage.", + "$refs": [ + "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "cloud-only", + "position": "after_header", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + } + ] + }, + "rpk cluster storage mount": { + "description": "Mount a topic from Tiered Storage, making it available for reads.", + "$refs": [ + "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "xref:manage:tiered-storage.adoc#enable-tiered-storage[Tiered Storage must be enabled]." + }, + { + "type": "cloud-only", + "position": "after_header", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Mounts topic `` from Tiered Storage to the cluster in the ``", + "code": "rpk cluster storage mount " + }, + { + "description": "Mount topic `` from Tiered Storage to the cluster in the `` with `` as the new topic name", + "code": "rpk cluster storage mount / --to /" + } + ] + } + ] + }, + "rpk cluster storage unmount": { + "description": "Unmount a topic, removing it from local storage while preserving data in Tiered Storage.", + "$refs": [ + "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "cloud-only", + "position": "after_header", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Unmount topic '' from the cluster in the ''", + "code": "rpk cluster storage unmount /" + } + ] + } + ] + }, + "rpk cluster storage cancel-mount": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Cancel a mount/unmount operation", + "code": "rpk cluster storage cancel-mount 123" + } + ] + } + ] + }, + "rpk cluster storage list-mountable": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "List all mountable topics", + "code": "rpk cluster storage list-mountable" + } + ] + } + ] + }, + "rpk cluster storage list-mount": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Lists mount/unmount operations", + "code": "rpk cluster storage list-mount" + }, + { + "description": "Use a filter to list only migrations in a specific state", + "code": "rpk cluster storage list-mount --filter planned" + } + ] + } + ] + }, + "rpk cluster storage status-mount": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Status for a mount/unmount operation", + "code": "rpk cluster storage status-mount 123" + } + ] + } + ] + }, + "rpk group": { + "description": "Manage Kafka consumer groups, including listing groups, viewing lag, and resetting offsets.", + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "pageAliases": "reference:rpk/rpk-group.adoc" + }, + "rpk group describe": { + "description": "Display detailed information about a consumer group, including member assignments, lag per partition, and group state.", + "flags": { + "lag": { + "description": "Show consumer lag information: current offset, log end offset, and lag per partition." + } + }, + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Describe groups `` and ``", + "code": "rpk group describe " + }, + { + "description": "Describe any group starting with f and ending in r", + "code": "rpk group describe -r '^f.*' '.*r$'" + }, + { + "description": "Describe all groups", + "code": "rpk group describe -r '*'" + }, + { + "description": "Describe any one-character group", + "code": "rpk group describe -r ." + } + ] + } + ] + }, + "rpk connect": { + "description": "Run and manage Redpanda Connect streaming pipelines. Redpanda Connect is a high-performance stream processor for mundane data engineering tasks.", + "flags": {} + }, + "rpk connect run": { + "description": "Run a Redpanda Connect pipeline from a configuration file. The pipeline streams data between inputs and outputs with optional processing.", + "flags": { + "log.level": { + "description": "Logging level: `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`. Default is `INFO`." + }, + "set": { + "description": "Override a configuration field. Format: `path=value`. Can be used multiple times." + }, + "resources": { + "description": "Additional resource configuration files containing caches, rate limits, or other shared components." + } + } + }, + "rpk connect lint": { + "description": "Check a Redpanda Connect configuration file for syntax errors and potential issues without running it.", + "flags": {}, + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Lint a specific file", + "code": "rpk connect lint target.yaml" + }, + { + "description": "Lint all YAML files in a directory", + "code": "rpk connect lint ./configs/*.yaml" + }, + { + "description": "Lint with resource imports", + "code": "rpk connect lint -r ./foo.yaml ./bar.yaml" + }, + { + "description": "Lint all files in a directory tree", + "code": "rpk connect lint ./configs/..." + } + ] + } + ] + }, + "rpk connect test": { + "description": "Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior.", + "flags": {}, + "seeAlso": [ + "xref:connect:configuration:unit_testing.adoc[Unit Testing]" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect test ./path/to/configs/..." + }, + { + "description": "Example", + "code": "rpk connect test ./foo_configs/*.yaml ./bar_configs/*.yaml" + }, + { + "description": "Example", + "code": "rpk connect test ./foo.yaml" + } + ] + } + ] + }, + "rpk profile": { + "description": "Manage rpk configuration profiles. Profiles store connection settings for different clusters, making it easy to switch between environments.", + "flags": {}, + "pageAliases": "reference:rpk/rpk-profile.adoc" + }, + "rpk profile create": { + "description": "Create a new rpk profile with connection settings for a Redpanda cluster.", + "appendToDescription": "There are multiple ways to create a profile. A name must be provided if not using `--from-cloud` or `--from-rpk-container`.\n\n* You can use `--from-redpanda` to generate a new profile from an existing `redpanda.yaml` file. The special value `current` creates a profile from the current `redpanda.yaml` as it is loaded within `rpk`.\n* You can use `--from-rpk-container` to generate a profile from an existing cluster created using `rpk container start` command. The name is not needed when using this flag.\n* You can use `--from-profile` to generate a profile from an existing profile or from a profile in a yaml file. First, the filename is checked, then an existing profile name is checked. The special value `current` creates a new profile from the existing profile with any active environment variables or flags applied.\n* You can use `--from-cloud` to generate a profile from an existing cloud cluster ID. Note that you must be logged in with `rpk cloud login` first. The special value `prompt` will prompt to select a cloud cluster to create a profile for.\n* For serverless clusters that support both public and private networking, you will be prompted to select a network type unless you specify `--serverless-network`. To avoid prompts in automation, explicitly set `--serverless-network` to `public` or `private`.\n* You can use `--set key=value` to directly set fields. The key can either be the name of a `-X` flag or the path to the field in the profile's YAML format. For example, using `--set tls.enabled=true` OR `--set kafka_api.tls.enabled=true` is equivalent.\n\nThe `--set` flag is always applied last and can be used to set additional fields in tandem with `--from-redpanda` or `--from-cloud`.\n\nThe `--set` flag supports autocompletion, suggesting the `-X` key format. If you begin writing a YAML path, the flag will suggest the rest of the path.\n\nIt is recommended to always use the `--description` flag; the description is printed in the output of xref:reference:rpk/rpk-profile/rpk-profile-list.adoc[`rpk profile list`].\n\nOnce the command completes successfully, `rpk` switches to the newly created profile.", + "flags": { + "set": { + "description": "Set a profile configuration field. Format: `key=value`. Common fields: `brokers`, `admin_api.addresses`, `tls.enabled`." + }, + "from-cloud": { + "description": "Create profile from Redpanda Cloud cluster. Automatically configures authentication and connection settings." + } + }, + "seeAlso": [ + "xref:reference:rpk/rpk-profile/rpk-profile-list.adoc[`rpk profile list`]" + ] + }, + "rpk profile set": { + "description": "Set a configuration field in the current rpk profile.", + "content": [ + { + "type": "include", + "position": "after_flags", + "path": "shared:partial$rpk-profile-sec-notice.adoc" + } + ] + }, + "rpk profile use": { + "description": "Switch to a different rpk profile, making it the active profile for subsequent rpk commands.", + "flags": {} + }, + "rpk security acl": { + "description": "Manage Kafka ACLs (Access Control Lists) for authorization. ACLs control which principals can perform operations on resources.", + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "content": [ + { + "type": "include", + "position": "after_description", + "path": "shared:partial$rpk-acl-tip.adoc" + } + ], + "pageAliases": "reference:rpk/rpk-acl.adoc, reference:rpk/rpk-acl/rpk-acl.adoc" + }, + "rpk security acl create": { + "description": "Create ACLs. Following the multiplying effect of combining flags, the create command works on a straightforward basis: every ACL combination is a created ACL.", + "flags": { + "allow-principal": { + "description": "Principal to allow. Format: `User:name` or `Group:name`. Can be specified multiple times." + }, + "deny-principal": { + "description": "Principal to deny. Format: `User:name` or `Group:name`. Can be specified multiple times." + }, + "operation": { + "description": "Operation to allow or deny: `all`, `read`, `write`, `create`, `delete`, `alter`, `describe`, `clusteraction`, `describeconfigs`, `alterconfigs`, `idempotentwrite`." + }, + "resource-type": { + "description": "Resource type: `topic`, `group`, `cluster`, `transactionalid`, `delegationtoken`." + }, + "resource-name": { + "description": "Name of the resource. Use `*` for wildcard matching all resources of the type." + }, + "resource-pattern-type": { + "description": "Pattern type: `literal` (exact match), `prefixed` (prefix match), `match` (either literal or prefixed), `any`." + } + }, + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "seeAlso": [ + "xref:manage:security/authorization/acl.adoc[Configure Access Control Lists]" + ], + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-create.adoc", + "content": [ + { + "type": "section", + "id": "acl-info", + "title": null, + "position": "after_description", + "content": "If no host is specified, an allowed principal is allowed access from all hosts. The wildcard principal `*` allows all principals. At least one principal, one host, one resource, and one operation is required to create a single ACL." + }, + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "User ACLs", + "items": [ + { + "description": "Allow all permissions to user bar on topic `foo` and group `g`", + "code": "rpk security acl create --allow-principal bar --operation all --topic foo --group g" + }, + { + "description": "Allow read permissions to all users on topics biz and baz", + "code": "rpk security acl create --allow-principal '*' --operation read --topic biz,baz" + }, + { + "description": "Allow write permissions to user buzz to transactional ID `txn`", + "code": "rpk security acl create --allow-principal User:buzz --operation write --transactional-id txn" + } + ] + }, + { + "title": "Role ACLs", + "items": [ + { + "description": "Allow all permissions to role bar on topic `foo` and group `g`", + "code": "rpk security acl create --allow-role bar --operation all --topic foo --group g" + } + ] + }, + { + "title": "Schema Registry ACLs", + "items": [ + { + "description": "Allow read permissions to user `panda` on topic `bar` and schema registry subject `bar-value`", + "code": "rpk security acl create --allow-principal panda --operation read --topic bar --registry-subject bar-value" + } + ] + }, + { + "title": "Schema migration permissions", + "items": [ + { + "description": "Source cluster (read-only) for schema migration", + "code": "rpk security acl create --allow-principal User:migrator-user --operation read,describe --registry-global --brokers " + }, + { + "description": "Target cluster (read-write) for schema migration", + "code": "rpk security acl create --allow-principal User:migrator-user --operation write,describe,alter_configs,describe_configs --registry-global --brokers " + } + ] + } + ] + }, + { + "type": "note", + "position": "after_usage", + "content": "The schema migration examples above are Schema Registry ACLs only. You also require Kafka ACLs for topics, consumer groups, and cluster operations. See xref:manage:security/authorization/acl.adoc[Configure Access Control Lists]." + } + ] + }, + "rpk connect list": { + "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.", + "flags": { + "format": { + "description": "Output format: `text` (human-readable table), `json` (machine-readable), `cue` (CUE schema). Default is `text`." + } + }, + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect list" + }, + { + "description": "Example", + "code": "rpk connect list --format json inputs output" + }, + { + "description": "Example", + "code": "rpk connect list rate-limits buffers" + } + ] + } + ] + }, + "rpk topic trim-prefix": { + "content": [ + { + "type": "include", + "position": "after_header", + "path": "shared:partial$warning-delete-records.adoc" + } + ] + }, + "rpk group offset-delete": {}, + "rpk group seek": { + "flags": { + "to": { + "description": "Target position: `start` (beginning), `end` (latest), a specific offset number, or a timestamp prefixed with `@`." + }, + "to-file": { + "description": "Path to a JSON file specifying offsets per partition. Format: `{\"topic\": {\"0\": 100, \"1\": 200}}`." + }, + "topics": { + "description": "Topics to seek. If not specified, seeks all topics the group has committed offsets for." + } + }, + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Seek group G to June 1st, 2021", + "code": "rpk group seek g --to 1622505600" + }, + { + "description": "or", + "code": "rpk group seek g --to 1622505600000" + }, + { + "description": "or", + "code": "rpk group seek g --to 1622505600000000000" + }, + { + "description": "Seek group X to the commits of group Y topic foo", + "code": "rpk group seek X --to-group Y --topics foo" + }, + { + "description": "Seek group G's topics foo, bar, and biz to the end", + "code": "rpk group seek G --to end --topics foo,bar,biz" + }, + { + "description": "Seek group G to the beginning of a topic it was not previously consuming", + "code": "rpk group seek G --to start --topics foo --allow-new-topics" + } + ] + } + ], + "description": "Modify a group's current offsets.\n\nThis command allows you to modify a group's offsets. Sometimes, you may need to rewind a group if you had a mistaken deploy, or fast-forward a group if it is falling behind.\n\nThe `--to` option allows you to seek to a specific offset, or to the start or end of partitions. The offset can be at any timestamp precision (seconds since epoch, millis since epoch, etc). The start and end options are self explanatory. If any partition is deleted and recreated (a la `rpk topic delete; rpk topic create`), the prior commits are wiped out and the group will be committed to the earliest offset (similar to if specifying start).\n\nThe `--to-group` option allows you to seek to commits that are in another group. This is a merging operation: if g1 is consuming topics A and B, and g2 is consuming only topic B, `rpk group seek g1 --to-group g2` will update g1's commits for topic B only. The `--topics` flag can be used to further narrow which topics are updated. Unlike `--to`, all non-filtered topics are committed, even topics not yet being consumed, meaning `--allow-new-topics` is not needed.\n\nThe `--to-file` option allows to seek to offsets specified in a text file with the following format:\n\n[,text]\n----\n \n \n...\n----\n\nEach line contains the topic, the partition, and the offset to seek to. As with the prior options, `--topics` allows filtering which topics are updated. Similar to `--to-group`, all non-filtered topics are committed, even topics not yet being consumed, meaning `--allow-new-topics` is not needed.\n\nThe `--to`, `--to-group`, and `--to-file` options are mutually exclusive. If you are not authorized to describe or read some topics used in a group, you will not be able to modify offsets for those topics." + }, + "rpk cluster partitions unsafe-recover": { + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This operation is unsafe because it allows the forced leader election of the partitions that have lost majority when nodes are gone and irrecoverable; this may result in data loss." + } + ] + }, + "rpk topic describe": { + "description": "Print detailed information about topics. There are three potential views: a summary of the topic, the topic configurations, and a detailed partitions section. By default, the summary and configs sections are printed.", + "flags": { + "print-all": { + "description": "Print all topic configuration properties, including defaults and read-only values." + }, + "summary": { + "description": "Print a brief summary instead of detailed partition information." + } + }, + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "content": [ + { + "type": "section", + "id": "format-info", + "title": null, + "position": "after_description", + "content": "Using the `--format` flag with either JSON or YAML prints all the topic information.\n\nThe `--regex` flag (`-r`) parses arguments as regular expressions and describes topics that match any of the expressions." + } + ] + }, + "rpk topic list": { + "description": "List topics, optionally listing specific topics. This command lists all topics that you have access to by default.", + "flags": { + "regex": { + "description": "Filter topics by regular expression pattern." + }, + "internal": { + "description": "Include internal topics (those starting with underscore) in the output." + } + }, + "$refs": [ + "#/definitions/common-kafka-flags", + "#/definitions/common-tls-flags" + ], + "content": [ + { + "type": "section", + "id": "regex-info", + "title": null, + "position": "after_description", + "content": "If specifying topics or regular expressions, this command can be used to know exactly what topics you would delete if using the same input to the delete command.\n\nAlternatively, you can request specific topics to list, which can be used to check authentication errors (do you not have access to a topic you were expecting to see?), or to list all topics that match regular expressions.\n\nThe `--regex` or `-r` flag opts into parsing the input topics as regular expressions and listing any non-internal topic that matches any of expressions. The input expressions are wrapped with `^` and `$` so that the expression must match the whole topic name.\n\nNOTE: Regular expressions cannot be used to match internal topics. Specifying both `-i` and `-r` will exit with failure." + } + ] + }, + "rpk cluster health": { + "description": "Queries cluster health overview. Health overview is created based on health reports collected periodically from all nodes in the cluster.", + "flags": { + "watch": { + "description": "Continuously monitor health status, refreshing at the specified interval." + }, + "exit-when-healthy": { + "description": "Exit with status 0 when the cluster becomes healthy. Useful for scripts waiting for cluster readiness." + } + }, + "$refs": [ + "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "section", + "id": "health-criteria", + "title": null, + "position": "after_description", + "content": "A cluster is considered healthy when the following conditions are met:\n\n* All cluster nodes are responding\n* All partitions have leaders\n* The cluster controller is present" + } + ] + }, + "rpk cluster maintenance": { + "description": "Manage cluster maintenance mode for performing rolling upgrades and other maintenance operations.", + "$refs": [ + "#/definitions/common-admin-flags" + ] + }, + "rpk cluster maintenance enable": { + "description": "Enable maintenance mode on a broker. The broker drains leadership and stops accepting new partition assignments.", + "flags": { + "node": { + "description": "Node ID to put into maintenance mode." + }, + "wait": { + "description": "Wait for the node to finish draining before returning. Useful for scripted rolling operations." + } + }, + "$refs": [ + "#/definitions/common-admin-flags" + ] + }, + "rpk cluster maintenance disable": { + "description": "Disable maintenance mode on a broker, allowing it to resume normal operations and accept partition assignments.", + "flags": { + "node": { + "description": "Node ID to take out of maintenance mode." + } + }, + "$refs": [ + "#/definitions/common-admin-flags" + ] + }, + "rpk debug bundle": { + "description": "The `rpk debug bundle` command collects environment data that can help debug and diagnose issues with a Redpanda cluster, a broker, or the machine it's running on. It then bundles the collected data into a ZIP file, called a diagnostics bundle.", + "content": [ + { + "type": "note", + "position": "after_description", + "content": "In Kubernetes, you must run the `rpk debug bundle` command inside a container that's running a Redpanda broker." + }, + { + "type": "section", + "id": "diagnostic-bundle-files", + "title": "Diagnostic bundle files", + "position": "after_description", + "content": "The files and directories in the diagnostics bundle differ depending on the environment in which Redpanda is running:\n\n=== Common files\n\n* Kafka metadata: Broker configs, topic configs, start/committed/end offsets, groups, group commits.\n* Controller logs: The controller logs directory up to a limit set by `--controller-logs-size-limit` flag\n* Data directory structure: A file describing the data directory's contents.\n* redpanda configuration: The redpanda configuration file (`redpanda.yaml`; SASL credentials are stripped).\n* /proc/cpuinfo: CPU information like make, core count, cache, frequency.\n* /proc/interrupts: IRQ distribution across CPU cores.\n* Resource usage data: CPU usage percentage, free memory available for the redpanda process.\n* Clock drift: The ntp clock delta (using pool.ntp.org as a reference) and round trip time.\n* Admin API calls: Cluster and broker configurations, cluster health data, CPU profiles, and license key information.\n* Broker metrics: The broker's Prometheus metrics, fetched through its admin API (/metrics and /public_metrics).\n\n=== Bare-metal\n\n* Kernel: The kernel logs ring buffer (syslog) and parameters (sysctl).\n* DNS: The DNS info as reported by 'dig', using the hosts in /etc/resolv.conf.\n* Disk usage: The disk usage for the data directory, as output by 'du'.\n* Redpanda logs: The broker's Redpanda logs written to `journald` since `yesterday` (00:00:00 of the previous day based on `systemd.time`). If `--logs-since` or `--logs-until` is passed, only the logs within the resulting time frame are included.\n* Socket info: The active sockets data output by 'ss'.\n* Running process info: As reported by 'top'.\n* Virtual memory stats: As reported by 'vmstat'.\n* Network config: As reported by 'ip addr'.\n* lspci: List the PCI buses and the devices connected to them.\n* dmidecode: The DMI table contents. Only included if this command is run as root.\n\n=== Extra requests for partitions\n\nYou can provide a list of partitions to save additional admin API requests specifically for those partitions.\n\nThe partition flag accepts the format `[namespace/]topic/partition[,partition...]` where the namespace is optional. If the namespace is not provided, `rpk` will assume 'kafka'. For example:\n\nTopic 'foo', partitions 1, 2 and 3:\n\n[,bash]\n----\n--partition foo/1,2,3\n----\n\nNamespace _redpanda-internal, topic 'bar', partition 2:\n\n[,bash]\n----\n--partition _redpanda-internal/bar/2\n----\n\nIf you have an upload URL from the Redpanda support team, provide it in the `--upload-url` flag to upload your diagnostics bundle to Redpanda.\n\n=== Kubernetes\n\n* Kubernetes Resources: Kubernetes manifests for all resources in the given Kubernetes namespace using `--namespace`, or the shorthand version `-n`.\n* redpanda logs: Logs of each Pod in the given Kubernetes namespace. If `--logs-since` is passed, only the logs within the given timeframe are included." + }, + { + "type": "section", + "id": "result", + "title": "Result", + "position": "after_flags", + "content": "The files and directories in the diagnostics bundle differ depending on the environment in which Redpanda is running.\n\n[tabs]\n====\nLinux::\n+\n--\ninclude::reference:partial$bundle-contents.adoc[]\n\n--\nKubernetes::\n+\n--\n:env-kubernetes: true\n\ninclude::reference:partial$bundle-contents.adoc[]\n\n--\n====" + }, + { + "type": "examples", + "position": "after_flags", + "title": "Examples", + "items": [ + { + "description": "Collect Redpanda logs from a specific timeframe", + "code": "rpk debug bundle --logs-since \"2022-02-01\" --logs-size-limit 3MiB" + }, + { + "description": "Use a custom Kubernetes namespace", + "code": "rpk debug bundle --namespace " + } + ] + } + ] + }, + "rpk redpanda start": { + "description": "Start the Redpanda broker process. This is the main command for running Redpanda on Linux systems.", + "flags": { + "seeds": { + "description": "Comma-separated list of seed broker addresses for cluster formation. Format: `host1:port1,host2:port2`." + }, + "advertise-kafka-addr": { + "description": "Address to advertise for Kafka client connections. Use when the broker's internal address differs from its externally reachable address." + }, + "advertise-rpc-addr": { + "description": "Address to advertise for internal RPC connections between brokers." + }, + "mode": { + "description": "Startup mode: `dev-container` for development/testing with relaxed requirements." + }, + "check": { + "description": "Run system prerequisite checks before starting. Disable with `--check=false` for development." + } + }, + "seeAlso": [ + "xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc[`rpk redpanda mode`]" + ], + "content": [ + { + "type": "section", + "id": "setting-up-a-mode", + "title": "Setting up a mode", + "position": "after_usage", + "content": "You can set up a mode for Redpanda to start. Currently the mode `dev-container` is supported.\n\nTo set up the mode `dev-container` run:\n\n[,bash]\n----\nrpk redpanda start --mode dev-container\n----\n\nMode uses well-known configuration properties for development or test environments:\n\nBundled flags:\n\n* `--overprovisioned`\n* `--reserve-memory 0M`\n* `--check=false`\n* `--unsafe-bypass-fsync`\n\nBundled cluster properties:\n\n* `write_caching_default: true`\n* `auto_create_topics_enabled: true`\n* `group_topic_partitions: 3`\n* `storage_min_free_bytes: 10485760 (10MiB)`\n* `topic_partitions_per_shard: 1000`\n* `fetch_reads_debounce_timeout: 10`\n\nAfter Redpanda starts you can modify the cluster properties using:\n\n[,bash]\n----\nrpk config set \n----", + "parent": "usage", + "headingLevel": 3 + } + ] + }, + "rpk redpanda config": { + "description": "View and modify the local Redpanda configuration file. Changes are written to redpanda.yaml." + }, + "rpk container": { + "description": "Manage a local Redpanda container cluster for development and testing. Creates containers using Docker or Podman.", + "prerequisites": [ + "Docker or Podman must be installed and running", + "The current user must have permission to run containers" + ], + "seeAlso": [ + "xref:get-started:intro-to-rpk.adoc[Introduction to rpk]", + "xref:get-started:quick-start.adoc[Quick Start Guide]" + ], + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Container clusters are intended for development and testing only. Do not use for production workloads." + } + ], + "pageAliases": "features:guide-rpk-container.adoc, deployment:guide-rpk-container.adoc" + }, + "rpk generate app": { + "description": "Generate application code to connect to Redpanda. Creates starter code for various programming languages.", + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "NOTE: This command is only supported in Serverless clusters." + }, + { + "type": "self-hosted", + "position": "after_description", + "content": "If you are having trouble connecting to your cluster, you can use the common xref:reference:rpk/rpk-x-options.adoc#adminhosts[`-X admin.hosts=`] flag to pass a specific Admin API address." + }, + { + "type": "section", + "id": "supported-languages", + "title": "Supported languages", + "position": "after_usage", + "content": "The following programming languages are supported:\n\n* Python\n* Go\n* Java\n* JavaScript/Node.js\n* Rust", + "parent": "usage", + "headingLevel": 3 + } + ] + }, + "rpk iotune": { + "description": "`rpk iotune` measures the I/O performance of the hardware used by a Redpanda instance. It writes its parameters to an I/O configuration file that Redpanda reads on startup to optimize its I/O performance. Its benchmarks measure read/write IOPS and bandwidth.\n\nBy default `rpk iotune` writes its output parameters to `/etc/redpanda/io-config.yaml`.", + "prerequisites": [ + "Root privileges or sudo access", + "At least 10 GB of free disk space for benchmarks" + ], + "seeAlso": [ + { + "content": "xref:manage:io-optimization.adoc[Optimize I/O]", + "selfHostedOnly": true + } + ], + "content": [ + { + "type": "section", + "id": "example-output", + "title": "Example output", + "position": "after_aliases", + "headingLevel": 2, + "content": "Running `rpk iotune` produces an output file that by default is saved in `/etc/redpanda/io-config.yaml`.\n\nThe contents of an example `io-config.yaml`:\n\n[,yaml]\n----\ndisks:\n- mountpoint: /var/lib/redpanda/data\n read_iops: 40952\n read_bandwidth: 5638210048\n write_iops: 6685\n write_bandwidth: 1491679488\n----" + }, + { + "type": "warning", + "position": "after_description", + "content": "Running iotune generates significant disk I/O and may impact other applications on the system." + } + ] + }, + "rpk transform": { + "description": "Develop, build, deploy, and manage WebAssembly (Wasm) data transforms for Redpanda.", + "pageAliases": "labs:data-transform/rpk-transform.adoc" + }, + "rpk cluster config force-reset": {}, + "rpk cluster config get": { + "description": "Get a cluster configuration property.", + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "This command is provided for use in scripts. For interactive editing, or bulk\noutput, use the `edit` and `export` commands respectively." + } + ] + }, + "rpk cluster config set": { + "seeAlso": [ + "xref:reference:properties/cluster-properties.adoc[Cluster Properties]" + ], + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "If you set the cluster property value to an empty string, the property is reset to its default.\n\nThis command is provided for use in scripts. For interactive editing, or bulk\nchanges, use the `edit` and `import` commands respectively." + }, + { + "type": "cloud-only", + "position": "after_description", + "content": "The output returns an operation ID. Use the xref:reference:rpk/rpk-cluster/rpk-cluster-config-status.adoc[`status`] command to check the progress of the configuration change." + }, + { + "type": "note", + "position": "after_flags", + "content": "Setting properties to non-number values (such as setting string values with `-`) can be problematic for some terminals due to how POSIX flags are parsed. For example, the following command may not work from some terminals:\n\n[,bash]\n----\nrpk cluster config set delete_retention_ms -1\n----\n\nWorkaround: Use `--` to disable parsing for all subsequent characters. For example:\n\n[,bash]\n----\nrpk cluster config set -- delete_retention_ms -1\n----" + }, + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Set a single property", + "items": [ + { + "description": "Enable auditing", + "code": "rpk cluster config set audit_enabled true" + } + ] + }, + { + "title": "Set multiple properties", + "items": [ + { + "description": "Enable Iceberg with REST catalog type (use `key=value` notation)", + "code": "rpk cluster config set iceberg_enabled=true iceberg_catalog_type=rest" + } + ] + } + ] + } + ] + }, + "rpk cluster config status": { + "descriptionScope": "self-hosted", + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "Check the progress of a cluster configuration change.\n\nSome cluster properties require a rolling restart when updated, and it can take several minutes for the update to complete. This command lists the long-running operations run by the update and their status:\n\n- In progress (running)\n- Completed\n- Failed\n\n[,bash,role=no-copy]\n----\nOPERATION-ID STATUS STARTED COMPLETED\nd0ec1obmpnr7lv17bfpg RUNNING 2025-05-08 14:34:09\nd0ec0sor49uba166af3g RUNNING 2025-05-08 14:32:20\n----" + } + ], + "description": "Get the configuration status of Redpanda brokers.\n\nFor each broker, the command output shows:\n\n- Whether you need to restart the broker to apply the new settings\n- Any settings that the broker has flagged as invalid or unknown\n\nThe command also returns the version of cluster configuration that each broker\nhas applied. The version should be the same across all brokers, and\nit is incremented each time a configuration change is applied to the\ncluster. If a broker is using an earlier version as indicated by a lower number,\nit may be out of sync with the rest of the cluster. This can happen if a broker\nis offline or if it has not yet applied the latest configuration changes. The cluster configuration version number is not the same as the Redpanda version number." + }, + "rpk cluster connections list": { + "description": "Display statistics about current Kafka connections. This command displays a table of active and recently closed connections within the cluster. Use filtering and sorting to identify the connections of the client applications that you are interested in. See `--help` for the list of filtering arguments and sorting arguments. By default only a subset of the per-connection data is printed. To see all of the available data, use `--format=json`.", + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "In addition to filtering shorthand CLI arguments (For example, `--client-id`, `--state`), you can also use the `--filter-raw` and `--order-by` arguments that take string expressions. To understand the syntax of these arguments, refer to the Admin API docs of the filter and order-by fields of the link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections[ListKafkaConnections endpoint]." + }, + { + "type": "cloud-only", + "position": "after_description", + "content": "In addition to filtering shorthand CLI arguments (For example, `--client-id`, `--state`), you can also use the `--filter-raw` and `--order-by` arguments that take string expressions. To understand the syntax of these arguments, refer to the Admin API docs of the filter and order-by fields of the link:/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections[`GET /v1/monitoring/kafka/connections`] Data Plane API endpoint." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "List connections ordered by their recent produce throughput", + "code": "rpk cluster connections list --order-by=\"recent_request_statistics.produce_bytes desc\"" + }, + { + "description": "List connections ordered by their recent fetch throughput", + "code": "rpk cluster connections list --order-by=\"recent_request_statistics.fetch_bytes desc\"" + }, + { + "description": "List connections ordered by the time that they've been idle", + "code": "rpk cluster connections list --order-by=\"idle_duration desc\"" + }, + { + "description": "List connections ordered by those that have made the least requests", + "code": "rpk cluster connections list --order-by=\"total_request_statistics.request_count asc\"" + }, + { + "description": "List extended output for open connections in JSON format", + "code": "rpk cluster connections list --format=json --state=\"OPEN\"" + } + ] + } + ] + }, + "rpk cluster license set": { + "description": "Upload a license to the cluster using a file path, inline string, or default location." + }, + "rpk cluster partitions disable": {}, + "rpk cluster partitions enable": {}, + "rpk cluster partitions list": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "List all partitions in the cluster", + "code": "rpk cluster partitions list --all" + }, + { + "description": "List all partitions in the cluster, filtering for topic foo and bar", + "code": "rpk cluster partitions list foo bar" + }, + { + "description": "List partitions with replicas that are assigned to brokers 1 and 2.", + "code": "rpk cluster partitions list foo --node-ids 1,2" + }, + { + "description": "List only the disabled partitions", + "code": "rpk cluster partitions list -a --disabled-only" + }, + { + "description": "List all in JSON format", + "code": "rpk cluster partition list -a --format json" + } + ] + } + ] + }, + "rpk cluster partitions move-cancel": { + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement-cancel.adoc" + }, + "rpk cluster partitions move-status": { + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement-status.adoc" + }, + "rpk cluster partitions move": { + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement.adoc", + "description": "Move partition replicas across nodes / cores.\n\nThis command changes replica assignments for given partitions. By default, it\nassumes the `kafka` namespace, but you can specify an internal namespace using\nthe `{namespace}/` prefix.", + "content": [ + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Basic replica movement", + "items": [ + { + "description": "Move partition 0 to brokers 1,2,3 and partition 1 to brokers 2,3,4 for topic foo", + "code": "rpk cluster partitions move foo --partition 0:1,2,3 -p 1:2,3,4" + } + ] + }, + { + "title": "Specifying cores", + "items": [ + { + "description": "Move replicas to specific cores on brokers", + "code": "rpk cluster partitions move foo -p 0:1-0,2-0,3-0" + } + ] + }, + { + "title": "Multi-topic movement", + "items": [ + { + "description": "Move partitions across different topics and namespaces", + "code": "rpk cluster partitions move -p foo/0:1,2,3 -p kafka_internal/tx/0:1-0,2-0,3-0" + } + ] + } + ] + } + ] + }, + "rpk cluster partitions balancer-status": {}, + "rpk cluster partitions balance": {}, + "rpk cluster partitions transfer-leadership": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "To transfer partition leadership for a partition `0` to a broker ID `2`, run", + "code": "rpk cluster partitions transfer-leadership foo --partition 0:2" + }, + { + "description": "The `--partition` flag accepts a value `:`, where `A` is a topic-partition and `B` is the ID of the broker to which you want to transfer leadership. To specify a topic-partition, you can use just the partition ID (`0`) or also use the topic name together with the partition using the following syntax", + "code": "rpk cluster partitions transfer-leadership --partition test-topic/0:2" + } + ] + } + ] + }, + "rpk cluster quotas alter": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Add quota (consumer_byte_rate) to client ID ``", + "code": "rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id=" + }, + { + "description": "Add quota (consumer_byte_rate) to client ID starting with `-`", + "code": "rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id-prefix=-" + }, + { + "description": "Add quota (producer_byte_rate) to default client ID", + "code": "rpk cluster quotas alter --add producer_byte_rate=180000 --default client-id" + }, + { + "description": "Remove quota (producer_byte_rate) from client ID `foo`", + "code": "rpk cluster quotas alter --delete producer_byte_rate --name client-id=" + } + ] + } + ] + }, + "rpk cluster quotas describe": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Describe all client quotas", + "code": "rpk cluster quotas describe" + }, + { + "description": "Describe all client quota with client ID ``", + "code": "rpk cluster quotas describe --name client-id=" + }, + { + "description": "Describe client quotas for a given client ID prefix `.`", + "code": "rpk cluster quotas describe --name client-id=." + } + ] + } + ] + }, + "rpk cluster quotas import": { + "description": "Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`.\n\nThe schema of the import string matches the schema from `rpk cluster quotas describe --format help`:\n\n[tabs]\n======\nYAML::\n+\n[,yaml]\n----\nquotas:\n - entity:\n - name: string\n - type: string\n values:\n - key: string\n - values: string\n----\nJSON::\n+\n[,yaml]\n----\n{\n \"quotas\": [\n {\n \"entity\": [\n {\n \"name\": \"string\",\n \"type\": \"string\"\n }\n ],\n \"values\": [\n {\n \"key\": \"string\",\n \"values\": \"string\"\n }\n ]\n }\n ]\n}\n----\n======\n\nUse the `--no-confirm` flag to avoid the confirmation prompt." + }, + "rpk cluster self-test start": { + "description": "Starts one or more benchmark tests on one or more nodes of the cluster.", + "seeAlso": [ + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`]" + ], + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Redpanda self-test runs benchmarks that consume significant system resources. Do not start self-test if large workloads are already running on the system." + }, + { + "type": "section", + "id": "available-tests", + "title": null, + "position": "after_description", + "content": "Available tests to run:\n\n* *Disk tests*\n** Throughput test: 512 KB messages, sequential read/write\n*** Uses larger request message sizes and deeper I/O queue depth to write/read more bytes in a shorter amount of time, at the cost of IOPS/latency.\n** Latency test: 4 KB messages, sequential read/write\n*** Uses smaller request message sizes and lower levels of parallelism to achieve higher IOPS and lower latency.\n* *Network tests*\n** Throughput test: 8192-bit messages\n*** Unique pairs of Redpanda nodes each act as a client and a server.\n*** The test pushes as much data over the wire, within the test parameters.\n* *Cloud storage tests*\n** Configuration/latency test: 1024-byte object.\n** If cloud storage is enabled, a series of remote operations are performed.\n\nThis command prompts users for confirmation (unless the flag `--no-confirm` is specified), then returns a test identifier ID, and runs the tests.\n\nTo view the test status, poll xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`]. Once the tests end, the cached results will be available with `rpk cluster self-test status`." + } + ] + }, + "rpk cluster self-test status": { + "content": [ + { + "type": "include", + "position": "after_description", + "path": "reference:partial$rpk-self-test-descriptions.adoc" + }, + { + "type": "examples", + "title": "Example", + "position": "after_aliases", + "items": [ + { + "description": "Example input", + "code": "rpk cluster self-test status" + } + ] + } + ] + }, + "rpk cluster self-test stop": { + "seeAlso": [ + "xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Guide for running self-test for cluster diagnostics]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[rpk cluster self-test]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[rpk cluster self-test start]" + ], + "content": [ + { + "type": "section", + "id": "example-output", + "title": "Example output", + "position": "after_aliases", + "headingLevel": 2, + "content": "$ rpk cluster self-test stop\n All self-test jobs have been stopped" + } + ] + }, + "rpk cluster self-test": { + "seeAlso": [ + "xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Guide for running self-test for cluster diagnostics]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[rpk cluster self-test start]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[rpk cluster self-test status]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc[rpk cluster self-test stop]" + ] + }, + "rpk cluster storage restore start": { + "description": "Start the cluster restoration process. This command starts the process of restoring data from a failed cluster with Tiered Storage enabled, including its metadata, onto a new cluster. If the wait flag (`--wait`/`-w`) is set, the command will poll the status of the recovery process until it's finished. Use `--cluster-uuid-override` if you want to specify an explicit cluster UUID to restore from.", + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery-start.adoc" + }, + "rpk cluster storage restore status": { + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery-status.adoc" + }, + "rpk cluster storage restore": { + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery.adoc" + }, + "rpk connect dry-run": { + "description": "Test pipeline configurations by performing a dry run. Exits with a status code 1 if any connection errors are detected in a directory.", + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "examples", + "title": "Example", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect dry-run ./pipeline.yaml" + }, + { + "description": "To disable all secret lookups", + "code": "rpk connect dry-run --secrets none: ./pipeline.yaml" + } + ] + } + ] + }, + "rpk connect help": {}, + "rpk connect mcp-server init": { + "description": "Initialize an MCP server project. Files that already exist will not be overwritten.", + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect mcp-server lint": { + "description": "Lint MCP server resources. Exits with a status code 1 if any linting errors are detected in the specified directory.", + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect mcp-server": { + "description": "Execute an MCP server against a suite of Redpanda Connect resources. Each resource will be exposed as a tool that AI can interact with.", + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect streams": { + "description": "Run Redpanda Connect in streams mode, where multiple pipelines can be executed in a single process and can be created, updated, and removed via REST HTTP endpoints. The config field specified with the `--observability`/`-o` flag is known as the root config and should only contain observability and service-wide config fields such as http, metrics, logger, resources, and so on.", + "seeAlso": [ + "xref:connect:guides:streams_mode/about.adoc[Streams Mode]" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect streams" + }, + { + "description": "Example", + "code": "rpk connect streams -o ./root_config.yaml" + }, + { + "description": "Example", + "code": "rpk connect streams ./path/to/stream/configs ./and/some/more" + }, + { + "description": "Example", + "code": "rpk connect streams -o ./root_config.yaml ./streams/*.yaml" + } + ] + } + ] + }, + "rpk container start": { + "seeAlso": [ + "https://hub.docker.com/r/redpandadata/redpanda/tags[Docker Hub]", + { + "content": "xref:get-started:quick-start.adoc#tabs-1-single-brokers[QuickStart - Deploy Redpanda to Docker with a Single Broker]", + "selfHostedOnly": true + }, + { + "content": "xref:get-started:quick-start.adoc#tabs-1-three-brokers[QuickStart - Deploy Redpanda to Docker with Three Nodes]", + "selfHostedOnly": true + } + ], + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Start a three-broker cluster", + "code": "rpk container start -n 3" + }, + { + "description": "Start a single-broker cluster, selecting random ports for every listener", + "code": "rpk container start --any-port" + }, + { + "description": "Start a 3-broker cluster, selecting the seed kafka and console port only", + "code": "rpk container start --kafka-ports 9092 --console-port 8080" + }, + { + "description": "Start a three-broker cluster, specifying the Admin API port for each broker", + "code": "rpk container start --admin-ports 9644,9645,9646" + } + ] + } + ] + }, + "rpk debug remote-bundle download": {}, + "rpk generate grafana-dashboard": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "|serverless |Monitoring dashboard for Redpanda Serverless clusters." + } + ] + }, + "rpk generate prometheus-config": {}, + "rpk group delete": { + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "+\nSee also: xref:reference:properties/cluster-properties.adoc#group_offset_retention_sec[Cluster properties: `group_offset_retention_sec`]" + } + ] + }, + "rpk plugin": { + "pageAliases": "reference:rpk/rpk-plugin.adoc" + }, + "rpk profile edit-globals": {}, + "rpk profile prompt": { + "description": "Prompt a profile name formatted for a PS1 prompt.\n\nThis command prints ANSI-escaped text per your current profile's `prompt`\nfield. If the current profile does not have a prompt, this prints nothing.\nIf the prompt is invalid, this exits 0 with no message. To validate the\ncurrent prompt, use the `--validate` flag.\n\nThis command may introduce other `%` variables in the future, if you want to\nprint a `%` directly, use `%%` to escape it.\n\nTo use this in zsh, be sure to add setopt PROMPT_SUBST to your .zshrc.\nTo edit your PS1, use something like `PS1='$(rpk profile prompt)` in your\nshell rc file." + }, + "rpk profile set-globals": {}, + "rpk redpanda config set": {}, + "rpk redpanda mode": { + "seeAlso": [ + "xref:develop:manage-topics/config-topics.adoc#configure-write-caching[Configure write caching]", + "xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`]", + "xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[`rpk redpanda tune`]" + ] + }, + "rpk redpanda tune list": { + "description": "List available redpanda tuners and check if they are enabled and supported by your system.\n\nTo enable a tuner it must be set in the `redpanda.yaml` configuration file under `rpk` section, for example:\n\n[,yaml]\n----\nrpk:\n tune_cpu: true\n tune_swappiness: true\n----\n\nYou may use `rpk redpanda config set` to enable or disable a tuner.", + "seeAlso": [ + "xref:reference:node-configuration-sample.adoc[redpanda.yaml]", + "xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[rpk redpanda tune]" + ], + "pageAttributes": { + "unsupported-os": "macOS, Windows" + }, + "content": [ + { + "type": "include", + "position": "after_header", + "path": "reference:partial$unsupported-os-rpk.adoc" + }, + { + "type": "section", + "id": "example-output", + "title": "Example output", + "position": "after_aliases", + "headingLevel": 2, + "content": "The output of the command lists each available tuner and whether it's enabled or supported (with a reason if it's unsupported).\n\n[,bash]\n----\nTUNER ENABLED SUPPORTED UNSUPPORTED-REASON\naio_events true true\nballast_file true true\nclocksource true false Clocksource setting not available for this architecture\ncoredump false true\ncpu true true\ndisk_irq true true\ndisk_nomerges true true\ndisk_scheduler true false open : no such file or directory\ndisk_write_cache true false Disk write cache tuner is only supported in GCP\nfstrim false false dial unix /var/run/dbus/system_bus_socket: connect: no such file or directory\nnet true true\nswappiness true true\ntransparent_hugepages false true\n----" + }, + { + "type": "section", + "id": "tuners", + "title": "Tuners", + "position": "after_examples", + "content": "This section describes each tuner and their configuration settings in xref:reference:node-configuration-sample.adoc[redpanda.yaml]. It provides overlapping and additional content to the descriptions returned by xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[rpk redpanda tune help].\n\n=== aio_events\n\nThe `aio_events` tuner maximizes throughput by increasing the number of simultaneous I/O requests. It sets the maximum number of outstanding asynchronous I/O operations to be above a calculated threshold.\n\nConfiguration (yaml):\n\n* `rpk.tune_aio_events`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== ballast_file\n\nThe `ballast_file` tuner improves debuggability and recoverability of a system with a full disk by creating a ballast file: if the disk becomes full, the ballast file can be deleted, thereby unblocking processes that are failing due to write failures and providing time for operators to stop any problematic processes causing the disk to fill, and to delete topics or records and change retention settings.\n\nConfiguration (yaml):\n\n* `rpk.tune_ballast_file`: flag to enable the tuner (Default for production mode: true)\n* `rpk.ballast_file_size`: size of the ballast file in bytes (Default for production mode: 1 GiB)\n* `rpk.ballast_file_path`: path to the ballast file (Default for production mode: `/var/lib/redpanda/data/ballast`)\n\n'''\n\n=== clocksource\n\nThe `clocksource` tuner improves the performance of getting system time by changing the clock source. It sets the clock source to the Time Stamp Counter (TSC) so time can be read in userspace via the Virtual Dynamic Shared Object (vDSO). This is more efficient than the usual virtual machine clock source, `xen`, that involves the overhead of a system call.\n\nConfiguration (yaml):\n\n* `rpk.tune_clocksource`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== coredump\n\nThe `coredump` tuner enables coredumps to be saved for production mode. By default, coredumps are not enabled for production. Enabling this tuner sets the location to save coredumps.\n\nConfiguration (yaml):\n\n* `rpk.tune_coredump`: flag to enable the tuner (Default for production mode: false)\n* `rpk.coredump_dir`: path to the saved coredump (Default for production mode: `/var/lib/redpanda/coredump`)\n\n'''\n\n=== cpu\n\nThe `cpu` tuner maximizes CPU performance for I/O intensive workloads by optimizing various CPU settings. It performs the following operations:\n\n* Sets the ACPI-cpufreq governor to `performance`\n\nIf system reboot is allowed (`rpk redpanda tune --reboot-allowed` option is set), the system must be rebooted after the first pass of the tuner, and it performs additional operations:\n\n* Disables Intel P-states\n* Disables Intel C-states\n* Disables turbo boost\n\nAfter tuning, the system CPUs operate at the maximum non-turbo frequency.\n\nConfiguration (yaml):\n\n* `rpk.tune_cpu`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== disk_irq\n\nThe `disk_irq` tuner optimizes the handling of interrupt requests (IRQs) for disks binding all disk IRQs to a requested set of CPUs. It tries to distribute IRQs according to the following guidelines:\n\n* Distribute NVMe disks IRQs equally among all available CPUs.\n* Distribute non-NVMe disks IRQs equally among designated CPUs or among all available CPUs in the `mq` mode.\n\nIRQs are distributed according to the operation mode set by `rpk redpanda tune --mode `. The available operation modes:\n\n* `sq`: set all IRQs of a given device to CPU0\n* `sq_split`: divide all IRQs of a given device between CPU0 and its HT siblings\n* `mq`: distribute device IRQs among all available CPUs instead of binding them all to CPU0\n\nIf no `--mode` is specified, a default mode is determined:\n\n* If there are only NVMe disks, the `mq` mode is set as the default.\n* For non-NVMe disks:\n** If the number of HT siblings is less than or equal to four, the `mq` mode is set as the default.\n** Otherwise, if the number of cores is less than or equal to four, the `sq` mode is set as the default.\n** For all other conditions, the `sq_split` mode is set as the default.\n\nConfiguration (yaml):\n\n* `rpk.tune_disk_irq`: flag to enable the tuner (Default for production mode: true)\n* `rpk redpanda tune --mode ` sets the IRQ distribution mode\n\n'''\n\n=== net\n\nThe `net` tuner optimizes the handling of interrupt requests (IRQs) for network interfaces (NICs) by binding all NIC IRQs to a requested set of CPUs.\n\nIts IRQ distribution operation modes are the same as described for the <> with NICs as the devices.\n\nConfiguration (yaml):\n\n* `rpk.tune_network`: flag to enable the tuner (Default for production mode: true)\n* `rpk redpanda tune --mode ` sets the IRQ distribution mode\n\n'''\n\n=== disk_nomerges\n\nThe `disk_nomerges` tuner reduces CPU overhead by disabling the merging of adjacent I/O requests.\n\nConfiguration (yaml):\n\n* `rpk.tune_disk_nomerges`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== disk_scheduler\n\nThe `disk_scheduler` tuner optimizes disk scheduler performance for the type of device (NVME, non-NVME). It provides a selectable set of schedulers:\n\n* `none`: minimizes latency of modern NVMe devices by bypassing the operating system's I/O scheduler\n* `noop`: preferred for non-NVME devices (and used when `none` is unavailable), this scheduler uses a simple FIFO queue where all I/O operations are first stored and then handled by the driver.\n\nConfiguration (yaml):\n\n* `rpk.tune_disk_scheduler`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== disk_write_cache\n\nThe `disk_write_cache` tuner optimizes write performance in cloud environments by enabling device write cache. This tuner is only supported in GCP.\n\nConfiguration (yaml):\n\n* `rpk.tune_disk_write_cache`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== fstrim\n\nThe `fstrim` tuner optimizes SSD performance by enabling periodic TRIM operations. It creates a weekly systemd timer that runs `fstrim` on the data directory.\n\nConfiguration (yaml):\n\n* `rpk.tune_fstrim`: flag to enable the tuner (Default for production mode: false)\n\n'''\n\n=== swappiness\n\nThe `swappiness` tuner optimizes memory usage by setting the kernel's swappiness value to 1, which minimizes swapping while still allowing the system to swap in critical situations.\n\nConfiguration (yaml):\n\n* `rpk.tune_swappiness`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== transparent_hugepages\n\nThe `transparent_hugepages` tuner disables transparent huge pages (THP) to prevent latency spikes caused by memory defragmentation. THP can cause unpredictable latency in database workloads.\n\nConfiguration (yaml):\n\n* `rpk.tune_transparent_hugepages`: flag to enable the tuner (Default for production mode: false)" + } + ] + }, + "rpk redpanda tune": { + "description": "`rpk redpanda tune`, also referred to as the autotuner, identifies the hardware configuration on your machine and optimizes the Linux kernel to give you the best performance for running Redpanda.", + "seeAlso": [ + "xref:deploy:deployment-option/self-hosted/manual/production/production-deployment.adoc[Deploy for Production]", + "xref:deploy:deployment-option/self-hosted/kubernetes/k-tune-workers.adoc[Tune Kubernetes Worker Nodes for Production]", + "xref:./rpk-redpanda-mode.adoc[`rpk redpanda mode production`]", + "xref:./rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`]" + ], + "pageAliases": "reference:autotune.adoc, introduction:autotune.adoc", + "content": [ + { + "type": "warning", + "position": "after_description", + "content": "Do not use this command in Azure self-managed environments." + }, + { + "type": "important", + "position": "after_description", + "content": "You should run the autotuner as part of the production deployment workflow. Redpanda recommends you first follow a guide for production deployment:\n\n* xref:deploy:deployment-option/self-hosted/manual/production/production-deployment.adoc[Deploy for Production]\n* xref:deploy:deployment-option/self-hosted/kubernetes/k-tune-workers.adoc[Tune Kubernetes Worker Nodes for Production]\n\nWhile you follow the guides, consult this reference for details about the autotuner." + }, + { + "type": "tip", + "position": "after_usage", + "content": "* When running `rpk redpanda tune`, make sure that your current Linux user has root privileges. The autotuner requires privileged access to the Linux kernel settings.\n* To run `rpk redpanda tune all` on a Redpanda broker automatically after broker or host restarts, configure the service `redpanda-tuner`, which runs `rpk redpanda tune all`, to run at boot-up:\n** For RHEL, after installing the rpm package, run `systemctl` to both start and enable the `redpanda-tuner` service:\n+\n[,bash]\n----\nsudo systemctl start redpanda-tuner\nsudo systemctl enable redpanda-tuner\n----\n\n** For Ubuntu, after installing the apt package, run `systemctl` to start the `redpanda-tuner` service (which is already enabled):\n+\n[,bash]\n----\nsudo systemctl start redpanda-tuner\n----" + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "+", + "code": "rpk redpanda config set rpk.tune_aio_events true" + }, + { + "description": "+", + "code": "rpk redpanda tune all" + }, + { + "description": "+", + "code": "rpk redpanda tune " + }, + { + "description": "+", + "code": "rpk redpanda tune help " + } + ] + } + ] + }, + "rpk registry context": { + "seeAlso": [ + "xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`]" + ] + }, + "rpk registry mode": { + "seeAlso": [ + "xref:manage:schema-reg/schema-reg-api.adoc#use-readonly-mode-for-disaster-recovery[Schema Registry API]" + ] + }, + "rpk registry schema create": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Create a Protobuf schema with subject `foo`", + "code": "rpk registry schema create foo --schema path/to/file.proto" + }, + { + "description": "Create an Avro schema, passing the type via flags", + "code": "rpk registry schema create foo --schema /path/to/file --type avro" + }, + { + "description": "Create a Protobuf schema that references the schema in subject `my_subject`, version 1", + "code": "rpk registry schema create foo --schema /path/to/file.proto --references my_name:my_subject:1" + }, + { + "description": "Create a schema with a specific ID and version in import mode", + "code": "rpk registry schema create foo --schema /path/to/file.proto --id 42 --schema-version 3" + }, + { + "description": "Create a schema with metadata properties as key=value pairs", + "code": "rpk registry schema create foo --schema /path/to/file.proto \\\n --metadata-properties owner=team-a \\\n --metadata-properties env=prod" + }, + { + "description": "Create a schema with metadata properties using JSON format", + "code": "rpk registry schema create foo --schema /path/to/file.proto \\\n --metadata-properties '{\"owner\":\"team-a\",\"env\":\"prod\"}'" + } + ] + } + ] + }, + "rpk shadow config generate": { + "seeAlso": [ + "xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]" + ], + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "Use the `--for-cloud` flag when generating your configuration." + } + ] + }, + "rpk shadow create": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "When creating a shadow link in Redpanda Cloud, use the `--for-cloud` flag.\n\nFirst log in and select the cluster where you want to create the shadow link before running this command. See xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] and xref:reference:rpk/rpk-cloud/rpk-cloud-cluster-select.adoc[`rpk cloud cluster select`]. For SCRAM authentication, store your password in the shadow cluster's secrets store (using either the cluster's secret store or xref:reference:rpk/rpk-security/rpk-security-secret.adoc[`rpk security secret`]), then reference it in your configuration file using `${secrets.SECRET_NAME}` syntax." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Create a shadow link using a configuration file", + "code": "rpk shadow create --config-file shadow-link.yaml" + }, + { + "description": "Create a shadow link without a confirmation prompt", + "code": "rpk shadow create -c shadow-link.yaml --no-confirm" + } + ] + } + ] + }, + "rpk shadow delete": { + "seeAlso": [ + "xref:reference:rpk/rpk-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`]" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Delete a shadow link", + "code": "rpk shadow delete my-shadow-link" + }, + { + "description": "Delete a shadow link without confirmation", + "code": "rpk shadow delete my-shadow-link --no-confirm" + }, + { + "description": "Force delete a shadow link with active shadow topics", + "code": "rpk shadow delete my-shadow-link --force" + } + ] + } + ] + }, + "rpk shadow describe": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "The command uses the Redpanda ID of the cluster you are currently logged into. To use a different cluster, either log in and create a profile for it, or use the `--redpanda-id` flag to specify it directly." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Describe a shadow link with default sections (overview and client)", + "code": "rpk shadow describe my-shadow-link" + }, + { + "description": "Display all configuration sections", + "code": "rpk shadow describe my-shadow-link --print-all" + }, + { + "description": "Display specific sections", + "code": "rpk shadow describe my-shadow-link --print-overview --print-topic" + }, + { + "description": "Display only the client configuration", + "code": "rpk shadow describe my-shadow-link -c" + } + ] + } + ] + }, + "rpk topic add-partitions": { + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Existing topic data is not redistributed to the newly-added partitions." + } + ] + }, + "rpk topic describe-storage": {}, + "rpk transform deploy": { + "content": [ + { + "type": "self-hosted", + "position": "after_flags", + "content": "Enabling compression may increase computation costs and could impact latency at the output topic.\n\nFor more details, see xref:deploy:deployment-option/self-hosted/manual/sizing.adoc[Sizing for Production]." + }, + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Deploy Wasm files directly without a `transform.yaml` file", + "code": "rpk transform deploy --file transform.wasm --name myTransform \\\n--input-topic my-topic-1 \\\n--output-topic my-topic-2\n--output-topic my-topic-3" + }, + { + "description": "Deploy a transformation with multiple environment variables", + "code": "rpk transform deploy --var FOO=BAR --var FIZZ=BUZZ" + }, + { + "description": "Configure compression for batches output by data transforms. The default setting is `none` but you can choose from `none`, `gzip`, `snappy`, `lz4`, or `zstd`", + "code": "rpk transform deploy --compression " + } + ] + } + ], + "pageAliases": "labs:data-transform/rpk-transform-deploy.adoc" + }, + "rpk connect agent init": { + "description": "Initialize a template for building a Redpanda Connect agent.", + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "examples", + "title": "Example", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect agent init ./repo" + } + ] + }, + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect agent run": { + "description": "Run a Redpanda Connect agent from a repository directory. Each resource in the mcp subdirectory will create tools that can be used, then the redpanda_agents.yaml file along with Python agent modules will be invoked.", + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "examples", + "title": "Example", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect agent run ./repo" + }, + { + "description": "To disable all secret lookups", + "code": "rpk connect agent run --secrets none: ./repo" + } + ] + }, + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect agent": { + "description": "Manage Redpanda Connect agents. Agents allow you to build AI-powered workflows using Redpanda Connect resources.", + "seeAlso": [ + "xref:reference:rpk/rpk-connect/rpk-connect-agent-init.adoc[rpk connect agent init]", + "xref:reference:rpk/rpk-connect/rpk-connect-agent-run.adoc[rpk connect agent run]" + ], + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect plugin init": { + "description": "Generate a project on the local filesystem that can be used as a starting point for building a custom component for Redpanda Connect. It will overwrite all files in the specified directory (or the current directory if none is specified).", + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "examples", + "title": "Example", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect plugin init example-plugin" + } + ] + }, + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect plugin": { + "description": "Manage custom Redpanda Connect plugins. Use these commands to create and initialize plugin projects for extending Redpanda Connect with custom components.", + "seeAlso": [ + "xref:reference:rpk/rpk-connect/rpk-connect-plugin-init.adoc[rpk connect plugin init]" + ], + "pageAttributes": { + "page-topic-type": "reference" + }, + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + "rpk connect create": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Create a config with stdin input, bloblang/awk processor, and nats output", + "code": "rpk connect create stdin/bloblang,awk/nats" + }, + { + "description": "Create a config with file/http_server inputs, protobuf processor, and http_client output", + "code": "rpk connect create file,http_server/protobuf/http_client" + } + ] + } + ] + }, + "rpk connect echo": { + "description": "Parse a config file and echo back a normalized version. This command is useful for sanity checking a config if it isn't behaving as expected, as it shows you a normalised version after environment variables have been resolved." + }, + "rpk connect blobl server": { + "description": "Run a web server that provides an interactive application for writing and testing Bloblang mappings.", + "content": [ + { + "type": "warning", + "position": "after_description", + "content": "This server is intended for local debugging and experimentation purposes only. Do NOT expose it to the internet." + } + ] + }, + "rpk connect template lint": { + "description": "Lint Redpanda Connect template files. Exits with a status code 1 if any linting errors are detected. If a path ends with '...' then Redpanda Connect will walk the target and lint any files with the .yaml or .yml extension.", + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Example", + "code": "rpk connect template lint" + }, + { + "description": "Example", + "code": "rpk connect template lint ./templates/*.yaml" + }, + { + "description": "Example", + "code": "rpk connect template lint ./foo.yaml ./bar.yaml" + }, + { + "description": "Example", + "code": "rpk connect template lint ./templates/..." + } + ] + } + ] + }, + "rpk connect template": { + "description": "Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns.", + "seeAlso": [ + "xref:connect:configuration:templating.adoc[Templating]" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This subcommand, and templates in general, are experimental and subject to change outside of major version releases." + } + ] + }, + "rpk connect blobl": { + "description": "Execute Bloblang mappings from the command line. Provides a convenient tool for mapping JSON documents.", + "seeAlso": [ + "xref:connect:guides:bloblang/about.adoc[Bloblang]" + ], + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Map JSON documents from stdin", + "code": "cat documents.jsonl | rpk connect blobl 'foo.bar.map_each(this.uppercase())'" + }, + { + "description": "Use a mapping file", + "code": "echo '{\"foo\":\"bar\"}' | rpk connect blobl -f ./mapping.blobl" + }, + { + "description": "Process input from a file", + "code": "rpk connect blobl -i input.jsonl -f ./mapping.blobl" + } + ] + } + ] + }, + "rpk registry mode set": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Set the global schema registry mode to `READONLY`", + "code": "rpk registry mode set --mode READONLY" + }, + { + "description": "Set the schema registry mode to `READWRITE` in subjects `` and ``", + "code": "rpk registry mode set --mode READWRITE" + }, + { + "description": "Set the schema registry mode to IMPORT, overriding the emptiness check", + "code": "rpk registry mode set --mode IMPORT --global --force" + } + ] + } + ] + }, + "rpk security acl delete": { + "content": [ + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Delete all permissions for a user", + "content": "Delete all permissions to user bar on topic `foo` and group `g`:\n\n[,bash]\n----\nrpk security acl delete --allow-principal bar --operation all --topic foo --group g\n----" + }, + { + "title": "Delete specific ACL from a role", + "content": "In a scenario that 2 ACLs were created for the same role (red-role), 1 that allows access to topic foo, 1 that deny access to topic bar:\n\n[,bash]\n----\nrpk security acl create --topic foo --operation all --allow-role red-role\nrpk security acl create --topic bar --operation all --deny-role red-role\n----\n\nIt's possible to delete one of the roles:\n\n[,bash]\n----\nrpk security acl delete --topic foo --operation all --allow-role red-role\n----" + } + ] + } + ], + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-delete.adoc" + }, + "rpk security acl list": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "List all ACLs", + "code": "rpk security acl list" + }, + { + "description": "List all Schema Registry ACLs", + "code": "rpk security acl list --subsystem registry" + }, + { + "description": "List all ACLs for topic \"foo\"", + "code": "rpk security acl list --topic foo" + }, + { + "description": "List all ACLs for user \"bar\" on topic \"foo\"", + "code": "rpk security acl list --allow-principal bar --topic foo" + }, + { + "description": "List all ACLs for role \"admin\" on schema registry subject \"foo-value\"", + "code": "rpk security acl list --allow-role admin --registry-subject foo-value" + } + ] + } + ], + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-list.adoc" + }, + "rpk security role assign": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Assign role `redpanda-admin` to user `red`", + "code": "rpk security role assign redpanda-admin --principal red" + }, + { + "description": "Assign role `redpanda-admin` to users `red` and `panda`", + "code": "rpk security role assign redpanda-admin --principal red,panda" + }, + { + "description": "Assign role `topic-reader` to group `analytics`", + "code": "rpk security role assign topic-reader --principal Group:analytics" + }, + { + "description": "Assign role `ops-admin` to both a user and a group", + "code": "rpk security role assign ops-admin --principal alice,Group:sre" + } + ] + } + ] + }, + "rpk security role describe": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Describe the role `red` (print members and ACLs)", + "code": "rpk security role describe red" + }, + { + "description": "Print only the members of role `red`", + "code": "rpk security role describe red --print-members" + }, + { + "description": "Print only the ACL associated to the role `red`", + "code": "rpk security role describe red --print-permissions" + } + ] + } + ] + }, + "rpk security role list": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "List all roles in Redpanda", + "code": "rpk security role list" + }, + { + "description": "List all roles assigned to the user `red`", + "code": "rpk security role list --principal red" + }, + { + "description": "List all roles with the prefix `agent-`", + "code": "rpk security role list --prefix \"agent-\"" + }, + { + "description": "List all roles assigned to the group `analytics`", + "code": "rpk security role list --principal Group:analytics" + } + ] + } + ] + }, + "rpk security role unassign": { + "content": [ + { + "type": "examples", + "position": "after_aliases", + "title": "Examples", + "items": [ + { + "description": "Unassign role `redpanda-admin` from user `red`", + "code": "rpk security role unassign redpanda-admin --principal red" + }, + { + "description": "Unassign role `redpanda-admin` from users `red` and `panda`", + "code": "rpk security role unassign redpanda-admin --principal red,panda" + }, + { + "description": "Unassign role `topic-reader` from group `contractors`", + "code": "rpk security role unassign topic-reader --principal Group:contractors" + } + ] + } + ] + }, + "rpk shadow failover": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Failover all topics for a shadow link", + "code": "rpk shadow failover my-shadow-link --all" + }, + { + "description": "Failover a specific topic", + "code": "rpk shadow failover my-shadow-link --topic my-topic" + }, + { + "description": "Failover without confirmation", + "code": "rpk shadow failover my-shadow-link --all --no-confirm" + } + ] + } + ] + }, + "rpk shadow status": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Display the status of a shadow link", + "code": "rpk shadow status my-shadow-link" + }, + { + "description": "Display specific sections", + "code": "rpk shadow status my-shadow-link --print-overview --print-topic" + } + ] + } + ] + }, + "rpk shadow update": { + "content": [ + { + "type": "examples", + "title": "Examples", + "position": "after_aliases", + "items": [ + { + "description": "Update a shadow link configuration", + "code": "rpk shadow update my-shadow-link" + } + ] + } + ] + }, + "rpk cluster config list": { + "content": [ + { + "type": "self-hosted", + "position": "after_description", + "content": "Use xref:reference:rpk/rpk-cluster/rpk-cluster-config-edit.adoc[`rpk cluster config edit`] for interactive editing." + }, + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Filtering with regex", + "items": [ + { + "description": "List properties matching a pattern", + "code": "rpk cluster config list --filter=\"kafka.*\"" + }, + { + "description": "Filter properties containing 'log'", + "code": "rpk cluster config list --filter=\".*log.*\"" + } + ] + }, + { + "title": "Output formats", + "items": [ + { + "description": "List in JSON format", + "code": "rpk cluster config list --format=json" + }, + { + "description": "List in YAML format", + "code": "rpk cluster config list --format=yaml" + } + ] + } + ] + } + ] + }, + "rpk cluster info": { + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-metadata.adoc" + }, + "rpk debug": { + "pageAliases": "reference:rpk/rpk-debug.adoc" + }, + "rpk generate": { + "pageAliases": "reference:rpk/rpk-generate.adoc" + }, + "rpk security secret create": { + "content": [ + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "after_aliases", + "headingLevel": 2, + "subsections": [ + { + "title": "Create a secret with a single scope", + "content": "Create a secret and set its scope to `redpanda_connect`:\n\n[,bash]\n----\nrpk security secret create --name NETT --value value --scopes redpanda_connect\n----" + }, + { + "title": "Create a secret with multiple scopes", + "content": "Set the scope to both `redpanda_connect` and `redpanda_cluster`:\n\n[,bash]\n----\nrpk security secret create --name NETT2 --value value --scopes redpanda_connect,redpanda_cluster\n----\n\nYou can also pass the scopes as a quoted string:\n\n[,bash]\n----\nrpk security secret create --name NETT2 --value value --scopes \"redpanda_connect,redpanda_cluster\"\n----" + } + ] + } + ] + }, + "rpk security user create": { + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-user-create.adoc, reference:rpk/rpk-security/rpk-security-acl-user-create.adoc" + }, + "rpk security user delete": { + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-user-delete.adoc, reference:rpk/rpk-security/rpk-security-acl-user-delete.adoc" + }, + "rpk security user list": { + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-user-list.adoc, reference:rpk/rpk-security/rpk-security-acl-user-list.adoc" + }, + "rpk security user update": { + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-user-update.adoc, reference:rpk/rpk-security/rpk-security-acl-user-update.adoc" + }, + "rpk security user": { + "pageAliases": "reference:rpk/rpk-acl/rpk-acl-user.adoc, reference:rpk/rpk-security/rpk-security-acl-user.adoc" + }, + "rpk transform build": { + "pageAliases": "labs:data-transform/rpk-transform-build.adoc" + }, + "rpk transform delete": { + "pageAliases": "labs:data-transform/rpk-transform-delete.adoc" + }, + "rpk transform init": { + "pageAliases": "labs:data-transform/rpk-transform-init.adoc" + }, + "rpk transform list": { + "pageAliases": "labs:data-transform/rpk-transform-list.adoc" + }, + "rpk ai": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai agent": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai agent list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai connection": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai connection list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai connection revoke": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai install": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs", + "appendToDescription": "\n\nSupported provider types: `openai`, `anthropic`, `google`, `bedrock`." + }, + "rpk ai llm create": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm delete": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm get": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm update": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp create": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp delete": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp get": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp tools": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp tools call": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp tools list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp types": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai mcp update": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai model": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs", + "appendToDescription": "\n\nThe catalog is read-only. The catalog is populated from each LLM provider's metadata plus any extras the operator has pinned to a tenant." + }, + "rpk ai model get": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai model list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs", + "appendToDescription": "\n\nOAuth providers describe third-party authorization servers (GitHub, Google, Slack, etc.) that user-facing MCP servers can authenticate against using the device-consent flow." + }, + "rpk ai oauth create": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth delete": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth get": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth update": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth-client": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs", + "appendToDescription": "\n\nAn OAuthClient is the external tool (Claude.ai, ChatGPT, Cursor, etc.) that requests access tokens for an MCP. Create one per tool you want to allow in; the `client_secret` is returned exactly once on create and cannot be retrieved afterward." + }, + "rpk ai oauth-client create": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth-client delete": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth-client get": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai oauth-client list": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai uninstall": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai upgrade": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai version": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk oxla": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + } + } +} \ No newline at end of file diff --git a/docs-data/rpk-overrides.schema.json b/docs-data/rpk-overrides.schema.json new file mode 100644 index 0000000000..be9cf77df6 --- /dev/null +++ b/docs-data/rpk-overrides.schema.json @@ -0,0 +1,740 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://redpanda.com/schemas/rpk-overrides.json", + "title": "RPK Documentation Overrides", + "description": "Schema for overriding auto-generated rpk command documentation. Provides comprehensive controls for technical writers to customize, exclude, deprecate, and enhance command documentation.", + "type": "object", + "properties": { + "$schema": { + "type": "string", + "description": "Reference to this schema file" + }, + "textTransformations": { + "type": "object", + "description": "Global text transformation rules applied to all command descriptions during generation. Allows writers to define patterns that should be formatted as inline code or replaced consistently across all commands.", + "properties": { + "replacements": { + "type": "array", + "description": "Text replacements applied BEFORE inline code formatting. Use for normalizing text (e.g., STDOUT → stdout). Applied in order.", + "items": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Regular expression pattern to match text that should be replaced. Use JavaScript regex syntax." + }, + "replacement": { + "type": "string", + "description": "Replacement text. Can use $1, $2, etc. for capture groups, or $& for entire match." + }, + "description": { + "type": "string", + "description": "Human-readable explanation of what this transformation does" + }, + "flags": { + "type": "string", + "description": "Regular expression flags. Default: 'g' (global). Common: 'gi' (global, case-insensitive)", + "default": "g", + "pattern": "^[gimsuvy]*$" + } + }, + "required": ["pattern", "replacement"], + "additionalProperties": false + } + }, + "inlineCode": { + "type": "array", + "description": "Patterns to wrap in inline code (backticks). Applied AFTER replacements and AFTER code block protection. Use negative lookbehind/lookahead to avoid double-wrapping.", + "items": { + "oneOf": [ + { + "type": "string", + "description": "Regular expression pattern. Matched text will be wrapped in backticks." + }, + { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Regular expression pattern to match text that should be wrapped in backticks" + }, + "replacement": { + "type": "string", + "description": "Optional custom replacement (e.g., '`$1`' for first capture group). If omitted, wraps entire match in backticks." + }, + "description": { + "type": "string", + "description": "Human-readable explanation of what this pattern matches" + }, + "flags": { + "type": "string", + "description": "Regular expression flags. Default: 'g'", + "default": "g", + "pattern": "^[gimsuvy]*$" + } + }, + "required": ["pattern"], + "additionalProperties": false + } + ] + } + } + }, + "additionalProperties": false + }, + "definitions": { + "type": "object", + "description": "Reusable definitions that can be referenced via $ref", + "additionalProperties": { + "$ref": "#/$defs/flagOverrides" + } + }, + "commands": { + "type": "object", + "description": "Command-specific overrides, keyed by full command path (e.g., 'rpk topic create')", + "additionalProperties": { + "$ref": "#/$defs/commandOverride" + } + } + }, + "$defs": { + "commandOverride": { + "type": "object", + "description": "Overrides for a specific command", + "properties": { + "description": { + "type": "string", + "description": "Override the command description. Replaces only the main description; sections from rpk output are preserved." + }, + "appendToDescription": { + "type": "string", + "description": "Content to append to the auto-generated description instead of replacing it." + }, + "descriptionScope": { + "type": "string", + "enum": ["cloud", "self-hosted", "both"], + "description": "Scope for the description override: 'cloud' (only in cloud docs), 'self-hosted' (only in self-hosted docs), or 'both' (default)" + }, + "introducedInVersion": { + "type": "string", + "description": "Version when this command was introduced (e.g., 'v26.2.0')" + }, + "flags": { + "$ref": "#/$defs/flagOverrides" + }, + "$refs": { + "type": "array", + "description": "Array of $ref paths to merge into this command (e.g., ['#/definitions/common-kafka-flags'])", + "items": { + "type": "string" + } + }, + "exclude": { + "type": "boolean", + "description": "If true, exclude this command from documentation entirely. Use for internal or hidden commands that shouldn't be documented." + }, + "excludeFlags": { + "type": "array", + "description": "List of flag names to exclude from documentation (without dashes)", + "items": { + "type": "string" + } + }, + "excludeExamples": { + "type": "array", + "description": "List of regex patterns to exclude specific examples from the source EXAMPLES section. Matches against example descriptions or commands.", + "items": { + "type": "string" + } + }, + "deprecated": { + "type": "boolean", + "description": "Mark this command as deprecated. A deprecation notice will be shown." + }, + "deprecatedMessage": { + "type": "string", + "description": "Custom deprecation message explaining what to use instead. Only used when deprecated is true." + }, + "deprecatedInVersion": { + "type": "string", + "description": "Version when this command was deprecated (e.g., 'v26.1.0')" + }, + "removedInVersion": { + "type": "string", + "description": "Version when this command will be or was removed (e.g., 'v27.0.0')" + }, + "replacement": { + "type": "string", + "description": "For deprecated commands, specify what command or approach to use instead. This is displayed in the deprecation notice." + }, + "minVersion": { + "type": "string", + "description": "Minimum rpk version required for this command (e.g., 'v25.3.0')" + }, + "platforms": { + "type": "array", + "description": "Platforms where this command is available. If not specified, assumed available on all platforms.", + "items": { + "type": "string", + "enum": ["linux", "darwin", "windows"] + } + }, + "prerequisites": { + "type": "array", + "description": "Prerequisites or requirements before using this command", + "items": { + "type": "string" + } + }, + "seeAlso": { + "type": "array", + "description": "Related commands or documentation pages. Can be strings (always shown) or objects with cloudOnly/selfHostedOnly properties for platform-specific links.", + "items": { + "oneOf": [ + { + "type": "string", + "description": "xref link or command name (shown on all platforms)" + }, + { + "type": "object", + "description": "Conditional see-also item shown only on specific platforms", + "properties": { + "content": { + "type": "string", + "description": "The xref link or command name" + }, + "cloudOnly": { + "type": "boolean", + "description": "If true, only shown in cloud docs (wrapped with ifdef::env-cloud[])" + }, + "selfHostedOnly": { + "type": "boolean", + "description": "If true, only shown in self-hosted docs (wrapped with ifndef::env-cloud[])" + } + }, + "required": ["content"], + "additionalProperties": false, + "oneOf": [ + { + "required": ["cloudOnly"], + "not": { "required": ["selfHostedOnly"] } + }, + { + "required": ["selfHostedOnly"], + "not": { "required": ["cloudOnly"] } + } + ] + } + ] + } + }, + "aliases": { + "type": "array", + "description": "Override or add command aliases", + "items": { + "type": "string" + } + }, + "excludeAliases": { + "type": "array", + "description": "List of alias names to exclude from documentation (e.g., intentional misspellings for autocorrect)", + "items": { + "type": "string" + } + }, + "aliasNotes": { + "type": "string", + "description": "A note to display after the aliases section explaining non-obvious aliases (e.g., autocorrect aliases)" + }, + "content": { + "type": "array", + "description": "Unified content additions. Use this for all custom content (sections, cloud-only, self-hosted, admonitions, includes). Each item has: type, position, and type-specific fields.", + "items": { + "$ref": "#/$defs/contentItem" + } + }, + "pageAliases": { + "type": "string", + "description": "Comma-separated list of page aliases for backwards compatibility. Preserves old URLs when commands are renamed. Example: 'reference:rpk/old-name.adoc, features:guide.adoc'" + }, + "pageAttributes": { + "type": "object", + "description": "Custom page attributes to add to the header (e.g., page-topic-type, learning-objective-*)", + "additionalProperties": { + "type": "string" + } + }, + "cloudOnly": { + "type": "boolean", + "description": "If true, this command only appears in cloud documentation (entire page wrapped in ifdef::env-cloud[])" + }, + "selfHostedOnly": { + "type": "boolean", + "description": "If true, this command only appears in self-hosted documentation (entire page wrapped in ifndef::env-cloud[])" + }, + "_note": { + "type": "string", + "description": "Internal note for writers. Not used in documentation generation. Use for explaining override rationale or tracking issues." + } + }, + "additionalProperties": false + }, + "flagOverrides": { + "type": "object", + "description": "Flag-specific overrides, keyed by flag name (without dashes)", + "additionalProperties": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "Override the flag description" + }, + "type": { + "type": "string", + "description": "Override the flag type display" + }, + "deprecated": { + "type": "boolean", + "description": "Mark this flag as deprecated" + }, + "deprecatedMessage": { + "type": "string", + "description": "Custom deprecation message for the flag" + }, + "required": { + "type": "boolean", + "description": "Override whether the flag is marked as required" + }, + "default": { + "type": "string", + "description": "Override the displayed default value" + }, + "validValues": { + "type": "array", + "description": "List of valid values for this flag (shown in docs)", + "items": { + "type": "string" + } + }, + "cloudOnly": { + "type": "boolean", + "description": "Flag only available in cloud environment" + }, + "selfHostedOnly": { + "type": "boolean", + "description": "Flag only available in self-hosted environment" + }, + "introducedInVersion": { + "type": "string", + "description": "Version when this flag was introduced (e.g., 'v26.2.0'). Auto-populated by diff when new flags are detected." + } + } + } + }, + "contentItem": { + "type": "object", + "description": "A content item to add to the documentation. The 'type' field determines what kind of content and which additional fields are required.", + "oneOf": [ + { + "$ref": "#/$defs/contentItemSection" + }, + { + "$ref": "#/$defs/contentItemExample" + }, + { + "$ref": "#/$defs/contentItemExamples" + }, + { + "$ref": "#/$defs/contentItemCloudOnly" + }, + { + "$ref": "#/$defs/contentItemSelfHosted" + }, + { + "$ref": "#/$defs/contentItemNote" + }, + { + "$ref": "#/$defs/contentItemWarning" + }, + { + "$ref": "#/$defs/contentItemTip" + }, + { + "$ref": "#/$defs/contentItemCaution" + }, + { + "$ref": "#/$defs/contentItemImportant" + }, + { + "$ref": "#/$defs/contentItemInclude" + } + ] + }, + "contentPosition": { + "type": "string", + "description": "Where to insert this content in the document", + "enum": [ + "after_header", + "after_description", + "after_usage", + "after_aliases", + "after_flags", + "after_modifiers", + "after_examples", + "before_see_also", + "end" + ] + }, + "contentItemSection": { + "type": "object", + "description": "A custom section with optional title. Supports subsections and parent sections with dynamic heading levels. If 'id' matches a source section (e.g., 'EXAMPLES', 'FIELDS'), you can: (1) use 'exclude: true' to remove it, or (2) provide 'content' to replace its content.", + "properties": { + "type": { + "const": "section" + }, + "id": { + "type": "string", + "description": "Unique identifier for this section. If it matches a source section ID (e.g., 'EXAMPLES', 'FIELDS'), you can exclude or replace that section." + }, + "title": { + "type": ["string", "null"], + "description": "Section title (e.g., 'Examples', 'Concept'). Use null for content without a section header." + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Section content in AsciiDoc format. Omit if using subsections." + }, + "subsections": { + "type": "array", + "description": "Array of nested subsections. Template automatically adjusts heading levels (=== for subsections, ==== for sub-subsections, etc.)", + "items": { + "$ref": "#/$defs/subsection" + } + }, + "parent": { + "type": "string", + "description": "ID or lowercase title of an existing rpk section to nest this section inside. Template automatically adjusts heading levels. Example: 'flags' nests this section inside the Flags section." + }, + "exclude": { + "type": "boolean", + "description": "If true, exclude a section from the rpk source output (use when overriding with custom content). The generator checks all case variations of the ID." + }, + "headingLevel": { + "type": "integer", + "description": "Override the automatic heading level (2 for ==, 3 for ===, etc.). Use sparingly - template usually determines this automatically.", + "minimum": 2, + "maximum": 6 + } + }, + "required": ["type"], + "additionalProperties": false, + "anyOf": [ + { + "required": ["position"], + "description": "Normal section with position" + }, + { + "required": ["exclude"], + "properties": { + "exclude": { "const": true } + }, + "description": "Exclude-only section doesn't need position" + } + ] + }, + "contentItemCloudOnly": { + "type": "object", + "description": "Content shown only in cloud docs (wrapped in ifdef::env-cloud[])", + "properties": { + "type": { + "const": "cloud-only" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Content in AsciiDoc format" + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemSelfHosted": { + "type": "object", + "description": "Content shown only in self-hosted docs (wrapped in ifndef::env-cloud[])", + "properties": { + "type": { + "const": "self-hosted" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Content in AsciiDoc format" + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemNote": { + "type": "object", + "description": "A NOTE admonition. Use plain text only - template automatically wraps in NOTE: or [NOTE]====...==== depending on complexity.", + "properties": { + "type": { + "const": "note" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Note content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically." + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemWarning": { + "type": "object", + "description": "A WARNING admonition. Use plain text only - template automatically wraps in WARNING: or [WARNING]====...==== depending on complexity.", + "properties": { + "type": { + "const": "warning" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Warning content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically." + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemTip": { + "type": "object", + "description": "A TIP admonition. Use plain text only - template automatically wraps in TIP: or [TIP]====...==== depending on complexity.", + "properties": { + "type": { + "const": "tip" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Tip content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically." + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemCaution": { + "type": "object", + "description": "A CAUTION admonition. Use plain text only - template automatically wraps in CAUTION: or [CAUTION]====...==== depending on complexity.", + "properties": { + "type": { + "const": "caution" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Caution content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically." + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemImportant": { + "type": "object", + "description": "An IMPORTANT admonition. Use plain text only - template automatically wraps in IMPORTANT: or [IMPORTANT]====...==== depending on complexity.", + "properties": { + "type": { + "const": "important" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "content": { + "type": "string", + "description": "Important content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically." + } + }, + "required": ["type", "position", "content"], + "additionalProperties": false + }, + "contentItemInclude": { + "type": "object", + "description": "An include directive to add a partial or shared content", + "properties": { + "type": { + "const": "include" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "path": { + "type": "string", + "description": "Include path (e.g., 'shared:partial$warning-delete-records.adoc')" + }, + "paths": { + "type": "array", + "description": "Multiple include paths", + "items": { + "type": "string" + } + } + }, + "required": ["type", "position"], + "additionalProperties": false + }, + "contentItemExample": { + "type": "object", + "description": "A single structured example. Writers provide plain text; template generates AsciiDoc code block automatically.", + "properties": { + "type": { + "const": "example" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "description": { + "type": "string", + "description": "Optional description shown before the code block (plain text, inline code allowed)" + }, + "code": { + "type": "string", + "description": "The code content. Template wraps in [,language]\\n----\\n...\\n----" + }, + "language": { + "type": "string", + "description": "Code language (e.g., 'bash', 'json', 'yaml', 'text'). Defaults to 'bash'.", + "default": "bash" + }, + "attributes": { + "type": "object", + "description": "Optional AsciiDoc block attributes (e.g., {\"role\": \"no-copy\"})", + "properties": { + "role": { + "type": "string" + }, + "subs": { + "type": "string" + } + }, + "additionalProperties": true + } + }, + "required": ["type", "position", "code"], + "additionalProperties": false + }, + "contentItemExamples": { + "type": "object", + "description": "Multiple structured examples with optional section title. Template generates proper AsciiDoc section with code blocks.", + "properties": { + "type": { + "const": "examples" + }, + "position": { + "$ref": "#/$defs/contentPosition" + }, + "title": { + "type": "string", + "description": "Section title (e.g., 'Examples'). Defaults to 'Examples'.", + "default": "Examples" + }, + "items": { + "type": "array", + "description": "Array of example items", + "items": { + "$ref": "#/$defs/exampleItem" + }, + "minItems": 1 + } + }, + "required": ["type", "position", "items"], + "additionalProperties": false + }, + "exampleItem": { + "type": "object", + "description": "A single example with description, code, and optional output", + "properties": { + "description": { + "type": "string", + "description": "Optional description for this example" + }, + "code": { + "type": "string", + "description": "The code content" + }, + "language": { + "type": "string", + "description": "Code language. Defaults to 'bash'.", + "default": "bash" + }, + "output": { + "type": "string", + "description": "Optional expected output from running the command" + }, + "outputLanguage": { + "type": "string", + "description": "Output block language. Defaults to 'bash'.", + "default": "bash" + }, + "attributes": { + "type": "object", + "description": "Optional AsciiDoc block attributes", + "additionalProperties": true + } + }, + "required": ["code"], + "additionalProperties": false + }, + "subsection": { + "type": "object", + "description": "A subsection within a parent section. Template automatically determines heading level based on nesting depth. Use 'content' for AsciiDoc text or 'items' for structured examples.", + "properties": { + "title": { + "type": "string", + "description": "Subsection title" + }, + "id": { + "type": "string", + "description": "Optional ID for this subsection (used for anchors)" + }, + "content": { + "type": "string", + "description": "Subsection content in AsciiDoc format" + }, + "items": { + "type": "array", + "description": "Structured examples with description, code, and optional output", + "items": { + "$ref": "#/$defs/exampleItem" + } + }, + "subsections": { + "type": "array", + "description": "Nested subsections (can be nested arbitrarily deep)", + "items": { + "$ref": "#/$defs/subsection" + } + } + }, + "required": ["title"], + "anyOf": [ + { "required": ["content"] }, + { "required": ["items"] } + ], + "additionalProperties": false + } + } +}