diff --git a/.github/workflows/update-rpk-docs.yml b/.github/workflows/update-rpk-docs.yml new file mode 100644 index 0000000000..66688a0254 --- /dev/null +++ b/.github/workflows/update-rpk-docs.yml @@ -0,0 +1,282 @@ +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: Resolve diff base version + id: diffbase + run: | + DIFF_VERSION="${{ steps.params.outputs.diff_version }}" + VERSION="${{ steps.params.outputs.version }}" + + # When no diff version is supplied (the usual case for the rpk-release + # repository_dispatch trigger), fall back to the currently-published + # version recorded in antora.yml (full-version). That is the version the + # docs currently target, so it is the correct baseline for "what's new". + if [ -z "$DIFF_VERSION" ]; then + FULL_VERSION=$(grep -E '^\s*full-version:' antora.yml \ + | head -1 \ + | sed -E "s/.*full-version:[[:space:]]*['\"]?([^'\"[:space:]]+).*/\1/") + if [ -n "$FULL_VERSION" ]; then + DIFF_VERSION="v${FULL_VERSION#v}" + echo "Using antora.yml full-version as diff base: $DIFF_VERSION" + else + echo "Could not read full-version from antora.yml; skipping diff" + fi + else + echo "Using supplied diff version: $DIFF_VERSION" + fi + + # Never diff a version against itself. + if [ -n "$DIFF_VERSION" ] && { [ "$DIFF_VERSION" = "$VERSION" ] || [ "$DIFF_VERSION" = "v${VERSION#v}" ]; }; then + echo "Diff base ($DIFF_VERSION) equals the target version; skipping diff" + DIFF_VERSION="" + fi + + # The generator diffs against a committed baseline snapshot + # (docs-data/rpk-.json); it does not rebuild the old version + # from source. If the snapshot is missing, skip the diff so the PR does + # not claim a comparison that did not run. The snapshot is written and + # committed on each run, so it is available from the next run onward. + if [ -n "$DIFF_VERSION" ] && [ ! -f "docs-data/rpk-${DIFF_VERSION}.json" ]; then + echo "::warning::No baseline snapshot docs-data/rpk-${DIFF_VERSION}.json found. What's new update and change summary are skipped until a baseline is committed." + DIFF_VERSION="" + fi + + echo "diff_version=$DIFF_VERSION" >> $GITHUB_OUTPUT + + - 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.diffbase.outputs.diff_version }}" + if [ -n "$DIFF_VERSION" ]; then + # A diff is required for the What's new update and the change summary. + CMD="$CMD --diff $DIFF_VERSION" + CMD="$CMD --update-whats-new" + fi + + DRAFT_MISSING="${{ steps.params.outputs.draft_missing }}" + if [ "$DRAFT_MISSING" = "true" ]; then + CMD="$CMD --draft-missing" + fi + + CMD="$CMD --output-dir modules/reference/pages/rpk" + # Write the generator's own (richer) PR summary outside the repo tree so + # it is not committed into the generated PR. + CMD="$CMD --summary-file ${{ runner.temp }}/pr-summary.md" + echo "cmd=$CMD" >> $GITHUB_OUTPUT + + - name: Run rpk-docs generator + id: generate + run: | + echo "Running: ${{ steps.command.outputs.cmd }}" + # Log outside the repo tree so it is not committed into the generated PR. + ${{ steps.command.outputs.cmd }} 2>&1 | tee "${{ runner.temp }}/generation-output.txt" + + - 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 + env: + PR_BODY: ${{ runner.temp }}/pr-body.md + PR_SUMMARY: ${{ runner.temp }}/pr-summary.md + WHATS_NEW: modules/get-started/pages/release-notes/redpanda.adoc + run: | + VERSION="${{ steps.params.outputs.version }}" + DIFF_VERSION="${{ steps.diffbase.outputs.diff_version }}" + + # Header + cat > "$PR_BODY" << 'HEADER' + ## Summary + + Automated update of rpk CLI documentation. + + HEADER + + # Version info + if [ "$VERSION" = "dev" ]; then + echo "**Source**: \`dev\` branch (pre-release)" >> "$PR_BODY" + else + echo "**Version**: \`$VERSION\`" >> "$PR_BODY" + fi + + if [ -n "$DIFF_VERSION" ]; then + echo "**Diff against**: \`$DIFF_VERSION\`" >> "$PR_BODY" + fi + echo "" >> "$PR_BODY" + + # Call out the What's new update when the generator touched it. + if git diff --staged --name-only | grep -q "$WHATS_NEW"; then + echo "> :memo: Updated the What's new page (\`$WHATS_NEW\`) with the Redpanda CLI changes." >> "$PR_BODY" + echo "" >> "$PR_BODY" + fi + + # Detailed, maintained change summary produced by the generator + # (generation stats, change tables, command lists, and validation report). + if [ -f "$PR_SUMMARY" ]; then + cat "$PR_SUMMARY" >> "$PR_BODY" + echo "" >> "$PR_BODY" + fi + + # Footer + cat >> "$PR_BODY" << '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: ${{ runner.temp }}/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/antora.yml b/antora.yml index dabf2d47ab..9d27b58d54 100644 --- a/antora.yml +++ b/antora.yml @@ -31,8 +31,8 @@ asciidoc: # Fallback versions # We try to fetch the latest versions from GitHub at build time # -- - full-version: 26.1.10 - latest-redpanda-tag: 'v26.1.10' + full-version: 26.1.12 + latest-redpanda-tag: 'v26.1.12' latest-console-tag: 'v3.3.1' latest-release-commit: 'ebee215fdb2b8004735c6f800e532564cdcc05e1' latest-operator-version: 'v2.3.8-24.3.6' 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": "(? `-o json`, `--format` yaml -> `--format yaml`)", + "pattern": "`(-{1,2}[a-zA-Z][a-z-]*)` (json|yaml|text|wide|help|csv)", + "replacement": "`$1 $2`", + "flags": "g" + }, + { + "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `\u200c-f json`, --format yaml -> `--format yaml`)", + "pattern": "(? `--mode help`)", + "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" + } + ] + } + ] + } + ], + "flags": { + "balancer": { + "description": "Group balancer to use when consuming with a consumer group (`range`, `roundrobin`, `sticky`, `cooperative-sticky`)." + }, + "use-schema-registry": { + "description": "Decode record keys and values using schemas from the schema registry. Use `=key` or `=value` to decode only the key or value." + }, + "fetch-max-bytes": { + "description": "Maximum number of bytes per fetch request per broker." + }, + "fetch-max-partition-bytes": { + "description": "Maximum number of bytes to fetch for a single partition per fetch request." + } + } + }, + "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" + } + ] + } + ], + "description": "Check the status of a mount or unmount operation for a topic in Tiered Storage." + }, + "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." + } + }, + "content": [ + { + "type": "section", + "id": "connect-flags", + "title": "Flags", + "position": "after_description", + "headingLevel": 2, + "content": "[cols=\"1m,1a,2a\"]\n|===\n|Value |Type |Description\n\n|--log.level |string |Override the configured log level. Acceptable values: `off`, `error`, `warn`, `info`, `debug`, `trace`.\n|--set |stringArray |Set a field (identified by a dot path) in the main configuration file. For example: `metrics.type=prometheus`.\n|--resources, -r |stringArray |Pull in extra resources from a file, which can be referenced the same as resources defined in the main config. This supports glob patterns (requires quotes).\n|--chilled |bool |Continue to execute a config containing linter errors (default: false).\n|--watcher, -w |bool |EXPERIMENTAL: Watch config files for changes and automatically apply them (default: false).\n|--env-file, -e |string |Import environment variables from a dotenv file.\n|--templates, -t |stringArray |EXPERIMENTAL: Import Redpanda Connect templates. This supports glob patterns (requires quotes).\n|===" + } + ] + }, + "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" + }, + { + "type": "section", + "id": "principals", + "title": "Principals", + "position": "after_description", + "headingLevel": 2, + "content": "All ACLs require a principal or a role. A principal is composed of a user and a type. Within Redpanda, only the \"User\" type is supported. Having prefixes for new types ensures that potential future authorizers can add authorization using other types, such as \"Group\".\n\nWhen you create a user, you need to add ACLs for it before it can be used. You can create/delete/list ACLs for that user with either `User:bar` or `bar` in the `--allow-principal` and `--deny-principal` flags. This command will add the `User:` prefix for you if it is missing. The wildcard pass:q[`*`] matches any user. Creating an ACL with user `*` grants or denies the permission for all users.\n\n== Hosts\n\nHosts can be seen as an extension of the principal, and effectively gate where the principal can connect from. When creating ACLs, unless otherwise specified, the default host is the wildcard `*` which allows or denies the principal from all hosts (where allow & deny are based on whether `--allow-principal` or `--deny-principal` is used). If specifying hosts, you must pair the `--allow-host` flag with the `--allow-principal` flag, and the `--deny-host` flag with the `--deny-principal` flag.\n\n== Roles\n\nYou can bind ACLs to a role. A role has only one part: the name. In contrast to principals, there is no need to supply the type. If a type-like prefix is present, it is treated as text rather than as principal type information.\n\nWhen you create a role, you must bind or associate ACLs to it before it can be used. You can create / delete / list ACLs for that role with \"\" in the `--allow-role` and `--deny-role` flags. Note that the wildcard role name `*` is not permitted here.\n\n== Resources\n\nA resource is what an ACL allows or denies access to. There are six resources within Redpanda: topics, groups, the cluster itself, transactional IDs, schema registry, and schema registry subjects. Names for each of these resources can be specified with their respective flags.\n\nResources combine with the operation that is allowed or denied on that resource. By default, resources are specified on an exact name match (a `literal` match). The `--resource-pattern-type` flag can be used to specify that a resource name is `prefixed`, meaning to allow anything with the given prefix. A literal name of `foo` will match only the topic `foo`, while the prefixed name of `foo-` will match both `foo-bar` and `foo-baz`. The special wildcard resource name pass:q[`*`] matches any name of the given resource type (`--topic *` matches all topics).\n\n== Operations\n\nPairing with resources, operations are the actions that are allowed or denied. Redpanda has the following operations:\n\n[cols=\"1,2a\"]\n|===\n|Operation |Description\n\n|`all` |Allows all operations below.\n|`read` |Allows reading a given resource.\n|`write` |Allows writing to a given resource.\n|`create` |Allows creating a given resource (except for Redpanda Schema Registry).\n|`delete` |Allows deleting a given resource.\n|`alter` |Allows altering non-configurations.\n|`describe` |Allows querying non-configurations.\n|`describe_configs` |Allows describing configurations.\n|`alter_configs` |Allows altering configurations.\n|===\n\nYou can run `rpk security acl --help-operations` to see which operations are required for which requests. In flag form to set up a general producing/consuming client, you can invoke `rpk security acl create` three times with the following (including your `--allow-principal`):\n\n`rpk security acl create --operation write,read,describe --topic [topics]`\n\n`rpk security acl create --operation describe,read --group [group.id]`\n\n`rpk security acl create --operation describe,write --transactional-id [transactional.id]`\n\n== Permissions\n\nA client can be allowed access or denied access. By default, all permissions are denied. You only need to specifically deny a permission if you allow a wide set of permissions and then want to deny a specific permission in that set. You could allow all operations, and then specifically deny writing to topics.\n\n== Management\n\nCreating ACLs works on a specific ACL basis, but listing and deleting ACLs works on filters. Filters allow matching many ACLs to be printed listed and deleted at once. Because this can be risky for deleting, the delete command prompts for confirmation by default. More details and examples for creating, listing, and deleting can be seen in each of the commands.\n\nUsing SASL requires setting `enable_sasl: true` in the redpanda section of your `redpanda.yaml`. User management is a separate, simpler concept that is described in the user command." + } + ], + "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" + } + ], + "description": "Trim records from topics by setting the LogStartOffset for partitions to the requested offset. All segments whose base offset is less than the requested offset are deleted, and any records within the segment before the requested offset can no longer be read.", + "flags": { + "from-file": { + "description": "Path to a file specifying topic, partition, and offset values to trim." + } + } + }, + "rpk group offset-delete": { + "description": "Forcefully delete offsets for a Kafka group.", + "flags": { + "from-file": { + "description": "Path to a file containing topic/partition tuples for which to delete offsets." + } + } + }, + "rpk group seek": { + "flags": { + "to": { + "description": "Target position to seek to. Use `start` (or `beginning`), `end` (or `latest`), a specific offset number, or a Unix timestamp prefixed with `@` (for example, `@1622505600`)." + }, + "to-file": { + "description": "Path to a text file specifying offsets per partition. Each line must contain the topic, partition, and offset separated by a space or tab." + }, + "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." + }, + "stable": { + "description": "Include the stable offsets column in the partitions section. Stable offsets reflect only committed transactional records and are only useful if you produce to this topic transactionally." + } + }, + "$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 using regular expressions. Expressions are automatically anchored with `^` and `$`, so they must match the full topic name." + }, + "internal": { + "description": "Include internal topics (those starting with `__`) 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": "Query cluster health and display the overall health status of the cluster. Redpanda collects health reports periodically from all nodes and aggregates them into a health overview.", + "flags": { + "watch": { + "description": "Continuously monitor health status, refreshing periodically." + }, + "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. While in maintenance mode, the broker drains partition leadership to other brokers. Use this command before performing broker upgrades or hardware maintenance. After maintenance is complete, run `rpk cluster maintenance disable ` to restore normal operation.", + "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 " + } + ] + } + ], + "flags": { + "kafka-connections-limit": { + "description": "The maximum number of Kafka connections to store in the bundle." + } + } + }, + "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 + } + ], + "flags": { + "language": { + "description": "The language for the generated code sample (`go`, `python`, `java`, `js`, `rust`)." + } + } + }, + "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": { + "flags": { + "cache-file": { + "description": "Location of the configuration cache file. Defaults to the Redpanda data directory." + } + } + }, + "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\"" + } + ] + } + ], + "flags": { + "state": { + "description": "Filter results by state. Acceptable values: `OPEN`, `CLOSED`." + } + } + }, + "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 partitions list -a --format json" + } + ] + }, + { + "type": "section", + "id": "enabled-disabled", + "title": "Enabled/Disabled", + "position": "after_description", + "headingLevel": 2, + "content": "Disabling a partition in Redpanda involves prohibiting any data consumption or production to and from it. All internal processes associated with the partition are stopped, and it remains unloaded during system startup. This measure aims to maintain cluster health by preventing issues caused by specific corrupted partitions that may lead to Redpanda crashes. Although the data remains stored on disk, Redpanda ceases interaction with the disabled partitions to ensure system stability. You may disable/enable partitions using `rpk cluster partitions enable/disable`." + } + ], + "description": "List partitions in the cluster. This command lists the cluster-level metadata of all partitions, including current replica assignments on brokers and CPU cores for given topics.", + "flags": { + "all": { + "description": "List all partitions in the cluster." + }, + "disabled-only": { + "description": "List disabled partitions only." + } + } + }, + "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": { + "description": "Trigger on-demand partition balancing to redistribute partitions evenly across brokers. Redpanda automatically balances partitions when it detects imbalance; run this command to trigger balancing manually." + }, + "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" + } + ] + } + ], + "flags": { + "partition": { + "description": "Topic-partition and target leader in the format `:`, for example `0:2` or `test-topic/0:2`. Use the `/` prefix for internal namespaces." + } + } + }, + "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=." + } + ] + } + ], + "flags": { + "any": { + "description": "Entity type for any matching (names or default). Valid type values: `client-id` or `client-id-prefix`. Repeatable." + }, + "default": { + "description": "Entity type for default matching. Valid type values: `client-id` or `client-id-prefix`. Repeatable." + }, + "name": { + "description": "Entity type and name pair for exact name matching. Valid type values: `client-id` or `client-id-prefix`. Repeatable." + }, + "strict": { + "description": "Use strict matching: exclude entities with unspecified entity types." + } + } + }, + "rpk cluster quotas import": { + "description": "Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`.", + "content": [ + { + "type": "section", + "id": "quotas-schema", + "title": "", + "position": "after_description", + "headingLevel": 2, + "content": "The 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" + } + ] + } + ], + "flags": { + "format": { + "description": "Output format (`text`, `json`)." + } + } + }, + "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" + } + ] + } + ], + "flags": { + "retries": { + "description": "The number of times to check for the cluster before considering it unstable and exiting." + } + } + }, + "rpk debug remote-bundle download": { + "description": "Download the debug bundle from a remote cluster configured in flags, environment variables, or your rpk profile." + }, + "rpk generate grafana-dashboard": { + "content": [ + { + "type": "cloud-only", + "position": "after_description", + "content": "|serverless |Monitoring dashboard for Redpanda Serverless clusters." + }, + { + "type": "section", + "id": "available-dashboards", + "title": "Available dashboards", + "position": "after_description", + "headingLevel": 2, + "content": "You can select one of the following dashboard types:\n\n[cols=\"1m,2a\"]\n|===\n|Name |Description\n\n|consumer-metrics |Monitoring of Java Kafka consumers, using the Prometheus JMX Exporter and the Kafka Sample Configuration.\n|consumer-offsets |Metrics and KPIs that provide details of topic consumers and how far they are lagging behind the end of the log.\n|operations |Provides an overview of KPIs for a Redpanda cluster with health indicators. This is suitable for ops or SRE to monitor on a daily or continuous basis. This is the default dashboard.\n|topic-metrics |Provides throughput, read/write rates, and on-disk sizes of each/all topics.\n|legacy |Generates dashboard based on selected metrics endpoint (`--metrics-endpoint`). Modify prometheus datasource and job-name with `--datasource` and `--job-name` flags.\n|===" + } + ], + "description": "Generate Grafana dashboards for Redpanda metrics. Use this command to generate sample Grafana dashboards that can be imported into a Grafana or Grafana Cloud instance.", + "flags": { + "dashboard": { + "description": "The name of the dashboard to download. Use `--dashboard=help` to list available dashboards." + } + } + }, + "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`]" + } + ], + "description": "Delete one or more consumer groups from Redpanda brokers. A group must have no active members to be deleted." + }, + "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 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\"}'" + } + ] + } + ], + "flags": { + "metadata-properties": { + "description": "Schema metadata properties as key=value pairs or JSON (for example, `{\"key\":\"value\"}`)." + } + } + }, + "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." + } + ], + "flags": { + "print-template": { + "description": "Generate a configuration template with field descriptions instead of a sample 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" + } + ] + } + ], + "description": "Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to." + }, + "rpk topic add-partitions": { + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Existing topic data is not redistributed to the newly-added partitions." + } + ], + "flags": { + "num": { + "description": "Number of partitions to add to each topic." + }, + "force": { + "description": "Force change the partition count in internal topics, for example, `__consumer_offsets`." + } + } + }, + "rpk topic describe-storage": { + "description": "Describe the cloud storage status of a topic, including storage mode, offset availability, segment sizes, and synchronization state.", + "flags": { + "human-readable": { + "description": "Print times (in milliseconds) and byte values in human-readable units (for example, 1.2 GiB, 3m 20s)." + } + } + }, + "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", + "flags": { + "compression": { + "description": "Output batch compression type. Valid values: `none`, `gzip`, `snappy`, `lz4`, `zstd`. Defaults to `none`." + }, + "from-offset": { + "description": "Starting offset for input topic partitions. Use `@T` for a timestamp (Unix milliseconds), `+N` for N records from the start, or `-N` for N records from the end. Only respected on first deploy." + } + } + }, + "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", + "flags": { + "deny-host": { + "description": "Hosts from which access will be denied (`repeatable`)." + }, + "cluster": { + "description": "Whether to remove ACLs for the cluster." + } + } + }, + "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", + "flags": { + "registry-global": { + "description": "Whether to match ACLs for the schema registry." + }, + "registry-subject": { + "description": "Schema registry subjects to match ACLs for (`repeatable`)." + } + } + }, + "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" + } + ] + } + ], + "description": "Display the status of a shadow link. When using `--format json` or `--format yaml`, the command outputs all sections by default." + }, + "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", + "flags": { + "mechanism": { + "description": "SASL mechanism to use for the user you are creating (`scram-sha-256`, `scram-sha-512`, case insensitive)." + } + } + }, + "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", + "description": "Initialize a new data transform project. Creates a new directory with the required project files. To initialize in a new subdirectory, specify the directory name as an argument.", + "flags": { + "install-deps": { + "description": "Install project dependencies automatically after initialization." + } + } + }, + "rpk transform list": { + "pageAliases": "labs:data-transform/rpk-transform-list.adoc" + }, + "rpk oxla": { + "exclude": true, + "_note": "Command mentions \"coming soon\" and needs proper review before inclusion in docs" + }, + "rpk ai llm": { + "appendToDescription": "\n\nSupported provider types: `openai`, `anthropic`, `google`, `bedrock`." + }, + "rpk ai model": { + "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 topic analyze": { + "flags": { + "batches": { + "description": "Minimum number of batches to consume per partition." + }, + "timeout": { + "description": "Maximum duration for the command to run before timing out." + } + } + }, + "rpk cluster config import": { + "flags": { + "filename": { + "description": "Full path to the configuration file to import, for example, `/tmp/config.yml`." + } + } + }, + "rpk cluster config lint": { + "description": "Identify any Redpanda configuration properties that are not recognized. These may be properties that were valid in earlier versions of Redpanda but are now managed via the central configuration store." + }, + "rpk cluster storage restore-start": { + "description": "Start a topic recovery operation from Tiered Storage. If the `--wait` (`-w`) flag is set, the command polls the status of the recovery process until it finishes." + }, + "rpk cluster logdirs describe": { + "flags": { + "aggregate-into": { + "description": "Aggregate results into the specified column starting from the partition column. Valid values: `broker`, `dir`, `topic`." + } + }, + "description": "Describe log directories on Redpanda brokers.\n\nThis command prints information about log directories on brokers, as well as the number of records in those log directories. The information is sorted first by topic, then by partition, and last by broker.\n\nThe directory returned is the root directory for partitions. Within Redpanda, the partition data lives underneath the returned root directory in `+kafka/{topic}/{partition}_{revision}/+`, where `revision` is a Redpanda internal concept." + }, + "rpk profile clear": { + "description": "Clear the current profile. This command clears the current profile, which can be useful to unset a production cluster profile." + }, + "rpk profile rename-to": { + "description": "Rename the current rpk profile. This command renames the currently active profile to the specified name. To switch profiles first, use `rpk profile use`." + }, + "rpk registry mode reset": { + "description": "Reset schema registry mode. This command deletes any subject modes and reverts to the global default. The command also prints the subject mode before reverting to the global default." + }, + "rpk registry mode get": { + "description": "Get schema registry mode. Running this command with no subject returns the global mode. Alternatively, use the `--global` flag to get the global mode at the same time as per-subject modes." + }, + "rpk registry schema check-compatibility": { + "flags": { + "schema": { + "description": "Schema filepath to check. Must be `.avro`, `.json`, or `.proto`." + } + } + }, + "rpk registry schema get": { + "flags": { + "schema": { + "description": "Schema file to check existence of. Must be `.avro`, `.json`, or `.proto`. Subject is required." + } + } + }, + "rpk registry schema delete": { + "description": "Delete a specific schema for the given subject. By default, schemas are soft deleted and can still be retrieved with the `--deleted` flag on other commands. Use `--permanent` to hard delete a schema, which cannot be undone." + }, + "rpk registry subject delete": { + "description": "Delete one or more schema registry subjects. By default, subjects are soft deleted. Use `--permanent` to hard delete a subject, which removes all versions permanently. Hard deletion is required before a schema registry context can be deleted." + }, + "rpk container status": { + "description": "Get the status of a local container cluster, including the node IDs, ports, and running state of each broker.", + "content": [ + { + "type": "section", + "id": "example", + "title": "Example", + "position": "end", + "headingLevel": 2, + "content": "[,bash]\n----\nrpk container status\nNODE-ID STATUS KAFKA-ADDRESS ADMIN-ADDRESS PROXY-ADDRESS SCHEMA-REGISTRY-ADDRESS\n0 running 127.0.0.1:9092 127.0.0.1:9644 127.0.0.1:8082 127.0.0.1:8081\n\nRedpanda Console started in: http://localhost:8080\n\nYou can use rpk to interact with this cluster. E.g:\n\n rpk cluster info\n rpk cluster health\n\nYou may also set an environment variable with the comma-separated list of\nbroker addresses:\n\n export RPK_BROKERS=\"127.0.0.1:34189,127.0.0.1:45523,127.0.0.1:37223\"\n rpk cluster info\n----" + } + ] + }, + "rpk debug remote-bundle cancel": { + "flags": { + "job-id": { + "description": "The job ID of the debug bundle to cancel. If not specified, cancels the current debug bundle job." + } + } + }, + "rpk debug remote-bundle start": { + "flags": { + "kafka-connections-limit": { + "description": "The maximum number of Kafka connections to store in the bundle." + } + } + }, + "rpk plugin install": { + "flags": { + "dir": { + "description": "Destination directory to save the installed plugin (defaults to `$HOME/.local/bin`)." + } + } + }, + "rpk connect install": { + "description": "Install Redpanda Connect. This command installs the latest version by default. Use the `--connect-version` flag to specify a version." + }, + "rpk connect studio sync-schema": { + "description": "Synchronize the schema of a Redpanda Connect instance with a Redpanda Connect Studio session. This command ensures that your pipeline components are configured and linted correctly within Redpanda Connect Studio." + }, + "rpk transform logs": { + "description": "View logs for a data transform. Streams STDOUT and STDERR output captured during runtime to your terminal." + }, + "rpk generate license": { + "description": "Generate a trial license for a 30-day Redpanda Enterprise Edition trial. The license is saved in your working directory or the specified path." + }, + "rpk ai auth login": { + "description": "Run the OAuth 2.0 device authorization grant against Redpanda Cloud, persist the resulting credentials, and prompt to select an environment whose AI Gateway URL becomes the active profile's dataplane URL." + }, + "rpk ai oauth-client": { + "description": "Manage OAuth clients registered with the AI gateway's OAuth Authorization Server. An OAuth client is an external tool (such as Claude AI, ChatGPT, or Cursor) that requests access tokens for an MCP server." + }, + "rpk ai oauth-provider": { + "description": "Manage OAuth authorization-server configurations registered with the Redpanda AI gateway. OAuth providers describe third-party authorization servers that user-facing MCP servers can authenticate against via the device-consent flow." + }, + "rpk ai agent start": { + "description": "Start a managed agent, setting its desired state to running." + }, + "rpk ai agent stop": { + "description": "Stop a managed agent, setting its desired state to stopped." + }, + "rpk ai llm check": { + "description": "Run a lightweight probe against the configured LLM provider to verify credentials and reachability." + }, + "rpk ai agent credential create": { + "description": "Create a client ID and secret pair for an agent. The client secret is shown once and cannot be retrieved again." + }, + "rpk ai agent credential delete": { + "description": "Delete a credential. Specify the full resource name as shown by `rpk ai agent credential list`, for example `agents/my-agent/credentials/abc123`." + }, + "rpk ai oauth-client revoke-tokens": { + "description": "Revoke every refresh token the AI gateway has issued for the named OAuth client. Forces all users who connected this client to sign in again." + }, + "rpk ai oauth-client create": { + "description": "Register an OAuth client with the AI gateway. The generated client secret is printed once and cannot be retrieved afterward. Save it immediately in a secret manager." + }, + "rpk ai oauth-client dcr get": { + "description": "Show the Dynamic Client Registration (DCR) settings for the current tenant, including whether DCR is enabled and the configured admission mode." + }, + "rpk ai oauth-client dcr iat mint": { + "description": "Mint a one-shot Initial Access Token for use at the OAuth client registration endpoint. The token plaintext is printed once and only a hash is stored." + }, + "rpk ai agent a2a task": { + "description": "Manage tasks created by agent-to-agent (A2A) conversations. Task IDs come from `rpk ai agent a2a send` replies. Use subcommands to get, watch, or cancel a task." + }, + "rpk ai oauth-client dcr": { + "description": "Manage Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint." + }, + "rpk redpanda tune list": { + "content": [ + { + "type": "section", + "id": "example-output", + "title": "Example output", + "position": "end", + "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": "end", + "headingLevel": 2, + "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 performance in Google Cloud Platform (GCP) by enabling write-through caching for its NVMe `Local SSD` drives.\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 improves SSD performance by starting a background systemd service to periodically wipe memory blocks that are not used by the file system. This is desirable for SSDs because they require wiping the space where new data will be written, so not wiping during non-write cycles will eventually cause performance degradations, when the lack of free space results in writes triggering synchronous erasures.\n\nIf it's available, the `fstrim` systemd service will be run. If it's unavailable but systemd is available, an equivalent service will be installed and run. Otherwise, no service will be run.\n\nConfiguration (yaml):\n\n* `rpk.tune_fstrim`: flag to enable the tuner (Default for production mode: true)\n\n'''\n\n=== swappiness\n\nThe `swappiness` tuner tunes the kernel to keep process data in-memory for as long as possible instead of swapping it out to disk.\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\nRedpanda makes excellent use of operating system-level Transparent HugePages (THP) by pre-allocating memory at startup. For CPUs that support THPs, this results in improved memory page caching and reduced cache misses from translation lookaside buffer (TLB) lookups.\n\nMost operating systems configure THP use to `madvise` by default, meaning a process must explicitly request them. Redpanda is designed to make the required `madvise` call, meaning THPs are in use under typical operation scenarios. Other possible values for THP use are `disabled` or `always`.\n\nThe `transparent_hugepages` tuner overrides the operating system setting, configuring THP use to `always`. This tuner only has a practical effect if the operating system is configured to `disabled` for THP use. For this reason, this tuner is disabled by default in production mode. It primarily exists to allow operators to ensure THPs are in use for their installations if there is any possibility the operating system is configured to `disabled`.\n\nConfiguration (yaml):\n\n* `rpk.tune_transparent_hugepages`: flag to enable the tuner (Default for production mode: false)\n\n'''\n\n=== Related topics\n\n* xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[rpk redpanda tune]" + } + ], + "flags": { + "mode": { + "description": "Operation Mode. Acceptable values: (`sq`, `sq_split`, `mq`)." + } + } + }, + "rpk redpanda tune": { + "flags": { + "mode": { + "description": "Operation Mode. Acceptable values: (`sq`, `sq_split`, `mq`)." + } + }, + "content": [ + { + "type": "section", + "id": "examples", + "title": "Examples", + "position": "end", + "headingLevel": 2, + "content": "This section provides examples of using the autotuner.\n\n* To enable a predetermined set of tuners for production, run the xref:./rpk-redpanda-mode.adoc[`rpk redpanda mode prod`] command. This command modifies settings in the `redpanda.yaml` configuration file.\n* To list the available tuners and to see whether they're enabled or supported (and a reason for if they're unsupported), run the xref:./rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`] command.\n* To enable or disable a tuner, run the xref:./rpk-redpanda-config-set.adoc[`rpk redpanda config set`], as the tuner flags are configurable node properties.\n** Each tuner has a YAML key flag for enabling/disabling itself in `redpanda.yaml`. Most are formed by prepending `rpk.tune_` to the name of the tuner listed by xref:./rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`]. See the xref:./rpk-redpanda-tune-list.adoc#tuners[Tuners reference] for the exact key for a tuner. For an example of enabling a tuner, the key for the `aio_events` tuner is `rpk.tune_aio_events`, and it can be enabled with the following command:\n+\n[,bash]\n----\nrpk redpanda config set rpk.tune_aio_events true\n----\n* To run all available tuners, use the xref:./rpk-redpanda-tune.adoc[`rpk redpanda tune`] command for `all`:\n+\n[,bash]\n----\nrpk redpanda tune all\n----\n* To run a specific tuner, use the xref:./rpk-redpanda-tune.adoc[`rpk redpanda tune`] command for the tuner:\n+\n[,bash]\n----\nrpk redpanda tune \n----\n* To learn more about a tuner, use the xref:./rpk-redpanda-tune.adoc[`rpk redpanda tune help`] command for the tuner:\n+\n[,bash]\n----\nrpk redpanda tune help \n----\n+\nSee also the xref:./rpk-redpanda-tune-list.adoc#tuners[Tuners reference] for descriptions about each tuner.\n\n'''\n\n=== Related topics\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* xref:./rpk-redpanda-mode.adoc[`rpk redpanda mode production`]\n* xref:./rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`]" + } + ] + }, + "rpk redpanda start": { + "content": [ + { + "type": "section", + "id": "set-up-a-mode", + "title": "Set up a mode", + "position": "after_description", + "headingLevel": 2, + "content": "Redpanda supports a `dev-container` mode with preset configuration for development and test environments.\n\nRun the following command to start Redpanda in `dev-container` mode:\n\n[,bash]\n----\nrpk redpanda start --mode dev-container\n----\n\nThis mode bundles the following flags and cluster properties:\n\nBundled flags:\n\n* xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc#development-mode[`--overprovisioned`] (disables thread affinity and other production guards; see xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc#development-mode[`rpk redpanda mode`] for details)\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 cluster properties by running:\n\n[,bash]\n----\nrpk config set \n----" + } + ] + }, + "rpk iotune": { + "content": [ + { + "type": "section", + "id": "example-output", + "title": "Example output", + "position": "end", + "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----\n\n=== Related topics\n\n* xref:manage:io-optimization.adoc[Optimize I/O]" + } + ] + }, + "rpk cloud byoc install": { + "content": [ + { + "type": "section", + "id": "example", + "title": "Example", + "position": "after_description", + "headingLevel": 2, + "content": "[,bash]\n----\nrpk cloud byoc install -X cloud.client_id= -X cloud.client_secret=\n----" + } + ] + }, + "rpk cloud mcp install": { + "description": "Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud.\n\nThis command generates and installs the necessary configuration files for your MCP client (like Claude Code) to automatically connect to the local MCP server for Redpanda Cloud. The local MCP server provides your AI assistant with tools to manage your Redpanda Cloud account and clusters.\n\nSupports Claude Desktop and Claude Code.", + "flags": { + "client": { + "description": "Name of the MCP client to configure. Supported values: `claude` or `claude-code`." + } + }, + "content": [ + { + "type": "section", + "id": "mcp-install-example", + "title": "Examples", + "position": "after_description", + "headingLevel": 2, + "content": "Install configuration for Claude Code:\n\n[,bash]\n----\nrpk cloud mcp install --client claude-code\n----" + } + ], + "seeAlso": [ + "xref:ai-agents:mcp/local/quickstart.adoc[]", + "xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[]" + ] + }, + "rpk cloud mcp stdio": { + "description": "Communicate with the local MCP server for Redpanda Cloud using the stdio protocol.\n\nThis command provides a direct stdio interface for communicating with the local MCP server for Redpanda Cloud. The local MCP server runs on your machine and provides tools for managing your Redpanda Cloud account and clusters. It's typically used as the transport mechanism when your MCP client is configured to use `rpk` as the stdio server process.\n\nMost users should use xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install`] instead, which automatically configures your MCP client.", + "content": [ + { + "type": "section", + "id": "mcp-stdio-example", + "title": "Examples", + "position": "after_description", + "headingLevel": 2, + "content": "Start the local MCP server for Redpanda Cloud using the stdio protocol:\n\n[,bash]\n----\nrpk cloud mcp stdio\n----" + } + ], + "seeAlso": [ + "xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[]", + "xref:ai-agents:mcp/local/overview.adoc[]" + ] + }, + "rpk cloud cluster select": { + "flags": { + "profile": { + "description": "Name of a profile to create or update (avoids updating `rpk-cloud`)." + } + } + }, + "rpk ai": { + "asPartial": true, + "content": [ + { + "type": "section", + "id": "agentic-cluster-note", + "position": "after_header", + "content": "include::partial$rpk-ai-agentic-cluster.adoc[]" + } + ] + }, + "rpk ai connection": { + "exclude": true + }, + "rpk ai connection list": { + "exclude": true + }, + "rpk ai connection revoke": { + "exclude": true + } + } +} diff --git a/docs-data/rpk-overrides.schema.json b/docs-data/rpk-overrides.schema.json new file mode 100644 index 0000000000..8bfe96f2b6 --- /dev/null +++ b/docs-data/rpk-overrides.schema.json @@ -0,0 +1,744 @@ +{ + "$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." + }, + "asPartial": { + "type": "boolean", + "description": "If true, write this command's .adoc file to the partials directory instead of the pages directory. Inherited by child commands — set on a parent command (e.g., 'rpk ai') to route the entire subtree to partials." + }, + "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 + } + } +} diff --git a/docs-data/rpk-v26.1.12.json b/docs-data/rpk-v26.1.12.json new file mode 100644 index 0000000000..c0394ecd01 --- /dev/null +++ b/docs-data/rpk-v26.1.12.json @@ -0,0 +1,18184 @@ +{ + "rpk_version": "v26.1.12", + "plugin_versions": {}, + "generated_at": "2026-07-06T07:48:48.950Z", + "tree": { + "name": "rpk", + "version": "(Redpanda CLI): (rev )", + "description": "rpk is the Redpanda CLI and toolbox for managing Redpanda clusters, topics, consumer groups, and streaming pipelines.", + "usage": "rpk [flags]", + "global_flags": [ + { + "name": "config", + "type": "string", + "description": "Redpanda or rpk config file; default search paths are \"/root/.config/rpk/rpk.yaml\", $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml", + "default": "", + "required": false + }, + { + "name": "config-opt", + "shorthand": "X", + "type": "stringArray", + "description": "Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail", + "default": [], + "required": false + }, + { + "name": "ignore-profile", + "type": "bool", + "description": "Ignore rpk.yaml and redpanda.yaml; use default settings", + "default": false, + "required": false + }, + { + "name": "profile", + "type": "string", + "description": "rpk profile to use", + "default": "", + "required": false + }, + { + "name": "verbose", + "shorthand": "v", + "type": "bool", + "description": "Enable verbose logging", + "default": false, + "required": false + } + ], + "commands": [ + { + "name": "ai", + "description": "Manage the Redpanda AI Gateway", + "usage": "rpk ai [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "agent", + "description": "Manage agents registered with the Redpanda AI platform.\n\nAgents are either managed (adp runs them; configured via a model, LLM\nprovider, system prompt and MCP servers) or self-managed (a metadata-only\nrecord tracking a user-hosted agent). `create` makes a managed agent by\ndefault; pass --self-managed for the metadata-only variant.\n\nThe `credential` subcommand provisions client-id/secret pairs an agent\nuses to authenticate against the gateway. The `a2a` subcommand talks to\na running agent over the A2A protocol (fetch its card, send messages,\nmanage tasks).", + "usage": "rpk ai agent [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "a2a", + "description": "Interact with an agent over the A2A (Agent-to-Agent) protocol.\n\nThe AGENT argument is either a registry agent name (resolved to the\nagent's A2A endpoint via its runtime status) or a full A2A endpoint URL\n(anything starting with http:// or https://).\n\nAuthentication: your profile's bearer token is attached when the target\nis a registry agent or an explicit URL on the profile's dataplane host.\nExplicit URLs on other hosts are called without credentials so your\ntoken never leaves the platform (a note on stderr says so when this\nhappens).\n\nOutput formats: table (default, human-readable) and -o json / -o yaml.\nStreams (--stream, task watch) emit one JSON event per line under both\njson and yaml.\n\nExit codes: 0 success (including tasks waiting for more input), 4 task\nended failed/canceled/rejected, 1 anything else.", + "usage": "rpk ai agent a2a [flags]", + "aliases": [], + "examples": " # Discover what an agent can do\n rpai agent a2a card financial-advisor\n\n # Ask a question (waits for the reply)\n rpai agent a2a send financial-advisor \"How did tech stocks do today?\"\n\n # Continue the same conversation\n rpai agent a2a send financial-advisor --context-id CTX \"And yesterday?\"\n\n # Stream the reply as it is produced\n rpai agent a2a send financial-advisor --stream \"Summarize the market\"\n\n # Inspect, watch, or cancel a long-running task\n rpai agent a2a task get financial-advisor TASK_ID\n rpai agent a2a task watch financial-advisor TASK_ID\n rpai agent a2a task cancel financial-advisor TASK_ID", + "flags": [], + "commands": [ + { + "name": "card", + "description": "Fetch the A2A agent card — the JSON discovery document describing the\nagent's identity, skills, supported transports and capabilities.\n\nUse -o json to feed the raw card to other tools.", + "usage": "rpk ai agent a2a card [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "send", + "description": "Send a text message to an agent over A2A and print the reply.\n\nThe message comes from the positional argument, or from stdin when the\nargument is omitted or \"-\" (so you can pipe a prompt in).\n\nBy default the call blocks until the agent replies. Replies that spawn a\nlong-running task print the task id so you can follow up with\n`rpai agent a2a task get|watch|cancel`. For work that may outlive\n--timeout (default 5m), prefer --stream or --no-block so the task id is\nin hand from the start.\n\nConversation state: every reply prints a context-id (stderr in the\ndefault format, part of the JSON in -o json). Pass it back via\n--context-id to continue the same conversation. When a task ends in\nstate input-required, answer it by sending again with both --task-id\nand --context-id from the reply.\n\nOutput: the agent's reply text goes to stdout; ids and state go to\nstderr as `key: value` lines so pipes stay clean. Use -o json for the\nfull A2A response (message or task object). With --stream, json and\nyaml both emit one JSON event per line (JSONL).\n\nExit codes: 0 success or input-required, 4 task failed/canceled/\nrejected, 1 anything else.", + "usage": "rpk ai agent a2a send [flags]", + "aliases": [], + "examples": " # Ask and wait for the answer\n rpai agent a2a send financial-advisor \"What moved the S&P 500 today?\"\n\n # Continue the conversation from a previous reply's context-id\n rpai agent a2a send financial-advisor --context-id CTX \"Why?\"\n\n # Answer a task that ended in input-required\n rpai agent a2a send financial-advisor --task-id TASK --context-id CTX \"Account A-17\"\n\n # Pipe the prompt from a file, get the full JSON reply\n cat prompt.txt | rpai agent a2a send financial-advisor -o json\n\n # Stream events as they happen\n rpai agent a2a send financial-advisor --stream \"Give me a market summary\"\n\n # Fire-and-forget: submit, then poll with `task get`\n rpai agent a2a send financial-advisor --no-block \"Deep analysis please\"", + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "task", + "description": "Inspect and control long-running A2A tasks.\n\nTask ids come from `rpai agent a2a send` replies (printed as task-id).", + "usage": "rpk ai agent a2a task [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "cancel", + "description": "Ask the agent to cancel a running task and print the task's resulting\nstate. Cancellation is cooperative — the agent may already have\nfinished, in which case the terminal state is returned unchanged.", + "usage": "rpk ai agent a2a task cancel [flags]", + "aliases": [], + "examples": " rpai agent a2a task cancel financial-advisor TASK_ID", + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Fetch a task's current state, status message, artifacts and (optionally\ntruncated) message history. Use -o json for the full task object.", + "usage": "rpk ai agent a2a task get [flags]", + "aliases": [], + "examples": " rpai agent a2a task get financial-advisor TASK_ID\n rpai agent a2a task get financial-advisor TASK_ID --history 10 -o json", + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "watch", + "description": "Reattach to a running task's event stream (A2A tasks/resubscribe) and\nprint events until the task reaches a terminal state. Use after a\ndisconnected --stream send or a --no-block send.\n\nWatch waits as long as the task runs (no timeout by default; bound it\nwith --timeout). Exit codes match send: 0 success or input-required,\n4 task failed/canceled/rejected, 1 anything else.", + "usage": "rpk ai agent a2a task watch [flags]", + "aliases": [], + "examples": " rpai agent a2a task watch financial-advisor TASK_ID\n rpai agent a2a task watch financial-advisor TASK_ID -o json # one JSON event per line", + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "apply", + "description": "Reconcile agents from one or more YAML manifests.\n\nFor each manifest: create the resource if absent, otherwise update only the\nfields that are present in the manifest AND differ from the live resource.\nFields you omit are left untouched; to clear a field, write it explicitly.\nLists, maps and oneof variants replace wholesale. Fields that can only be set\nat creation time are immutable; changing one is an error.\n\nManifests round-trip with `get -o yaml` for this resource. Pass -f - to\nread stdin.\n\nThis does not delete resources absent from the manifests (no prune), and drift\nis detected only for the fields a manifest names — see `diff --help`.", + "usage": "rpk ai agent apply [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "create", + "description": "Create an agent", + "usage": "rpk ai agent create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "credential", + "description": "Manage an agent's credentials (create, list, delete)", + "usage": "rpk ai agent credential [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "create", + "description": "Creates a client-id/secret pair for the agent. The client_secret is shown exactly once — save it now; it cannot be retrieved again.", + "usage": "rpk ai agent credential create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Deletes a credential. is the full resource name as shown by `list`/`create`, e.g. agents/my-agent/credentials/abc123. Idempotent.", + "usage": "rpk ai agent credential delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List an agent's credentials", + "usage": "rpk ai agent credential list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an agent", + "usage": "rpk ai agent delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "diff", + "description": "Dry-run of apply for agents. Prints, per manifest, whether apply would\ncreate, update (and which fields), or leave the resource unchanged. Exits\nnon-zero when any change is pending, so CI can gate on \"no drift\".\n\nNote: diff proves only that the fields a manifest names match live. It does not\ndetect resources that exist live but are absent from the manifests (no prune),\nnor drift in fields a manifest omits.", + "usage": "rpk ai agent diff [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Get an agent", + "usage": "rpk ai agent get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List agents", + "usage": "rpk ai agent list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "start", + "description": "Start a managed agent (desired_state=RUNNING)", + "usage": "rpk ai agent start [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "stop", + "description": "Stop a managed agent (desired_state=STOPPED)", + "usage": "rpk ai agent stop [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "transcript", + "description": "Inspect an agent's conversation transcripts (list, get)", + "usage": "rpk ai agent transcript [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "get", + "description": "Get a single conversation transcript with its turns", + "usage": "rpk ai agent transcript get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List an agent's conversation transcripts", + "usage": "rpk ai agent transcript list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "update", + "description": "Update an agent", + "usage": "rpk ai agent update [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "auth", + "description": "Manage rpai authentication (login, logout, token, status)", + "usage": "rpk ai auth [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "login", + "description": "Run the OAuth 2.0 device authorization grant against Redpanda Cloud's\ncloud-api, persist the resulting credentials to the rpai credentials file\n(0600), and — for new profiles — prompt to pick an ADP environment whose AI\nGateway URL becomes the profile's dataplane_url.\n\nIf the active profile's stored credentials are still valid, login is a\nno-op and prints \"Already logged in ...\". Log out first (or delete the\ncredential entry) to force a re-auth.", + "usage": "rpk ai auth login [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "logout", + "description": "Delete stored credentials for the current profile (or all)", + "usage": "rpk ai auth logout [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "status", + "description": "Show the authentication state for the current profile", + "usage": "rpk ai auth status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "token", + "description": "Print the current bearer access token to stdout (refreshes if expired)", + "usage": "rpk ai auth token [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "connection", + "description": "Manage OAuth connections — coming soon", + "usage": "rpk ai connection [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "list", + "description": "List OAuth connections — coming soon", + "usage": "rpk ai connection list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "revoke", + "description": "Revoke an OAuth connection — coming soon", + "usage": "rpk ai connection revoke [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "env", + "description": "Manage rpai environments (list, use, add, show, rename, delete)", + "usage": "rpk ai env [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "add", + "description": "Add a manual rpai environment with explicit URLs", + "usage": "rpk ai env add [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an environment from config and credentials files", + "usage": "rpk ai env delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List environments (local + live ADP environments, merged)", + "usage": "rpk ai env list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "rename", + "description": "Rename an environment in both config and credentials files", + "usage": "rpk ai env rename [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "show", + "description": "Show the effective resolved environment as YAML (tokens redacted)", + "usage": "rpk ai env show [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "use", + "description": "Switch to a local environment, or select an ADP environment by name or id", + "usage": "rpk ai env use [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "install", + "description": "Install the Redpanda AI CLI.\n\nThis command installs the latest version by default.\n\nAlternatively, you may specify an rpk ai version using the --ai-version flag.\n\nYou may force the installation using the --force flag.\n", + "usage": "rpk ai install [flags]", + "aliases": [], + "flags": [ + { + "name": "ai-version", + "type": "string", + "description": "Redpanda AI CLI version to install (e.g. 0.1.2)", + "default": "latest", + "required": false + }, + { + "name": "force", + "type": "bool", + "description": "Force install of the Redpanda AI CLI", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "llm", + "description": "Manage LLM providers registered with the Redpanda AI gateway.\n\nSupported provider types: openai, anthropic, google, bedrock.\n\nAliases: `llm-provider` (compat with aigwctl), `provider`, `lp`.\n\n\n\nSupported provider types: `openai`, `anthropic`, `google`, `bedrock`.", + "usage": "rpk ai llm [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "apply", + "description": "Reconcile LLM providers from one or more YAML manifests.\n\nFor each manifest: create the resource if absent, otherwise update only the\nfields that are present in the manifest AND differ from the live resource.\nFields you omit are left untouched; to clear a field, write it explicitly.\nLists, maps and oneof variants replace wholesale. Fields that can only be set\nat creation time are immutable; changing one is an error.\n\nManifests round-trip with `get -o yaml` for this resource. Pass -f - to\nread stdin.\n\nThis does not delete resources absent from the manifests (no prune), and drift\nis detected only for the fields a manifest names — see `diff --help`.", + "usage": "rpk ai llm apply [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "check", + "description": "Runs a lightweight probe against the upstream to verify credentials and reachability.", + "usage": "rpk ai llm check [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "create", + "description": "Create an LLM provider", + "usage": "rpk ai llm create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an LLM provider", + "usage": "rpk ai llm delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "diff", + "description": "Dry-run of apply for LLM providers. Prints, per manifest, whether apply would\ncreate, update (and which fields), or leave the resource unchanged. Exits\nnon-zero when any change is pending, so CI can gate on \"no drift\".\n\nNote: diff proves only that the fields a manifest names match live. It does not\ndetect resources that exist live but are absent from the manifests (no prune),\nnor drift in fields a manifest omits.", + "usage": "rpk ai llm diff [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Get an LLM provider", + "usage": "rpk ai llm get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List LLM providers", + "usage": "rpk ai llm list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "update", + "description": "Update an LLM provider", + "usage": "rpk ai llm update [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "mcp", + "description": "Manage MCP servers (create, get, list, update, delete, types)", + "usage": "rpk ai mcp [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "apply", + "description": "Reconcile MCP servers from one or more YAML manifests.\n\nFor each manifest: create the resource if absent, otherwise update only the\nfields that are present in the manifest AND differ from the live resource.\nFields you omit are left untouched; to clear a field, write it explicitly.\nLists, maps and oneof variants replace wholesale. Fields that can only be set\nat creation time are immutable; changing one is an error.\n\nManifests round-trip with `get -o yaml` for this resource. Pass -f - to\nread stdin.\n\nThis does not delete resources absent from the manifests (no prune), and drift\nis detected only for the fields a manifest names — see `diff --help`.", + "usage": "rpk ai mcp apply [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "create", + "description": "Create an MCP server", + "usage": "rpk ai mcp create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an MCP server", + "usage": "rpk ai mcp delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "diff", + "description": "Dry-run of apply for MCP servers. Prints, per manifest, whether apply would\ncreate, update (and which fields), or leave the resource unchanged. Exits\nnon-zero when any change is pending, so CI can gate on \"no drift\".\n\nNote: diff proves only that the fields a manifest names match live. It does not\ndetect resources that exist live but are absent from the manifests (no prune),\nnor drift in fields a manifest omits.", + "usage": "rpk ai mcp diff [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Get an MCP server", + "usage": "rpk ai mcp get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List MCP servers", + "usage": "rpk ai mcp list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "tools", + "description": "Interact with tools on an MCP server", + "usage": "rpk ai mcp tools [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "call", + "description": "Invoke a tool on an MCP server through the aigw MCP proxy.\n\nThe server's /mcp/v1/ endpoint is reached with the same bearer token\nused by the rest of rpai; aigw resolves user-delegated OAuth tokens from the\nvault when the MCP server is configured with --user-oauth-provider.\n\nArguments passed to the tool are a JSON object supplied via --args. Example:\n\n rpai mcp tools call gf-servicenow-sand2 listtablerecords \\\n --args '{\"tableName\":\"incident\",\"sysparm_limit\":3}'\n\nWith --code-mode the call targets the virtual code-mode sibling endpoint\n(/mcp/v1/-code). That endpoint exposes search (tool catalog for the\nprimary) and execute (runs JavaScript in a sandbox with call_tool bound to\nthe primary's tools). Example:\n\n rpai mcp tools call pg-garrett execute --code-mode \\\n --args '{\"code\":\"var r = call_tool({name:\\\"query\\\", arguments:{query:\\\"SELECT 1\\\"}}); JSON.stringify(r);\"}'\n", + "usage": "rpk ai mcp tools call [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List tools on an MCP server by calling tools/list through the aigw MCP proxy.\n\nHits the server's /mcp/v1/ endpoint, so the same auth and token-vault\npath used by tools/call is exercised here. Useful for checking that a managed\nMCP's tool schema loaded correctly and that a user-delegated server is\nreachable with the caller's vault token.\n\nWith --code-mode the session targets the virtual code-mode sibling endpoint\n(/mcp/v1/-code), which exposes the sandbox meta-tools (search,\nexecute). To see the parent's tool catalog from the sandbox, invoke the\nsearch tool explicitly:\n\n rpai mcp tools call search --code-mode\n", + "usage": "rpk ai mcp tools list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "types", + "description": "List available managed MCP types", + "usage": "rpk ai mcp types [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "update", + "description": "Update an MCP server", + "usage": "rpk ai mcp update [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "model", + "description": "Discover the models the Redpanda AI gateway exposes.\n\nThe catalog is read-only — `model list` and `model get` are the only verbs. The\ncatalog is populated from each LLM provider's metadata plus any extras the\noperator has pinned to a tenant.\n\nAliases: `models`, `m`.\n\n\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.", + "usage": "rpk ai model [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "get", + "description": "Get model details from the catalog", + "usage": "rpk ai model get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List available models in the catalog", + "usage": "rpk ai model list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "oauth-client", + "description": "Manage OAuth clients registered with the AI gateway's in-dataplane\nOAuth Authorization Server.\n\nAn OAuthClient is the external tool (Claude.ai, ChatGPT, Cursor, …) that\nrequests access tokens for an MCP. Create one per tool you want to allow\nin; the client_secret is returned exactly once on create and cannot be\nretrieved afterward. Rotate via delete + re-create until Phase 2 lands\na dedicated rotation RPC.\n\nAliases: `oauth-clients`, `oc`.\n\n\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.", + "usage": "rpk ai oauth-client [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "apply", + "description": "Reconcile OAuth clients from one or more YAML manifests.\n\nFor each manifest: create the resource if absent, otherwise update only the\nfields that are present in the manifest AND differ from the live resource.\nFields you omit are left untouched; to clear a field, write it explicitly.\nLists, maps and oneof variants replace wholesale. Fields that can only be set\nat creation time are immutable; changing one is an error.\n\nManifests round-trip with `get -o yaml` for this resource. Pass -f - to\nread stdin.\n\nThis does not delete resources absent from the manifests (no prune), and drift\nis detected only for the fields a manifest names — see `diff --help`.", + "usage": "rpk ai oauth-client apply [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "create", + "description": "Register an OAuth client. The generated client_secret is printed\nonce to stderr with a \"copy this now\" banner — it cannot be retrieved\nafterward. Store it in whatever secret manager the external tool uses.", + "usage": "rpk ai oauth-client create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "dcr", + "description": "Manage the tenant's Dynamic Client Registration policy.\n\nWhen DCR is enabled, spec-conformant MCP clients (Claude, Cursor, …)\nself-register at the public /oauth/idp/register endpoint — no admin\npre-provisioning. Admission is governed by the mode:\n\n open anyone may register (rate limit + client cap still apply)\n initial-access-token callers must present an admin-minted one-shot bearer\n software-statement reserved; not yet supported\n\nDCR is disabled per tenant by default; the gateway operator must also\nship the binary with the global ingress.idp.dcr.global_enabled flag.", + "usage": "rpk ai oauth-client dcr [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "get", + "description": "Show the tenant's DCR settings", + "usage": "rpk ai oauth-client dcr get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "iat", + "description": "Manage Initial Access Tokens (IATs) — one-shot bearer credentials a\ncaller presents to the public registration endpoint when the tenant's\nadmission mode is initial-access-token. The plaintext is printed\nexactly once on mint; only a hash is stored.", + "usage": "rpk ai oauth-client dcr iat [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "list", + "description": "List Initial Access Tokens (plaintext is never shown)", + "usage": "rpk ai oauth-client dcr iat list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "mint", + "description": "Mint a one-shot Initial Access Token", + "usage": "rpk ai oauth-client dcr iat mint [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "revoke", + "description": "Revoke an unconsumed Initial Access Token so it can no longer be\nexchanged at the registration endpoint. Idempotent — revoking an\nalready-revoked or consumed token returns 0.", + "usage": "rpk ai oauth-client dcr iat revoke [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "update", + "description": "Update the tenant's DCR settings. Only the flags you pass change;\neverything else keeps its current value (the CLI reads the current\nsettings and writes back the merged result).\n\nEnable open self-registration:\n\n rpai oauth-client dcr update --enabled --admission-mode open\n\nRequire admin-minted Initial Access Tokens instead:\n\n rpai oauth-client dcr update --admission-mode initial-access-token\n\nTurn the endpoint off again:\n\n rpai oauth-client dcr update --enabled=false", + "usage": "rpk ai oauth-client dcr update [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an OAuth client", + "usage": "rpk ai oauth-client delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "diff", + "description": "Dry-run of apply for OAuth clients. Prints, per manifest, whether apply would\ncreate, update (and which fields), or leave the resource unchanged. Exits\nnon-zero when any change is pending, so CI can gate on \"no drift\".\n\nNote: diff proves only that the fields a manifest names match live. It does not\ndetect resources that exist live but are absent from the manifests (no prune),\nnor drift in fields a manifest omits.", + "usage": "rpk ai oauth-client diff [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Get an OAuth client", + "usage": "rpk ai oauth-client get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List OAuth clients", + "usage": "rpk ai oauth-client list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "revoke-tokens", + "description": "Revoke every refresh token aigw has issued under . Forces\nall users that have connected this client to sign in again. Already-\nissued short-lived access tokens may continue working until natural\nexpiry (typically minutes).\n\nIdempotent: running again returns 0.", + "usage": "rpk ai oauth-client revoke-tokens [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "oauth-provider", + "description": "Manage OAuth authorization-server configurations registered with the Redpanda AI gateway.\n\nOAuth providers describe third-party authorization servers (GitHub, Google, Slack, ...)\nthat user-facing MCP servers can authenticate against via the device-consent flow.\n\nAliases: `oauth`, `op`.", + "usage": "rpk ai oauth-provider [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "apply", + "description": "Reconcile OAuth providers from one or more YAML manifests.\n\nFor each manifest: create the resource if absent, otherwise update only the\nfields that are present in the manifest AND differ from the live resource.\nFields you omit are left untouched; to clear a field, write it explicitly.\nLists, maps and oneof variants replace wholesale. Fields that can only be set\nat creation time are immutable; changing one is an error.\n\nManifests round-trip with `get -o yaml` for this resource. Pass -f - to\nread stdin.\n\nThis does not delete resources absent from the manifests (no prune), and drift\nis detected only for the fields a manifest names — see `diff --help`.", + "usage": "rpk ai oauth-provider apply [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "create", + "description": "Create an OAuth provider", + "usage": "rpk ai oauth-provider create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "delete", + "description": "Delete an OAuth provider", + "usage": "rpk ai oauth-provider delete [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "diff", + "description": "Dry-run of apply for OAuth providers. Prints, per manifest, whether apply would\ncreate, update (and which fields), or leave the resource unchanged. Exits\nnon-zero when any change is pending, so CI can gate on \"no drift\".\n\nNote: diff proves only that the fields a manifest names match live. It does not\ndetect resources that exist live but are absent from the manifests (no prune),\nnor drift in fields a manifest omits.", + "usage": "rpk ai oauth-provider diff [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "get", + "description": "Get an OAuth provider", + "usage": "rpk ai oauth-provider get [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "list", + "description": "List OAuth providers", + "usage": "rpk ai oauth-provider list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "update", + "description": "Update an OAuth provider", + "usage": "rpk ai oauth-provider update [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "run", + "description": "Launch a third-party coding agent configured to send its model traffic\nthrough the Redpanda AI gateway for the active profile, reusing rpai's\nlogin and auto-refreshing token.", + "usage": "rpk ai run [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "claude", + "description": "Launch Anthropic's Claude Code CLI with its model traffic\nrouted through the Redpanda AI gateway for the active rpai profile.\n\nrpai points ANTHROPIC_BASE_URL at the gateway's Anthropic Messages endpoint for\nthe chosen provider and wires the gateway auth for the life of the session. No\ntoken is ever written to disk.\n\nBoth auth modes run in your REAL Claude Code config home, so your workspace\ntrust, onboarding, theme, and MCP servers all apply. rpai writes nothing into\n~/.claude in either mode:\n\n - managed (api key): the gateway apiKeyHelper (`rpai auth token`, which Claude\n Code re-runs to refresh the bearer; aigw injects the upstream Anthropic key)\n is passed via `claude --settings` as a JSON string — off disk, merged on top\n of your settings, your ~/.claude/settings.json untouched.\n - passthrough (enterprise/Max subscription): your existing subscription login\n (stored under your config home) is used. rpai only sets the gateway base URL\n and the X-Redpanda-Cloud-Token header (minted fresh at launch) in the\n environment; your subscription OAuth flows through aigw to Anthropic untouched.\n\nPass --claude-config-dir to run against an isolated config home instead of your\nreal one (rpai still never writes into it).\n\nIn passthrough mode the X-Redpanda-Cloud-Token gateway JWT is set in the\nlaunched process environment, so Claude Code's tool subprocesses (Bash, hooks,\nMCP) inherit it — the same Redpanda Cloud token any process running as you can\nalready mint with `rpai auth token`, and Claude Code has no documented mechanism\nto scrub it from those subprocesses.\n\nBecause passthrough uses your real config home, any auth configured in your\n~/.claude/settings.json (an apiKeyHelper, or env.ANTHROPIC_AUTH_TOKEN) still\napplies and outranks the subscription OAuth aigw needs to relay — rpai scrubs\nonly the inherited shell env, not your on-disk settings.\n\nAnthropic and Bedrock providers are supported. A bedrock provider launches\nClaude Code in its native Bedrock mode pointed at the same gateway prefix; aigw\nsigns the upstream call with the provider's AWS credentials (SigV4), so no AWS\nkeys ever reach your machine and the managed apiKeyHelper auth works exactly as\nabove (passthrough does not apply — there is no Bedrock analog of a Claude\nsubscription). Pass -m an inference-profile id from the provider's model\nallowlist (Bedrock Anthropic models 4.6+ carry a us./eu./apac./global. prefix).\nClaude Code's background (small/fast) model defaults to a Haiku-class inference\nprofile in Bedrock mode; if the provider's allowlist doesn't include it, export\nANTHROPIC_SMALL_FAST_MODEL with an allowlisted id.\n\nPass Claude Code's own flags after a literal --:\n\n rpai run claude -L anthropic -m claude-sonnet-4-6 -- --permission-mode plan\n rpai run claude -L bedrock -m us.anthropic.claude-sonnet-4-6 -- -p \"hi\"", + "usage": "rpk ai run claude [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + }, + { + "name": "codex", + "description": "Launch the OpenAI Codex CLI with its model traffic routed\nthrough the Redpanda AI gateway for the active rpai profile.\n\nrpai generates a throwaway Codex config in a temporary CODEX_HOME, points it at\nthe gateway's OpenAI-compatible Responses endpoint for the chosen provider, and\nwires Codex's bearer to `rpai auth token` so it refreshes itself for the\nlife of the session. Your own ~/.codex config is never read or modified, and no\ntoken is written to disk.\n\nThe launch directory is auto-trusted under a workspace-write sandbox\n(approval_policy=on-request) so the fresh CODEX_HOME doesn't prompt for trust on\nevery run; pass --no-auto-trust to keep Codex's normal first-run trust prompt.\n\nOnly openai / openai_compatible providers are supported (Codex speaks the OpenAI\nResponses API). Pass Codex's own flags after a literal --:\n\n rpai run codex -L openai -m gpt-5.3-codex -e high -- --ask-for-approval never", + "usage": "rpk ai run codex [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux" + ] + }, + { + "name": "uninstall", + "description": "Uninstall the Redpanda AI CLI", + "usage": "rpk ai uninstall [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "upgrade", + "description": "Upgrade to the latest Redpanda AI CLI version", + "usage": "rpk ai upgrade [flags]", + "aliases": [], + "flags": [ + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt for major version upgrades", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "version", + "description": "Print rpai version and commit", + "usage": "rpk ai version [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "cloud", + "description": "Interact with Redpanda cloud", + "usage": "rpk cloud [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "auth", + "description": "Manage rpk cloud authentications.\n\nAn rpk cloud authentication allows you to talk to Redpanda Cloud. Most likely,\nyou will only ever need to use a single SSO based login and you will not need\nthis command space. Multiple authentications can be useful if you have multiple\nRedpanda Cloud accounts for different organizations and want to swap between\nthem, or if you use SSO as well as client credentials. It is recommended to\nonly use a single SSO based login.\n", + "usage": "rpk cloud auth [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "delete", + "description": "Delete an rpk cloud authentication.\n\nDeleting a cloud authentication removes it from the rpk.yaml file. If the\ndeleted auth was the current authentication, rpk will use a default SSO auth the\nnext time you try to login and save that auth.\n\nIf you delete an authentication that is used by profiles, affected profiles have\ntheir authentication cleared and you will only be able to access the profile's\ncluster using SASL credentials.\n", + "usage": "rpk cloud auth delete [NAME] [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "list", + "description": "List rpk cloud authentications", + "usage": "rpk cloud auth list [flags]", + "aliases": [ + "ls" + ], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "token", + "description": "Print the cloud auth token of the current profile.\n\nThis command prints the auth token for the currently selected cloud\nauthentication to stdout. This is useful for piping the token into other\ncommands or scripts that need to authenticate with Redpanda Cloud.", + "usage": "rpk cloud auth token [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "use", + "description": "Select the rpk cloud authentication to use.\n\nThis swaps the current cloud authentication to the specified cloud\nauthentication. If your current profile is a cloud profile, this unsets the\ncurrent profile (since the authentication is now different). If your current\nprofile is for a self hosted cluster, the profile is kept.\n", + "usage": "rpk cloud auth use [NAME] [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "byoc", + "description": "Manage a Redpanda cloud BYOC agent\n\nFor BYOC, Redpanda installs an agent service in your owned cluster. The agent\nthen proceeds to provision further infrastructure and eventually, a full\nRedpanda cluster.\n\nThe BYOC command runs Terraform to create and start the agent. You first need\na redpanda-id (or cluster ID); this is used to get the details of how your\nagent should be provisioned. You can create a BYOC cluster in our cloud UI\nand then come back to this command to complete the process.\n", + "usage": "rpk cloud byoc [flags]", + "aliases": [], + "flags": [ + { + "name": "client-id", + "type": "string", + "description": "The client ID of the organization in Redpanda Cloud", + "default": "", + "required": false + }, + { + "name": "client-secret", + "type": "string", + "description": "The client secret of the organization in Redpanda Cloud", + "default": "", + "required": false + }, + { + "name": "redpanda-id", + "type": "string", + "description": "The redpanda ID of the cluster you are creating", + "default": "", + "required": false + } + ], + "commands": [ + { + "name": "install", + "description": "Install the BYOC plugin\n\nThis command downloads the BYOC managed plugin if necessary. The plugin is\ninstalled by default if you try to run a non-install command, but this command\nexists if you want to download the plugin ahead of time.\n", + "usage": "rpk cloud byoc install [flags]", + "aliases": [], + "flags": [ + { + "name": "redpanda-id", + "type": "string", + "description": "The redpanda ID of the cluster you are creating", + "default": "", + "required": true + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "uninstall", + "description": "Uninstall the BYOC plugin\n\nThis command deletes your locally downloaded BYOC managed plugin if it exists.\nOften, you only need to download the plugin to create your cluster once, and\nthen you never need the plugin again. You can uninstall to save a small bit of\ndisk space.\n", + "usage": "rpk cloud byoc uninstall [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "cluster", + "description": "Manage rpk cloud clusters.\n\nThis command allows you to manage cloud clusters, as well as easily switch\nbetween which cluster you are talking to.\n", + "usage": "rpk cloud cluster [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "select", + "description": "Update your rpk profile to talk to the requested cluster.\n\nThis command is essentially an alias for the following command:\n\n rpk profile create --from-cloud=${NAME}\n\nIf you want to name this profile rather than creating or updating values in\nthe default cloud-dedicated profile, you can use the --profile flag.\n\nFor serverless clusters that support both public and private networking, you\nwill be prompted to select a network type unless you specify --serverless-network.\nTo avoid prompts in automation, explicitly set --serverless-network to 'public'\nor 'private'.\n", + "usage": "rpk cloud cluster select [NAME] [flags]", + "aliases": [ + "use" + ], + "flags": [ + { + "name": "profile", + "type": "string", + "description": "Name of a profile to create or update (avoids updating \"rpk-cloud\")", + "default": "", + "required": false + }, + { + "name": "serverless-network", + "type": "string", + "description": "Networking type for serverless clusters: 'public' or 'private' (if not specified, will prompt if both are available)", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "login", + "description": "Log in to the Redpanda cloud\n\nThis command checks for an existing Redpanda Cloud API token and, if present, \nensures it is still valid. If no token is found or the token is no longer valid, \nthis command will login and save your token along with the client ID used to \nrequest the token.\n\nYou may use either SSO or client credentials to log in.\n\nSSO\n\nThis will automatically launch your default web browser and prompt you to \nauthenticate via our Redpanda Cloud page. Once you have successfully \nauthenticated, you will be ready to use rpk cloud commands.\n\nYou may opt out of auto-opening the browser by passing the '--no-browser' flag.\n\nCLIENT CREDENTIALS\n\nCloud client credentials can be used to login to Redpanda, they can be created \nin the Clients tab of the Users section in the Redpanda Cloud online interface. \nclient credentials can be provided in three ways, in order of preference:\n\n* In your rpk cloud auth, 'client_id' and 'client_secret' fields\n* Through RPK_CLOUD_CLIENT_ID and RPK_CLOUD_CLIENT_SECRET environment variables\n* Through the --client-id and --client-secret flags\n\nIf none of these are provided, rpk will use the SSO method to login. \nIf you specify environment variables or flags, they will not be synced to the\nrpk.yaml file unless the --save flag is passed. The cloud authorization \ntoken and client ID is always synced.\n", + "usage": "rpk cloud login [flags]", + "aliases": [], + "flags": [ + { + "name": "client-id", + "type": "string", + "description": "The client ID of the organization in Redpanda Cloud", + "default": "", + "required": false + }, + { + "name": "client-secret", + "type": "string", + "description": "The client secret of the organization in Redpanda Cloud", + "default": "", + "required": false + }, + { + "name": "no-browser", + "type": "bool", + "description": "Opt out of auto-opening authentication URL", + "default": false, + "required": false + }, + { + "name": "no-profile", + "type": "bool", + "description": "Skip automatic profile creation and any associated prompts", + "default": false, + "required": false + }, + { + "name": "save", + "type": "bool", + "description": "Save environment or flag specified client ID and client secret to the configuration file", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "logout", + "description": "Log out from Redpanda cloud\n\nThis command deletes your cloud auth token. If you want to log out entirely and\nswitch to a different organization, you can use the --clear-credentials flag to\nadditionally clear your client ID and client secret.\n\nYou can use the --all flag to log out of all organizations you may be logged\ninto.\n", + "usage": "rpk cloud logout [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "shorthand": "a", + "type": "bool", + "description": "Log out of all organizations you may be logged into, rather than just the current auth's organization", + "default": false, + "required": false + }, + { + "name": "clear-credentials", + "shorthand": "c", + "type": "bool", + "description": "Clear the client ID and client secret in addition to the auth token", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "mcp", + "description": "Manage Redpanda Cloud MCP server", + "usage": "rpk cloud mcp [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "install", + "description": "Install Redpanda Cloud MCP server.\n\t\t\nSupports Claude Desktop and Claude Code.\nWrites an mcpServer entry with name \"redpandaCloud\" into the appropriate config file.", + "usage": "rpk cloud mcp install [flags]", + "aliases": [], + "flags": [ + { + "name": "allow-delete", + "type": "bool", + "description": "Allow delete RPCs", + "default": false, + "required": false + }, + { + "name": "client", + "type": "string", + "description": "Name of the MCP client to configure", + "default": "claude", + "required": true + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "proxy", + "description": "Proxy MCP requests to a remote Redpanda Cloud MCP server.\n\nThis command connects to a specific cluster and MCP server running in that cluster,\nthen proxies MCP requests from stdio to the remote MCP server over HTTP.\n\nUse --install to configure the MCP client instead of serving stdio.", + "usage": "rpk cloud mcp proxy [flags]", + "aliases": [], + "flags": [ + { + "name": "client", + "type": "string", + "description": "Name of the MCP client to configure (required with --install)", + "default": "", + "required": false + }, + { + "name": "cluster-id", + "type": "string", + "description": "Cluster ID to connect to", + "default": "", + "required": false + }, + { + "name": "install", + "type": "bool", + "description": "Install MCP proxy configuration instead of serving stdio", + "default": false, + "required": false + }, + { + "name": "mcp-server-id", + "type": "string", + "description": "MCP Server ID to proxy to", + "default": "", + "required": true + }, + { + "name": "serverless-cluster-id", + "type": "string", + "description": "Serverless cluster ID to connect to", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "stdio", + "description": "MCP stdio server. Can be used by MCP clients.", + "usage": "rpk cloud mcp stdio [flags]", + "aliases": [], + "flags": [ + { + "name": "allow-delete", + "type": "bool", + "description": "Allow delete RPCs. Off by default", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "cluster", + "description": "Manage and inspect Redpanda cluster configuration, health, and maintenance operations.", + "usage": "rpk cluster [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "config", + "description": "View and modify cluster-wide configuration properties. Changes take effect across all brokers.", + "usage": "rpk cluster config [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "edit", + "description": "Edit cluster-wide configuration properties.\n\nThis command opens a text editor to modify the cluster's configuration.\n\nCluster properties are redpanda settings which apply to all nodes in\nthe cluster. These are separate to node properties, which are set with\n'rpk redpanda config'.\n\nModified values are written back when the file is saved and the editor\nis closed. Properties which are deleted are reset to their default\nvalues.\n\nBy default, low level tunables are excluded: use the '--all' flag\nto edit all properties including these tunables.\n", + "usage": "rpk cluster config edit [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "type": "bool", + "description": "Include all properties, including tunables", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "export", + "description": "Export cluster configuration.\n\nWrites out a YAML representation of the cluster configuration to a file,\nsuitable for editing and later applying with the corresponding 'import'\ncommand.\n\nBy default, low level tunables are excluded: use the '--all' flag\nto include all properties including these low level tunables.\n", + "usage": "rpk cluster config export [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "type": "bool", + "description": "Include all properties, including tunables", + "default": false, + "required": false + }, + { + "name": "filename", + "shorthand": "f", + "type": "string", + "description": "path to file to export to, e.g. './config.yml'", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "force-reset", + "description": "Forcibly clear a cluster configuration property on this node.\n\nThis command is not for general changes to cluster configuration: use this only\nwhen redpanda will not start due to a configuration issue.\n\nIf your cluster is working properly and you would like to reset a property\nto its default, you may use the 'set' command with an empty string, or\nuse the 'edit' command and delete the property's line.\n\nThis command erases a named property from an internal cache of the cluster\nconfiguration on the local node, so that on next startup redpanda will treat\nthe setting as if it was set to the default.\n\nWARNING: this should only be used when redpanda is not running.\n", + "usage": "rpk cluster config force-reset [PROPERTY...] [flags]", + "aliases": [], + "flags": [ + { + "name": "cache-file", + "type": "string", + "description": "location of configuration cache file (defaults to redpanda data directory)", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "get", + "description": "Get a cluster configuration property.", + "usage": "rpk cluster config get [KEY] [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + }, + { + "name": "import", + "description": "Import cluster configuration from a file.\n\nImport configuration from a YAML file, usually generated with\ncorresponding 'export' command. This downloads the current cluster\nconfiguration, calculates the difference with the YAML file, and\nupdates any properties that were changed. If a property is removed\nfrom the YAML file, it is reset to its default value. ", + "usage": "rpk cluster config import [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "type": "bool", + "description": "Include all properties, including tunables", + "default": false, + "required": false + }, + { + "name": "filename", + "shorthand": "f", + "type": "string", + "description": "full path to file to import, e.g. '/tmp/config.yml'", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "lint", + "description": "Remove any deprecated content from redpanda.yaml.\n\nDeprecated content includes properties which were set via redpanda.yaml\nin earlier versions of redpanda, but are now managed via Redpanda's\ncentral configuration store (and via 'rpk cluster config edit').\n", + "usage": "rpk cluster config lint [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "list", + "description": "List cluster configuration properties.\n\nThis command lists all available cluster configuration properties. Use the 'get'\ncommand to retrieve specific property values, or 'edit' for interactive editing.\n\nUse the --filter flag with a regular expression to filter configuration keys.", + "usage": "rpk cluster config list [flags]", + "aliases": [], + "examples": "\nList all cluster configuration properties:\n rpk cluster config list\n\nList configuration properties matching a filter:\n rpk cluster config list --filter=\"kafka.*\"\n\nList configuration properties in JSON format:\n rpk cluster config list --format=json\n\nList configuration properties in YAML format:\n rpk cluster config list --format=yaml", + "flags": [ + { + "name": "filter", + "type": "string", + "description": "Filter configuration keys using regular expression", + "default": "", + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + } + ] + }, + { + "name": "set", + "description": "Set a single cluster configuration property.\n\nThis command is provided for use in scripts. For interactive editing, or bulk\nchanges, use the 'edit' and 'import' commands respectively.\n\nYou may also use = notation for setting configuration properties:\n\n rpk cluster config set log_retention_ms=-1\n\nIf an empty string is given as the value, the property is reset to its default.\nUse the flag '--no-confirm' to avoid the confirmation prompt.", + "usage": "rpk cluster config set [KEY] [VALUE] [flags]", + "aliases": [], + "flags": [ + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt", + "default": false, + "required": false + }, + { + "name": "timeout", + "type": "duration", + "description": "Maximum time to poll for operation completion before displaying operation ID for manual status checking (e.g. 300ms, 1.5s, 30s)", + "default": "10s", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + } + ] + }, + { + "name": "status", + "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.", + "usage": "rpk cluster config status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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----" + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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`." + } + ] + }, + { + "name": "connections", + "description": "Manage and monitor cluster connections.", + "usage": "rpk cluster connections [flags]", + "aliases": [ + "connection" + ], + "flags": [], + "commands": [ + { + "name": "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`.", + "usage": "rpk cluster connections list [flags]", + "aliases": [], + "examples": "\nList connections ordered by their recent produce throughput:\n\trpk cluster connections list --order-by=\"recent_request_statistics.produce_bytes desc\"\n\nList connections ordered by their recent fetch throughput:\n\trpk cluster connections list --order-by=\"recent_request_statistics.fetch_bytes desc\"\n\nList connections ordered by the time that they've been idle:\n\trpk cluster connections list --order-by=\"idle_duration desc\"\n\nList connections ordered by those that have made the least requests:\n\trpk cluster connections list --order-by=\"total_request_statistics.request_count asc\"\n\nList extended output for open connections in json format:\n\trpk cluster connections list --format=json --state=\"OPEN\"", + "flags": [ + { + "name": "client-id", + "type": "string", + "description": "Filter results by the client ID", + "default": "", + "required": false + }, + { + "name": "client-software-name", + "type": "string", + "description": "Filter results by the client software name", + "default": "", + "required": false + }, + { + "name": "client-software-version", + "type": "string", + "description": "Filter results by the client software version", + "default": "", + "required": false + }, + { + "name": "filter-raw", + "type": "string", + "description": "Filter connections based on a raw query (overrides other filters)", + "default": "", + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "group-id", + "shorthand": "g", + "type": "string", + "description": "Filter by client group ID", + "default": "", + "required": false + }, + { + "name": "idle-ms", + "shorthand": "i", + "type": "int64", + "description": "Show connections idle for more than i milliseconds", + "default": 0, + "required": false + }, + { + "name": "ip-address", + "type": "string", + "description": "Filter results by the client ip address", + "default": "", + "required": false + }, + { + "name": "limit", + "type": "int32", + "description": "Limit how many records can be returned", + "default": 20, + "required": false + }, + { + "name": "order-by", + "type": "string", + "description": "Order the results by their values. See Examples above", + "default": "", + "required": false + }, + { + "name": "state", + "shorthand": "s", + "type": "string", + "description": "Filter results by state (OPEN, CLOSED)", + "default": "", + "required": false + }, + { + "name": "user", + "shorthand": "u", + "type": "string", + "description": "Filter results by a specific user principal", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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\"" + } + ] + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "health", + "description": "Queries cluster health overview. Health overview is created based on health reports collected periodically from all nodes in the cluster.", + "usage": "rpk cluster health [flags]", + "aliases": [], + "examples": "\nBasic usage, get cluster health information:\n rpk cluster health\n\nGet cluster health information and watch for changes:\n rpk cluster health --watch\n\nGet cluster health information and exit when the cluster is healthy:\n rpk cluster health --exit-when-healthy\n", + "flags": [ + { + "name": "exit-when-healthy", + "shorthand": "e", + "type": "bool", + "description": "Exit with status 0 when the cluster becomes healthy. Useful for scripts waiting for cluster readiness.", + "default": false, + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "watch", + "shorthand": "w", + "type": "bool", + "description": "Continuously monitor health status, refreshing at the specified interval.", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + }, + { + "name": "info", + "description": "Request broker metadata information.\n\nThe Kafka protocol's metadata contains information about brokers, topics, and\nthe cluster as a whole.\n\nThis command only runs if specific sections of metadata are requested. There\nare currently three sections: the cluster, the list of brokers, and the topics.\nIf no section is specified, this defaults to printing all sections.\n\nIf the topic section is requested, all topics are requested by default unless\nsome are manually specified as arguments. Expanded per-partition information\ncan be printed with the -d flag, and internal topics can be printed with the -i\nflag.\n\nIn the broker section, the controller node is suffixed with *.\n\nUsing this command with --format json/yaml implies that all sections are \nincluded.\n", + "usage": "rpk cluster info [flags]", + "aliases": [ + "status", + "metadata" + ], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "print-brokers", + "shorthand": "b", + "type": "bool", + "description": "Print brokers section", + "default": false, + "required": false + }, + { + "name": "print-cluster", + "shorthand": "c", + "type": "bool", + "description": "Print cluster section", + "default": false, + "required": false + }, + { + "name": "print-detailed-topics", + "shorthand": "d", + "type": "bool", + "description": "Print per-partition information for topics (implies -t)", + "default": false, + "required": false + }, + { + "name": "print-internal-topics", + "shorthand": "i", + "type": "bool", + "description": "Print internal topics (if all topics requested, implies -t)", + "default": false, + "required": false + }, + { + "name": "print-topics", + "shorthand": "t", + "type": "bool", + "description": "Print topics section (implied if any topics are specified)", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-metadata.adoc" + }, + { + "name": "license", + "description": "Manage cluster license", + "usage": "rpk cluster license [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "info", + "description": "Retrieve license information:\n\n Organization: Organization the license was generated for.\n Type: Type of license: free, enterprise, etc.\n Expires: Expiration date of the license.\n License Status: Status of the loaded license (valid, expired, not_present).\n Violation: Whether the cluster is using enterprise features without\n a valid license.\n", + "usage": "rpk cluster license info [flags]", + "aliases": [ + "status" + ], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "set", + "description": "Upload a license to the cluster using a file path, inline string, or default location.", + "usage": "rpk cluster license set [flags]", + "aliases": [], + "flags": [ + { + "name": "path", + "type": "string", + "description": "Path to the license file", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "logdirs", + "description": "Describe log directories on Redpanda brokers", + "usage": "rpk cluster logdirs [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "describe", + "description": "Describe log directories on Redpanda brokers.\n\nThis command prints information about log directories on brokers, particularly,\nthe base directory that topics and partitions are located in, and the size of\ndata that has been written to the partitions. The size you see may not exactly\nmatch the size on disk as reported by du: Redpanda allocates files in chunks.\nThe chunks will show up in du, while the actual bytes so far written to the\nfile will show up in this command.\n\nThe directory returned is the root directory for partitions. Within Redpanda,\nthe partition data lives underneath the the returned root directory in\n\n kafka/{topic}/{partition}_{revision}/\n\nwhere revision is a Redpanda internal concept.\n", + "usage": "rpk cluster logdirs describe [flags]", + "aliases": [], + "flags": [ + { + "name": "aggregate-into", + "type": "string", + "description": "If non-empty, what column to aggregate into starting from the partition column (broker, dir, topic)", + "default": "", + "required": false + }, + { + "name": "broker", + "shorthand": "b", + "type": "int32", + "description": "If non-negative, the specific broker to describe", + "default": -1, + "required": false + }, + { + "name": "human-readable", + "shorthand": "H", + "type": "bool", + "description": "Print the logdirs size in a human-readable form", + "default": false, + "required": false + }, + { + "name": "sort-by-size", + "type": "bool", + "description": "If true, sort by size", + "default": false, + "required": false + }, + { + "name": "topics", + "type": "stringSlice", + "description": "Specific topics to describe", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "maintenance", + "description": "Manage cluster maintenance mode for performing rolling upgrades and other maintenance operations.", + "usage": "rpk cluster maintenance [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "disable", + "description": "Disable maintenance mode on a broker, allowing it to resume normal operations and accept partition assignments.", + "usage": "rpk cluster maintenance disable [BROKER-ID] [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "enable", + "description": "Enable maintenance mode on a broker. The broker drains leadership and stops accepting new partition assignments.", + "usage": "rpk cluster maintenance enable [BROKER-ID] [flags]", + "aliases": [], + "flags": [ + { + "name": "wait", + "shorthand": "w", + "type": "bool", + "description": "Wait for the node to finish draining before returning. Useful for scripted rolling operations.", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "status", + "description": "Report maintenance status.\n\nThis command reports maintenance status for each node in the cluster. The output\nis presented as a table with each row representing a node in the cluster. The\noutput can be used to monitor the progress of node draining.\n\n NODE-ID ENABLED FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED\n 1 false false false 0 0 0 0\n\nField descriptions:\n\n NODE-ID: the node ID\n ENABLED: true if the node is currently in maintenance mode\n FINISHED: leadership draining has completed\n ERRORS: errors have been encountered while draining\n PARTITIONS: number of partitions whose leadership has moved\n ELIGIBLE: number of partitions with leadership eligible to move\n TRANSFERRING: current active number of leadership transfers\n FAILED: number of failed leadership transfers\n\nNotes:\n\n - When errors are present further information will be available in the logs\n for the corresponding node.\n\n - Only partitions with more than one replica are eligible for leadership\n transfer.\n", + "usage": "rpk cluster maintenance status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "partitions", + "description": "Manage cluster partitions", + "usage": "rpk cluster partitions [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "balance", + "description": "Triggers on-demand partition balancing.\n\nThis command allows you to trigger on-demand partition balancing.\n\nWith Redpanda Community Edition, the partition count on each broker\ncan easily become uneven, which leads to data skewing. To distribute\npartitions across brokers, you can run this command to trigger\non-demand partition balancing.\n\nWith Redpanda Enterprise Edition, Continuous Data Balancing monitors\nbroker and rack availability, as well as disk usage, to avoid topic\nhotspots. However, there are edge cases where users should manually\ntrigger partition balancing (such as a node becoming unavailable for\na prolonged time and rejoining the cluster thereafter). In such cases,\nyou should run this command to trigger partition balancing manually.\n\nAfter you run this command, monitor the balancer progress using:\n\n rpk cluster partitions balancer-status\n\nTo see more detailed movement status, monitor the progress using:\n\n rpk cluster partitions move-status\n", + "usage": "rpk cluster partitions balance [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "balancer-status", + "description": "Queries cluster for partition balancer status:\n\nIf continuous partition balancing is enabled, redpanda will continuously\nreassign partitions from both unavailable nodes and from nodes using more disk\nspace than the configured limit.\n\nUse this command to monitor the partition balancer status and\nthe partition distribution across brokers in the cluster.\n\nFIELDS\n\n Status: Either off, ready, starting, in progress, or\n stalled.\n Seconds Since Last Tick: The last time the partition balancer ran.\n Current Reassignments Count: Current number of partition reassignments in\n progress.\n Unavailable Nodes: The nodes that have been unavailable after a\n time set by the\n \"partition_autobalancing_node_availability_timeout_sec\"\n cluster property.\n Over Disk Limit Nodes: The nodes that surpassed the threshold of\n used disk percentage specified in the\n \"partition_autobalancing_max_disk_usage_percent\"\n cluster property.\n\nBALANCER STATUS\n\n off: The balancer is disabled.\n ready: The balancer is active but there is nothing to do.\n starting: The balancer is starting but has not run yet.\n in_progress: The balancer is active and is in the process of scheduling\n partition movements.\n stalled: Violations have been detected and the balancer cannot correct\n them.\n\nSTALLED BALANCER\n\nA stalled balancer can occur for a few reasons and requires a bit of manual\ninvestigation. A few areas to investigate:\n\n* Are there are enough healthy nodes to which to move partitions? For example,\n in a three node cluster, no movements are possible for partitions with three\n replicas. You will see a stall every time there is a violation.\n\n* Does the cluster have sufficient space? If all nodes in the cluster are\n utilizing more than 80% of their disk space, rebalancing cannot proceed.\n\n* Do all partitions have quorum? If the majority of a partition's replicas are\n down, the partition cannot be moved.\n\n* Are any nodes in maintenance mode? Partitions are not moved if any node is in\n maintenance mode.\n", + "usage": "rpk cluster partitions balancer-status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "disable", + "description": "Disable partitions of a topic\n\nYou may disable all partitions of a topic using the --all flag or you may select \na set of topic/partitions to disable with the '--partitions/-p' flag.\n\nThe partition flag accepts the format {namespace}/{topic}/[partitions...]\nwhere namespace and topic are optional parameters. If the namespace is not\nprovided, rpk will assume 'kafka'. If the topic is not provided in the flag, rpk\nwill use the topic provided as an argument to this command.\n\nDISABLED PARTITIONS\n\nDisabling a partition in Redpanda involves prohibiting any data consumption or\nproduction to and from it. All internal processes associated with the partition\nare stopped, and it remains unloaded during system startup. This measure aims to\nmaintain cluster health by preventing issues caused by specific corrupted\npartitions that may lead to Redpanda crashes. Although the data remains stored\non disk, Redpanda ceases interaction with the disabled partitions to ensure\nsystem stability.\n\nEXAMPLES\n\nDisable all partitions in topic 'foo'\n rpk cluster partitions disable foo --all\n\nDisable partitions 1,2 and 3 of topic 'bar' in the namespace 'internal'\n rpk cluster partitions disable internal/bar --partitions 1,2,3\n\nDisable partition 1, and 2 of topic 'foo', and partition 5 of topic 'bar' in the \n'internal' namespace' \n rpk cluster partitions disable -p foo/1,2 -p internal/bar/5\n", + "usage": "rpk cluster partitions disable [TOPIC] [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "shorthand": "a", + "type": "bool", + "description": "If true, disable all partitions for the specified topic", + "default": false, + "required": false + }, + { + "name": "partitions", + "shorthand": "p", + "type": "stringArray", + "description": "Comma-separated list of partitions you want to disable. Use --help for additional information", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "enable", + "description": "Enable partitions of a topic\n\nYou may enable all partitions of a topic using the --all flag or you may select \na set of topic/partitions to enable with the '--partitions/-p' flag.\n\nThe partition flag accepts the format {namespace}/{topic}/[partitions...]\nwhere namespace and topic are optional parameters. If the namespace is not\nprovided, rpk will assume 'kafka'. If the topic is not provided in the flag, rpk\nwill use the topic provided as an argument to this command.\n\nEXAMPLES\n\nEnable all partitions in topic 'foo'\n rpk cluster partitions enable foo --all\n\nEnable partitions 1,2 and 3 of topic 'bar' in the namespace 'internal'\n rpk cluster partitions enable internal/bar --partitions 1,2,3\n\nEnable partition 1, and 2 of topic 'foo', and partition 5 of topic 'bar' in the \n'internal' namespace'\n rpk cluster partitions enable -p foo/1,2 -p internal/bar/5\n", + "usage": "rpk cluster partitions enable [TOPIC] [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "shorthand": "a", + "type": "bool", + "description": "If true, enable all partitions for the specified topic", + "default": false, + "required": false + }, + { + "name": "partitions", + "shorthand": "p", + "type": "stringArray", + "description": "Comma-separated list of partitions you want to enable. Check help for extended usage", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "list", + "description": "List partitions in the cluster\n\nThis commands lists the cluster-level metadata of all partitions in the cluster.\nIt shows the current replica assignments on both brokers and CPU cores for given\ntopics. By default, it assumes the \"kafka\" namespace, but you can specify an\ninternal namespace using the \"{namespace}/\" prefix.\n\nThe REPLICA-CORE column displayed in the output table contains a list of\nreplicas assignments in the form of: -.\n\nIf the DISABLED column contains a '-' value, then it means you are running this\ncommand against a cluster that does not support the underlying API.\n\nENABLED/DISABLED\n\nDisabling a partition in Redpanda involves prohibiting any data consumption or\nproduction to and from it. All internal processes associated with the partition\nare stopped, and it remains unloaded during system startup. This measure aims to\nmaintain cluster health by preventing issues caused by specific corrupted\npartitions that may lead to Redpanda crashes. Although the data remains stored\non disk, Redpanda ceases interaction with the disabled partitions to ensure\nsystem stability.\n\nYou may disable/enable partition using 'rpk cluster partitions enable/disable'.\t\n\nEXAMPLES\n\nList all partitions in the cluster.\n rpk cluster partitions list --all\n\nList all partitions in the cluster, filtering for topic foo and bar.\n rpk cluster partitions list foo bar\n\nList partitions which replicas are assigned to brokers 1 and 2.\n rpk cluster partitions list foo --node-ids 1,2\n\nList only the disabled partitions.\n rpk cluster partitions list -a --disabled-only\n\nList all in json format.\n rpk cluster partition list -a --format json\n", + "usage": "rpk cluster partitions list [TOPICS...] [flags]", + "aliases": [ + "ls", + "describe" + ], + "flags": [ + { + "name": "all", + "shorthand": "a", + "type": "bool", + "description": "If true, list all partitions in the cluster", + "default": false, + "required": false + }, + { + "name": "disabled-only", + "type": "bool", + "description": "If true, list disabled partitions only", + "default": false, + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "node-ids", + "shorthand": "n", + "type": "intSlice", + "description": "List of comma-separated broker IDs that you wish to filter the results with", + "default": [], + "required": false + }, + { + "name": "partition", + "shorthand": "p", + "type": "intSlice", + "description": "List of comma-separated partitions IDs that you wish to filter the results with", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "move", + "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.", + "usage": "rpk cluster partitions move [flags]", + "aliases": [], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "partition", + "shorthand": "p", + "type": "stringArray", + "description": "Topic partitions to move and new replica locations (repeatable)", + "default": [], + "required": true + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement.adoc", + "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" + } + ] + } + ] + } + ] + }, + { + "name": "move-cancel", + "description": "Cancel ongoing partition movements.\n\nBy default, this command cancels all the partition movements in the cluster. \nTo ensure that you do not accidentally cancel all partition movements, this \ncommand prompts users for confirmation before issuing the cancellation request. \nYou can use \"--no-confirm\" to disable the confirmation prompt:\n\n rpk cluster partitions move-cancel --no-confirm\n\nIf \"--node\" is set, this command will only stop the partition movements \noccurring in the specified node:\n\n rpk cluster partitions move-cancel --node 1\n", + "usage": "rpk cluster partitions move-cancel [flags]", + "aliases": [ + "alter-cancel" + ], + "flags": [ + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt", + "default": false, + "required": false + }, + { + "name": "node", + "type": "int", + "description": "ID of a specific node on which to cancel ongoing partition movements", + "default": -1, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement-cancel.adoc" + }, + { + "name": "move-status", + "description": "Show ongoing partition movements.\n\nBy default this command lists all ongoing partition movements in the cluster.\nTopics can be specified to print the move status of specific topics. By default,\nthis command assumes the \"kafka\" namespace, but you can use a \"namespace/\" to\nspecify internal namespaces.\n\n rpk cluster partitions move-status\n rpk cluster partitions move-status foo bar kafka_internal/tx\n\nThe \"--partition / -p\" flag can be used with topics to additional filter\nrequested partitions:\n\n rpk cluster partitions move-status foo bar --partition 0,1,2\n\nThe output contains the following columns with PARTITION-SIZE in bytes.\nUsing -H, it prints the partition size in a human-readable format\n\n NAMESPACE-TOPIC\n PARTITION\n MOVING-FROM\n MOVING-TO\n COMPLETION-%\n PARTITION-SIZE\n BYTES-MOVED\n BYTES-REMAINING\n\nUsing \"--print-all / -a\" the command additionally prints the column\n\"RECONCILIATION STATUSES\", which reveals the internal status of the ongoing\nreconciliations. Reported errors do not necessarily mean real problems.\n", + "usage": "rpk cluster partitions move-status [flags]", + "aliases": [], + "flags": [ + { + "name": "human-readable", + "shorthand": "H", + "type": "bool", + "description": "Print the partition size in a human-readable form", + "default": false, + "required": false + }, + { + "name": "partition", + "shorthand": "p", + "type": "stringSlice", + "description": "Partitions to filter ongoing movements status (repeatable)", + "default": [], + "required": false + }, + { + "name": "print-all", + "shorthand": "a", + "type": "bool", + "description": "Print internal states about movements for debugging", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement-status.adoc" + }, + { + "name": "transfer-leadership", + "description": "Transfer partition leadership between brokers.\n\nThis command allows you to transfer partition leadership.\nYou can transfer only one partition leader at a time.\n\nTo transfer partition leadership, use the following syntax:\n\trpk cluster partitions transfer-leadership foo --partition 0:2\n\nHere, the command transfers leadership for the partition \"kafka/foo/0\"\nto broker 2. By default, it assumes the \"kafka\" namespace, but you can specify\nan internal namespace using the \"{namespace}/\" prefix.\n\nHere is an equivalent command using different syntax:\n\trpk cluster partitions transfer-leadership --partition foo/0:2\n\nWarning: Redpanda tries to balance leadership distribution across brokers by default.\nIf the distribution of leaders becomes uneven as a result of transferring leadership\nacross brokers, the cluster may move leadership back to the original\nbrokers automatically.\n", + "usage": "rpk cluster partitions transfer-leadership [flags]", + "aliases": [], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "partition", + "shorthand": "p", + "type": "string", + "description": "Topic-partition to transfer leadership and new leader location", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "unsafe-recover", + "description": "Recover unsafely from partitions that have lost majority.\n\nThis command allows you to unsafely recover all data adversely affected by the\nloss of the nodes specified in the '--from-nodes' flag. This operation is unsafe \nbecause it allows you to bulk move all partitions that have lost majority when \nnodes are gone and irrecoverable; this may result in data loss.\n\nYou can perform a dry run and verify the partitions that will be recovered by \nusing the '--dry' flag.\n", + "usage": "rpk cluster partitions unsafe-recover [flags]", + "aliases": [], + "flags": [ + { + "name": "dry", + "type": "bool", + "description": "Dry run: print the partition movement plan. Does not execute it", + "default": false, + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + }, + { + "name": "from-nodes", + "type": "intSlice", + "description": "Comma-separated list of node IDs from which to recover the partitions", + "default": [], + "required": true + }, + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "quotas", + "description": "Manage Redpanda client quotas", + "usage": "rpk cluster quotas [flags]", + "aliases": [ + "quota" + ], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [ + { + "name": "alter", + "description": "Add or delete a client quota\n\nThis command allows you to add or delete a client quota.\n\nA client quota consists of an entity (to whom the quota is applied) and a quota \ntype (what is being applied).\n\nThere are three entity types supported by Redpanda: user, client ID, and \nclient ID prefix.\n\nAssigning quotas to default entity types is possible using the '--default' flag.\n\nYou can perform a dry run using the '--dry' flag.\n", + "usage": "rpk cluster quotas alter [flags]", + "aliases": [], + "examples": "\nAdd quota (consumer_byte_rate) to client ID 'foo':\n rpk cluster quotas alter --add consumer_byte_rate=200000 \\\n --name client-id=foo\n\nAdd quota (consumer_byte_rate) to client ID starting with 'bar-':\n rpk cluster quotas alter --add consumer_byte_rate=200000 \\\n --name client-id-prefix=bar-\n\nAdd quota (producer_byte_rate) to default client ID:\n rpk cluster quotas alter --add producer_byte_rate=180000 --default client-id\n\nRemove quota (producer_byte_rate) from client ID 'foo':\n rpk cluster quotas alter --delete producer_byte_rate \\\n --name client-id=foo\n", + "flags": [ + { + "name": "add", + "type": "stringSlice", + "description": "Key=value quota to add, where the value is a float number (repeatable)", + "default": [], + "required": false + }, + { + "name": "default", + "type": "stringSlice", + "description": "Entity type for default matching, where type is client-id or client-id-prefix (repeatable)", + "default": [], + "required": false + }, + { + "name": "delete", + "type": "stringSlice", + "description": "Key of the quota to delete (repeatable)", + "default": [], + "required": false + }, + { + "name": "dry", + "type": "bool", + "description": "Dry run: validate the request without altering the quotas", + "default": false, + "required": false + }, + { + "name": "name", + "type": "stringSlice", + "description": "Entity for exact matching. Format type=name where type is client-id or client-id-prefix (repeatable)", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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=" + } + ] + } + ] + }, + { + "name": "describe", + "description": "Describe client quotas.\n\nThis command describes client quotas that match the provided filtering criteria.\nRunning the command without filters returns all client quotas. Use the \n'--strict' flag for strict matching, which means that the only quotas returned \nexactly match the filters.\n\nFilters can be provided in terms of entities. An entity consists of either a \nclient ID or a client ID prefix.\n", + "usage": "rpk cluster quotas describe [flags]", + "aliases": [], + "examples": "\nDescribe all client quotas:\n rpk cluster quotas describe\n\nDescribe all client quota with client ID foo:\n rpk cluster quotas describe --name client-id=foo\n\nDescribe client quotas for a given client ID prefix 'bar.':\n rpk cluster quotas describe --name client-id=bar.\n", + "flags": [ + { + "name": "any", + "type": "stringSlice", + "description": "type for any matching (names or default), where type is client-id or client-id-prefix (repeatable)", + "default": [], + "required": false + }, + { + "name": "default", + "type": "stringSlice", + "description": "type for default matching, where type is client-id or client-id-prefix (repeatable)", + "default": [], + "required": false + }, + { + "name": "name", + "type": "stringSlice", + "description": "type=name pair for exact name matching, where type is client-id or client-id-prefix (repeatable)", + "default": [], + "required": false + }, + { + "name": "strict", + "type": "bool", + "description": "whether matches are strict, if true, entities with unspecified entity types are excluded", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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=." + } + ] + } + ] + }, + { + "name": "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.", + "usage": "rpk cluster quotas import [flags]", + "aliases": [], + "examples": "\nImport client quotas from a file:\n rpk cluster quotas import --from /path/to/file\n\nImport client quotas from a string:\n rpk cluster quotas import --from '{\"quotas\":...}'\n", + "flags": [ + { + "name": "from", + "type": "string", + "description": "Either the quotas or a path to a file containing the quotas to import; check help text for more information", + "default": "", + "required": true + }, + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "self-test", + "description": "Start, stop and query runs of Redpanda self-test through the Admin API listener", + "usage": "rpk cluster self-test [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "start", + "description": "Starts one or more benchmark tests on one or more nodes of the cluster.", + "usage": "rpk cluster self-test start [flags]", + "aliases": [], + "flags": [ + { + "name": "cloud-backoff-ms", + "type": "uint", + "description": "The backoff in milliseconds for a cloud storage request", + "default": 100, + "required": false + }, + { + "name": "cloud-timeout-ms", + "type": "uint", + "description": "The timeout in milliseconds for a cloud storage request", + "default": 10000, + "required": false + }, + { + "name": "disk-duration-ms", + "type": "uint", + "description": "The duration in milliseconds of individual disk test runs", + "default": 30000, + "required": false + }, + { + "name": "network-duration-ms", + "type": "uint", + "description": "The duration in milliseconds of individual network test runs", + "default": 30000, + "required": false + }, + { + "name": "no-confirm", + "type": "bool", + "description": "Acknowledge warning prompt skipping read from stdin", + "default": false, + "required": false + }, + { + "name": "only-cloud-test", + "type": "bool", + "description": "Runs only cloud storage verification", + "default": false, + "required": false + }, + { + "name": "only-disk-test", + "type": "bool", + "description": "Runs only the disk benchmarks", + "default": false, + "required": false + }, + { + "name": "only-network-test", + "type": "bool", + "description": "Runs only network benchmarks", + "default": false, + "required": false + }, + { + "name": "participant-node-ids", + "type": "intSlice", + "description": "Comma-separated list of broker IDs that the tests will run on. If not set, tests will run for all node IDs.", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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`." + } + ] + }, + { + "name": "status", + "description": "Returns the status of the current running tests or the cached results of the last completed run.\n\nUse this command after invoking 'self-test start' to determine the status of\nthe jobs launched. Possible results are:\n\n* One or more jobs still running\n * Returns the IDs of Redpanda brokers (nodes) still running self-tests.\n\n* No jobs running:\n * Returns the cached results for all brokers of the last completed test.\n\nTest results are grouped by broker ID. Each test returns the following:\n\n* Name: Description of the test.\n* Info: Details about the test run attached by Redpanda.\n* Type: Either 'disk', 'network', or 'cloud' test.\n* Test Id: Unique identifier given to jobs of a run. All IDs in a test should match. If they don't match, then newer and/or older test results have been included erroneously.\n* Timeouts: Number of timeouts incurred during the test.\n* Start time: Time that the test started, in UTC.\n* End time: Time that the test ended, in UTC.\n* Avg Duration: Duration of the test.\n* IOPS: Number of operations per second. For disk, it's 'seastar::dma_read' and 'seastar::dma_write'. For network, it's 'rpc.send()'.\n* Throughput: For disk, throughput rate is in bytes per second. For network, throughput rate is in bits per second. Note that GiB vs. Gib is the correct notation displayed by the UI.\n* Latency: 50th, 90th, etc. percentiles of operation latency, reported in microseconds (μs). Represented as P50, P90, P99, P999, and MAX respectively.\nIf Tiered Storage is not enabled, the cloud storage tests won't run and a warning will be displayed showing \"Cloud storage is not enabled.\". All results will be shown as 0.\n", + "usage": "rpk cluster self-test status [flags]", + "aliases": [], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (text, json)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "stop", + "description": "Stops all self-test tests.\n\nThis command stops all currently running self-tests. The command is synchronous and returns\nsuccess when all jobs have been stopped or reports errors if broker timeouts have expired.\n", + "usage": "rpk cluster self-test stop [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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]" + ] + }, + { + "name": "storage", + "description": "Manage cluster storage, including mounting and unmounting topics from Tiered Storage.", + "usage": "rpk cluster storage [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "cancel-mount", + "description": "Cancels a mount/unmount operation on a topic.\n\nUse the migration ID that is emitted when the mount or unmount operation is executed. \nYou can also get the migration ID by listing the mount/unmount operations.", + "usage": "rpk cluster storage cancel-mount [MIGRATION ID] [flags]", + "aliases": [ + "cancel-unmount" + ], + "examples": "\nCancel a mount/unmount operation\n rpk cluster storage cancel-mount 123\n", + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "list-mount", + "description": "List mount/unmount operations on a topic to the Redpanda cluster from Tiered Storage.\n\nYou can also filter the list by state using the --filter flag. The possible states are:\n- planned\n- prepared\n- executed\n- finished\n\nIf no filter is provided, all migrations will be listed.", + "usage": "rpk cluster storage list-mount [flags]", + "aliases": [ + "list-unmount" + ], + "examples": "\nLists mount/unmount operations\n\trpk cluster storage list-mount\n\nUse filter to list only migrations in a specific state\n\trpk cluster storage list-mount --filter planned\n", + "flags": [ + { + "name": "filter", + "shorthand": "f", + "type": "string", + "description": "Filter the list of migrations by state. Only valid for text", + "default": "all", + "required": false + }, + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "list-mountable", + "description": "List topics that are available to mount from object storage.\n\nThis command displays topics that exist in object storage and can be mounted\nto your Redpanda cluster. Each topic includes its location in object storage\nand namespace information if applicable.", + "usage": "rpk cluster storage list-mountable [flags]", + "aliases": [], + "examples": "\nList all mountable topics:\n rpk cluster storage list-mountable\n", + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "mount", + "description": "Mount a topic from Tiered Storage, making it available for reads.", + "usage": "rpk cluster storage mount [TOPIC] [flags]", + "aliases": [], + "examples": "\nMounts topic my-typic from Tiered Storage to the cluster in the my-namespace\n\trpk cluster storage mount my-topic\n\nMount topic my-topic from Tiered Storage to the cluster in the my-namespace \nwith my-new-topic as the new topic name\n\trpk cluster storage mount my-namespace/my-topic --to my-namespace/my-new-topic\n", + "flags": [ + { + "name": "to", + "type": "string", + "description": "New namespace/topic name for the mounted topic (optional)", + "default": "", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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 /" + } + ] + } + ] + }, + { + "name": "restore", + "description": "Interact with the topic restoration process.\n\t\t\nThis command is used to restore topics from the archival bucket, which can be \nuseful for disaster recovery or if a topic was accidentally deleted.\n\nTo begin the recovery process, use the \"restore start\" command. Note that this \nprocess can take a while to complete, so the command will exit after starting \nit. If you want the command to wait for the process to finish, use the \"--wait\"\nor \"-w\" flag.\n\nYou can check the status of the recovery process with the \"restore status\" \ncommand after it has been started.\n", + "usage": "rpk cluster storage restore [flags]", + "aliases": [ + "recovery" + ], + "flags": [], + "commands": [ + { + "name": "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.", + "usage": "rpk cluster storage restore start [flags]", + "aliases": [], + "flags": [ + { + "name": "cluster-uuid-override", + "type": "string", + "description": "Explicit cluster UUID to restore from; uses the latest if unset", + "default": "", + "required": false + }, + { + "name": "polling-interval", + "type": "duration", + "description": "The status check interval (e.g. '30s', '1.5m'); ignored if --wait is not used", + "default": "5s", + "required": false + }, + { + "name": "wait", + "shorthand": "w", + "type": "bool", + "description": "Wait until auto-restore is complete", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery-start.adoc" + }, + { + "name": "status", + "description": "Fetch the status of the topic restoration process.\n\t\t\nThis command fetches the status of the process of restoring topics from the \narchival bucket.", + "usage": "rpk cluster storage restore status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery-status.adoc" + } + ], + "platforms": [ + "linux", + "darwin" + ], + "seeAlso": [ + "xref:manage:whole-cluster-restore.adoc[Whole-Cluster Restore]" + ], + "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-storage-recovery.adoc" + }, + { + "name": "status-mount", + "description": "Status of mount/unmount operation on topic to Redpanda cluster from Tiered Storage", + "usage": "rpk cluster storage status-mount [MIGRATION ID] [flags]", + "aliases": [ + "status-unmount" + ], + "examples": "\nStatus for a mount/unmount operation\n\trpk cluster storage status-mount 123\n", + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "unmount", + "description": "Unmount a topic, removing it from local storage while preserving data in Tiered Storage.", + "usage": "rpk cluster storage unmount [TOPIC] [flags]", + "aliases": [], + "examples": "\nUnmount topic 'my-topic' from the cluster in the 'my-namespace'\n rpk cluster storage unmount my-namespace/my-topic\n", + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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 /" + } + ] + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "content": [ + { + "type": "cloud-only", + "position": "after_header", + "content": "NOTE: This command is only supported in BYOC and Dedicated clusters." + } + ] + }, + { + "name": "txn", + "description": "Information about transactions and transactional producers.\n\nTransactions allow producing, or consume-modifying-producing, to Redpanda.\nThe consume-modify-produce loop is also referred to as EOS (exactly once\nsemantics). Transactions involve a lot of technical complexity that is largely\nhidden within clients. This command space helps shed a light on what is\nactually happening in clients and brokers while transactions are in use.\n\nTRANSACTIONAL ID\n\nThe transactional ID is the string you define in clients when actually using\ntransactions.\n\nPRODUCER ID & EPOCH\n\nThe producer ID is generated within clients when you transactionally produce.\nThe producer ID is a number that maps to your transactional ID, allowing\nrequests to be smaller when producing, and allowing some optimizations within\nbrokers when managing transactions.\n\nSome clients expose the producer ID, allowing you to track the transactional ID\nthat a producer ID maps to. If possible, it is recommended to monitor the\nproducer ID used in your applications.\n\nThe producer epoch is a number that somewhat \"counts\" the number of times your\ntransaction has been initialized or expired. If you have one client that uses\na transactional ID, it may receive producer ID 3 epoch 0. Another client that\nuses that same transactional ID will receive producer ID 3 epoch 1. If the\nclient starts a transaction but does not finish it in time, the cluster will\ninternally bump the epoch to 2. The epoch allows the cluster to \"fence\"\nclients: if a client attempts to use a producer ID with an old epoch, the\ncluster will reject the client's produce request as stale.\n\nTRANSACTION STATE\n\nThe state of a transaction indicates what is currently happening with a\ntransaction. A high level overview of transactional states:\n\n * Empty: the transactional ID is ready but there are no partitions\n nor groups added to it -- there is no active transaction\n * Ongoing: the transactional ID is being used in a began transaction\n * PrepareCommit: a commit is in progress\n * PrepareAbort: an abort is in progress\n * PrepareEpochFence: the transactional ID is timing out\n * Dead: the transactional ID has expired and/or is not in use\n\nLAST STABLE OFFSET\n\nThe last stable offset is the offset at which a transaction has begun and\nclients cannot consume past, if the client is configured to read only committed\noffsets. The last stable offset can be seen when describing active transactional\nproducers by looking for the earliest transaction start offset per partition.\n", + "usage": "rpk cluster txn [flags]", + "aliases": [ + "transaction" + ], + "flags": [ + { + "name": "format", + "type": "string", + "description": "Output format (json,yaml,text,wide,help)", + "default": "text", + "required": false + } + ], + "commands": [ + { + "name": "describe", + "description": "Describe transactional IDs.\n\nThis command, in comparison to 'list', is a more detailed per-transaction view\nof transactional IDs. In addition to the state and producer ID, this command\nalso outputs when a transaction started, the epoch of the producer ID, how long\nuntil the transaction times out, and the partitions currently a part of the\ntransaction. For information on what the columns in the output mean, see\n'rpk cluster txn --help'.\n\nBy default, all topics in a transaction are merged into one line. To print a\nrow per topic, use --format=long. To include partitions with topics, use\n--print-partitions; --format=json/yaml will return the equivalent of the long\nformat with print partitions included.\n\nIf no transactional IDs are requested, all transactional IDs are printed.\n", + "usage": "rpk cluster txn describe [TXN-IDS...] [flags]", + "aliases": [], + "flags": [ + { + "name": "print-partitions", + "shorthand": "p", + "type": "bool", + "description": "Include per-topic partitions that are in the transaction", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "describe-producers", + "description": "Describe transactional producers to partitions.\n\nThis command describes partitions that active transactional producers are\nproducing to. For more information on the producer ID and epoch columns, see\n'rpk cluster txn --help'.\n\nThe last timestamp corresponds to the timestamp of the last record that was\nwritten by the client. The transaction start offset corresponds to the offset\nthat the transaction is began at. All consumers configured to read only\ncommitted records cannot read past the transaction start offset.\n\nThe output includes a few advanced fields that can be used for sanity checking:\nthe last sequence is the last sequence number that the producer has written,\nand the coordinator epoch is the epoch of the broker that is being written to.\nThe last sequence should always go up and then wrap back to 0 at MaxInt32. The\ncoordinator epoch should remain fixed, or rarely, increase.\n\nYou can query all topics and partitions that have active producers with --all.\nTo filter for specific topics, use --topics. You can additionally filter by\npartitions with --partitions.\n", + "usage": "rpk cluster txn describe-producers [flags]", + "aliases": [], + "flags": [ + { + "name": "all", + "shorthand": "a", + "type": "bool", + "description": "Query all producer IDs on any topic", + "default": false, + "required": false + }, + { + "name": "partitions", + "shorthand": "p", + "type": "int32Slice", + "description": "Partitions to describe producers for (repeatable)", + "default": [], + "required": false + }, + { + "name": "topics", + "shorthand": "t", + "type": "stringSlice", + "description": "Topic to describe producers for (repeatable)", + "default": [], + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "list", + "description": "List transactions and their current states\n\nThis command lists all known transactions in the cluster, the producer ID for\nthe transactional ID, and the and the state of the transaction. For information\non what the columns in the output mean, see 'rpk cluster txn --help'.\n", + "usage": "rpk cluster txn list [flags]", + "aliases": [ + "ls" + ], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "connect", + "description": "Run and manage Redpanda Connect streaming pipelines. Redpanda Connect is a high-performance stream processor for mundane data engineering tasks.", + "usage": "rpk connect [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "agent", + "description": "Manage Redpanda Connect agents. Agents allow you to build AI-powered workflows using Redpanda Connect resources.", + "usage": "rpk connect agent [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "init", + "description": "Initialize a template for building a Redpanda Connect agent.", + "usage": "rpk connect agent init [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + }, + { + "name": "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.", + "usage": "rpk connect agent run [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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]" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + { + "name": "blobl", + "description": "Execute Bloblang mappings from the command line. Provides a convenient tool for mapping JSON documents.", + "usage": "rpk connect blobl [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "server", + "description": "Run a web server that provides an interactive application for writing and testing Bloblang mappings.", + "usage": "rpk connect blobl server [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "create", + "description": "Prints a new Redpanda Connect config to stdout containing specified components\naccording to an expression. The expression must take the form of three\ncomma-separated lists of inputs, processors and outputs, divided by\nforward slashes:\n\n redpanda-connect create stdin/bloblang,awk/nats\n redpanda-connect create file,http_server/protobuf/http_client\n\nIf the expression is omitted a default config is created.", + "usage": "rpk connect create [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "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.", + "usage": "rpk connect dry-run [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "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.", + "usage": "rpk connect echo [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "help", + "description": "Shows a list of commands or help for one command", + "usage": "rpk connect help [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "install", + "description": "Install Redpanda Connect\n\nThis command install the latest version by default.\n\nAlternatively, you may specify a Redpanda Connect version using the \n--connect-version flag.\n\nYou may force the installation of Redpanda Connect using the --force flag.\n", + "usage": "rpk connect install [flags]", + "aliases": [], + "flags": [ + { + "name": "connect-version", + "type": "string", + "description": "Redpanda Connect version to install. (e.g. 4.32.0)", + "default": "latest", + "required": false + }, + { + "name": "force", + "type": "bool", + "description": "Force install of Redpanda Connect", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "lint", + "description": "Check a Redpanda Connect configuration file for syntax errors and potential issues without running it.", + "usage": "rpk connect lint [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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/..." + } + ] + } + ] + }, + { + "name": "list", + "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.", + "usage": "rpk connect list [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "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.", + "usage": "rpk connect mcp-server [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "init", + "description": "Initialize an MCP server project. Files that already exist will not be overwritten.", + "usage": "rpk connect mcp-server init [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + { + "name": "lint", + "description": "Lint MCP server resources. Exits with a status code 1 if any linting errors are detected in the specified directory.", + "usage": "rpk connect mcp-server lint [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + { + "name": "plugin", + "description": "Manage custom Redpanda Connect plugins. Use these commands to create and initialize plugin projects for extending Redpanda Connect with custom components.", + "usage": "rpk connect plugin [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "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).", + "usage": "rpk connect plugin init [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "seeAlso": [ + "xref:reference:rpk/rpk-connect/rpk-connect-plugin-init.adoc[rpk connect plugin init]" + ], + "content": [ + { + "type": "important", + "position": "after_description", + "content": "This command is experimental and subject to change." + } + ] + }, + { + "name": "run", + "description": "Run a Redpanda Connect pipeline from a configuration file. The pipeline streams data between inputs and outputs with optional processing.", + "usage": "rpk connect run [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "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.", + "usage": "rpk connect streams [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "template", + "description": "Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns.", + "usage": "rpk connect template [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "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.", + "usage": "rpk connect template lint [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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/..." + } + ] + } + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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." + } + ] + }, + { + "name": "test", + "description": "Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior.", + "usage": "rpk connect test [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "uninstall", + "description": "Uninstall the Redpanda Connect plugin", + "usage": "rpk connect uninstall [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "upgrade", + "description": "Upgrade to the latest Redpanda Connect version", + "usage": "rpk connect upgrade [flags]", + "aliases": [], + "flags": [ + { + "name": "no-confirm", + "type": "bool", + "description": "Disable confirmation prompt for major version upgrades", + "default": false, + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "container", + "description": "Manage a local Redpanda container cluster for development and testing. Creates containers using Docker or Podman.", + "usage": "rpk container [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "purge", + "description": "Stop and remove an existing local container cluster's data", + "usage": "rpk container purge [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "start", + "description": "Start a local container cluster.\n\nThis command uses Docker to initiate a local Redpanda container cluster,\nincluding Redpanda Console. Use the '--nodes'/'-n' flag to specify the number of\nbrokers.\n\nThe initial broker starts on default ports, with subsequent brokers' ports\noffset by 1000. You can use the listeners flag to specify ports:\n\n * --kafka-ports\n * --admin-ports\n * --rpc-ports\n * --schema-registry-ports\n * --proxy-ports\n * --console-port\n\nEach flag accepts a comma-separated list of ports for your listeners. Use the\n'--any-port' flag to let rpk select random available ports for every listener on\nthe host machine.\n\nBy default, this command uses the redpandadata/redpanda:latest and \nredpandadata/console:latest container images. You can specify a container image \nby using the '--image' flag.\n\nIn case of IP address pool conflict, you may specify a custom subnet and gateway\nusing the '--subnet' and '--gateway' flags respectively.\n", + "usage": "rpk container start [flags]", + "aliases": [], + "examples": "\nStart a three-broker cluster:\n rpk container start -n 3\n\nStart a single-broker cluster, selecting random ports for every listener:\n rpk container start --any-port\n\nStart a three-broker cluster, selecting the seed Kafka and Redpanda Console \nports only:\n rpk container start --kafka-ports 9092 --console-port 8080\n\nStart a three-broker cluster, selecting the Admin API port for each broker:\n rpk container start --admin-ports 9644,9645,9646\n", + "flags": [ + { + "name": "admin-ports", + "type": "stringSlice", + "description": "Redpanda Admin API ports to listen on; check help text for more information", + "default": [], + "required": false + }, + { + "name": "any-port", + "type": "bool", + "description": "Opt in for any (random) ports in all listeners", + "default": false, + "required": false + }, + { + "name": "console-image", + "type": "string", + "description": "An arbitrary Redpanda Console container image to use", + "default": "redpandadata/console:v3.7.1", + "required": false + }, + { + "name": "console-port", + "type": "string", + "description": "Redpanda console ports to listen on; check help text for more information", + "default": "8080", + "required": false + }, + { + "name": "gateway", + "type": "string", + "description": "Gateway IP address for the subnet. Must be in the subnet address range", + "default": "172.24.1.1", + "required": false + }, + { + "name": "image", + "type": "string", + "description": "An arbitrary Redpanda container image to use", + "default": "redpandadata/redpanda:latest", + "required": false + }, + { + "name": "kafka-ports", + "type": "stringSlice", + "description": "Kafka protocol ports to listen on; check help text for more information", + "default": [], + "required": false + }, + { + "name": "no-profile", + "type": "bool", + "description": "If true, rpk will not create an rpk profile after creating a cluster", + "default": false, + "required": false + }, + { + "name": "nodes", + "shorthand": "n", + "type": "uint", + "description": "The number of brokers (nodes) to start", + "default": 1, + "required": false + }, + { + "name": "proxy-ports", + "type": "stringSlice", + "description": "HTTP Proxy ports to listen on; check help text for more information", + "default": [], + "required": false + }, + { + "name": "pull", + "type": "bool", + "description": "Force pull the container image used", + "default": false, + "required": false + }, + { + "name": "retries", + "type": "uint", + "description": "The amount of times to check for the cluster before considering it unstable and exiting", + "default": 10, + "required": false + }, + { + "name": "rpc-ports", + "type": "stringSlice", + "description": "RPC ports to listen on; check help text for more information", + "default": [], + "required": false + }, + { + "name": "schema-registry-ports", + "type": "stringSlice", + "description": "Schema Registry ports to listen on; check help text for more information", + "default": [], + "required": false + }, + { + "name": "set", + "type": "string", + "description": "Redpanda configuration property to set upon start. Follows 'rpk redpanda config set' format", + "default": "", + "required": false + }, + { + "name": "subnet", + "type": "string", + "description": "Subnet to create the cluster network on", + "default": "172.24.1.0/24", + "required": false + } + ], + "commands": [], + "platforms": [ + "linux", + "darwin" + ], + "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" + } + ] + } + ] + }, + { + "name": "status", + "description": "Get status", + "usage": "rpk container status [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + }, + { + "name": "stop", + "description": "Stop an existing local container cluster", + "usage": "rpk container stop [flags]", + "aliases": [], + "flags": [], + "commands": [], + "platforms": [ + "linux", + "darwin" + ] + } + ], + "platforms": [ + "linux", + "darwin" + ], + "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]" + ], + "pageAliases": "features:guide-rpk-container.adoc, deployment:guide-rpk-container.adoc", + "content": [ + { + "type": "note", + "position": "after_description", + "content": "Container clusters are intended for development and testing only. Do not use for production workloads." + } + ] + }, + { + "name": "debug", + "description": "Debug the local Redpanda process", + "usage": "rpk debug [flags]", + "aliases": [], + "flags": [], + "commands": [ + { + "name": "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.", + "usage": "rpk debug bundle [flags]", + "aliases": [], + "flags": [ + { + "name": "controller-logs-size-limit", + "type": "string", + "description": "The size limit of the controller logs that can be stored in the bundle. For example: 3MB, 1GiB", + "default": "132MB", + "required": false + }, + { + "name": "cpu-profiler-wait", + "type": "duration", + "description": "How long to collect samples for the CPU profiler. For example: 30s, 1.5m. Must be higher than 15s", + "default": "30s", + "required": false + }, + { + "name": "kafka-connections-limit", + "type": "int", + "description": "The maximum number of kafka connections to store in the bundle.", + "default": 256, + "required": false + }, + { + "name": "label-selector", + "shorthand": "l", + "type": "stringArray", + "description": "Comma-separated label selectors to filter your resources. For example: :`, 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: +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. -```bash +[,bash] +---- rpk cluster partitions transfer-leadership --partition test-topic/0:2 -``` - -In this case, the name of the topic is `test-topic` and the partition ID is `0`. - -The preceding examples transfer leadership for the partition `kafka/test-topic/0`. The command behavior is based on the assumption that the default namespace is `kafka`, but you can also specify an internal namespace using the `+{namespace}/+` prefix. +---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|Value |Type |Description -|-h, --help |- |Help for transfer-leadership. - -|-p, --partition |string |Specify the topic-partition's leadership to transfer and the location of the new leader. Use the syntax `-p :`. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-p, --partition |string |Topic-partition and target leader in the format `:`, for example `0:2` or `test-topic/0:2`. Use the `/` prefix for internal namespaces. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc index 65fbe5cefc..21edb0d004 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc @@ -1,12 +1,21 @@ = rpk cluster partitions unsafe-recover +:description: pass:q[Recover unsafely from partitions that have lost majority. This command allows you to unsafely recover all data adversely affected by the loss of the nodes specified in the `--from-nodes` flag.] +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Recover unsafely from partitions that have lost majority. -IMPORTANT: 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. +This command allows you to unsafely recover all data adversely affected by the +loss of the nodes specified in the `--from-nodes` flag. This operation is unsafe +because it allows you to bulk move all partitions that have lost majority when +nodes are gone and irrecoverable; this may result in data loss. -This command allows you to unsafely recover all data adversely affected by the loss of the nodes specified in the `--from-nodes` flag. +You can perform a dry run and verify the partitions that will be recovered by +using the `--dry` flag. -You can perform a dry run and verify the partitions that will be recovered by using the `--dry` flag. +IMPORTANT: 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. == Usage @@ -15,30 +24,32 @@ You can perform a dry run and verify the partitions that will be recovered by us rpk cluster partitions unsafe-recover [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--dry |- |Dry run: print the partition movement plan. Does not execute it. -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. -|--from-nodes |- |Comma-separated list of node IDs from which to recover the partitions. -|-h, --help |- |Help for unsafe-recover. - -|--no-confirm |- |Disable confirmation prompt. +== Flags -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description +|--dry |bool |Dry run: print the partition movement plan. Does not execute it. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|--from-nodes |intSlice |Comma-separated list of node IDs from which to recover the partitions. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions.adoc index dbe86da4aa..a9297d760b 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions.adoc @@ -1,30 +1,72 @@ = rpk cluster partitions +:description: Manage cluster partitions. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Manage cluster partitions. == Usage [,bash] ---- -rpk cluster partitions [command] +rpk cluster partitions [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-balance.adoc[`rpk cluster partitions balance`] +|Trigger on-demand partition balancing to redistribute partitions evenly across brokers. Redpanda automatically balances partitions when it detects imbalance; run this command to trigger balancing manually. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-balancer-status.adoc[`rpk cluster partitions balancer-status`] +|Queries cluster for partition balancer status: If continuous partition balancing is enabled, Redpanda will continuously reassign partitions from both unavailable nodes and from nodes using more disk space than the configured limit. Use this command to monitor the partition balancer status and the partition distribution across brokers in the cluster. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-disable.adoc[`rpk cluster partitions disable`] +|Disable partitions of a topic You may disable all partitions of a topic using the `--all` flag or you may select a set of topic/partitions to disable with the `--partitions`/`-p` flag. The partition flag accepts the format `\{namespace}/\{topic}/[partitions...]` where namespace and topic are optional parameters. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-enable.adoc[`rpk cluster partitions enable`] +|Enable partitions of a topic You may enable all partitions of a topic using the `--all` flag or you may select a set of topic/partitions to enable with the `--partitions`/`-p` flag. The partition flag accepts the format `\{namespace}/\{topic}/[partitions...]` where namespace and topic are optional parameters. -|-h, --help |- |Help for partitions. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-list.adoc[`rpk cluster partitions list`] +|List partitions in the cluster. This command lists the cluster-level metadata of all partitions, including current replica assignments on brokers and CPU cores for given topics. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-move.adoc[`rpk cluster partitions move`] +|Move partition replicas across nodes / cores. This command changes replica assignments for given partitions. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-move-cancel.adoc[`rpk cluster partitions move-cancel`] +|Cancel ongoing partition movements. By default, this command cancels all the partition movements in the cluster. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-move-status.adoc[`rpk cluster partitions move-status`] +|Show ongoing partition movements. By default this command lists all ongoing partition movements in the cluster. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership.adoc[`rpk cluster partitions transfer-leadership`] +|Transfer partition leadership between brokers. This command allows you to transfer partition leadership. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc[`rpk cluster partitions unsafe-recover`] +|Recover unsafely from partitions that have lost majority. This command allows you to unsafely recover all data adversely affected by the loss of the nodes specified in the `--from-nodes` flag. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc index ae760fe752..cdc73cbb85 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc @@ -1,11 +1,21 @@ = rpk cluster quotas alter -// tag::single-source[] +:description: Add or delete a client quota This command allows you to add or delete a client quota. A client quota consists of an entity (to whom the quota is applied) and a quota type (what is being applied). +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Add or delete a client quota. -A client quota consists of an entity (to which the quota is applied) and a quota type (what is being applied). +This command allows you to add or delete a client quota. + +A client quota consists of an entity (to whom the quota is applied) and a quota +type (what is being applied). + +There are three entity types supported by Redpanda: user, client ID, and +client ID prefix. -There are three entity types supported by Redpanda: user, client ID, and client ID prefix. Use the `--default` flag to assign quotas to default entity types. +Assigning quotas to default entity types is possible using the `--default` flag. You can perform a dry run using the `--dry` flag. @@ -16,66 +26,65 @@ You can perform a dry run using the `--dry` flag. rpk cluster quotas alter [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--add |strings |Key=value quota to add, where the value is a float number (repeatable). - -|--default |strings |Entity type for default matching, where type is client-id or client-id-prefix (repeatable). - -|--delete |strings |Key of the quota to delete (repeatable). - -|--dry |- |Perform a dry run. Validate the request without altering the quotas. Show what would be done, but do not execute the command. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|-h, --help |- |Help for alter. - -|--name |strings |Entity for exact matching. Format `type=name` where `type` is the `client-id` or `client-id-prefix` (repeatable). - -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. - -|-v, --verbose |- |Enable verbose logging. -|=== == Examples -Add quota (consumer_byte_rate) to client ID ``: +This section provides examples of how to use `rpk cluster quotas alter`. + +Add quota (consumer_byte_rate) to client ID ``. [,bash] ---- rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id= ---- -Add quota (consumer_byte_rate) to client ID starting with `-`: +Add quota (consumer_byte_rate) to client ID starting with `-`. [,bash] ---- rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id-prefix=- ---- -Add quota (producer_byte_rate) to default client ID: +Add quota (producer_byte_rate) to default client ID. [,bash] ---- rpk cluster quotas alter --add producer_byte_rate=180000 --default client-id ---- -Remove quota (producer_byte_rate) from client ID `foo`: +Remove quota (producer_byte_rate) from client ID `foo`. [,bash] ---- rpk cluster quotas alter --delete producer_byte_rate --name client-id= ---- -// end::single-source[] \ No newline at end of file +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--add |stringSlice |Key=value quota to add, where the value is a float number (`repeatable`). +|--default |stringSlice |Entity type for default matching, where type is client-id or client-id-prefix (`repeatable`). +|--delete |stringSlice |Key of the quota to delete (`repeatable`). +|--dry |bool |Dry run: validate the request without altering the quotas. +|--name |stringSlice |Entity for exact matching. Format type=name where type is client-id or client-id-prefix (`repeatable`). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc index f35ca52554..1a175bf793 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc @@ -1,12 +1,19 @@ = rpk cluster quotas describe -// tag::single-source[] +:description: Describe client quotas. This command describes client quotas that match the provided filtering criteria. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Describe client quotas. -This command describes client quotas that match the provided filtering criteria. Running the command without filters returns all client quotas. Use the -`--strict` flag for strict matching, which means that the only quotas returned exactly match the filters. +This command describes client quotas that match the provided filtering criteria. +Running the command without filters returns all client quotas. Use the +`--strict` flag for strict matching, which means that the only quotas returned +exactly match the filters. -You can specify filters in terms of entities. An entity consists of either a client ID or a client ID prefix. +Filters can be provided in terms of entities. An entity consists of either a +client ID or a client ID prefix. == Usage @@ -15,57 +22,57 @@ You can specify filters in terms of entities. An entity consists of either a cli rpk cluster quotas describe [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--any |strings |Type for any matching (names or default), where type is `client-id` or `client-id-prefix` (repeatable). - -|--default |strings |Type for default matching, where type is `client-id` or `client-id-prefix` (repeatable). - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|-h, --help |- |Help for describe. - -|--name |strings |The `type=name` pair for exact name matching, where type is `client-id` or `client-id-prefix` (repeatable). - -|--strict |- |Specifies whether matches are strict. If `true`, entities with unspecified entity types are excluded. - -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. - -|-v, --verbose |- |Enable verbose logging. -|=== == Examples -Describe all client quotas: +This section provides examples of how to use `rpk cluster quotas describe`. + +Describe all client quotas. [,bash] ---- rpk cluster quotas describe ---- -Describe all client quota with client ID ``: +Describe all client quota with client ID ``. [,bash] ---- rpk cluster quotas describe --name client-id= ---- -Describe client quotas for a given client ID prefix `.`: +Describe client quotas for a given client ID prefix `.`. [,bash] ---- rpk cluster quotas describe --name client-id=. ---- -// end::single-source[] \ No newline at end of file +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--any |stringSlice |Entity type for any matching (names or default). Valid type values: `client-id` or `client-id-prefix`. Repeatable. +|--default |stringSlice |Entity type for default matching. Valid type values: `client-id` or `client-id-prefix`. Repeatable. +|--name |stringSlice |Entity type and name pair for exact name matching. Valid type values: `client-id` or `client-id-prefix`. Repeatable. +|--strict |bool |Use strict matching: exclude entities with unspecified entity types. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-import.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-import.adoc index f14104e324..debe90bdc3 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-import.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-import.adoc @@ -1,6 +1,10 @@ = rpk cluster quotas import -// tag::single-source[] +:description: pass:q[Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`.] +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`. The schema of the import string matches the schema from `rpk cluster quotas describe --format help`: @@ -53,105 +57,46 @@ Use the `--no-confirm` flag to avoid the confirmation prompt. rpk cluster quotas import [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--from |string |Either the quotas or a path to a file containing the quotas to import; check help text for more information. - -|-h, --help |- |Help for import. - -|--no-confirm |- |Disable confirmation prompt. - -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. -|-v, --verbose |- |Enable verbose logging. -|=== == Examples -Import client quotas from a file: +This section provides examples of how to use `rpk cluster quotas import`. +Import client quotas from a file: [,bash] ---- rpk cluster quotas import --from /path/to/file ---- Import client quotas from a string: - [,bash] ---- -rpk cluster quotas import --from '{"quotas":...}' +rpk cluster quotas import --from '{`quotas`:...}' ---- -Import client quotas from a JSON string: +== Flags -[,bash] ----- -rpk cluster quotas import --from ' -{ - "quotas": [ - { - "entity": [ - { - "name": "retrievals-", - "type": "client-id-prefix" - } - ], - "values": [ - { - "key": "consumer_byte_rate", - "value": "140000" - } - ] - }, - { - "entity": [ - { - "name": "consumer-1", - "type": "client-id" - } - ], - "values": [ - { - "key": "producer_byte_rate", - "value": "140000" - } - ] - } - ] -} -' ----- +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -Import client quotas from a YAML string: +|--from |string |Either the quotas or a path to a file containing the quotas to import; check help text for more information. +|--no-confirm |bool |Disable confirmation prompt. +|=== -[,bash] ----- -rpk cluster quotas import --from ' -quotas: - - entity: - - name: retrievals- - type: client-id-prefix - values: - - key: consumer_byte_rate - value: "140000" - - entity: - - name: consumer-1 - type: client-id - values: - - key: producer_byte_rate - value: "140000" -' ----- +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas.adoc index 548b144f66..600627c612 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas.adoc @@ -1,41 +1,65 @@ = rpk cluster quotas -// tag::single-source[] +:description: Manage Redpanda client quotas. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Manage Redpanda client quotas. == Usage [,bash] ---- -rpk cluster quotas [command] [flags] +rpk cluster quotas [flags] ---- + + == Aliases [,bash] ---- -quotas, quota +rpk cluster quota ---- -== Flags +== Subcommands -[cols="1m,1a,2a"] +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc[`rpk cluster quotas alter`] +|Add or delete a client quota This command allows you to add or delete a client quota. A client quota consists of an entity (to whom the quota is applied) and a quota type (what is being applied). -|-h, --help |- |Help for quotas. +|xref:reference:rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc[`rpk cluster quotas describe`] +|Describe client quotas. This command describes client quotas that match the provided filtering criteria. -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-quotas-import.adoc[`rpk cluster quotas import`] +|Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-start.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-start.adoc index ef187e6570..f5e3bfb8cc 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-start.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-start.adoc @@ -1,15 +1,19 @@ = rpk cluster self-test start -:description: Reference for the 'rpk cluster self-test start' command. Starts one or more benchmark tests on one or more nodes of the cluster. +:description: Starts one or more benchmark tests on one or more nodes of the cluster. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Starts one or more benchmark tests on one or more nodes of the cluster. -NOTE: Redpanda self-test runs benchmarks that consume significant system resources. Do not start self-test if large workloads are already running on the system. +NOTE: Redpanda self-test runs benchmarks that consume significant system resources. Do not start self-test if large workloads are already running on the system. Available tests to run: * *Disk tests* ** Throughput test: 512 KB messages, sequential read/write -*** Uses a 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. +*** 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. ** Latency test: 4 KB messages, sequential read/write *** Uses smaller request message sizes and lower levels of parallelism to achieve higher IOPS and lower latency. * *Network tests* @@ -18,15 +22,11 @@ Available tests to run: *** The test pushes as much data over the wire, within the test parameters. * *Cloud storage tests* ** Configuration/latency test: 1024-byte object. -** If cloud storage is enabled (xref:reference:properties/object-storage-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`]), a series of remote operations are performed: -+ --- -include::reference:partial$rpk-self-test-cloud-tests.adoc[] --- +** If cloud storage is enabled, a series of remote operations are performed. This command prompts users for confirmation (unless the flag `--no-confirm` is specified), then returns a test identifier ID, and runs the tests. -To view the test status, poll xref:./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`. +To 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`. == Usage @@ -35,43 +35,42 @@ To view the test status, poll xref:./rpk-cluster-self-test-status.adoc[rpk clust rpk cluster self-test start [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--cloud-backoff-ms |uint | The backoff in milliseconds for a cloud storage request (default `100`). - -|--cloud-timeout-ms |uint | The timeout in milliseconds for a cloud storage request (default `10000`). - -|--disk-duration-ms |uint | The duration in milliseconds of individual -disk test runs (default `30000`). - -|-h, --help |- |Help for start. -|--network-duration-ms |uint | The duration in milliseconds of individual -network test runs (default `30000`). -|--no-confirm |- |Acknowledge warning prompt skipping read from stdin. -|--only-cloud-test |- |Runs only cloud storage verification. - -|--only-disk-test |- |Runs only the disk benchmarks. +== Flags -|--only-network-test |- |Runs only network benchmarks. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--cloud-backoff-ms |uint |The backoff in milliseconds for a cloud storage request. +|--cloud-timeout-ms |uint |The timeout in milliseconds for a cloud storage request. +|--disk-duration-ms |uint |The duration in milliseconds of individual disk test runs. +|--network-duration-ms |uint |The duration in milliseconds of individual network test runs. +|--no-confirm |bool |Acknowledge warning prompt skipping read from stdin. +|--only-cloud-test |bool |Runs only cloud storage verification. +|--only-disk-test |bool |Runs only the disk benchmarks. +|--only-network-test |bool |Runs only network benchmarks. +|--participant-node-ids |intSlice |Comma-separated list of broker IDs that the tests will run on. If not set, tests will run for all node IDs. +|=== -|--participant-node-ids |uints |Comma-separated list of broker IDs that the tests will run -on. If not set, tests will run for all node IDs. +== Global flags -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Suggested reading -|-v, --verbose |- |Enable verbose logging. -|=== +* xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`] +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-status.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-status.adoc index c3f65fdedc..2852918fe6 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-status.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-status.adoc @@ -1,68 +1,89 @@ = rpk cluster self-test status -:description: Reference for the 'rpk cluster self-test status' command. Queries the status of the currently running or last completed self-test run. +:description: pass:q[Returns the status of the current running tests or the cached results of the last completed run. Use this command after invoking `self-test start` to determine the status of the jobs launched.] +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Returns the status of the current running tests or the cached results of the last completed run. -Use this command after invoking xref:./rpk-cluster-self-test-start.adoc[rpk cluster self-test start] to determine the status of +Use this command after invoking `self-test start` to determine the status of the jobs launched. Possible results are: * One or more jobs still running -** Returns the IDs of Redpanda brokers (nodes) still running self-tests. Example: + * Returns the IDs of Redpanda brokers (`nodes`) still running self-tests. -[,bash,role=no-copy] ----- -Node 1 is still running net self test ----- +* No jobs running: + * Returns the cached results for all brokers of the last completed test. -* No jobs running -** Returns the cached results for all brokers of the last completed test. +Test results are grouped by broker ID. Each test returns the following: -include::reference:partial$rpk-self-test-descriptions.adoc[] +* Name: Description of the test. -== Usage +* Info: Details about the test run attached by Redpanda. -[,bash] ----- -rpk cluster self-test status [flags] ----- +* Type: Either `disk`, `network`, or `cloud` test. -== Flags +* Test Id: Unique identifier given to jobs of a run. All IDs in a test should match. If they don't match, then newer and/or older test results have been included erroneously. -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* +* Timeouts: Number of timeouts incurred during the test. -|--format |string |Output format. Possible values: `json`, `text`. Default: `text`. +* Start time: Time that the test started, in UTC. -|-h, --help |- |Help for status. +* End time: Time that the test ended, in UTC. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +* Avg Duration: Duration of the test. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +* IOPS: Number of operations per second. For disk, it`s `seastar::dma_read' and 'seastar::dma_write'. For network, it`s `rpc.send()'. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +* Throughput: For disk, throughput rate is in bytes per second. For network, throughput rate is in bits per second. Note that GiB vs. Gib is the correct notation displayed by the UI. + +* Latency: 50th, 90th, etc. percentiles of operation latency, reported in microseconds (μs). Represented as P50, P90, P99, P999, and MAX respectively. +If Tiered Storage is not enabled, the cloud storage tests won't run and a warning will be displayed showing "Cloud storage is not enabled.". All results will be shown as 0. + +include::reference:partial$rpk-self-test-descriptions.adoc[] + +== Usage + +[,bash] +---- +rpk cluster self-test status [flags] +---- -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. -|-v, --verbose |- |Enable verbose logging. -|=== == Example -Example input: +This section provides examples of how to use `rpk cluster self-test status`. + +Example input. [,bash] ---- rpk cluster self-test status ---- -.Example output -include::reference:partial$rpk-self-test-status-output.adoc[] +== Flags -== Related topics +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--format |string |Output format (`text`, `json`). +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -* xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Guide for running self-test for cluster diagnostics] -* xref:./rpk-cluster-self-test.adoc[rpk cluster self-test] -* xref:./rpk-cluster-self-test-start.adoc[rpk cluster self-test start] -* xref:./rpk-cluster-self-test-stop.adoc[rpk cluster self-test stop] +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc index bfe8eaa958..a46c227b07 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc @@ -1,6 +1,10 @@ = rpk cluster self-test stop -:description: Reference for the 'rpk cluster self-test stop' command. Stops the currently executing self-test. +:description: Stops all self-test tests. This command stops all currently running self-tests. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Stops all self-test tests. This command stops all currently running self-tests. The command is synchronous and returns @@ -13,34 +17,33 @@ success when all jobs have been stopped or reports errors if broker timeouts hav rpk cluster self-test stop [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for stop. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +== Example output -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +$ rpk cluster self-test stop + All self-test jobs have been stopped -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Global flags -|-v, --verbose |- |Enable verbose logging. +[cols="1m,1a,2a"] |=== +|Value |Type |Description +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -== Example output - $ rpk cluster self-test stop - All self-test jobs have been stopped - -== Related topics +== Suggested reading * xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Guide for running self-test for cluster diagnostics] -* xref:./rpk-cluster-self-test.adoc[rpk cluster self-test] -* xref:./rpk-cluster-self-test-start.adoc[rpk cluster self-test start] -* xref:./rpk-cluster-self-test-status.adoc[rpk cluster self-test status] +* 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] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc index 98b898f2d1..60e327345e 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc @@ -1,34 +1,59 @@ = rpk cluster self-test +:description: Start, stop and query runs of Redpanda self-test through the Admin API listener. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Start, stop and query runs of Redpanda self-test through the Admin API listener. == Usage [,bash] ---- -rpk cluster self-test [command] +rpk cluster self-test [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for self-test. +|xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[`rpk cluster self-test start`] +|Starts one or more benchmark tests on one or more nodes of the cluster. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`] +|Returns the status of the current running tests or the cached results of the last completed run. Use this command after invoking `self-test start` to determine the status of the jobs launched. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc[`rpk cluster self-test stop`] +|Stops all self-test tests. This command stops all currently running self-tests. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|=== -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. -|-v, --verbose |- |Enable verbose logging. +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -== Related topics + +== Suggested reading * xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Guide for running self-test for cluster diagnostics] -* xref:./rpk-cluster-self-test-start.adoc[rpk cluster self-test start] -* xref:./rpk-cluster-self-test-status.adoc[rpk cluster self-test status] -* xref:./rpk-cluster-self-test-stop.adoc[rpk cluster self-test stop] +* 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] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc index 2fc0318a3d..d6101eaa11 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc @@ -1,15 +1,19 @@ -= rpk cluster storage cancel mount += rpk cluster storage cancel-mount +:description: Cancels a mount/unmount operation on a topic. Use the migration ID that is emitted when the mount or unmount operation is executed. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + // tag::single-source[] +Cancels a mount/unmount operation on a topic. + +Use the migration ID that is emitted when the mount or unmount operation is executed. +You can also get the migration ID by listing the mount/unmount operations. ifdef::env-cloud[] NOTE: This command is only supported in BYOC and Dedicated clusters. - endif::[] -Cancels a mount/unmount operation on a topic. - -Use the migration ID that is emitted when the mount or unmount operation is executed. You can also get the migration ID by listing the mount/unmount operations. - == Usage [,bash] @@ -17,39 +21,38 @@ Use the migration ID that is emitted when the mount or unmount operation is exec rpk cluster storage cancel-mount [MIGRATION ID] [flags] ---- + + == Aliases [,bash] ---- -cancel-mount, cancel-unmount +rpk cluster storage cancel-unmount ---- == Examples -Cancel a mount/unmount operation: +This section provides examples of how to use `rpk cluster storage cancel-mount`. + +Cancel a mount/unmount operation. [,bash] ---- rpk cluster storage cancel-mount 123 ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for cancel-mount. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc index 77d5f4f5a1..c61aa5634f 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc @@ -1,12 +1,11 @@ -= rpk cluster storage list mount -// tag::single-source[] - -ifdef::env-cloud[] -NOTE: This command is only supported in BYOC and Dedicated clusters. += rpk cluster storage list-mount +:description: pass:q[List mount/unmount operations on a topic to the Redpanda cluster from Tiered Storage. You can also filter the list by state using the `--filter` flag.] +:page-platforms: linux,darwin -endif::[] +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -List mount/unmount operations on a topic in the Redpanda cluster from glossterm:Tiered Storage[]. +// tag::single-source[] +List mount/unmount operations on a topic to the Redpanda cluster from Tiered Storage. You can also filter the list by state using the `--filter` flag. The possible states are: @@ -18,7 +17,11 @@ You can also filter the list by state using the `--filter` flag. The possible st - `finished` -If no filter is provided, all migrations are listed. +If no filter is provided, all migrations will be listed. + +ifdef::env-cloud[] +NOTE: This command is only supported in BYOC and Dedicated clusters. +endif::[] == Usage @@ -27,26 +30,27 @@ If no filter is provided, all migrations are listed. rpk cluster storage list-mount [flags] ---- + + == Aliases [,bash] ---- -list-mount, list-unmount +rpk cluster storage list-unmount ---- +== Examples +This section provides examples of how to use `rpk cluster storage list-mount`. -== Examples +Lists mount/unmount operations. -Lists mount/unmount operations: [,bash] ---- rpk cluster storage list-mount ---- - - -Use a filter to list only migrations in a specific state: +Use a filter to list only migrations in a specific state. [,bash] ---- @@ -57,21 +61,23 @@ rpk cluster storage list-mount --filter planned [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-f, --filter |string |Filter the list of migrations by state. Only valid for text (default `all`). +|Value |Type |Description -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|-f, --filter |string |Filter the list of migrations by state. Only valid for text. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc index 557c8597f7..08e080e17c 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc @@ -1,15 +1,20 @@ = rpk cluster storage list-mountable +:description: List topics that are available to mount from object storage. This command displays topics that exist in object storage and can be mounted to your Redpanda cluster. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + // tag::single-source[] +List topics that are available to mount from object storage. + +This command displays topics that exist in object storage and can be mounted +to your Redpanda cluster. Each topic includes its location in object storage +and namespace information if applicable. ifdef::env-cloud[] NOTE: This command is only supported in BYOC and Dedicated clusters. - endif::[] -List topics that are available to mount from object storage. - -This command displays topics that exist in object storage and can be mounted to your Redpanda cluster. Each topic includes its location in object storage and namespace information if applicable. - == Usage [,bash] @@ -17,9 +22,14 @@ This command displays topics that exist in object storage and can be mounted to rpk cluster storage list-mountable [flags] ---- + + + == Examples -List all mountable topics: +This section provides examples of how to use `rpk cluster storage list-mountable`. + +List all mountable topics. [,bash] ---- @@ -30,21 +40,22 @@ rpk cluster storage list-mountable [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for list-mountable. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|Value |Type |Description -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-mount.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-mount.adoc index da7b99daad..c4aef22e7d 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-mount.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-mount.adoc @@ -1,46 +1,42 @@ = rpk cluster storage mount -// tag::single-source[] +:description: Mount a topic from Tiered Storage, making it available for reads. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] ifdef::env-cloud[] NOTE: This command is only supported in BYOC and Dedicated clusters. - endif::[] -Mount a topic to the Redpanda cluster from glossterm:Tiered Storage[]. - -This command mounts a topic in the Redpanda cluster using log segments stored in Tiered Storage. - -You can optionally rename the topic using the `--to` flag. - -Requirements: +Mount a topic from Tiered Storage, making it available for reads. ifndef::env-cloud[] -- xref:manage:tiered-storage.adoc#enable-tiered-storage[Tiered Storage must be enabled]. +xref:manage:tiered-storage.adoc#enable-tiered-storage[Tiered Storage must be enabled]. endif::[] -- Log segments for the topic must be available in Tiered Storage. - -- A topic with the same name must not already exist in the cluster. - == Usage [,bash] ---- -rpk cluster storage mount [TOPIC] [flags] +rpk cluster storage mount [flags] ---- + + == Examples -Mounts topic ` from Tiered Storage to the cluster in the my-namespace: +This section provides examples of how to use `rpk cluster storage mount`. + +Mounts topic `` from Tiered Storage to the cluster in the ``. [,bash] ---- rpk cluster storage mount ---- - -Mount topic `` from Tiered Storage to the cluster in the `` with `` as the new topic name: +Mount topic `` from Tiered Storage to the cluster in the `` with `` as the new topic name. [,bash] ---- @@ -51,21 +47,22 @@ rpk cluster storage mount / --to / [flags] ---- + + + == Examples -Unmount topic '' from the cluster in the '': +This section provides examples of how to use `rpk cluster storage unmount`. + +Unmount topic '' from the cluster in the ''. [,bash] ---- rpk cluster storage unmount / ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for unmount. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage.adoc index d0ebd027d8..68a79721f2 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage.adoc @@ -1,37 +1,67 @@ = rpk cluster storage -// tag::single-source[] +:description: Manage cluster storage, including mounting and unmounting topics from Tiered Storage. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] ifdef::env-cloud[] NOTE: This command is only supported in BYOC and Dedicated clusters. - endif::[] -Manage the cluster storage. +Manage cluster storage, including mounting and unmounting topics from Tiered Storage. == Usage [,bash] ---- -rpk cluster storage [command] +rpk cluster storage [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc[`rpk cluster storage cancel-mount`] +|Cancels a mount/unmount operation on a topic. Use the migration ID that is emitted when the mount or unmount operation is executed. -|-h, --help |- |Help for storage. +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc[`rpk cluster storage list-mount`] +|List mount/unmount operations on a topic to the Redpanda cluster from Tiered Storage. You can also filter the list by state using the `--filter` flag. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc[`rpk cluster storage list-mountable`] +|List topics that are available to mount from object storage. This command displays topics that exist in object storage and can be mounted to your Redpanda cluster. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-mount.adoc[`rpk cluster storage mount`] +|Mount a topic from Tiered Storage, making it available for reads. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-restore.adoc[`rpk cluster storage restore`] +|Interact with the topic restoration process. This command is used to restore topics from the archival bucket, which can be useful for disaster recovery or if a topic was accidentally deleted. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-status-mount.adoc[`rpk cluster storage status-mount`] +|Check the status of a mount or unmount operation for a topic in Tiered Storage. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage-unmount.adoc[`rpk cluster storage unmount`] +|Unmount a topic, removing it from local storage while preserving data in Tiered Storage. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc index 9fce1c7a38..e2313f5d4d 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc @@ -1,17 +1,30 @@ = rpk cluster txn describe-producers -// tag::single-source[] +:description: Describe transactional producers to partitions. This command describes partitions that active transactional producers are producing to. +:page-platforms: linux,darwin -Describe transactional producers to partitions. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -This command describes partitions that active transactional producers are producing to. For more information on the producer ID and epoch columns, see `rpk cluster txn --help`. +// tag::single-source[] +Describe transactional producers to partitions. -== Concept +This command describes partitions that active transactional producers are +producing to. For more information on the producer ID and epoch columns, see +`rpk cluster txn --help`. -The last timestamp corresponds to the timestamp of the last record that was written by the client. The transaction start offset corresponds to the offset that the transaction is began at. All consumers configured to read only committed records cannot read past the transaction start offset. +The last timestamp corresponds to the timestamp of the last record that was +written by the client. The transaction start offset corresponds to the offset +that the transaction is began at. All consumers configured to read only +committed records cannot read past the transaction start offset. -The output includes a few advanced fields that can be used for sanity checking: the last sequence is the last sequence number that the producer has written, and the coordinator epoch is the epoch of the broker that is being written to. The last sequence should always go up and then wrap back to 0 at MaxInt32. The coordinator epoch should remain fixed, or rarely, increase. +The output includes a few advanced fields that can be used for sanity checking: +the last sequence is the last sequence number that the producer has written, +and the coordinator epoch is the epoch of the broker that is being written to. +The last sequence should always go up and then wrap back to 0 at MaxInt32. The +coordinator epoch should remain fixed, or rarely, increase. -You can query all topics and partitions that have active producers with --all. To filter for specific topics, use `--topics`. You can additionally filter by partitions with `--partitions`. +You can query all topics and partitions that have active producers with `--all`. +To filter for specific topics, use `--topics`. You can additionally filter by +partitions with `--partitions`. == Usage @@ -20,32 +33,31 @@ You can query all topics and partitions that have active producers with --all. T rpk cluster txn describe-producers [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-a, --all |- |Query all producer IDs on any topic. -|-h, --help |- |Help for describe-producers. -|-p, --partitions |int32 |int32Slice Partitions to describe producers for (repeatable) (default []). - -|-t, --topics |strings |Topic to describe producers for (repeatable). - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +== Flags -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|-a, --all |bool |Query all producer IDs on any topic. +|-p, --partitions |int32Slice |Partitions to describe producers for (`repeatable`). +|-t, --topics |stringSlice |Topic to describe producers for (`repeatable`). +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe.adoc index 3f1b7fe5d5..abc131f0f2 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe.adoc @@ -1,11 +1,23 @@ = rpk cluster txn describe -// tag::single-source[] +:description: pass:q[Describe transactional IDs. This command, in comparison to `list`, is a more detailed per-transaction view of transactional IDs.] +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Describe transactional IDs. -This command, in comparison to `list`, is a more detailed per-transaction view of transactional IDs. In addition to the state and producer ID, this command also outputs when a transaction started, the epoch of the producer ID, how long until the transaction times out, and the partitions currently a part of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`. +This command, in comparison to `list`, is a more detailed per-transaction view +of transactional IDs. In addition to the state and producer ID, this command +also outputs when a transaction started, the epoch of the producer ID, how long +until the transaction times out, and the partitions currently a part of the +transaction. For information on what the columns in the output mean, see +`rpk cluster txn --help`. -By default, all topics in a transaction are merged into one line. To print a row per topic, use `--format=long`. To include partitions with topics, use `--print-partitions`; `--format=json/yaml` will return the equivalent of the long format with print partitions included. +By default, all topics in a transaction are merged into one line. To print a +row per topic, use `--format=long`. To include partitions with topics, use +`--print-partitions`; `--format=json/yaml` will return the equivalent of the long +format with print partitions included. If no transactional IDs are requested, all transactional IDs are printed. @@ -13,31 +25,32 @@ If no transactional IDs are requested, all transactional IDs are printed. [,bash] ---- -rpk cluster txn describe [TXN-IDS...] [flags] +rpk cluster txn describe [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for describe. -|-p, --print-partitions |- |Include per-topic partitions that are in the transaction. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +== Flags -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|-p, --print-partitions |bool |Include per-topic partitions that are in the transaction. +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-list.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-list.adoc index ad826f091d..a5b6464527 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-list.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-list.adoc @@ -1,9 +1,15 @@ = rpk cluster txn list -// tag::single-source[] +:description: pass:q[List transactions and their current states This command lists all known transactions in the cluster, the producer ID for the transactional ID, and the and the state of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`.] +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] List transactions and their current states. -This command lists all known transactions in the cluster, the producer ID for the transactional ID, and the and the state of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`. +This command lists all known transactions in the cluster, the producer ID for +the transactional ID, and the and the state of the transaction. For information +on what the columns in the output mean, see `rpk cluster txn --help`. == Usage @@ -12,33 +18,27 @@ This command lists all known transactions in the cluster, the producer ID for th rpk cluster txn list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk cluster txn ls ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for list. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn.adoc index 78114c69f5..9c84f66fd5 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn.adoc @@ -1,81 +1,117 @@ = rpk cluster txn -// tag::single-source[] +:description: Information about transactions and transactional producers. Transactions allow producing, or consume-modifying-producing, to Redpanda. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Information about transactions and transactional producers. -== Concept +Transactions allow producing, or consume-modifying-producing, to Redpanda. +The consume-modify-produce loop is also referred to as EOS (exactly once +semantics). Transactions involve a lot of technical complexity that is largely +hidden within clients. This command space helps shed a light on what is +actually happening in clients and brokers while transactions are in use. + +== Usage + +[,bash] +---- +rpk cluster txn [flags] +---- -Transactions allow producing, or consume-modifying-producing, to Redpanda. The consume-modify-produce loop is also referred to as EOS (exactly once semantics). Transactions involve a lot of technical complexity that is largely hidden within clients. This command space helps shed a light on what is actually happening in clients and brokers while transactions are in use. === Transactional ID -The transactional ID is the string you define in clients when actually using transactions. +The transactional ID is the string you define in clients when actually using +transactions. === Producer ID & Epoch The producer ID is generated within clients when you transactionally produce. - -The producer ID is a number that maps to your transactional ID, allowing requests to be smaller when producing, and allowing some optimizations within brokers when managing transactions. - -Some clients expose the producer ID, allowing you to track the transactional ID that a producer ID maps to. If possible, it is recommended to monitor the producer ID used in your applications. - -The producer epoch is a number that somewhat "counts" the number of times your transaction has been initialized or expired. If you have one client that uses a transactional ID, it may receive producer ID 3 epoch 0. Another client that uses that same transactional ID will receive producer ID 3 epoch 1. If the client starts a transaction but does not finish it in time, the cluster will internally bump the epoch to 2. The epoch allows the cluster to "fence" clients: if a client attempts to use a producer ID with an old epoch, the cluster will reject the client's produce request as stale. +The producer ID is a number that maps to your transactional ID, allowing +requests to be smaller when producing, and allowing some optimizations within +brokers when managing transactions. + +Some clients expose the producer ID, allowing you to track the transactional ID +that a producer ID maps to. If possible, it is recommended to monitor the +producer ID used in your applications. + +The producer epoch is a number that somewhat `counts` the number of times your +transaction has been initialized or expired. If you have one client that uses +a transactional ID, it may receive producer ID 3 epoch 0. Another client that +uses that same transactional ID will receive producer ID 3 epoch 1. If the +client starts a transaction but does not finish it in time, the cluster will +internally bump the epoch to 2. The epoch allows the cluster to `fence` +clients: if a client attempts to use a producer ID with an old epoch, the +cluster will reject the client's produce request as stale. === Transaction State -The state of a transaction indicates what is currently happening with a transaction. A high level overview of transactional states: +The state of a transaction indicates what is currently happening with a +transaction. A high level overview of transactional states: -* Empty: The transactional ID is ready, but there are no partitions - nor groups added to it. There is no active transaction. -* Ongoing: The transactional ID is being used in a began transaction. +* `Empty`: the transactional ID is ready but there are no partitions nor groups added to it -- there is no active transaction +* `Ongoing`: the transactional ID is being used in a began transaction +* `PrepareCommit`: a commit is in progress +* `PrepareAbort`: an abort is in progress +* `PrepareEpochFence`: the transactional ID is timing out +* `Dead`: the transactional ID has expired and/or is not in use -* PrepareCommit: A commit is in progress. - -* PrepareAbort: An abort is in progress. - -* PrepareEpochFence: The transactional ID is timing out. - -* Dead: The transactional ID has expired and/or is not in use. === Last Stable Offset -The last stable offset is the offset at which a transaction has begun and clients cannot consume past, if the client is configured to read only committed offsets. The last stable offset can be seen when describing active transactional producers by looking for the earliest transaction start offset per partition. +The last stable offset is the offset at which a transaction has begun and +clients cannot consume past, if the client is configured to read only committed +offsets. The last stable offset can be seen when describing active transactional +producers by looking for the earliest transaction start offset per partition. -== Usage - -[,bash] ----- -rpk cluster txn [command] [flags] ----- == Aliases [,bash] ---- -txn, transaction +rpk cluster transaction ---- -== Flags +== Subcommands -[cols="1m,1a,2a"] +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-txn-describe.adoc[`rpk cluster txn describe`] +|Describe transactional IDs. This command, in comparison to `list`, is a more detailed per-transaction view of transactional IDs. -|-h, --help |- |Help for txn. +|xref:reference:rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc[`rpk cluster txn describe-producers`] +|Describe transactional producers to partitions. This command describes partitions that active transactional producers are producing to. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-txn-list.adoc[`rpk cluster txn list`] +|List transactions and their current states This command lists all known transactions in the cluster, the producer ID for the transactional ID, and the and the state of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster.adoc index 4bdbca9268..0f95180216 100644 --- a/modules/reference/pages/rpk/rpk-cluster/rpk-cluster.adoc +++ b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster.adoc @@ -1,33 +1,78 @@ = rpk cluster -// tag::single-source[] -:description: These commands let you interact with a Redpanda cluster. +:description: Manage and inspect Redpanda cluster configuration, health, and maintenance operations. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -Interact with a Redpanda cluster. +// tag::single-source[] +Manage and inspect Redpanda cluster configuration, health, and maintenance operations. == Usage [,bash] ---- -rpk cluster [command] +rpk cluster [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-cluster/rpk-cluster-config.adoc[`rpk cluster config`] +|View and modify cluster-wide configuration properties. Changes take effect across all brokers. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-connections.adoc[`rpk cluster connections`] +|Manage and monitor cluster connections. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-health.adoc[`rpk cluster health`] +|Query cluster health and display the overall health status of the cluster. Redpanda collects health reports periodically from all nodes and aggregates them into a health overview. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-info.adoc[`rpk cluster info`] +|Request broker metadata information. The Kafka protocol's metadata contains information about brokers, topics, and the cluster as a whole. -|-h, --help |- |Help for cluster. +|xref:reference:rpk/rpk-cluster/rpk-cluster-license.adoc[`rpk cluster license`] +|Manage cluster license. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-cluster/rpk-cluster-logdirs.adoc[`rpk cluster logdirs`] +|Describe log directories on Redpanda brokers. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-cluster/rpk-cluster-maintenance.adoc[`rpk cluster maintenance`] +|Manage cluster maintenance mode for performing rolling upgrades and other maintenance operations. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-cluster/rpk-cluster-partitions.adoc[`rpk cluster partitions`] +|Manage cluster partitions. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-cluster/rpk-cluster-quotas.adoc[`rpk cluster quotas`] +|Manage Redpanda client quotas. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[`rpk cluster self-test`] +|Start, stop and query runs of Redpanda self-test through the Admin API listener. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-storage.adoc[`rpk cluster storage`] +|Manage cluster storage, including mounting and unmounting topics from Tiered Storage. + +|xref:reference:rpk/rpk-cluster/rpk-cluster-txn.adoc[`rpk cluster txn`] +|Information about transactions and transactional producers. Transactions allow producing, or consume-modifying-producing, to Redpanda. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-init.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-init.adoc index e619983eac..12d9feca34 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-init.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-init.adoc @@ -1,41 +1,48 @@ = rpk connect agent init -:description: Initialize a Redpanda Connect agent. -:page-topic-type: reference -:learning-objective-1: Find the syntax for initializing an agent template -:learning-objective-2: Identify available initialization options +:description: Initialize a template for building a Redpanda Connect agent. +:page-platforms: linux,darwin -[IMPORTANT] -==== -This command is experimental and subject to change. -==== +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +:page-topic-type: reference +// tag::single-source[] Initialize a template for building a Redpanda Connect agent. -Use this reference to: - -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} +IMPORTANT: This command is experimental and subject to change. == Usage - rpk connect agent init [OPTIONS] +[,bash] +---- +rpk connect agent init [flags] +---- + + + == Example +This section provides examples of how to use `rpk connect agent init`. + +Example. + [,bash] ---- rpk connect agent init ./repo ---- -== Flags -[cols="1m,2a"] -|=== -| Option | Description +== Global flags -| --name -| The name of the agent. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -| --help, -h -| Show help for the command. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-run.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-run.adoc index b1b4cc0c65..3af810c6f8 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-run.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent-run.adoc @@ -1,59 +1,55 @@ = rpk connect agent run -:description: Execute a Redpanda Connect agent as part of a pipeline with MCP tool access. +:description: pass:q[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.] +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc :page-topic-type: reference -:learning-objective-1: Find the syntax for executing agents -:learning-objective-2: Identify secret management options -:learning-objective-3: Look up security-related flags -[IMPORTANT] -==== -This command is experimental and subject to change. -==== +// tag::single-source[] +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. + +IMPORTANT: This command is experimental and subject to change. -Execute a Redpanda Connect agent as part of a pipeline that has access to tools via the Model Context Protocol (MCP). The command first reads resource definitions from the `mcp` subdirectory and exposes them as tools. It then runs the agent defined in `redpanda_agents.yaml` along with any Python agent modules. +== Usage -Use this reference to: +[,bash] +---- +rpk connect agent run [flags] +---- -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -* [ ] {learning-objective-3} -== Usage - rpk connect agent run [OPTIONS] == Example +This section provides examples of how to use `rpk connect agent run`. + +Example. + [,bash] ---- rpk connect agent run ./repo ---- -To disable all secret lookups: +To disable all secret lookups. [,bash] ---- rpk connect agent run --secrets none: ./repo ---- -== Flags - -[cols="1m,2a"] -|=== -| Option | Description - -| --secrets -| Attempt to load secrets from a provided URN. If more than one entry is specified, they are attempted in order until a value is found. Environment variable lookups are specified with the URN `env:`, which by default is the only entry. To disable all secret lookups, specify a single entry of `none:` (default: `env:`). -| --redpanda-license -| Provide an explicit Redpanda license, which enables enterprise functionality. By default, licenses found at the path `/etc/redpanda/redpanda.license` are applied. +== Global flags -| --help, -h -| Show help for the command. - -| --chroot -| (Linux only) Chroot into the provided directory after parsing configuration. Common `/etc/` files are copied to the chroot directory, and the directory is made read-only. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -| --chroot-passthrough -| (Linux only) Specify additional files to be copied into the chroot directory. Can be specified multiple times. Only valid when `--chroot` is used. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc index 3ed40783bf..d8a209f68e 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-agent.adoc @@ -1,37 +1,57 @@ = rpk connect agent -:description: Redpanda Connect agent commands. +:description: Manage Redpanda Connect agents. Agents allow you to build AI-powered workflows using Redpanda Connect resources. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc :page-topic-type: reference -:learning-objective-1: Look up available agent subcommands -:learning-objective-2: Identify agent command options -[IMPORTANT] -==== -This command is experimental and subject to change. -==== +// tag::single-source[] +Manage Redpanda Connect agents. Agents allow you to build AI-powered workflows using Redpanda Connect resources. + +IMPORTANT: This command is experimental and subject to change. -Run and initialize Redpanda Connect agents. Agents are pipelines that have access to tools via the Model Context Protocol (MCP) and can interact with AI models. +== Usage -Use this reference to: +[,bash] +---- +rpk connect agent [flags] +---- -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -== Usage - rpk connect agent [command] == Subcommands -* xref:reference:rpk/rpk-connect/rpk-connect-agent-init.adoc[init]: Initialize a Redpanda Connect agent. -* xref:reference:rpk/rpk-connect/rpk-connect-agent-run.adoc[run]: Execute a Redpanda Connect agent as part of a pipeline with MCP tool access. -* help, h: Show a list of commands or help for one command. +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-connect/rpk-connect-agent-init.adoc[`rpk connect agent init`] +|Initialize a template for building a Redpanda Connect agent. + +|xref:reference:rpk/rpk-connect/rpk-connect-agent-run.adoc[`rpk connect agent run`] +|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. + +|=== -== Flags -[cols="1m,2a"] +== Global flags + +[cols="1m,1a,2a"] |=== -| Option | Description +|Value |Type |Description -| --help, -h -| Show help for the command. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + + +== Suggested reading + +* 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] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl-server.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl-server.adoc index cb7b8b2faa..26948a80a8 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl-server.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl-server.adoc @@ -1,31 +1,36 @@ = rpk connect blobl server +:description: Run a web server that provides an interactive application for writing and testing Bloblang mappings. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Run a web server that provides an interactive application for writing and testing Bloblang mappings. +WARNING: This server is intended for local debugging and experimentation purposes only. Do NOT expose it to the internet. + == Usage [,bash] ---- -rpk connect blobl server [command options] [arguments...] +rpk connect blobl server [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--host |- | The host to bind to (default: "localhost"). -|--port, -p |- | The port to bind to (default: "4195"). -|--no-open, -n |- | Do not open the app in the browser automatically (default: false). -|--mapping-file, -m |- | An optional path to a mapping file to load as the initial mapping within the app. +== Global flags -|--input-file, -i |- | An optional path to an input file to load as the initial input to the mapping within the app. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--write, -w |- | When editing a mapping or input file, write changes made back to the respective source file. If the file does not exist, it is created (default: false). +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--help, -h |- | When editing a mapping or input file, write changes made back to the respective source file. If the file does not exist, it is created (default: false). -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl.adoc new file mode 100644 index 0000000000..83b62b1a96 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl.adoc @@ -0,0 +1,75 @@ += rpk connect blobl +:description: Execute Bloblang mappings from the command line. Provides a convenient tool for mapping JSON documents. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Execute Bloblang mappings from the command line. Provides a convenient tool for mapping JSON documents. + +== Usage + +[,bash] +---- +rpk connect blobl [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk connect blobl`. + +Map JSON documents from stdin. + +[,bash] +---- +cat documents.jsonl | rpk connect blobl 'foo.bar.map_each(this.uppercase())' +---- + +Use a mapping file. + +[,bash] +---- +echo '{"foo":"bar"}' | rpk connect blobl -f ./mapping.blobl +---- + +Process input from a file. + +[,bash] +---- +rpk connect blobl -i input.jsonl -f ./mapping.blobl +---- + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-connect/rpk-connect-blobl-server.adoc[`rpk connect blobl server`] +|Run a web server that provides an interactive application for writing and testing Bloblang mappings. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + + +== Suggested reading + +* xref:connect:guides:bloblang/about.adoc[Bloblang] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-create.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-create.adoc index 503f5ec31a..63a3eeba5c 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-create.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-create.adoc @@ -1,34 +1,60 @@ = rpk connect create +:description: Prints a new Redpanda Connect config to stdout containing specified components according to an expression. +:page-platforms: linux,darwin -Create a new Redpanda Connect config and print a new Redpanda Connect config to stdout containing specified components according to an expression. The expression must take the form of three comma-separated lists of inputs, processors, and outputs, divided by forward slashes. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -If the expression is omitted, a default config is created. +// tag::single-source[] +Prints a new Redpanda Connect config to stdout containing specified components +according to an expression. The expression must take the form of three +comma-separated lists of inputs, processors and outputs, divided by +forward slashes: + +redpanda-connect create stdin/bloblang,awk/nats + redpanda-connect create file,http_server/protobuf/http_client. + +If the expression is omitted a default config is created. == Usage [,bash] ---- -rpk connect create [command options] [arguments...] +rpk connect create [flags] ---- + + + == Examples -```bash +This section provides examples of how to use `rpk connect create`. + +Create a config with stdin input, bloblang/awk processor, and nats output. + +[,bash] +---- rpk connect create stdin/bloblang,awk/nats -``` +---- -```bash +Create a config with file/http_server inputs, protobuf processor, and http_client output. + +[,bash] +---- rpk connect create file,http_server/protobuf/http_client -``` +---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--small, -s |- | Print only the main components of a Redpanda Connect config (input, pipeline, output) and omit all fields marked as advanced (default: false). +|Value |Type |Description -|--help, -h |- | Show help +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-dry-run.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-dry-run.adoc index e5208a52f0..c8fd662fdd 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-dry-run.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-dry-run.adoc @@ -1,52 +1,53 @@ = rpk connect dry-run -:description: Parse Redpanda Connect configs and test the connections of each plugin. +:description: Test pipeline configurations by performing a dry run. Exits with a status code 1 if any connection errors are detected in a directory. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc :page-topic-type: reference -:learning-objective-1: Find the syntax for testing pipeline configurations -:learning-objective-2: Look up connection testing options -Parse Redpanda Connect configs and test the connections of each plugin. Exits with a status code of `1` if the command detects any connection errors. +// tag::single-source[] +Test pipeline configurations by performing a dry run. Exits with a status code 1 if any connection errors are detected in a directory. + +== Usage -Use this reference to: +[,bash] +---- +rpk connect dry-run [flags] +---- -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -== Usage - rpk connect dry-run [OPTIONS] [files...] == Example +This section provides examples of how to use `rpk connect dry-run`. + +Example. + [,bash] ---- rpk connect dry-run ./pipeline.yaml ---- -To disable all secret lookups: +To disable all secret lookups. [,bash] ---- rpk connect dry-run --secrets none: ./pipeline.yaml ---- -== Flags - -[cols="1m,2a"] -|=== -| Option | Description - -| --verbose -| Print the lint result for each target file (default: false). -| --secrets -| Attempt to load secrets from a provided URN. If more than one entry is specified, they are attempted in order until a value is found. Environment variable lookups are specified with the URN `env:`, which by default is the only entry. To disable all secret lookups, specify a single entry of `none:` (default: `env:`). +== Global flags -| --env-file, -e -| Import environment variables from a dotenv file. - -| --redpanda-license -| Provide an explicit Redpanda license, which enables enterprise functionality. By default, licenses found at the path `/etc/redpanda/redpanda.license` are applied. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -| --help, -h -| Show help for the command. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-echo.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-echo.adoc index 31a2e5f2c7..3fe6450e34 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-echo.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-echo.adoc @@ -1,27 +1,34 @@ = 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. +:page-platforms: linux,darwin -Parse a configuration file and echo back a normalized version. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -This command is useful to check a configuration that isn't working as expected. It shows a normalized version after environment variables have been resolved. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk connect echo [arguments...] +rpk connect echo [flags] ---- -== Example -```bash -rpk connect echo ./config.yaml | less -``` -== Flags + + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|--help, -h |- | Show help. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-help.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-help.adoc new file mode 100644 index 0000000000..b0d85e859b --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-help.adoc @@ -0,0 +1,34 @@ += rpk connect help +:description: Shows a list of commands or help for one command. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Shows a list of commands or help for one command. + +== Usage + +[,bash] +---- +rpk connect help [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-install.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-install.adoc index f231f852d6..5094eefbd7 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-install.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-install.adoc @@ -1,10 +1,11 @@ = rpk connect install +:description: Install Redpanda Connect. This command installs the latest version by default. +:page-platforms: linux,darwin -Install Redpanda Connect. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -By default, this command installs the latest version of Redpanda Connect. Alternatively, you can use the command with the `--connect-version` flag to install a specific version. - -To force the installation of Redpanda Connect, use the `--force` flag. +// tag::single-source[] +Install Redpanda Connect. This command installs the latest version by default. Use the `--connect-version` flag to specify a version. == Usage @@ -13,25 +14,30 @@ To force the installation of Redpanda Connect, use the `--force` flag. rpk connect install [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--connect-version |string |The Redpanda Connect version to install. For example: "4.32.0" (default "latest"). -|--force |- |Force install of Redpanda Connect. +== Flags -|-h, --help |- |Help for install. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|--connect-version |string |Redpanda Connect version to install. (for example, 4.32.0). +|--force |bool |Force install of Redpanda Connect. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-lint.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-lint.adoc index e7a0e343d5..c34b7c11ba 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-lint.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-lint.adoc @@ -1,47 +1,66 @@ = rpk connect lint +:description: Check a Redpanda Connect configuration file for syntax errors and potential issues without running it. +:page-platforms: linux,darwin -Parse Redpanda Connect configs and report any linting errors. Exits with a status code 1 if any linting errors are detected. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -If a path ends with `...`, Redpanda Connect lints any files with the `.yaml` or `.yml` extension. +// tag::single-source[] +Check a Redpanda Connect configuration file for syntax errors and potential issues without running it. == Usage [,bash] ---- -rpk connect lint [command options] [arguments...] +rpk connect lint [flags] ---- + + + == Examples -```bash +This section provides examples of how to use `rpk connect lint`. + +Lint a specific file. + +[,bash] +---- rpk connect lint target.yaml -``` +---- + +Lint all YAML files in a directory. -```bash +[,bash] +---- rpk connect lint ./configs/*.yaml -``` +---- + +Lint with resource imports. -```bash +[,bash] +---- rpk connect lint -r ./foo.yaml ./bar.yaml -``` +---- -```bash +Lint all files in a directory tree. + +[,bash] +---- rpk connect lint ./configs/... -``` +---- + -== Flags +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--resources, -r |- | Pulls in extra resources from a file, which you can reference with a unique label in the main configuration. Supports glob patterns (requires quotes). +|Value |Type |Description -|--deprecated |- | Print linting errors for the presence of deprecated fields (default: false). - -|--labels |- | Print linting errors when components do not have labels (default: false). - -|--skip-env-var-check |- | Do not produce lint errors for environment interpolations missing defaults (default: false). +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--help, -h |- | Show help. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-list.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-list.adoc index 9a5ada4287..1dd8b1bf12 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-list.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-list.adoc @@ -1,42 +1,59 @@ = 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. +:page-platforms: linux,darwin -List all Redpanda Connect component types. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -If any component types are explicitly listed, then only types of those components are shown. +// tag::single-source[] +List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines. == Usage [,bash] ---- -rpk connect list [command options] [arguments...] +rpk connect list [flags] ---- + + + == Examples +This section provides examples of how to use `rpk connect list`. + +Example. + [,bash] ---- rpk connect list ---- +Example. + [,bash] ---- rpk connect list --format json inputs output ---- +Example. + [,bash] ---- rpk connect list rate-limits buffers ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|--format |- | Print the component list in a specific format. Options are text, json, or cue (default: "text"). - -|--status |- | Filter the component list to only those matching the given status. Options are stable, beta, or experimental. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--help, -h |- | Show help. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-init.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-init.adoc new file mode 100644 index 0000000000..fcdab22fab --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-init.adoc @@ -0,0 +1,36 @@ += rpk connect mcp-server init +:description: Initialize an MCP server project. Files that already exist will not be overwritten. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Initialize an MCP server project. Files that already exist will not be overwritten. + +IMPORTANT: This command is experimental and subject to change. + +== Usage + +[,bash] +---- +rpk connect mcp-server init [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc new file mode 100644 index 0000000000..5846329a70 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Lint MCP server resources. Exits with a status code 1 if any linting errors are detected in the specified directory. + +IMPORTANT: This command is experimental and subject to change. + +== Usage + +[,bash] +---- +rpk connect mcp-server lint [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server.adoc new file mode 100644 index 0000000000..d7b321d49e --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server.adoc @@ -0,0 +1,50 @@ += 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. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Execute an MCP server against a suite of Redpanda Connect resources. Each resource will be exposed as a tool that AI can interact with. + +IMPORTANT: This command is experimental and subject to change. + +== Usage + +[,bash] +---- +rpk connect mcp-server [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-connect/rpk-connect-mcp-server-init.adoc[`rpk connect mcp-server init`] +|Initialize an MCP server project. Files that already exist will not be overwritten. + +|xref:reference:rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc[`rpk connect mcp-server lint`] +|Lint MCP server resources. Exits with a status code 1 if any linting errors are detected in the specified directory. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin-init.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin-init.adoc index fce84c9d1d..8dfd6ee8d7 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin-init.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin-init.adoc @@ -1,44 +1,48 @@ = rpk connect plugin init -:description: Create the boilerplate for a custom Redpanda Connect plugin. +: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). +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc :page-topic-type: reference -:learning-objective-1: Find the syntax for creating custom plugins -:learning-objective-2: Identify supported languages and component types -[IMPORTANT] -==== -This command is experimental and subject to change. -==== +// tag::single-source[] +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). -Generate a project on the local filesystem that can be used as a starting point for building a custom component for Redpanda Connect. The command overwrites existing files in the specified directory. +IMPORTANT: This command is experimental and subject to change. -Use this reference to: +== Usage + +[,bash] +---- +rpk connect plugin init [flags] +---- -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -== Usage - rpk connect plugin init [OPTIONS] == Example +This section provides examples of how to use `rpk connect plugin init`. + +Example. + [,bash] ---- rpk connect plugin init example-plugin ---- -== Flags - -[cols="1m,2a"] -|=== -| Option | Description -| --language, --lang -| The programming language for the plugin. Supported languages are `golang` and `python` (default: `python`). +== Global flags -| --component -| The type of component to generate. Supported components are `input`, `output`, and `processor` (default: `processor`). +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -| --help, -h -| Show help for the command. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc index a506bcc39c..63de74bd03 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-plugin.adoc @@ -1,36 +1,53 @@ = rpk connect plugin -:description: Plugin management commands for Redpanda Connect. +:description: Manage custom Redpanda Connect plugins. Use these commands to create and initialize plugin projects for extending Redpanda Connect with custom components. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc :page-topic-type: reference -:learning-objective-1: Look up available plugin management commands -:learning-objective-2: Identify plugin command options -[IMPORTANT] -==== -This command is experimental and subject to change. -==== +// tag::single-source[] +Manage custom Redpanda Connect plugins. Use these commands to create and initialize plugin projects for extending Redpanda Connect with custom components. + +IMPORTANT: This command is experimental and subject to change. -Manage custom Redpanda Connect plugins. Use these commands to scaffold and build custom components. +== Usage -Use this reference to: +[,bash] +---- +rpk connect plugin [flags] +---- -* [ ] {learning-objective-1} -* [ ] {learning-objective-2} -== Usage - rpk connect plugin [command] == Subcommands -* xref:reference:rpk/rpk-connect/rpk-connect-plugin-init.adoc[init]: Create the boilerplate for a custom component plugin. -* help, h: Show a list of commands or help for one command. +[cols="1,2a"] +|=== +|Command |Description -== Flags +|xref:reference:rpk/rpk-connect/rpk-connect-plugin-init.adoc[`rpk connect plugin init`] +|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). -[cols="1m,2a"] |=== -| Option | Description -| --help, -h -| Show help for the command. + +== Global flags + +[cols="1m,1a,2a"] |=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + + +== Suggested reading + +* xref:reference:rpk/rpk-connect/rpk-connect-plugin-init.adoc[rpk connect plugin init] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-run.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-run.adoc index b7524f33ac..edaf65cbad 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-run.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-run.adoc @@ -1,42 +1,49 @@ = rpk connect run +:description: Run a Redpanda Connect pipeline from a configuration file. The pipeline streams data between inputs and outputs with optional processing. +:page-platforms: linux,darwin -Run Redpanda Connect in normal mode against a specified config file. - -== Usage - -[,bash] ----- -rpk connect run [command options] [arguments...] ----- - -== Example - -[,bash] ----- -rpk connect run ./foo.yaml ----- +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -== Flags +// tag::single-source[] +Run a Redpanda Connect pipeline from a configuration file. The pipeline streams data between inputs and outputs with optional processing. == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description + +|--log.level |string |Override the configured log level. Acceptable values: `off`, `error`, `warn`, `info`, `debug`, `trace`. +|--set |stringArray |Set a field (identified by a dot path) in the main configuration file. For example: `metrics.type=prometheus`. +|--resources, -r |stringArray |Pull in extra resources from a file, which can be referenced the same as resources defined in the main config. This supports glob patterns (requires quotes). +|--chilled |bool |Continue to execute a config containing linter errors (default: false). +|--watcher, -w |bool |EXPERIMENTAL: Watch config files for changes and automatically apply them (default: false). +|--env-file, -e |string |Import environment variables from a dotenv file. +|--templates, -t |stringArray |EXPERIMENTAL: Import Redpanda Connect templates. This supports glob patterns (requires quotes). +|=== -|--log.level |- |Override the configured log level. Available values: `off`, `error`, `warn`, `info`, `debug`, `trace` +== Usage -|--set |- |Set a field (identified by a dot path) in the main configuration file. For example: `metrics.type=prometheus` +[,bash] +---- +rpk connect run [flags] +---- -|--resources, -r |- |Pull in extra resources from a file, which can be referenced by the same as resources defined in the main config. This supports glob patterns (requires quotes). -|--chilled |- |Continue to execute a config containing linter errors (default: false). -|--watcher, -w |- |EXPERIMENTAL: Watch config files for changes and automatically apply them (default: false). -|--env-file, -e |- |Import environment variables from a dotenv file. -|--templates, -t |- |EXPERIMENTAL: Import Redpanda Connect templates. This supports glob patterns (requires quotes). +== Global flags -|--set |- |Set a field (identified by a dot path) in the main configuration file. For example: `metrics.type=prometheus` +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-streams.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-streams.adoc index b4d15171d9..6045b5a505 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-streams.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-streams.adoc @@ -1,51 +1,71 @@ = rpk connect streams +:description: pass:q[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.] +:page-platforms: linux,darwin -Run Redpanda Connect in streams mode, where multiple pipelines can be executed in a single process and can be created, updated, and removed with REST HTTP endpoints. In streams mode, the stream fields of a root target configuration (input, buffer, pipeline, output) are ignored. Other fields are shared across all loaded streams (resources, metrics, etc.). +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -See xref:connect:guides:streams_mode/about.adoc[Streams Mode]. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk connect streams [command options] [arguments...] +rpk connect streams [flags] ---- + + + == Examples +This section provides examples of how to use `rpk connect streams`. + +Example. + [,bash] ---- rpk connect streams ---- +Example. + [,bash] ---- rpk connect streams -o ./root_config.yaml ---- +Example. + [,bash] ---- rpk connect streams ./path/to/stream/configs ./and/some/more ---- +Example. + [,bash] ---- rpk connect streams -o ./root_config.yaml ./streams/*.yaml ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|--no-api |- | Disable the HTTP API for streams mode (default: false). +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--observability, -o |- | Specify a path to a service wide configuration file, which can include observability configuration, such as metrics, logger, and tracing sections. -|--prefix-stream-endpoints |- | Whether HTTP endpoints registered by stream configs should be prefixed with the stream ID (default: true). +== Suggested reading -|--resources, -r |- | Pull in extra resources from a file, which can be referenced by a unique label in the main configuration. Supports glob patterns (requires quotes). +* xref:connect:guides:streams_mode/about.adoc[Streams Mode] -|--help, -h |- | Show help. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-pull.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-pull.adoc deleted file mode 100644 index efb0856464..0000000000 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-pull.adoc +++ /dev/null @@ -1,33 +0,0 @@ -= rpk connect studio pull - -Run deployments configured within a Redpanda Connect session. - -When a Studio session has one or more deployments added, this command synchronizes with the session and obtains a deployment assignment. The assigned deployment then determines which configs from the session to download and execute. - -When changes are made to files of an assigned deployment, or when a new deployment is assigned, this service automatically downloads the new config files and executes them, replacing the previous running stream. - -== Usage - -[,bash] ----- -rpk connect studio pull [command options] [arguments...] ----- - -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--session, -s |- | The session ID to synchronize with. - -|--name |- | An explicit name to adopt in this instance, used to identify its connection to the session. Each running node must have a unique name. If left unset, a name is generated each time the command is run. - -|--token, -h |- | A token for the session, used to authenticate requests. If left blank, the environment variable `BSTDIO_NODE_TOKEN` is used. - -|--token-secret |- | A token secret the session, used to authenticate requests. If left blank, the environment variable `BSTDIO_NODE_SECRET` is used. - -|--send-traces |- | Whether to send trace data back to Studio during execution. This is an opt-in way to add trace events to the graph editor for testing and debugging configs. This is a very useful feature, but use it with caution, because it exports information about messages passing through the stream (default: false). - -|--help, -h |- | Show help. -|=== \ No newline at end of file diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-sync-schema.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-sync-schema.adoc deleted file mode 100644 index 07e249fb6e..0000000000 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-sync-schema.adoc +++ /dev/null @@ -1,27 +0,0 @@ -= rpk connect studio sync-schema - -Synchronizes the schema of this Redpanda Connect instance with a Studio session. - -This sync allows custom plugins and templates to be configured and linted correctly within Benthos Studio. - -To synchronize a single use, a token must be generated from the session page within the Studio application. - -== Usage - -[,bash] ----- -rpk connect studio sync-schema [command options] [arguments...] ----- - -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--session, -s |- | The session ID to synchronize with. - -|--token, -t |- | The single use token used to authenticate the request. - -|--help, -h |- | Show help. -|=== \ No newline at end of file diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-template-lint.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-template-lint.adoc index a4961df2b1..1dabe1b98a 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-template-lint.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-template-lint.adoc @@ -1,45 +1,66 @@ = rpk connect template lint +:description: Lint Redpanda Connect template files. Exits with a status code 1 if any linting errors are detected. +:page-platforms: linux,darwin -Parse Redpanda Connect templates and report any linting errors. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -Exits with a status code 1 if any linting errors are detected. - -If a path ends with `...`, Redpanda Connect lints any files with the `.yaml` or `.yml` extension. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk connect template lint [command options] [arguments...] +rpk connect template lint [flags] ---- + + + == Examples +This section provides examples of how to use `rpk connect template lint`. + +Example. + [,bash] ---- rpk connect template lint ---- +Example. + [,bash] ---- rpk connect template lint ./templates/*.yaml ---- +Example. + [,bash] ---- rpk connect template lint ./foo.yaml ./bar.yaml ---- +Example. + [,bash] ---- rpk connect template lint ./templates/... ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|--help, -h |- | Show help. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-template.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-template.adoc new file mode 100644 index 0000000000..fcf0474873 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-template.adoc @@ -0,0 +1,52 @@ += rpk connect template +:description: Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns. + +IMPORTANT: This subcommand, and templates in general, are experimental and subject to change outside of major version releases. + +== Usage + +[,bash] +---- +rpk connect template [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-connect/rpk-connect-template-lint.adoc[`rpk connect template lint`] +|Lint Redpanda Connect template files. Exits with a status code 1 if any linting errors are detected. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + + +== Suggested reading + +* xref:connect:configuration:templating.adoc[Templating] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-test.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-test.adoc index 1a750bd398..edc4a175cb 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-test.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-test.adoc @@ -1,42 +1,64 @@ = rpk connect test +:description: Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior. +:page-platforms: linux,darwin -Execute any number of Redpanda Connect unit test definitions. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -If any tests fail, the process reports the errors and exits with a status code 1. - -See xref:connect:configuration:unit_testing.adoc[Unit Testing]. +// tag::single-source[] +Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior. == Usage [,bash] ---- -/opt/redpanda/bin/.rpk.ac-connect test [command options] [arguments...] +rpk connect test [flags] ---- + + + == Examples +This section provides examples of how to use `rpk connect test`. + +Example. + [,bash] ---- rpk connect test ./path/to/configs/... ---- +Example. + [,bash] ---- rpk connect test ./foo_configs/*.yaml ./bar_configs/*.yaml ---- +Example. + [,bash] ---- rpk connect test ./foo.yaml ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + + +== Suggested reading -|--log |- | Allow components to write logs at a provided level to stdout. +* xref:connect:configuration:unit_testing.adoc[Unit Testing] -|--help, -h |- | Show help. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-uninstall.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-uninstall.adoc index bbd9c82495..ecdbf7b8ed 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-uninstall.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-uninstall.adoc @@ -1,5 +1,10 @@ = rpk connect uninstall +:description: Uninstall the Redpanda Connect plugin. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Uninstall the Redpanda Connect plugin. == Usage @@ -9,21 +14,21 @@ Uninstall the Redpanda Connect plugin. rpk connect uninstall [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for uninstall. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect-upgrade.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect-upgrade.adoc index e35258f406..9b3b1bd709 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect-upgrade.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect-upgrade.adoc @@ -1,5 +1,10 @@ = rpk connect upgrade +:description: Upgrade to the latest Redpanda Connect version. +:page-platforms: linux,darwin +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] Upgrade to the latest Redpanda Connect version. == Usage @@ -9,23 +14,29 @@ Upgrade to the latest Redpanda Connect version. rpk connect upgrade [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--no-confirm |- |Disable confirmation prompt for major version upgrades. +|Value |Type |Description -|-h, --help |- |Help for upgrade. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|--no-confirm |bool |Disable confirmation prompt for major version upgrades. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc b/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc index 7dd7fc8138..fecfe93afc 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc @@ -1,30 +1,93 @@ = rpk connect -:description: These commands let you create and manage data pipelines using Redpanda Connect. +:description: Run and manage Redpanda Connect streaming pipelines. Redpanda Connect is a high-performance stream processor for mundane data engineering tasks. +:page-platforms: linux,darwin -Create and manage data pipelines using Redpanda Connect. For full details, see the xref:connect:streaming:about.adoc[Redpanda Connect documentation]. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + +// tag::single-source[] +Run and manage Redpanda Connect streaming pipelines. Redpanda Connect is a high-performance stream processor for mundane data engineering tasks. == Usage [,bash] ---- -rpk connect [command] [flags] +rpk connect [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-connect/rpk-connect-agent.adoc[`rpk connect agent`] +|Manage Redpanda Connect agents. Agents allow you to build AI-powered workflows using Redpanda Connect resources. + +|xref:reference:rpk/rpk-connect/rpk-connect-blobl.adoc[`rpk connect blobl`] +|Execute Bloblang mappings from the command line. Provides a convenient tool for mapping JSON documents. + +|xref:reference:rpk/rpk-connect/rpk-connect-create.adoc[`rpk connect create`] +|Prints a new Redpanda Connect config to stdout containing specified components according to an expression. + +|xref:reference:rpk/rpk-connect/rpk-connect-dry-run.adoc[`rpk connect dry-run`] +|Test pipeline configurations by performing a dry run. Exits with a status code 1 if any connection errors are detected in a directory. + +|xref:reference:rpk/rpk-connect/rpk-connect-echo.adoc[`rpk connect echo`] +|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. + +|xref:reference:rpk/rpk-connect/rpk-connect-help.adoc[`rpk connect help`] +|Shows a list of commands or help for one command. + +|xref:reference:rpk/rpk-connect/rpk-connect-install.adoc[`rpk connect install`] +|Install Redpanda Connect. This command installs the latest version by default. + +|xref:reference:rpk/rpk-connect/rpk-connect-lint.adoc[`rpk connect lint`] +|Check a Redpanda Connect configuration file for syntax errors and potential issues without running it. -|-h, --help |- |Help for connect. +|xref:reference:rpk/rpk-connect/rpk-connect-list.adoc[`rpk connect list`] +|List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-connect/rpk-connect-mcp-server.adoc[`rpk connect mcp-server`] +|Execute an MCP server against a suite of Redpanda Connect resources. Each resource will be exposed as a tool that AI can interact with. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-connect/rpk-connect-plugin.adoc[`rpk connect plugin`] +|Manage custom Redpanda Connect plugins. Use these commands to create and initialize plugin projects for extending Redpanda Connect with custom components. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-connect/rpk-connect-run.adoc[`rpk connect run`] +|Run a Redpanda Connect pipeline from a configuration file. The pipeline streams data between inputs and outputs with optional processing. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-connect/rpk-connect-streams.adoc[`rpk connect streams`] +|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. + +|xref:reference:rpk/rpk-connect/rpk-connect-template.adoc[`rpk connect template`] +|Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns. + +|xref:reference:rpk/rpk-connect/rpk-connect-test.adoc[`rpk connect test`] +|Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior. + +|xref:reference:rpk/rpk-connect/rpk-connect-uninstall.adoc[`rpk connect uninstall`] +|Uninstall the Redpanda Connect plugin. + +|xref:reference:rpk/rpk-connect/rpk-connect-upgrade.adoc[`rpk connect upgrade`] +|Upgrade to the latest Redpanda Connect version. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== -|-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container-purge.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container-purge.adoc index ae299289a7..b929cd2168 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container-purge.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container-purge.adoc @@ -1,6 +1,10 @@ = rpk container purge -// tag::single-source[] +:description: Stop and remove an existing local container cluster's data. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Stop and remove an existing local container cluster's data. == Usage @@ -10,23 +14,21 @@ Stop and remove an existing local container cluster's data. rpk container purge [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for purge. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== // end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc index b529541238..8279b7a386 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc @@ -1,27 +1,36 @@ = rpk container start -// tag::single-source[] +:description: Start a local container cluster. This command uses Docker to initiate a local Redpanda container cluster, including Redpanda Console. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Start a local container cluster. -This command uses Docker to initiate a local container cluster. Use the `--nodes` (or the shorthand version `-n`) flag to specify the number of brokers. +This command uses Docker to initiate a local Redpanda container cluster, +including Redpanda Console. Use the `--nodes`/`-n` flag to specify the number of +brokers. -The initial broker starts on default ports, with subsequent brokers' ports offset by 1000. You can use the following flags to specify listener ports: +The initial broker starts on default ports, with subsequent brokers' ports +offset by 1000. You can use the listeners flag to specify ports: * `--kafka-ports` + * `--admin-ports` + * `--rpc-ports` + * `--schema-registry-ports` + * `--proxy-ports` + * `--console-port` -* `--admin-ports` - -* `--rpc-ports` - -* `--schema-registry-ports` - -* `--proxy-ports` - -Each flag accepts a comma-separated list of ports for your listeners. Use the `--any-port` flag to let `rpk` randomly select an available port on the host machine. +Each flag accepts a comma-separated list of ports for your listeners. Use the +`--any-port` flag to let `rpk` select random available ports for every listener on +the host machine. -In case of IP address pool conflict, you may specify a custom subnet and gateway using the `--subnet` and `--gateway` flags respectively. +By default, this command uses the redpandadata/redpanda:latest and +redpandadata/console:latest container images. You can specify a container image +by using the `--image` flag. -By default, this command uses the `redpandadata/redpanda:latest` Redpanda container image. You can specify a container image by using the `--image` flag. See the available images at xref:https://hub.docker.com/r/redpandadata/redpanda/tags[Docker Hub]. +In case of IP address pool conflict, you may specify a custom subnet and gateway +using the `--subnet` and `--gateway` flags respectively. == Usage @@ -30,86 +39,87 @@ By default, this command uses the `redpandadata/redpanda:latest` Redpanda contai rpk container start [flags] ---- + + + == Examples -Start a three-broker cluster: +This section provides examples of how to use `rpk container start`. -```bash +Start a three-broker cluster. + +[,bash] +---- rpk container start -n 3 -``` +---- -Start a single-broker cluster, selecting random ports for every listener: +Start a single-broker cluster, selecting random ports for every listener. -```bash +[,bash] +---- rpk container start --any-port -``` +---- -Start a 3-broker cluster, selecting the seed kafka and console port only: +Start a 3-broker cluster, selecting the seed kafka and console port only. -```bash +[,bash] +---- rpk container start --kafka-ports 9092 --console-port 8080 -``` +---- + +Start a three-broker cluster, specifying the Admin API port for each broker. -Start a three-broker cluster, specifying the Admin API port for each broker: -```bash +[,bash] +---- rpk container start --admin-ports 9644,9645,9646 -``` +---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--admin-ports |strings |Redpanda Admin API ports to listen on; check help text for more information. - -|--any-port |- |Opt in for any (random) ports in all listeners. - -|--console-image |string |An arbitrary Redpanda Console container image to use (default `redpandadata/console:latest`). - -|--console-port |string |Redpanda Console ports to listen on; check help text for more information (default `8080`). - -|--gateway |string |Gateway IP address for the subnet. Must be in the subnet address range (default `172.24.1.1`). - -|-h, --help |- |Help for start. - -|--image |string |An arbitrary container Redpanda image to use (default `redpandadata/redpanda:{latest-redpanda-tag}`). - -|--kafka-ports |strings |Kafka protocol ports to listen on; check help text for more information. - -|--no-profile |- |If true, `rpk` will not create an `rpk profile` after creating a cluster. - -|-n, --nodes |uint |The number of brokers (nodes) to start (default `1`). - -|--proxy-ports |strings |HTTP Proxy ports to listen on; check help text for more information. - -|--pull |- |Force pull the container image used. - -|--retries |uint |The amount of times to check for the cluster before considering it unstable and exiting (default `10`). - -|--rpc-ports |strings |RPC ports to listen on; check help text for more information. - -|--schema-registry-ports |strings |Schema Registry ports to listen on; check help text for more information. - -|--subnet |string |Subnet to create the cluster network on (default `172.24.1.0/24`). - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|Value |Type |Description + +|--admin-ports |stringSlice |Redpanda Admin API ports to listen on; check help text for more information. +|--any-port |bool |Opt in for any (`random`) ports in all listeners. +|--console-image |string |An arbitrary Redpanda Console container image to use. +|--console-port |string |Redpanda console ports to listen on; check help text for more information. +|--gateway |string |Gateway IP address for the subnet. Must be in the subnet address range. +|--image |string |An arbitrary Redpanda container image to use. +|--kafka-ports |stringSlice |Kafka protocol ports to listen on; check help text for more information. +|--no-profile |bool |If true, `rpk` will not create an rpk profile after creating a cluster. +|-n, --nodes |uint |The number of brokers (`nodes`) to start. +|--proxy-ports |stringSlice |HTTP Proxy ports to listen on; check help text for more information. +|--pull |bool |Force pull the container image used. +|--retries |uint |The number of times to check for the cluster before considering it unstable and exiting. +|--rpc-ports |stringSlice |RPC ports to listen on; check help text for more information. +|--schema-registry-ports |stringSlice |Schema Registry ports to listen on; check help text for more information. +|--set |string |Redpanda configuration property to set upon start. Follows `rpk redpanda config set` format. +|--subnet |string |Subnet to create the cluster network on. +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -ifndef::env-cloud[] -== See also -* xref:get-started:quick-start.adoc#tabs-1-single-brokers[QuickStart - Deploy Redpanda to Docker with a Single Broker] -* xref:get-started:quick-start.adoc#tabs-1-three-brokers[QuickStart - Deploy Redpanda to Docker with Three Nodes] +== Suggested reading +* https://hub.docker.com/r/redpandadata/redpanda/tags[Docker Hub] +ifndef::env-cloud[] +* xref:get-started:quick-start.adoc#tabs-1-single-brokers[QuickStart - Deploy Redpanda to Docker with a Single Broker] +endif::[] +ifndef::env-cloud[] +* xref:get-started:quick-start.adoc#tabs-1-three-brokers[QuickStart - Deploy Redpanda to Docker with Three Nodes] endif::[] -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc index 022e7a0d89..a444a32e20 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc @@ -1,7 +1,11 @@ = rpk container status -// tag::single-source[] +:description: Get the status of a local container cluster, including the node IDs, ports, and running state of each broker. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -Get a local container's status. +// tag::single-source[] +Get the status of a local container cluster, including the node IDs, ports, and running state of each broker. == Usage @@ -10,12 +14,24 @@ Get a local container's status. rpk container status [flags] ---- -== Example -ifndef::env-cloud[] -If you're following xref:get-started:quick-start.adoc#tabs-1-three-brokers[QuickStart - Deploy Redpanda to Docker with Three Nodes], you can run `rpk container status` to see more information about your containers: -endif::[] + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. +|=== + +== Example [,bash] ---- @@ -37,23 +53,4 @@ broker addresses: rpk cluster info ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for status. - -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. - -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. - -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. - -|-v, --verbose |- |Enable verbose logging. -|=== - -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container-stop.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container-stop.adoc index d50abf7087..4e8d0244cb 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container-stop.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container-stop.adoc @@ -1,6 +1,10 @@ = rpk container stop -// tag::single-source[] +:description: Stop an existing local container cluster. +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc +// tag::single-source[] Stop an existing local container cluster. == Usage @@ -10,23 +14,21 @@ Stop an existing local container cluster. rpk container stop [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for stop. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container.adoc index d277b9023f..f8d7c65925 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container.adoc @@ -1,34 +1,68 @@ = rpk container +:description: Manage a local Redpanda container cluster for development and testing. Creates containers using Docker or Podman. :page-aliases: features:guide-rpk-container.adoc, deployment:guide-rpk-container.adoc +:page-platforms: linux,darwin + +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc + // tag::single-source[] -:description: These commands let you manage (start, stop, purge) a local container cluster. +Manage a local Redpanda container cluster for development and testing. Creates containers using Docker or Podman. + +NOTE: Container clusters are intended for development and testing only. Do not use for production workloads. -Manage a local container cluster. +== Prerequisites + +* Docker or Podman must be installed and running +* The current user must have permission to run containers == Usage [,bash] ---- -rpk container [command] +rpk container [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for container. +|xref:reference:rpk/rpk-container/rpk-container-purge.adoc[`rpk container purge`] +|Stop and remove an existing local container cluster's data. -|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|xref:reference:rpk/rpk-container/rpk-container-start.adoc[`rpk container start`] +|Start a local container cluster. This command uses Docker to initiate a local Redpanda container cluster, including Redpanda Console. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-container/rpk-container-status.adoc[`rpk container status`] +|Get the status of a local container cluster, including the node IDs, ports, and running state of each broker. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-container/rpk-container-stop.adoc[`rpk container stop`] +|Stop an existing local container cluster. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|=== -|-v, --verbose |- |Enable verbose logging. + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `/root/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|-X, --config-opt |stringArray |Override `rpk` configuration settings; `-X help` for detail or `-X list` for terser detail. +|--ignore-profile |bool |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--profile |string |`rpk` profile to use. +|-v, --verbose |bool |Enable verbose logging. |=== -// end::single-source[] \ No newline at end of file + +== Suggested reading + +* xref:get-started:intro-to-rpk.adoc[Introduction to rpk] +* xref:get-started:quick-start.adoc[Quick Start Guide] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc b/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc index 464e01878f..0f44aea12a 100644 --- a/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc +++ b/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc @@ -1,44 +1,35 @@ = rpk debug bundle -:description: This command generates a diagnostics bundle for troubleshooting Redpanda deployments. -// tag::single-source[] +:description: pass:q[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.] +:page-platforms: linux,darwin -NOTE: In Kubernetes, you must run the `rpk debug bundle` command inside a container that's running a Redpanda broker. +// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc -== Concept +// tag::single-source[] +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. -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. +NOTE: In Kubernetes, you must run the `rpk debug bundle` command inside a container that's running a Redpanda broker. -=== Diagnostic bundle files +== Diagnostic bundle files -The files and directories in the diagnostics bundle differ depending on the -environment in which Redpanda is running: +The files and directories in the diagnostics bundle differ depending on the environment in which Redpanda is running: === Common files -* Kafka metadata: Broker configs, topic configs, start/committed/end offsets, -groups, group commits. -* Controller logs: The controller logs directory up to a limit set by ---controller-logs-size-limit flag +* Kafka metadata: Broker configs, topic configs, start/committed/end offsets, groups, group commits. +* Controller logs: The controller logs directory up to a limit set by `--controller-logs-size-limit` flag * Data directory structure: A file describing the data directory's contents. -* redpanda configuration: The redpanda configuration file (`redpanda.yaml`; -SASL credentials are stripped). +* redpanda configuration: The redpanda configuration file (`redpanda.yaml`; SASL credentials are stripped). * /proc/cpuinfo: CPU information like make, core count, cache, frequency. * /proc/interrupts: IRQ distribution across CPU cores. -* Resource usage data: CPU usage percentage, free memory available for the -redpanda process. -* Clock drift: The ntp clock delta (using pool.ntp.org as a reference) and round -trip time. -* Admin API calls: Cluster and broker configurations, cluster health data, CPU profiles, and -license key information. -* Broker metrics: The broker's Prometheus metrics, fetched through its -admin API (/metrics and /public_metrics). +* Resource usage data: CPU usage percentage, free memory available for the redpanda process. +* Clock drift: The ntp clock delta (using pool.ntp.org as a reference) and round trip time. +* Admin API calls: Cluster and broker configurations, cluster health data, CPU profiles, and license key information. +* Broker metrics: The broker's Prometheus metrics, fetched through its admin API (/metrics and /public_metrics). === Bare-metal * Kernel: The kernel logs ring buffer (syslog) and parameters (sysctl). -* DNS: The DNS info as reported by 'dig', using the hosts in -/etc/resolv.conf. +* DNS: The DNS info as reported by 'dig', using the hosts in /etc/resolv.conf. * Disk usage: The disk usage for the data directory, as output by 'du'. * 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. * Socket info: The active sockets data output by 'ss'. @@ -46,8 +37,7 @@ admin API (/metrics and /public_metrics). * Virtual memory stats: As reported by 'vmstat'. * Network config: As reported by 'ip addr'. * lspci: List the PCI buses and the devices connected to them. -* dmidecode: The DMI table contents. Only included if this command is run -as root. +* dmidecode: The DMI table contents. Only included if this command is run as root. === Extra requests for partitions @@ -62,21 +52,19 @@ Topic 'foo', partitions 1, 2 and 3: --partition foo/1,2,3 ---- -Namespace _redpanda-internal, topic 'bar', partition 2 +Namespace _redpanda-internal, topic 'bar', partition 2: + [,bash] ---- --partition _redpanda-internal/bar/2 ---- -If you have an upload URL from the Redpanda support team, provide it in the --upload-url flag to upload your diagnostics bundle to Redpanda. +If you have an upload URL from the Redpanda support team, provide it in the `--upload-url` flag to upload your diagnostics bundle to Redpanda. -== Kubernetes +=== Kubernetes -* Kubernetes Resources: Kubernetes manifests for all resources in the given -Kubernetes namespace using `--namespace`, or the shorthand version `-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. +* Kubernetes Resources: Kubernetes manifests for all resources in the given Kubernetes namespace using `--namespace`, or the shorthand version `-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. == Usage @@ -85,68 +73,43 @@ included. rpk debug bundle [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--controller-logs-size-limit |string |Sets the limit of the controller -log size that can be stored in the bundle. Multipliers are also -supported, e.g. 3MB, 1GiB (default `132MB`). - -|--cpu-profiler-wait |duration |Specifies the duration for collecting samples for the CPU profiler (for example, 30s, 1.5m). Must be higher than 15s (default `30s`). - -|-h, --help |- |Display documentation for `rpk debug bundle`. - -|--kafka-connections-limit |int |The maximum number of Kafka connections to store in the bundle (k8s only). Default `256`. - -|-l, --label-selector |stringArray |Comma-separated label selectors to filter your resources. e.g: