diff --git a/.github/workflows/update-rpk-docs.yml b/.github/workflows/update-rpk-docs.yml new file mode 100644 index 0000000000..00509c346b --- /dev/null +++ b/.github/workflows/update-rpk-docs.yml @@ -0,0 +1,300 @@ +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' + id: beta_check + env: + EVENT_NAME: ${{ github.event_name }} + 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 + # RC tags are also cut for patch releases of the current stable line + # (for example v26.1.12-rc1 while beta is 26.2). Those arrive through + # the automated repository_dispatch trigger and are expected, so skip + # quietly instead of failing the run. A manual workflow_dispatch run + # asked for this exact version, so a mismatch there is a real error. + if [ "$EVENT_NAME" = "repository_dispatch" ]; then + echo "::notice::RC version $VERSION targets the $VERSION_MAJOR_MINOR line, not the current beta version ($BETA_VERSION). Skipping docs generation." + echo "skip=true" >> $GITHUB_OUTPUT + exit 0 + fi + 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 + if: steps.beta_check.outputs.skip != 'true' + 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 + if: steps.beta_check.outputs.skip != 'true' + 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 + if: steps.beta_check.outputs.skip != 'true' + 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 + if: steps.beta_check.outputs.skip != 'true' + 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 + if: steps.beta_check.outputs.skip != 'true' + 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.beta_check.outputs.skip != 'true' && 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.beta_check.outputs.skip != 'true' && 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.beta_check.outputs.skip != 'true' && 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/add-parent-context-flag.sh b/add-parent-context-flag.sh deleted file mode 100755 index 2293f138a3..0000000000 --- a/add-parent-context-flag.sh +++ /dev/null @@ -1,82 +0,0 @@ -#!/bin/bash - -# Script to add page-use-parent-context flag to all Streaming version branches -# Usage: ./add-parent-context-flag.sh - -set -e - -# Define all branches to update -BRANCHES=( - "feature/rename-streaming-main" - "feature/rename-streaming-23.3" - "feature/rename-streaming-24.1" - "feature/rename-streaming-24.2" - "feature/rename-streaming-24.3" - "feature/rename-streaming-25.1" - "feature/rename-streaming-25.2" - "feature/rename-streaming-25.3" -) - -echo "🚀 Starting to add page-use-parent-context flag to all Streaming branches..." -echo "" - -for BRANCH in "${BRANCHES[@]}"; do - echo "═══════════════════════════════════════════════════════════════" - echo "📝 Processing branch: $BRANCH" - echo "═══════════════════════════════════════════════════════════════" - - # Checkout the branch - git checkout "$BRANCH" - - # Check if the flag already exists - if grep -q "page-use-parent-context: true" antora.yml; then - echo "✅ Flag already exists in $BRANCH, skipping..." - echo "" - continue - fi - - # Add the flag after "attributes:" line - # Using sed to insert the line - sed -i '' '/^ attributes:$/a\ - page-use-parent-context: true -' antora.yml - - # Verify the change was made - if grep -q "page-use-parent-context: true" antora.yml; then - echo "✅ Successfully added flag to antora.yml" - - # Show the change - echo "📄 Changes:" - git diff antora.yml | head -15 - - # Commit the change - git add antora.yml - git commit -m "Enable parent context navigation cards - -Add page-use-parent-context flag to enable hierarchical navigation -with parent context cards in the UI. This shows the Self-Managed -parent card with Streaming/Connect subcards when viewing Streaming pages. - -Co-Authored-By: Claude Sonnet 4.5 " - - echo "✅ Committed changes to $BRANCH" - echo "" - else - echo "❌ Failed to add flag to $BRANCH" - echo "" - exit 1 - fi -done - -echo "═══════════════════════════════════════════════════════════════" -echo "✅ All branches updated successfully!" -echo "═══════════════════════════════════════════════════════════════" -echo "" -echo "📤 Ready to push. Run the following commands to push all branches:" -echo "" -for BRANCH in "${BRANCHES[@]}"; do - echo "git push origin $BRANCH" -done -echo "" -echo "Or push all at once with:" -echo "git push origin $(echo ${BRANCHES[@]})" diff --git a/antora.yml b/antora.yml index 4e2c794239..512cc4b025 100644 --- a/antora.yml +++ b/antora.yml @@ -34,7 +34,7 @@ asciidoc: # We try to fetch the latest versions from GitHub at build time # -- full-version: 26.2.1 - latest-redpanda-tag: 'v26.1.9' + 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' @@ -52,6 +52,9 @@ asciidoc: supported-rhel-recommended: '9+' supported-ubuntu-required: '20.04 LTS' supported-ubuntu-recommended: '22.04+' + # Linux package repository migration (dl.redpanda.com -> linux.pkg.redpanda.com) + legacy-repo-shutdown-date: 'September 28, 2026' + repo-dual-publish-start: 'June 1, 2026' badge-deprecated: 'image:https://img.shields.io/badge/-Deprecated-red.svg[xref=upgrade:deprecated/index.adoc]' removals-without-aliases: - page: reference/rpk/rpk-cloud/ 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": "(?> and <>, whichever is reached first.\n\nThe `write_caching_default` cluster property can be overridden with the xref:reference:properties/topic-properties.adoc#write-caching[`write.caching`] topic property." - }, - "delete_topic_enable": { - "type": "boolean", - "default": true, - "description": "Controls whether topics can be deleted through the Kafka DeleteTopics API. When set to `false`, all topic deletion requests are rejected for all users, including superusers. Use this as a cluster-wide safety setting to prevent accidental topic deletion in production environments.\n\nFor per-topic deletion protection, see xref:reference:properties/cluster-properties.adoc#kafka_nodelete_topics[`kafka_nodelete_topics`].", - "related_topics": [ - "xref:reference:properties/cluster-properties.adoc#kafka_nodelete_topics[`kafka_nodelete_topics`]", - "xref:get-started:licensing/index.adoc[enterprise license]" - ], - "config_scope": "cluster" - }, - "raft_election_timeout_ms": { - "exclude_from_docs": true, - "config_scope": "cluster" } } } diff --git a/docs-data/redpanda-property-changes-v26.1.10-to-v26.1.12.json b/docs-data/redpanda-property-changes-v26.1.10-to-v26.1.12.json new file mode 100644 index 0000000000..ba7e929f07 --- /dev/null +++ b/docs-data/redpanda-property-changes-v26.1.10-to-v26.1.12.json @@ -0,0 +1,43 @@ +{ + "comparison": { + "oldVersion": "v26.1.10", + "newVersion": "v26.1.12", + "timestamp": "2026-06-28T05:12:42.568Z" + }, + "summary": { + "newProperties": 1, + "changedDefaults": 0, + "changedDescriptions": 0, + "changedTypes": 0, + "deprecatedProperties": 0, + "removedDeprecatedProperties": 0, + "removedProperties": 0, + "emptyDescriptions": 2 + }, + "details": { + "newProperties": [ + { + "name": "controller_log_learner_recovery_rate_enabled", + "type": "boolean", + "default": false, + "description": "Whether the controller raft group (raft0) honors `raft_learner_recovery_rate`. When `false` (default) the controller log replicates to new learners without throttling. When `true`, controller-log recovery is subject to the same per-node recovery bucket as user partitions." + } + ], + "changedDefaults": [], + "changedDescriptions": [], + "changedTypes": [], + "deprecatedProperties": [], + "removedDeprecatedProperties": [], + "removedProperties": [], + "emptyDescriptions": [ + { + "name": "redpanda.remote.allowgaps", + "type": "boolean" + }, + { + "name": "redpanda.virtual.cluster.id", + "type": "string" + } + ] + } +} \ No newline at end of file diff --git a/docs-data/redpanda-property-changes-v26.1.8-to-v26.1.9.json b/docs-data/redpanda-property-changes-v26.1.8-to-v26.1.9.json deleted file mode 100644 index d44a130e30..0000000000 --- a/docs-data/redpanda-property-changes-v26.1.8-to-v26.1.9.json +++ /dev/null @@ -1,43 +0,0 @@ -{ - "comparison": { - "oldVersion": "v26.1.8", - "newVersion": "v26.1.9", - "timestamp": "2026-05-22T12:46:58.695Z" - }, - "summary": { - "newProperties": 1, - "changedDefaults": 0, - "changedDescriptions": 0, - "changedTypes": 0, - "deprecatedProperties": 0, - "removedDeprecatedProperties": 0, - "removedProperties": 0, - "emptyDescriptions": 2 - }, - "details": { - "newProperties": [ - { - "name": "features_auto_finalization", - "type": "boolean", - "default": true, - "description": "Controls whether Redpanda advances the cluster's active logical version automatically after you upgrade all nodes (`true`), or only when you explicitly request finalization through the Admin API (`false`). When set to `false`, you can downgrade to the previous version until you request finalization. Note: If you performed the upgrade with this set to `false` and the cluster is ready to finalize, setting this property to `true` does not reliably trigger finalization. Keep this set to `false` and use the Admin API to finalize. After the upgrade completes, you can set this back to `true` to restore automatic finalization for future upgrades." - } - ], - "changedDefaults": [], - "changedDescriptions": [], - "changedTypes": [], - "deprecatedProperties": [], - "removedDeprecatedProperties": [], - "removedProperties": [], - "emptyDescriptions": [ - { - "name": "redpanda.remote.allowgaps", - "type": "boolean" - }, - { - "name": "redpanda.virtual.cluster.id", - "type": "string" - } - ] - } -} \ No newline at end of file diff --git a/docs-data/rpk-overrides.json b/docs-data/rpk-overrides.json new file mode 100644 index 0000000000..b9b8588242 --- /dev/null +++ b/docs-data/rpk-overrides.json @@ -0,0 +1,3391 @@ +{ + "$schema": "./rpk-overrides.schema.json", + "_notes": { + "excluded_commands": "Commands with exclude: true are not included in generated docs. Currently excludes rpk oxla and the rpk ai connection subtree (rpk ai connection, rpk ai connection list, rpk ai connection revoke).", + "rpk_ai_commands": "The remaining rpk ai commands are generated as partials only (asPartial: true on rpk ai), not as published pages, so they stay out of the nav and site until deliberately wired up.", + "rpk_oxla_command": "rpk oxla is a coming-soon placeholder in rpk (it only prints an early-access registration link), so it is excluded until the feature ships." + }, + "textTransformations": { + "replacements": [ + { + "description": "Merge broken inline code spans with embedded flags (e.g., `cmd `-f` rest` -> `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": {}, + "content": [ + { + "type": "section", + "id": "connect-docs-link", + "title": null, + "position": "after_description", + "content": "For full details, see the xref:connect:streaming:about.adoc[Redpanda Connect documentation]." + } + ] + }, + "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 (xref:reference:properties/object-storage-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`]), a series of remote operations are performed:\n+\n--\ninclude::reference:partial$rpk-self-test-cloud-tests.adoc[]\n--\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`)." + } + }, + "seeAlso": [ + "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-stop.adoc[`rpk cluster self-test stop`]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[`rpk cluster self-test`]", + "xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Disk and network self-test benchmarks]" + ] + }, + "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]", + "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`]" + ], + "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.", + "content": [ + { + "type": "section", + "id": "remote-bundle-download-details", + "title": null, + "position": "after_description", + "content": "For details, see xref:troubleshoot:debug-bundle/generate/index.adoc[Generate debug bundles]." + } + ] + }, + "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|===" + }, + { + "type": "section", + "id": "dashboard-source", + "title": null, + "position": "after_examples", + "content": "The selected dashboard is downloaded from Redpanda Data's https://github.com/redpanda-data/observability[observability GitHub repository^].\n\nNOTE: The legacy dashboard is still available as an option (`legacy`), but it isn't downloaded from GitHub. Instead, the generated dashboard is based on which metrics endpoint is used (`--metrics-endpoint`)." + } + ], + "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`]" + }, + { + "type": "section", + "id": "group-offset-deletion", + "title": null, + "position": "after_description", + "content": "Consumer groups are automatically deleted when the last committed offset expires. Group offset deletion can happen through:\n\n* Kafka `OffsetDelete` API: Offsets can be explicitly deleted using the Kafka `OffsetDelete` API. See xref:reference:rpk/rpk-group/rpk-group-offset-delete.adoc[`rpk group offset delete`].\n* Periodic offset expiration: Offsets expire automatically when the group has been empty for a set duration." + } + ], + "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" + } + ] + }, + { + "type": "section", + "id": "shadow-create-workflow", + "title": null, + "position": "after_description", + "content": "Before you create a shadow link, generate a configuration file with xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] and update it with your source cluster details.\n\nAfter you create the shadow link, use xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] to monitor the replication progress." + } + ] + }, + "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" + } + ] + } + ] + } + ], + "seeAlso": [ + "xref:reference:rpk/rpk-cluster/rpk-cluster-config-get.adoc[`rpk cluster config get`]" + ] + }, + "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----" + }, + { + "type": "self-hosted", + "position": "after_flags", + "content": "== Example\n\nIf you're following xref:get-started:quick-start.adoc#tabs-1-three-brokers[Quick Start - Deploy Redpanda to Docker with Three Nodes], you can run `rpk container status` to see more information about your containers." + } + ] + }, + "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`]" + }, + { + "type": "warning", + "position": "after_description", + "content": "Do not use this command in Azure self-managed environments." + }, + { + "type": "tip", + "position": "after_description", + "content": "* When running `rpk redpanda tune`, make sure that your current Linux user has root privileges. The autotuner requires privileged access to the Linux kernel settings.\n* To run `rpk redpanda tune all` on a Redpanda broker automatically after broker or host restarts, configure the service `redpanda-tuner`, which runs `rpk redpanda tune all`, to run at boot-up:\n** For RHEL, after installing the rpm package, run `systemctl` to both start and enable the `redpanda-tuner` service:\n+\n[,bash]\n----\nsudo systemctl start redpanda-tuner\nsudo systemctl enable redpanda-tuner\n----\n\n** For Ubuntu, after installing the apt package, run `systemctl` to start the `redpanda-tuner` service (which is already enabled):\n+\n[,bash]\n----\nsudo systemctl start redpanda-tuner\n----" + } + ] + }, + "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 + }, + "rpk redpanda mode": { + "content": [ + { + "type": "section", + "id": "mode-details", + "title": "Mode details", + "position": "after_usage", + "headingLevel": 2, + "content": "=== Development mode\n\nDevelopment mode (`development` or `dev`) includes the following development-only settings:\n\n* Sets `developer_mode` to `true`. This starts Redpanda with dev-mode only settings, including:\n** No minimal memory limits are enforced.\n** No core assignment rules for Redpanda brokers are enforced.\n** Enables write caching, which is a relaxed mode of `acks=all` that acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. For more information, or to disable this, see xref:develop:manage-topics/config-topics.adoc#configure-write-caching[write caching].\n** Bypasses `fsync` (from https://docs.seastar.io/master/structseastar_1_1reactor%5F%5Foptions.html#ad66cb23f59ed5dfa8be8189313988692[Seastar option `unsafe_bypass_fsync`^]), which results in unrealistically fast clusters and may result in data loss.\n* Sets `overprovisioned` to `true`. Redpanda expects a dev system to be an overprovisioned environment. Based on a https://docs.seastar.io/master/structseastar_1_1reactor%5F%5Foptions.html#a0caf6c2ad579b8c22e1352d796ec3c1d[Seastar option^], setting `overprovisioned` disables thread affinity, zeros idle polling time, and disables busy-poll for disk I/O.\n* Sets all autotuner xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc#tuners[tuners] to `false`. The tuners are intended to run only for production mode.\n\n=== Production mode\n\nProduction mode (`production` or `prod`) disables dev-mode settings:\n\n* `developer_mode: false`\n* `overprovisioned: false`\n\nIt also enables a set of tuners of the autotuner. For descriptions about the tuners, see xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc#tuners[Tuners] in the xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc[rpk redpanda tune list] command reference.\n\n=== Recovery mode\n\nRecovery mode (`recovery`) sets the broker configuration property `recovery_mode_enabled` to `true`. This provides a stable environment for troubleshooting and restoring a failed cluster." + } + ] + }, + "rpk cluster maintenance status": { + "description": "Report maintenance status.\n\nThis command reports maintenance status for each broker in the cluster. The output is presented as a table with each row representing a broker in the cluster. The output can be used to monitor the progress of node draining.", + "content": [ + { + "type": "section", + "id": "status-fields", + "title": null, + "position": "after_description", + "content": "For example:\n\n----\nNODE-ID ENABLED FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED\n1 false false false 0 0 0 0\n----\n\n[cols=\"1m,2a\"]\n|===\n|Field |Description\n\n|NODE-ID |The node ID.\n|ENABLED |`true` if the broker 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|===\n\n[NOTE]\n====\n* When errors are present, further information is available in the logs for the corresponding broker.\n* Only partitions with more than one replica are eligible for leadership transfer.\n====" + } + ], + "_note": "Description override replaces the raw help output, which otherwise renders as a broken table. The example output and field table live in a content section because literal blocks are stripped from description overrides." + } + } +} 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 `~/.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..31196fc497 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 `~/.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..deae6976da 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 `~/.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..c828cbb036 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 `~/.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..ddc7aecde6 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 `~/.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..0f14ec5134 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 `~/.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..4ed98b4228 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 `~/.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..05bbd9c0d3 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* @@ -26,7 +30,7 @@ include::reference:partial$rpk-self-test-cloud-tests.adoc[] 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 +39,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 `~/.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..06f9fc2066 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,21 +1,45 @@ = 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. + +Test results are grouped by broker ID. Each test returns the following: + +* Name: Description of the test. + +* Info: Details about the test run attached by Redpanda. + +* Type: Either `disk`, `network`, or `cloud` test. + +* 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. + +* Timeouts: Number of timeouts incurred during the test. -* No jobs running -** Returns the cached results for all brokers of the last completed test. +* Start time: Time that the test started, in UTC. + +* End time: Time that the test ended, in UTC. + +* Avg Duration: Duration of the test. + +* IOPS: Number of operations per second. For disk, it`s `seastar::dma_read' and 'seastar::dma_write'. For network, it`s `rpc.send()'. + +* 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[] @@ -26,43 +50,48 @@ include::reference:partial$rpk-self-test-descriptions.adoc[] rpk cluster self-test status [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--format |string |Output format. Possible values: `json`, `text`. Default: `text`. -|-h, --help |- |Help for status. +== Example -|--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`. +This section provides examples of how to use `rpk cluster self-test status`. -|-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. +Example input. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[,bash] +---- +rpk cluster self-test status +---- -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Flags -|-v, --verbose |- |Enable verbose logging. +[cols="1m,1a,2a"] |=== +|Value |Type |Description +|--format |string |Output format (`text`, `json`). +|=== -== Example +== Global flags -Example input: +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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. +|=== -[,bash] ----- -rpk cluster self-test status ----- -.Example output -include::reference:partial$rpk-self-test-status-output.adoc[] +== Suggested reading -== Related topics +* 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-stop.adoc[`rpk cluster self-test stop`] +* xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[`rpk cluster self-test`] +* xref:manage:cluster-maintenance/cluster-diagnostics.adoc#disk-and-network-self-test-benchmarks[Disk and network self-test benchmarks] -* 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..4300e04e36 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,34 @@ 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 `~/.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] +* 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.adoc b/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc index 98b898f2d1..0b54279b9c 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 `~/.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..3c294be496 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 `~/.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..708b896061 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 `~/.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..3b8f1aa8f9 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 `~/.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..9fbde8061e 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 `~/.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..cc0806e319 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 `~/.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..d0ba247723 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 `~/.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..fc12c65eb9 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 `~/.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..78cc2ad2bd 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 `~/.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..a2ae55e5b7 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 `~/.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..97d5d8e0dd 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 `~/.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..0cf4da3534 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 `~/.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..4dba97054d 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 `~/.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..75a01ba661 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 `~/.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..bce6c68cfc 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 `~/.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..6bff9bddc8 --- /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 `~/.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..ac70c4d21d 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 `~/.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..c5b303d6d0 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 `~/.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..e59149dcef 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 `~/.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..155eb02e6e --- /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 `~/.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..7de2800c8d 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 `~/.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..59a8c396b7 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 `~/.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..277d790f1c 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 `~/.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..2dde6d2d6b --- /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 `~/.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..d233718295 --- /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 `~/.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..ee4ce26451 --- /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 `~/.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..8e219569fb 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 `~/.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..3da78d469e 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 `~/.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..e6649c44fe 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 `~/.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..d8df67882e 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 `~/.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..161fa76c6d 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 `~/.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..eef414d69a --- /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 `~/.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..5f438d8484 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 `~/.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..3edaf4e17d 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 `~/.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..607b482d53 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 `~/.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..bb276be615 100644 --- a/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc +++ b/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc @@ -1,30 +1,95 @@ = 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. + +For full details, see the xref:connect:streaming:about.adoc[Redpanda Connect documentation]. == 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 `~/.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..f81841e5f3 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 `~/.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..84f1cf62b3 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 `~/.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..1e17f6fd34 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,13 +14,31 @@ Get a local container's status. rpk container status [flags] ---- -== Example + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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[] -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: +== Example +If you're following xref:get-started:quick-start.adoc#tabs-1-three-brokers[Quick Start - Deploy Redpanda to Docker with Three Nodes], you can run `rpk container status` to see more information about your containers. endif::[] +== Example + [,bash] ---- rpk container status @@ -37,23 +59,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..c8c407a469 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 `~/.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..99f6910eef 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 `~/.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..14771a13bd 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:
: for Redpanda to advertise the Kafka listener; if empty, defaults to `--self`. - -|--advertised-rpc |string |Optional
: for Redpanda to advertise the RPC listener; if empty, defaults to `--self`. -|-h, --help |- |Help for bootstrap. -|--ips |strings |Comma-separated list of the seed node addresses or -hostnames; at least three are recommended. -|--self |string |Optional IP address for redpanda to listen on; if -empty, defaults to a private address. +== 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. +|--advertised-kafka |string |Optional address:port for Redpanda to advertise the kafka listener; if empty, defaults to `--self`. +|--advertised-rpc |string |Optional address:port for Redpanda to advertise the rpc listener; if empty, defaults to `--self`. +|--ips |stringSlice |Comma-separated list of the seed node addresses or hostnames; at least three are recommended. +|--self |string |Optional IP address for Redpanda to listen on; if empty, defaults to a private address. +|=== -|--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 `~/.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-redpanda/rpk-redpanda-config-init.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-init.adoc index fd3b9bcf7c..5d50646b52 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-init.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-init.adoc @@ -1,11 +1,13 @@ = rpk redpanda config init -:unsupported-os: macOS, Windows +:description: This command has been deprecated. +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -{badge-deprecated} +// tag::single-source[] +This command has been deprecated. -Init the node after install, by setting the node's UUID. +NOTE: This command is only available on Linux. == Usage @@ -14,22 +16,21 @@ Init the node after install, by setting the node's UUID. rpk redpanda config init [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for init. -|--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 `~/.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-redpanda/rpk-redpanda-config-print.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc index 233bca13f5..fb5936838d 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc @@ -1,7 +1,14 @@ = rpk redpanda config print +:description: Display the selected node configuration. +:page-platforms: linux +// 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[] Display the selected node configuration. +NOTE: This command is only available on Linux. + == Usage [,bash] @@ -9,30 +16,35 @@ Display the selected node configuration. rpk redpanda config print [flags] ---- + + == Aliases [,bash] ---- -print, dump +rpk redpanda config dump ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--host |string |A hostname or the index (0-based) of the configured Kafka broker list. +|Value |Type |Description -|-h, --help |- |Help for print. - -|--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`. +|--host |string |a hostname or the index (0-based) of the configured Kafka broker list. +|=== -|-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 `~/.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-redpanda/rpk-redpanda-config-set.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-set.adoc index 1157e41ed2..81005ac3d0 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-set.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-set.adoc @@ -1,15 +1,14 @@ = rpk redpanda config set -:unsupported-os: macOS, Windows +:description: pass:q[Set node configuration values, such as the list of seed servers or the ports that various APIs listen on This command modifies the `redpanda.yaml` you have locally on disk. The first argument is the key within the `yaml` representing a property / field that you would like to set.] +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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[] Set node configuration values, such as the list of seed servers or the ports that various APIs listen on. -This command modifies the `redpanda.yaml` you have locally on disk. - -== Examples - -The first argument is the key within the yaml representing a property / field that you +This command modifies the `redpanda.yaml` you have locally on disk. The first +argument is the key within the `yaml` representing a property / field that you would like to set. Nested fields can be accessed through a dot: [,bash] @@ -17,34 +16,23 @@ would like to set. Nested fields can be accessed through a dot: rpk redpanda config set redpanda.developer_mode true ---- -All values are parsed as yaml and, since yaml is a superset of json, you can -also format your input as json. Individual specific fields or full structs can +All values are parsed as `yaml` and, since `yaml` is a superset of json, you can +also format your input as `json`. Individual specific fields or full structs can be set: [,bash] ---- -rpk redpanda config set rpk.tune_disk_irq true ----- - -or - -[,bash] ----- +rpk redpanda config set rpk.tune_disk_irq true \ rpk redpanda config set redpanda.rpc_server '{address: 3.250.158.1, port: 9092}' ---- -You can set an entire array by wrapping all items with braces, or by using one struct: - -[,bash] ----- -rpk redpanda config set redpanda.advertised_kafka_api '[{address: 10.0.0.1, port: 9092}]' ----- - -or +You can set an entire array by wrapping all items with braces, or by using one +struct: [,bash] ---- -rpk redpanda config set redpanda.advertised_kafka_api '{address: 10.0.0.1, port: 9092}' +rpk redpanda config set redpanda.advertised_kafka_api '[{address: 0.0.0.0, port: 9092}]' \ +rpk redpanda config set redpanda.advertised_kafka_api '{address: 0.0.0.0, port: 9092}' # same ---- Indexing can be used to set specific items in an array. You can index one past @@ -52,16 +40,18 @@ the end of an array to extend it: [,bash] ---- -rpk redpanda config set redpanda.advertised_kafka_api[1] '{address: 10.0.0.1, port: 9092}' +rpk redpanda config set redpanda.advertised_kafka_api[1] '{address: 0.0.0.0, port: 9092}' ---- -You may also use `=` notation for setting configuration properties: +You may also use = notation for setting configuration properties: [,bash] ---- rpk redpanda config set redpanda.kafka_api[0].port=9092 ---- +NOTE: This command is only available on Linux. + == Usage [,bash] @@ -69,22 +59,21 @@ rpk redpanda config set redpanda.kafka_api[0].port=9092 rpk redpanda config set [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for set. -|--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 `~/.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-redpanda/rpk-redpanda-config.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config.adoc index 43ce1ceb09..69e74d7401 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config.adoc @@ -1,34 +1,56 @@ = rpk redpanda config -:unsupported-os: macOS, Windows +:description: Edit configuration. +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -Edit Redpanda configuration. +// tag::single-source[] +Edit configuration. + +NOTE: This command is only available on Linux. == Usage [,bash] ---- - -rpk redpanda config [flags] [command] +rpk redpanda config [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for config. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-config-bootstrap.adoc[`rpk redpanda config bootstrap`] +|Initialize the configuration to bootstrap a cluster. This command generates a `redpanda.yaml` configuration file to bootstrap a 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-redpanda/rpk-redpanda-config-init.adoc[`rpk redpanda config init`] +|This command has been deprecated. -|-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-redpanda/rpk-redpanda-config-print.adoc[`rpk redpanda config print`] +|Display the selected node configuration. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-config-set.adoc[`rpk redpanda config set`] +|Set node configuration values, such as the list of seed servers or the ports that various APIs listen on This command modifies the `redpanda.yaml` you have locally on disk. The first argument is the key within the `yaml` representing a property / field that you would like to set. -|--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 `~/.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-redpanda/rpk-redpanda-mode.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-mode.adoc index edfcd1b510..ad01c3409d 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-mode.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-mode.adoc @@ -1,57 +1,85 @@ = rpk redpanda mode -:unsupported-os: macOS, Windows +:description: Enable a default configuration mode This command allows you to set one of the following modes: Development, Production, or Recovery. +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -== Development mode +// tag::single-source[] +Enable a default configuration mode. + +This command allows you to set one of the following modes: Development, +Production, or Recovery. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk redpanda mode [flags] +---- + +== Mode details + +=== Development mode Development mode (`development` or `dev`) includes the following development-only settings: * Sets `developer_mode` to `true`. This starts Redpanda with dev-mode only settings, including: - ** No minimal memory limits are enforced. - ** No core assignment rules for Redpanda nodes are enforced. - ** Enables write caching, which is a relaxed mode of `acks=all` that acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. For more information, or to disable this, see xref:develop:manage-topics/config-topics.adoc#configure-write-caching[write caching]. - ** Bypasses `fsync` (from https://docs.seastar.io/master/structseastar_1_1reactor%5F%5Foptions.html#ad66cb23f59ed5dfa8be8189313988692[Seastar option `unsafe_bypass_fsync`^]), which results in unrealistically fast clusters and may result in data loss. +** No minimal memory limits are enforced. +** No core assignment rules for Redpanda brokers are enforced. +** Enables write caching, which is a relaxed mode of `acks=all` that acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. For more information, or to disable this, see xref:develop:manage-topics/config-topics.adoc#configure-write-caching[write caching]. +** Bypasses `fsync` (from https://docs.seastar.io/master/structseastar_1_1reactor%5F%5Foptions.html#ad66cb23f59ed5dfa8be8189313988692[Seastar option `unsafe_bypass_fsync`^]), which results in unrealistically fast clusters and may result in data loss. * Sets `overprovisioned` to `true`. Redpanda expects a dev system to be an overprovisioned environment. Based on a https://docs.seastar.io/master/structseastar_1_1reactor%5F%5Foptions.html#a0caf6c2ad579b8c22e1352d796ec3c1d[Seastar option^], setting `overprovisioned` disables thread affinity, zeros idle polling time, and disables busy-poll for disk I/O. -* Sets all autotuner xref:./rpk-redpanda-tune-list.adoc#tuners[tuners] to `false`. The tuners are intended to run only for production mode. +* Sets all autotuner xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc#tuners[tuners] to `false`. The tuners are intended to run only for production mode. -== Production mode +=== Production mode Production mode (`production` or `prod`) disables dev-mode settings: * `developer_mode: false` * `overprovisioned: false` -It also enables a set of tuners of the autotuner. For descriptions about the tuners, see xref:./rpk-redpanda-tune-list.adoc#tuners[Tuners] in the xref:./rpk-redpanda-tune-list.adoc[rpk redpanda tune list] command reference. +It also enables a set of tuners of the autotuner. For descriptions about the tuners, see xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc#tuners[Tuners] in the xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc[rpk redpanda tune list] command reference. -== Recovery mode +=== Recovery mode Recovery mode (`recovery`) sets the broker configuration property `recovery_mode_enabled` to `true`. This provides a stable environment for troubleshooting and restoring a failed cluster. -== Usage -[,bash] ----- -rpk redpanda mode [flags] ----- +=== Production -== Flags +* Enforces optimal runtime checks. +* Enables all `rpk` tuners, for you to run `rpk redpanda tune`. -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* +=== Development -|-h, --help |- |Help for mode. +* Disables optimal checks and bypasses fsync, which results in unrealistically + fast clusters and may result in data loss. -|--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`. +* Disables all `rpk` tuners. The tuners are intended to run only for production + mode. -|-X, --config-opt |stringArray |Override rpk configuration settings; `-X -help` for detail or `-X list` for terser detail. +=== Recovery -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +Sets the broker configuration property 'redpanda.recovery_mode_enabled=true' in +your `redpanda.yaml`. This provides a stable environment for troubleshooting and +restoring a failed cluster. Restart required. -|--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 `~/.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-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 6aeff6ff6d..c14608b63c 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -1,9 +1,13 @@ = rpk redpanda start -:unsupported-os: macOS, Windows +:description: Start redpanda. +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -Start Redpanda. +// tag::single-source[] +Start redpanda. + +NOTE: This command is only available on Linux. == Set up a mode @@ -48,109 +52,43 @@ rpk config set rpk redpanda start [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--advertise-kafka-addr |strings |A comma-separated list of Kafka -addresses to advertise. - -[,bash] ----- -::\| ----- - -|--advertise-pandaproxy-addr |strings |A comma-separated list of -Pandaproxy addresses to advertise. -[,bash] ----- -::\| ----- -|--advertise-rpc-addr |string |The advertised RPC address -[,bash] ----- -: ----- - -|--check |- |When set to `false`, will disable system checking before -starting `redpanda` (default `true`). - -|-h, --help |- |Help for start. - -|--install-dir |string |Directory where `redpanda` has been installed. - -|--kafka-addr |strings |A comma-separated list of Kafka listener -addresses to bind to. - -[,bash] ----- -::\| ----- - -|--mode |string |Sets well-known configuration properties for -development or test environments; use `--mode help` for more info. +== Flags +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--advertise-kafka-addr |stringSlice |A comma-separated list of Kafka addresses to advertise (scheme://host:port{vbar}name). +|--advertise-pandaproxy-addr |stringSlice |A comma-separated list of Pandaproxy addresses to advertise (scheme://host:port{vbar}name). +|--advertise-rpc-addr |string |The advertised RPC address (host:port). +|--check |bool |When set to false will disable system checking before starting redpanda. +|--install-dir |string |Directory where Redpanda has been installed. +|--kafka-addr |stringSlice |A comma-separated list of Kafka listener addresses to bind to (scheme://host:port{vbar}name). +|--mode |string |Mode sets well-known configuration properties for development or test environments; use `--mode help` for more info. |--node-tuner-state-path |string |Alternative path to read the node tuner state file from (if exists). +|--pandaproxy-addr |stringSlice |A comma-separated list of Pandaproxy listener addresses to bind to (scheme://host:port{vbar}name). +|--rpc-addr |string |The RPC address to bind to (host:port). +|--schema-registry-addr |stringSlice |A comma-separated list of Schema Registry listener addresses to bind to (scheme://host:port{vbar}name). +|-s, --seeds |stringSlice |A comma-separated list of seed nodes to connect to (scheme://host:port{vbar}name). +|--timeout |duration |The maximum time to wait for the checks and tune processes to complete (for example, 300ms, 1.5s, 2h45m). +|--tune |bool |When present will enable tuning before starting redpanda. +|--well-known-io |string |The cloud provider and VM type, in the format ::. +|=== -|--pandaproxy-addr |strings |A comma-separated list of Pandaproxy -listener addresses to bind to. - -[,bash] ----- -::\| ----- - -|--rpc-addr |string |The RPC address to bind to. - -[,bash] ----- -: ----- - -|--schema-registry-addr |strings |A comma-separated list of Schema -Registry listener addresses to bind to. - -[,bash] ----- -::\| ----- - -|-s, --seeds |strings |A comma-separated list of seed nodes to connect -to. - -[,bash] ----- -::\| ----- - -|--timeout |duration |The maximum time to wait for the checks and tune -processes to complete. The value passed is a sequence of decimal -numbers, each with optional fraction and a unit suffix, such as -`300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` -(or `µs`), `ms`, `s`, `m`, `h` (default 10s). - -|--tune |- |When present will enable tuning before starting `redpanda`. - -|--well-known-io |string |The cloud vendor and VM type, in the format - -[,bash] ----- -:: ----- - -|--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 `~/.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-redpanda/rpk-redpanda-stop.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-stop.adoc index e5094a58e1..d7939819aa 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-stop.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-stop.adoc @@ -1,13 +1,16 @@ = rpk redpanda stop -:unsupported-os: macOS, Windows +:description: pass:q[Stop a local Redpanda process. `rpk stop` first sends SIGINT, and waits for the specified timeout.] +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -Stop a local Redpanda process. `rpk stop` first sends `SIGINT`, and waits for the specified timeout. +// tag::single-source[] +Stop a local Redpanda process. `rpk stop` +first sends SIGINT, and waits for the specified timeout. Then, if Redpanda +hasn't stopped, it sends SIGTERM. Lastly, it sends SIGKILL if it's still +running. -Then, if Redpanda hasn't stopped, it sends `SIGTERM`. - -Lastly, it sends `SIGKILL` if it's still running. +NOTE: This command is only available on Linux. == Usage @@ -16,25 +19,29 @@ Lastly, it sends `SIGKILL` if it's still running. rpk redpanda stop [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for stop. -|--timeout |duration |The maximum amount of time to wait for redpanda to -stop after each signal is sent (e.g. 300ms, 1.5s, 2h45m) (default 5s). +== 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. +|--timeout |duration |The maximum amount of time to wait for redpanda to stop after each signal is sent (for example, 300ms, 1.5s, 2h45m). +|=== -|--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 `~/.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-redpanda/rpk-redpanda-tune-help.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-help.adoc index 582ba25022..6a74760b1f 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-help.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-help.adoc @@ -1,29 +1,36 @@ = rpk redpanda tune help +:description: Display detailed information about the tuner. +:page-platforms: linux +// 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[] Display detailed information about the tuner. +NOTE: This command is only available on Linux. + == Usage [,bash] ---- -rpk redpanda tune help [TUNER] [flags] +rpk redpanda tune help [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for `rpk redpanda tune help`. -|--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; '-X help' for detail or '-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 |rpk profile to use. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-redpanda/rpk-redpanda-tune-list.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc index 0e3c4c41e8..b63cb047ad 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc @@ -1,23 +1,27 @@ = rpk redpanda tune list -:unsupported-os: macOS, Windows +:description: pass:q[List available redpanda tuners and check if they are enabled and supported by your system To enable a tuner it must be set in the `redpanda.yaml` configuration file under `rpk` section, e.g: [,yaml] ---- rpk:] +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 available Redpanda tuners and check if they are enabled and +// tag::single-source[] +List available redpanda tuners and check if they are enabled and supported by your system. To enable a tuner it must be set in the `redpanda.yaml` configuration file -under rpk section, for example: +under `rpk` section, e.g: [,yaml] ---- rpk: -tune_cpu: true -tune_swappiness: true + tune_cpu: true + tune_swappiness: true ---- You may use `rpk redpanda config set` to enable or disable a tuner. +NOTE: This command is only available on Linux. + == Usage [,bash] @@ -25,38 +29,34 @@ You may use `rpk redpanda config set` to enable or disable a tuner. rpk redpanda tune list [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-r, --dirs |strings |List of *data* directories or places to store data -(e.g. /var/vectorized/redpanda/); usually your XFS file system on an NVMe -SSD device. -|-d, --disks |strings |Lists of devices to tune (for example, 'sda1'). +== Flags -|-h, --help |- |Help for list. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description +|-r, --dirs |stringSlice |List of *data* directories or places to store data (for example, `/var/vectorized/redpanda/`); usually your XFS filesystem on an NVMe SSD device. +|-d, --disks |stringSlice |Lists of devices to tune f.e. `sda1`. |-m, --mode |string |Operation Mode. Acceptable values: (`sq`, `sq_split`, `mq`). - +|-n, --nic |stringSlice |Network Interface Controllers to tune. |--node-tuner-state-path |string |Alternative path to write the tuner state file to (default: `/var/run/redpanda_node_tuner_state.yaml`). +|--reboot-allowed |bool |Allow tuners to tune boot parameters and request system reboot. +|=== -|-n, --nic |strings |Network Interface Controllers to tune. - -|--reboot-allowed |- |Allow tuners to tune boot parameters and request -system reboot. - -|--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 `~/.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 @@ -261,3 +261,5 @@ Configuration (yaml): === Related topics * xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[rpk redpanda tune] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc index 6e827dc2e6..addc520d73 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc @@ -1,48 +1,34 @@ = rpk redpanda tune -:page-aliases: reference:autotune.adoc, introduction:autotune.adoc -:unsupported-os: macOS, Windows +:description: Sets the OS parameters to tune system performance. Available tuners: * all. +:page-platforms: linux -include::reference:partial$unsupported-os-rpk.adoc[] +// 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 -WARNING: Do not use this command in Azure self-managed environments. - -`rpk redpanda tune`, also referred to as the autotuner, identifies the hardware configuration on your machine and optimizes the Linux kernel to give you the best performance for running Redpanda. +// tag::single-source[] +Sets the OS parameters to tune system performance. Available tuners: -* all +* all. +* aio_events +* ballast_file +* clocksource +* coredump +* cpu * disk_irq -* disk_scheduler * disk_nomerges +* disk_scheduler * disk_write_cache * fstrim * net -* aio_events * swappiness -* ballast_file -* cpu -* clocksource * transparent_hugepages -* coredump -To learn more about a tuner, run xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-help.adoc[`rpk redpanda tune help `]. +To learn more about a tuner, run `rpk redpanda tune help `. -[IMPORTANT] -==== -You should run the autotuner as part of the production deployment workflow. Redpanda recommends you first follow a guide for production deployment: - -* xref:deploy:deployment-option/self-hosted/manual/production/production-deployment.adoc[Deploy for Production] -* xref:deploy:deployment-option/self-hosted/kubernetes/k-tune-workers.adoc[Tune Kubernetes Worker Nodes for Production] +NOTE: This command is only available on Linux. -While you follow the guides, consult this reference for details about the autotuner. -==== - -== Usage - -[,bash] ----- -rpk redpanda tune [command] [flags] ----- +WARNING: Do not use this command in Azure self-managed environments. [TIP] ==== @@ -62,60 +48,72 @@ sudo systemctl enable redpanda-tuner ---- sudo systemctl start redpanda-tuner ---- - ==== -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--cpu-set |string |Set of CPUs for tuners to use in cpuset(7) format; -if not specified, tuners will use all available CPUs (default "all"). +== Usage -|-r, --dirs |strings |List of *data* directories or places to store data -(e.g. /var/vectorized/redpanda/); usually your XFS file system on an NVMe -SSD device. +[,bash] +---- +rpk redpanda tune [list of elements to tune] [flags] +---- -|-d, --disks |strings |Lists of devices to tune f.e. 'sda1'. -|-h, --help |- |Help for tune. -|-m, --mode |string |Operation Mode. Acceptable values: (`sq`, `sq_split`, `mq`). -|--node-tuner-state-path |string |Alternative path to write the tuner state file to (default: `/var/run/redpanda_node_tuner_state.yaml`). +== Subcommands -|-n, --nic |strings |Network Interface Controllers to tune. +[cols="1,2a"] +|=== +|Command |Description -|--output-script |string |If a filename is provided, it will generate a tuning file that can later be used to tune the system. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-help.adoc[`rpk redpanda tune help`] +|Display detailed information about the tuner. -|--reboot-allowed |- |Allow tuners to tune boot parameters and request -system reboot. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`] +|List available redpanda tuners and check if they are enabled and supported by your system To enable a tuner it must be set in the `redpanda.yaml` configuration file under `rpk` section, e.g: [,yaml] ---- rpk: -|--timeout |duration |The maximum time to wait for the tune processes to -complete (e.g. 300ms, 1.5s, 2h45m) (default 10s). +|=== -|--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 -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--cpu-set |string |Set of CPUs for tuners to use in cpuset(7) format; if not specified, tuners will use all available CPUs. +|-r, --dirs |stringSlice |List of *data* directories or places to store data (for example, `/var/vectorized/redpanda/`); usually your XFS filesystem on an NVMe SSD device. +|-d, --disks |stringSlice |Lists of devices to tune f.e. `sda1`. +|-m, --mode |string |Operation Mode. Acceptable values: (`sq`, `sq_split`, `mq`). +|-n, --nic |stringSlice |Network Interface Controllers to tune. +|--node-tuner-state-path |string |Alternative path to write the tuner state file to (default: `/var/run/redpanda_node_tuner_state.yaml`). +|--output-script |string |If a filename is provided, it will generate a tuning file that can later be used to tune the system. +|--reboot-allowed |bool |Allow tuners to tune boot parameters and request system reboot. +|--timeout |duration |The maximum time to wait for the tune processes to complete (for example, 300ms, 1.5s, 2h45m). +|=== -|--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 `~/.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. +|=== == Examples +This section provides examples of how to use `rpk redpanda tune`. + This section provides examples of using the autotuner. * 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. * 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. * 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. - ** 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: +** 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: + [,bash] ---- @@ -127,14 +125,12 @@ rpk redpanda config set rpk.tune_aio_events true ---- rpk redpanda tune all ---- - * To run a specific tuner, use the xref:./rpk-redpanda-tune.adoc[`rpk redpanda tune`] command for the tuner: + [,bash] ---- rpk redpanda tune ---- - * To learn more about a tuner, use the xref:./rpk-redpanda-tune.adoc[`rpk redpanda tune help`] command for the tuner: + [,bash] @@ -152,3 +148,5 @@ See also the xref:./rpk-redpanda-tune-list.adoc#tuners[Tuners reference] for des * xref:deploy:deployment-option/self-hosted/kubernetes/k-tune-workers.adoc[Tune Kubernetes Worker Nodes for Production] * xref:./rpk-redpanda-mode.adoc[`rpk redpanda mode production`] * xref:./rpk-redpanda-tune-list.adoc[`rpk redpanda tune list`] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda.adoc index 2616d5854f..09f212e4d8 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda.adoc @@ -1,35 +1,63 @@ = rpk redpanda -:description: These commands let you interact with (start, stop, tune) a local Redpanda process. -:page-aliases: reference:rpk/rpk-redpanda.adoc -:unsupported-os: macOS, Windows +:description: Interact with a local Redpanda process. +:page-platforms: linux,darwin -include::reference:partial$unsupported-os-rpk.adoc[] +// 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[] Interact with a local Redpanda process. == Usage [,bash] ---- -rpk redpanda [flags] [command] +rpk redpanda [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-admin.adoc[`rpk redpanda admin`] +|Talk to the Redpanda admin listener. + +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-check.adoc[`rpk redpanda check`] +|Check if system meets Redpanda requirements. + +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-config.adoc[`rpk redpanda config`] +|Edit configuration. -|-h, --help |- |Help for redpanda. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc[`rpk redpanda mode`] +|Enable a default configuration mode This command allows you to set one of the following modes: Development, Production, or Recovery. PRODUCTION * Enforces optimal runtime checks. -|--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-redpanda/rpk-redpanda-start.adoc[`rpk redpanda start`] +|Start redpanda. -|-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-redpanda/rpk-redpanda-stop.adoc[`rpk redpanda stop`] +|Stop a local Redpanda process. `rpk stop` first sends SIGINT, and waits for the specified timeout. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-redpanda/rpk-redpanda-tune.adoc[`rpk redpanda tune`] +|Sets the OS parameters to tune system performance. Available tuners: * all. -|--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 `~/.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-registry/rpk-registry-compatibility-level-get.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc index 7a371c0e09..d4afc045a7 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc @@ -1,38 +1,46 @@ = rpk registry compatibility-level get -// tag::single-source[] +:description: pass:q[Get the global or per-subject compatibility levels. Running this command with no subject returns the global level, alternatively you can use the `--global` flag to get the global level at the same time as per-subject levels.] +: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[] Get the global or per-subject compatibility levels. -Running this command with no subject returns the global compatibility level. Use the `--global` flag to get the global level at the same time as per-subject levels. +Running this command with no subject returns the global level, alternatively +you can use the `--global` flag to get the global level at the same time as +per-subject levels. == Usage [,bash] ---- -rpk registry compatibility-level get [SUBJECT...] [flags] +rpk registry compatibility-level get [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--global |- |Return the global level in addition to subject levels. -|-h, --help |- |Help for get. -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--global |bool |Return the global level in addition to subject levels. +|=== -|--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 `~/.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-registry/rpk-registry-compatibility-level-set.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc index 8ac097d5ae..bbb30453ef 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc @@ -1,59 +1,60 @@ = rpk registry compatibility-level set -// tag::single-source[] - -Set the global or per-subject compatibility levels. - -Running this command without a subject sets the global compatibility level. To set the global level at the same time as per-subject levels, use the `--global` flag. - -== Concept - -=== Levels +:description: Set the global or per-subject compatibility levels. Running this command without a subject sets the global compatibility level. +:page-platforms: linux,darwin -- BACKWARD (default): Consumers using the new schema (for example, version 10) can read data from producers using the previous schema (for example, version 9). +// 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 -- BACKWARD_TRANSITIVE: Consumers using the new schema (for example, version 10) can read data from producers using all previous schemas (for example, versions 1-9). - -- FORWARD: Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10). - -- FORWARD_TRANSITIVE: Consumers using any previous schema (for example, versions 1-9) can read data from producers using the new schema (for example, version 10). +// tag::single-source[] +Set the global or per-subject compatibility levels. -- FULL: A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward compatible with each other. +Running this command without a subject sets the global compatibility level. To +set the global level at the same time as per-subject levels, use the `--global` +flag. -- FULL_TRANSITIVE: Each schema is both backward and forward compatible with all registered schemas. +LEVELS: -- NONE: No schema compatibility checks are done. +* BACKWARD (`default`): Consumers using the new schema (for example, version 10) + can read data from producers using the previous schema (for example, version + 9). +* `BACKWARD_TRANSITIVE`: Consumers using the new schema (for example, version . can read data from producers using all previous schemas (for example, versions 1-9). +* `FORWARD`: Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10). +* `FORWARD_TRANSITIVE`: Consumers using any previous schema (for example, versions 1-9) can read data from producers using the new schema (for example, version 10). +* `FULL`: A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward compatible with each other. +* `FULL_TRANSITIVE`: Each schema is both backward and forward compatible with all registered schemas. +* `NONE`: No schema compatibility checks are done. == Usage [,bash] ---- -rpk registry compatibility-level set [SUBJECT...] [flags] +rpk registry compatibility-level set [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--global |- |Set the global level in addition to subject levels. -|-h, --help |- |Help for set. -|--level |string |Level to set, one of `NONE`, `BACKWARD`,`BACKWARD_TRANSITIVE`, `FORWARD`,`FORWARD_TRANSITIVE`, `FULL`, `FULL_TRANSITIVE`. - -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--global |bool |Set the global level in addition to subject levels. +|--level |string |Level to set, see the `help` text of this command for the full list. +|=== -|--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 `~/.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-registry/rpk-registry-compatibility-level.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level.adoc index 59b6725de5..067615e19f 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-compatibility-level.adoc @@ -1,34 +1,56 @@ = rpk registry compatibility-level -// tag::single-source[] +:description: Manage global or per-subject compatibility levels. +: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 global or per-subject compatibility levels. == Usage [,bash] ---- -rpk registry compatibility-level [flags] [command] +rpk registry compatibility-level [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[`rpk registry compatibility-level get`] +|Get the global or per-subject compatibility levels. Running this command with no subject returns the global level, alternatively you can use the `--global` flag to get the global level at the same time as per-subject levels. -|-h, --help |- |Help for compatibility-level. +|xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[`rpk registry compatibility-level set`] +|Set the global or per-subject compatibility levels. Running this command without a subject sets the global compatibility level. -|--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. +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== + +== 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 `~/.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-registry/rpk-registry-context-delete.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc index b972a5fd88..a1c93e3ddc 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc @@ -1,42 +1,48 @@ = rpk registry context delete -// tag::single-source[] +:description: Delete a schema registry context. A context can only be deleted once all subjects within it have been hard deleted. +: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[] Delete a schema registry context. -A context can only be deleted once all subjects within it have been hard deleted. Soft-deleted subjects still block context deletion. Use `rpk registry subject delete --permanent` to hard delete subjects first. +A context can only be deleted once all subjects within it have been +hard deleted. Soft-deleted subjects still block context deletion. Use +`rpk registry subject delete --permanent` to hard delete subjects first. -The default context `.` cannot be deleted. +The default context "." cannot be deleted. == Usage [,bash] ---- -rpk registry context delete [CONTEXT] [flags] +rpk registry context delete [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for delete. -|--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. +== 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. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|--schema-context |string |Schema context to use for all registry operations. +== Global flags -|--skip-context-check |- |Skip the admin API verification of schema context support. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-registry/rpk-registry-context-list.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc index 4954d2c028..d5554b9bdc 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc @@ -1,6 +1,10 @@ = rpk registry context list -// tag::single-source[] +:description: List schema registry contexts. +: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 schema registry contexts. == Usage @@ -10,36 +14,35 @@ List schema registry contexts. rpk registry context list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk registry context ls ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. - -|-h, --help |- |Help for list. +|Value |Type |Description -|--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. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== -|--schema-context |string |Schema context to use for all registry operations. +== Global flags -|--skip-context-check |- |Skip the admin API verification of schema context support. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-registry/rpk-registry-context.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc index 181e348544..2fe3a108eb 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc @@ -1,48 +1,68 @@ = rpk registry context -// tag::single-source[] +:description: Manage schema registry contexts. Schema contexts provide namespace isolation within the schema registry, allowing multiple independent sets of subjects and schemas to coexist. +: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 schema registry contexts. -Schema contexts provide namespace isolation within the schema registry, allowing multiple independent sets of subjects and schemas to coexist. +Schema contexts provide namespace isolation within the schema registry, +allowing multiple independent sets of subjects and schemas to coexist. -Before using schema contexts, enable the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property: +Before using schema contexts, the cluster must have the +schema_registry_enable_qualified_subjects configuration set to true. You +can enable it with: [,bash] ---- rpk cluster config set schema_registry_enable_qualified_subjects true ---- -Use the `--schema-context` flag on the parent `registry` command to scope operations to a specific context. +Use the `--schema-context` flag on the parent `registry` command to scope +operations to a specific context. == Usage [,bash] ---- rpk registry context [flags] - rpk registry context [command] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for context. -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-registry/rpk-registry-context-delete.adoc[`rpk registry context delete`] +|Delete a schema registry context. A context can only be deleted once all subjects within it have been hard deleted. -|-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-registry/rpk-registry-context-list.adoc[`rpk registry context list`] +|List schema registry contexts. -|--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. -|--schema-context |string |Schema context to use for all registry operations. +== Global flags -|--skip-context-check |- |Skip the admin API verification of schema context support. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] + // end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-get.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-get.adoc index 72a35d6688..336e0bcc2b 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-get.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-get.adoc @@ -1,37 +1,42 @@ = rpk registry mode get -// tag::single-source[] +:description: Get schema registry mode. Running this command with no subject returns the global mode. +:page-platforms: linux,darwin -Check the mode Schema Registry is in. +// 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 -Running this command with no subject returns the global mode for Schema Registry. Alternatively, use the `--global` flag to return the global mode at the same time as per-subject modes. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk registry mode get [SUBJECT...] [flags] +rpk registry mode get [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--global |- |Return the global mode in addition to subject modes. -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. -|-h, --help |- |Help for get. +== Flags -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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. +|--global |bool |Return the global mode in addition to subject modes. +|=== -|--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 `~/.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-registry/rpk-registry-mode-reset.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-reset.adoc index a7ffc4579c..75aaa59c8e 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-reset.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-reset.adoc @@ -1,35 +1,34 @@ = rpk registry mode reset -// tag::single-source[] +:description: Reset schema registry mode. This command deletes any subject modes and reverts to the global default. +:page-platforms: linux,darwin -Reset the mode Schema Registry runs in. +// 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 deletes any subject modes and reverts to the global default. The command also prints the subject mode before reverting to the global default. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk registry mode reset [SUBJECT...] [flags] +rpk registry mode reset [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. -|-h, --help |- |Help for reset. -|--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. +== Global flags -|--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. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-registry/rpk-registry-mode-set.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-set.adoc index e6feb98557..5fe362b800 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-set.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-set.adoc @@ -1,78 +1,85 @@ = rpk registry mode set -// tag::single-source[] - -Set the mode Schema Registry runs in. - -Running this command with no subject sets the global mode for Schema Registry. Alternatively, use the `--global` flag to set the global mode for Schema Registry at the same time as per-subject modes. +:description: pass:q[Set schema registry mode Running this command with no subject sets the global schema registry mode, alternatively you can use the `--global` flag to set the global schema registry mode at the same time as per-subject mode. Acceptable mode values: * READONLY * READWRITE * IMPORT You can only enable IMPORT mode on an empty schema registry (if setting mode globally) or an empty subject (if setting at the subject level).] +:page-platforms: linux,darwin -Acceptable mode values: +// 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 -- `READONLY` +// tag::single-source[] +Set schema registry mode. -- `READWRITE` +Running this command with no subject sets the global schema registry mode, +alternatively you can use the `--global` flag to set the global schema registry +mode at the same time as per-subject mode. +Acceptable mode values: -- `IMPORT` +* READONLY +* READWRITE +* IMPORT -You can only enable `IMPORT` mode on an empty schema registry (if setting mode globally) or an empty subject (if setting at the subject level). Empty means no schemas have ever been registered. Soft deletions are not sufficient, so you must hard-delete any existing schemas before enabling `IMPORT` mode. To override this emptiness check, use the `--force` flag. +You can only enable IMPORT mode on an empty schema registry (if setting mode +globally) or an empty subject (if setting at the subject level). Empty means no +schemas have ever been registered. Soft deletions are not sufficient — you must +hard-delete any existing schemas before enabling IMPORT mode. To override this +emptiness check, use the `--force` flag. == Usage [,bash] ---- -rpk registry mode set [SUBJECT...] [flags] +rpk registry mode set [flags] ---- + + + == Examples -Set the global schema registry mode to `READONLY`: +This section provides examples of how to use `rpk registry mode set`. + +Set the global schema registry mode to `READONLY`. [,bash] ---- rpk registry mode set --mode READONLY ---- -Set the schema registry mode to `READWRITE` in subjects `` and ``: +Set the schema registry mode to `READWRITE` in subjects `` and ``. [,bash] ---- rpk registry mode set --mode READWRITE ---- -Set the schema registry mode to IMPORT, overriding the emptiness check: +Set the schema registry mode to IMPORT, overriding the emptiness check. [,bash] ---- rpk registry mode set --mode IMPORT --global --force ---- -NOTE: Replace the placeholder values with your own values. - == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|--force |- |Forces the setting mode to IMPORT when there are existing schemas. - -|--global |- |Set the global schema registry mode in addition to subject modes. - -|-h, --help |- |Help for set. - -|--mode |string |Schema registry mode to set. Acceptable values: `READONLY`, `READWRITE`, `IMPORT` (case insensitive). - -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. - -|--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. +|--force |bool |Whether to force setting mode to IMPORT when there are existing schemas. +|--global |bool |Set the global schema registry mode in addition to subject modes. +|--mode |string |Schema registry mode to set. Supported values: READONLY, READWRITE, IMPORT (case insensitive). +|=== -|--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 `~/.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-registry/rpk-registry-mode.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode.adoc index 2c6d64af9b..739fde9c3a 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-mode.adoc @@ -1,33 +1,64 @@ = rpk registry mode -// tag::single-source[] +:description: Manage schema registry mode. +: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 -Manage the mode Schema Registry runs in. Alternatively, you can use the xref:manage:schema-reg/schema-reg-api.adoc#use-readonly-mode-for-disaster-recovery[Schema Registry API] to do this. +// tag::single-source[] +Manage schema registry mode. == Usage [,bash] ---- -rpk registry mode [command] [flags] +rpk registry mode [flags] ---- + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[`rpk registry mode get`] +|Get schema registry mode. Running this command with no subject returns the global mode. + +|xref:reference:rpk/rpk-registry/rpk-registry-mode-reset.adoc[`rpk registry mode reset`] +|Reset schema registry mode. This command deletes any subject modes and reverts to the global default. + +|xref:reference:rpk/rpk-registry/rpk-registry-mode-set.adoc[`rpk registry mode set`] +|Set schema registry mode Running this command with no subject sets the global schema registry mode, alternatively you can use the `--global` flag to set the global schema registry mode at the same time as per-subject mode. Acceptable mode values: * READONLY * READWRITE * IMPORT You can only enable IMPORT mode on an empty schema registry (if setting mode globally) or an empty subject (if setting at the subject level). + +|=== + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description + +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +== Global flags -|-h, --help |- |Help for mode. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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. +|=== -|-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. +== Suggested reading -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +* xref:manage:schema-reg/schema-reg-api.adoc#use-readonly-mode-for-disaster-recovery[Schema Registry API] -|-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-registry/rpk-registry-schema-check-compatibility.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc index ba667968d3..ab4bb6de94 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc @@ -1,41 +1,45 @@ = rpk registry schema check-compatibility -// tag::single-source[] +:description: Check schema compatibility with existing schemas in the subject. +: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[] Check schema compatibility with existing schemas in the subject. == Usage [,bash] ---- -rpk registry schema check-compatibility [SUBJECT] [flags] +rpk registry schema check-compatibility [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for check-compatibility. -|--references |string |Comma-separated list of references (name:subject:version), or path to reference file. -|--schema |string |Schema file path to check. Must be `.avro`, `.json` or `.proto`. -|--schema-version |string |Schema version to check compatibility with (`latest`, `0`, `1`...). -|--type |string |Schema type (`avro`, `json`, `protobuf`). Overrides schema file extension. - -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--references |string |Comma-separated list of references (name:subject:version) or path to reference file. +|--schema |string |Schema filepath to check. Must be `.avro`, `.json`, or `.proto`. +|--schema-version |string |Schema version to check compatibility with (`latest`, 0, 1...). +|--type |string |Schema type (`avro`,`protobuf`,`json`); overrides schema file extension. +|=== -|--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 `~/.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-registry/rpk-registry-schema-create.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc index d5b73bfbec..ba54d594f9 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc @@ -1,44 +1,68 @@ = rpk registry schema create -// tag::single-source[] +:description: Create a schema for the given subject. This uploads a schema to the registry, creating the schema if it does not exist. +: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[] Create a schema for the given subject. +This uploads a schema to the registry, creating the schema if it does not +exist. The schema type is detected by the filename extension: ".avro" or ".avsc" +for Avro, ".json" for JSON, and ".proto" for Protobuf. You can manually specify +the type with the `--type` flag. + +You may pass the references using the `--reference` flag, which accepts either a +comma separated list of :: or a path to a file. The file +must contain lines of name, subject, and version separated by a tab or space, or +the equivalent in `json` / `yaml` format. + +In import mode, you can specify a schema ID and version using the `--id` and +`--schema-version` flags to assign specific values when creating the schema. + +== Usage + +[,bash] +---- +rpk registry schema create SUBJECT --schema {filename} [flags] +---- + -This uploads a schema to the registry, creating the schema if it does not exist. The schema type is detected by the filename extension: `.avro` or `.avsc` for Avro, `json` for JSON, and `.proto` for Protobuf. You can manually specify the type with the `--type` flag. -You may pass the references using the --reference flag, which accepts either a comma separated list of `::` or a path to a file. The file must contain lines of name, subject, and version separated by a tab or space, or the equivalent in json / yaml format. == Examples -Create a Protobuf schema with subject `foo`: +This section provides examples of how to use `rpk registry schema create`. + +Create a Protobuf schema with subject `foo`. [,bash] ---- rpk registry schema create foo --schema path/to/file.proto ---- -Create an avro schema, passing the type via flags: +Create an Avro schema, passing the type via flags. [,bash] ---- rpk registry schema create foo --schema /path/to/file --type avro ---- -Create a Protobuf schema that references the schema in subject `my_subject`, version 1: +Create a Protobuf schema that references the schema in subject `my_subject`, version 1. [,bash] ---- rpk registry schema create foo --schema /path/to/file.proto --references my_name:my_subject:1 ---- -Create a schema with a specific ID and version in import mode: +Create a schema with a specific ID and version in import mode. [,bash] ---- rpk registry schema create foo --schema /path/to/file.proto --id 42 --schema-version 3 ---- -Create a schema with metadata properties as key=value pairs: +Create a schema with metadata properties as key=value pairs. [,bash] ---- @@ -47,7 +71,7 @@ rpk registry schema create foo --schema /path/to/file.proto \ --metadata-properties env=prod ---- -Create a schema with metadata properties using JSON format: +Create a schema with metadata properties using JSON format. [,bash] ---- @@ -55,43 +79,31 @@ rpk registry schema create foo --schema /path/to/file.proto \ --metadata-properties '{"owner":"team-a","env":"prod"}' ---- -== Usage - -[,bash] ----- -rpk registry schema create SUBJECT --schema {filename} [flags] ----- - == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for create. - -|--id |int |Optional schema ID to use when creating the schema in import mode (default `-1`). - -|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (for example, `{"key":"value"}`). You can pass this flag multiple times. +|Value |Type |Description +|--id |int |Optional schema ID to use when creating the schema in import mode. +|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (for example, `{"key":"value"}`). |--references |string |Comma-separated list of references (name:subject:version) or path to reference file. +|--schema |string |Schema filepath to upload, must be .avro, .avsc, or .proto. +|--schema-version |int |Optional schema version to use when creating the schema in import mode (requires `--id`). +|--type |string |Schema type (`avro`,`protobuf`,`json`); overrides schema file extension. +|=== -|--schema |string |Schema filepath to upload, must be `.avro`, `.avsc`, or `.proto`. - -|--schema-version |int |Optional schema version to use when creating the schema in import mode (requires `--id` and the default is `-1`). - - -|--type |string |Schema type `avro` or `protobuf` ; overrides schema file extension. - -|--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. - -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +== 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 `~/.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-registry/rpk-registry-schema-delete.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-delete.adoc index 6f6048a3e6..2a6d6bbd53 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-delete.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-delete.adoc @@ -1,7 +1,11 @@ = rpk registry schema delete -// tag::single-source[] +:description: pass:q[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.] +: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 -Delete a specific schema for the given subject. +// tag::single-source[] +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. == Usage @@ -10,29 +14,30 @@ Delete a specific schema for the given subject. rpk registry schema delete SUBJECT --schema-version {version} [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for delete. -|--permanent |- |Perform a hard (permanent) delete of the schema. -|--schema-version |string |Schema version to check compatibility with (`latest`, `0`, `1`...). -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--permanent |bool |Perform a hard (`permanent`) delete of the schema. +|--schema-version |string |Schema version to delete (`latest`, 0, 1...). +|=== -|--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 `~/.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-registry/rpk-registry-schema-get.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-get.adoc index 2c930e7ba7..292edc72d0 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-get.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-get.adoc @@ -1,15 +1,20 @@ = rpk registry schema get -// tag::single-source[] +:description: pass:q[Get a schema by version, ID, or by an existing schema. This returns a lookup of an existing schema or schemas in one of a few potential (mutually exclusive) ways: * By version, returning a schema for a required subject and version * By ID, returning all subjects using the schema, or filtering for one subject * By schema, checking if the schema has been created in the subject To print the schema, use the `--print-schema` 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[] Get a schema by version, ID, or by an existing schema. -This returns a lookup of an existing schema or schemas in one of the following mutually exclusive ways: +This returns a lookup of an existing schema or schemas in one of a few +potential (mutually exclusive) ways: -* By version, returning a schema for a required subject and version. +* By version, returning a schema for a required subject and version -* By ID, returning all subjects using the schema, or filtered by the provided subject. +* By ID, returning all subjects using the schema, or filtering for one subject -* By schema, checking if the schema has been created in the subject. +* By schema, checking if the schema has been created in the subject To print the schema, use the `--print-schema` flag. @@ -19,44 +24,38 @@ To print schema metadata properties, use the `--print-metadata` flag. [,bash] ---- -rpk registry schema get [SUBJECT] [flags] +rpk registry schema get [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--deleted |- |If `true`, also return deleted schemas. - -|-h, --help |- |Help for get. - -|--id |int | Schema ID to look up usage; subject optional. - -|--print-metadata |- |Print the schema metadata properties. -|--print-schema |- |Prints the schema in JSON format. -|--schema |string |Schema filepath to upload, must be `.avro`, `.avsc`, `json`, or `.proto`. -|--schema-version |string |Schema version to check compatibility with (`latest`, `0`, `1`...). - -|--type |string |Schema type of the file used to lookup (`avro`, `json`, `protobuf`). Overrides schema file extension. - - -|--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. +== Flags -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--deleted |bool |If true, also return deleted schemas. +|--id |int |ID to lookup schemas usages of; subject optional. +|--print-metadata |bool |Print the schema metadata properties. +|--print-schema |bool |Prints the schema in JSON format. +|--schema |string |Schema file to check existence of. Must be `.avro`, `.json`, or `.proto`. Subject is required. +|--schema-version |string |Schema version to lookup (`latest`, 0, 1...); subject required. +|--type |string |Schema type of the file used to lookup (`avro`,`protobuf`,`json`); overrides schema file extension. +|=== -|--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 `~/.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-registry/rpk-registry-schema-list.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-list.adoc index fe0e4c6a2f..2f3c3c11b7 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-list.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-list.adoc @@ -1,43 +1,48 @@ = rpk registry schema list -// tag::single-source[] +:description: List the schemas for the requested subjects, or list all schemas. +: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 -List the schemas by subject, or list all schemas. +// tag::single-source[] +List the schemas for the requested subjects, or list all schemas. == Usage [,bash] ---- -rpk registry schema list [SUBJECT...] [flags] +rpk registry schema list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk registry schema ls ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--deleted |- |If `true`, list deleted schemas as well. +|Value |Type |Description -|-h, --help |- |Help for list. - -|--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. - -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--deleted |bool |If true, list deleted schemas as well. +|=== -|--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 `~/.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-registry/rpk-registry-schema-references.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-references.adoc index cde1ab3468..a5c7b5712d 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-references.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-references.adoc @@ -1,6 +1,10 @@ = rpk registry schema references -// tag::single-source[] +:description: Retrieve a list of schemas that reference the subject. +: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[] Retrieve a list of schemas that reference the subject. == Usage @@ -10,29 +14,30 @@ Retrieve a list of schemas that reference the subject. rpk registry schema references SUBJECT --schema-version {version} [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--deleted |- |If `true`, list deleted schemas as well. -|-h, --help |- |Help for references. -|--schema-version |string |Schema version to check compatibility with (`latest`, `0`, `1`...). -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--deleted |bool |If true, list deleted schemas as well. +|--schema-version |string |Schema version to check references with (`latest`, 0, 1...). +|=== -|--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 `~/.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-registry/rpk-registry-schema.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema.adoc index 7ff2e4da9a..d66d19dc80 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema.adoc @@ -1,34 +1,68 @@ = rpk registry schema -// tag::single-source[] +:description: Manage your schema registry schemas. +: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 -Manage schemas in the Schema Registry. +// tag::single-source[] +Manage your schema registry schemas. == Usage [,bash] ---- -rpk registry schema [command] [flags] +rpk registry schema [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc[`rpk registry schema check-compatibility`] +|Check schema compatibility with existing schemas in the subject. -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`rpk registry schema create`] +|Create a schema for the given subject. This uploads a schema to the registry, creating the schema if it does not exist. -|-h, --help |- |Help for schema. +|xref:reference:rpk/rpk-registry/rpk-registry-schema-delete.adoc[`rpk registry schema delete`] +|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. -|--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-registry/rpk-registry-schema-get.adoc[`rpk registry schema get`] +|Get a schema by version, ID, or by an existing schema. This returns a lookup of an existing schema or schemas in one of a few potential (mutually exclusive) ways: * By version, returning a schema for a required subject and version * By ID, returning all subjects using the schema, or filtering for one subject * By schema, checking if the schema has been created in the subject To print the schema, use the `--print-schema` flag. -|-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-registry/rpk-registry-schema-list.adoc[`rpk registry schema list`] +|List the schemas for the requested subjects, or list all schemas. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-registry/rpk-registry-schema-references.adoc[`rpk registry schema references`] +|Retrieve a list of schemas that reference the subject. + +|=== -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Flags + +[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 `~/.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-registry/rpk-registry-subject-delete.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-delete.adoc index d76affbfb9..ec7bbbcc0a 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-delete.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-delete.adoc @@ -1,36 +1,42 @@ = rpk registry subject delete -// tag::single-source[] +:description: Delete one or more schema registry subjects. By default, subjects are soft deleted. +: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 -Soft or hard delete subjects. +// tag::single-source[] +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. == Usage [,bash] ---- -rpk registry subject delete [SUBJECT...] [flags] +rpk registry subject delete [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for delete. -|--permanent |- |Perform a hard (permanent) delete of the subject. -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--permanent |bool |Perform a hard (`permanent`) delete of the subject. +|=== -|--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 `~/.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-registry/rpk-registry-subject-list.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-list.adoc index acf0075729..7bf0d1ecb5 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-list.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject-list.adoc @@ -1,6 +1,10 @@ = rpk registry subject list -// tag::single-source[] +:description: Display all subjects. +: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[] Display all subjects. == Usage @@ -10,34 +14,35 @@ Display all subjects. rpk registry subject list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk registry subject ls ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--deleted |- |If true, list deleted subjects as well. +|Value |Type |Description -|-h, --help |- |Help for list. - -|--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. - -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|--deleted |bool |If true, list deleted subjects as well. +|=== -|--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 `~/.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-registry/rpk-registry-subject.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject.adoc index 43d1482444..2dd710e028 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-subject.adoc @@ -1,34 +1,56 @@ = rpk registry subject -// tag::single-source[] +:description: List or delete schema registry subjects. +: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 -List or delete Schema Registry subjects. +// tag::single-source[] +List or delete schema registry subjects. == Usage [,bash] ---- -rpk registry subject [command] [flags] +rpk registry subject [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. +|xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[`rpk registry subject delete`] +|Delete one or more schema registry subjects. By default, subjects are soft deleted. -|-h, --help |- |Help for subject. +|xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[`rpk registry subject list`] +|Display all subjects. -|--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. +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|=== + +== 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 `~/.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-registry/rpk-registry.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry.adoc index c8bcd3201d..c34461cc65 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry.adoc @@ -1,40 +1,72 @@ = rpk registry -// tag::single-source[] -:description: pass:q[These commands let you manage Redpanda Schema Registry.] +:description: Commands to interact with the schema registry. +: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 -Commands to interact with the Schema Registry. +// tag::single-source[] +Commands to interact with the schema registry. == Usage [,bash] ---- -rpk registry [command] [flags] +rpk registry [flags] ---- + + == Aliases [,bash] ---- -registry, sr +rpk sr ---- -== Flags +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level.adoc[`rpk registry compatibility-level`] +|Manage global or per-subject compatibility levels. + +|xref:reference:rpk/rpk-registry/rpk-registry-context.adoc[`rpk registry context`] +|Manage schema registry contexts. Schema contexts provide namespace isolation within the schema registry, allowing multiple independent sets of subjects and schemas to coexist. + +|xref:reference:rpk/rpk-registry/rpk-registry-mode.adoc[`rpk registry mode`] +|Manage schema registry mode. + +|xref:reference:rpk/rpk-registry/rpk-registry-schema.adoc[`rpk registry schema`] +|Manage your schema registry schemas. + +|xref:reference:rpk/rpk-registry/rpk-registry-subject.adoc[`rpk registry subject`] +|List or delete schema registry subjects. -[cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for registry. +== Flags -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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. +|--schema-context |string |Schema context to use for all registry operations. +|--skip-context-check |bool |Skip the admin API verification of schema context support. +|=== -|--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 `~/.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-security/rpk-security-acl-create.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adoc index 7500234c6f..50f38e0a67 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adoc @@ -1,125 +1,126 @@ = 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. :page-aliases: reference:rpk/rpk-acl/rpk-acl-create.adoc -// tag::single-source[] - -Create ACLs. +:page-platforms: linux,darwin -Following the multiplying effect of combining flags, the create command works on a -straightforward basis: every ACL combination is a created ACL. +// 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 -As mentioned in the `rpk security acl` help text, 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. - -== Examples - -Allow all permissions to user bar on topic `foo` and group `g`: - -```bash -rpk security acl create --allow-principal bar --operation all --topic foo --group g -``` +// tag::single-source[] +Create ACLs. Following the multiplying effect of combining flags, the create command works on a straightforward basis: every ACL combination is a created ACL. -Allow all permissions to role bar on topic `foo` and group `g`: +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. -```bash -rpk security acl create --allow-role bar --operation all --topic foo --group g -``` +== Usage -Allow read permissions to all users on topics biz and baz: +[,bash] +---- +rpk security acl create [flags] +---- -```bash -rpk security acl create --allow-principal '*' --operation read --topic biz,baz -``` +NOTE: 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]. -Allow write permissions to user buzz to transactional ID `txn`: -```bash -rpk security acl create --allow-principal User:buzz --operation write --transactional-id txn -``` -Allow read permissions to user `panda` on topic `bar` and schema registry subject `bar-value`: -```bash -rpk security acl create --allow-principal panda --operation read --topic bar --registry-subject bar-value -``` +== Examples -Grant schema migration permissions for migrating schemas between clusters: +This section provides examples of how to use `rpk security acl create`. -```bash -# Source cluster (read-only) -rpk security acl create --allow-principal User:migrator-user \ - --operation read,describe --registry-global --brokers +=== User ACLs -# Target cluster (read-write and IMPORT mode management) -rpk security acl create --allow-principal User:migrator-user \ - --operation write,describe,alter_configs,describe_configs \ - --registry-global --brokers -``` +Allow all permissions to user bar on topic `foo` and group `g` -[NOTE] -==== -These 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]. -==== +[,bash] +---- +rpk security acl create --allow-principal bar --operation all --topic foo --group g +---- -== Usage +Allow read permissions to all users on topics biz and baz [,bash] ---- -rpk security acl create [flags] +rpk security acl create --allow-principal '*' --operation read --topic biz,baz ---- -== Flags +Allow write permissions to user buzz to transactional ID `txn` -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--allow-host |strings |Hosts from which access will be granted -(repeatable). +[,bash] +---- +rpk security acl create --allow-principal User:buzz --operation write --transactional-id txn +---- -|--allow-principal |strings |Principals for which these permissions will -be granted (repeatable). +=== Role ACLs -|--allow-role |strings |Roles for which these permissions will be granted (repeatable). +Allow all permissions to role bar on topic `foo` and group `g` -|--cluster |- |Whether to grant ACLs to the cluster. +[,bash] +---- +rpk security acl create --allow-role bar --operation all --topic foo --group g +---- -|--deny-host |strings |Hosts from from access will be denied -(repeatable). +=== Schema Registry ACLs -|--deny-principal |strings |Principal for which these permissions will -be denied (repeatable). +Allow read permissions to user `panda` on topic `bar` and schema registry subject `bar-value` -|--deny-role |strings |Role for which these permissions will be denied (repeatable). +[,bash] +---- +rpk security acl create --allow-principal panda --operation read --topic bar --registry-subject bar-value +---- -|--group |strings |Group to grant ACLs for (repeatable). +=== Schema migration permissions -|-h, --help |- |Help for create. +Source cluster (read-only) for schema migration -|--operation |strings |Operation to grant (repeatable). +[,bash] +---- +rpk security acl create --allow-principal User:migrator-user --operation read,describe --registry-global --brokers +---- -|--registry-global |- |Whether to grant ACLs for the schema registry. +Target cluster (read-write) for schema migration -|--registry-subject |strings |Schema Registry subjects to grant ACLs for (repeatable). +[,bash] +---- +rpk security acl create --allow-principal User:migrator-user --operation write,describe,alter_configs,describe_configs --registry-global --brokers +---- -|--resource-pattern-type |string |Pattern to use when matching resource -names (literal or prefixed) (default "literal"). +== Flags -|--topic |strings |Topic to grant ACLs for (repeatable). +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--allow-host |stringSlice |Hosts from which access will be granted (`repeatable`). +|--allow-principal |stringSlice |Principal to allow. Format: `User:name` or `Group:name`. Can be specified multiple times. +|--allow-role |stringSlice |Roles for which these permissions will be granted (`repeatable`). +|--cluster |bool |Whether to grant ACLs to the cluster. +|--deny-host |stringSlice |Hosts from from access will be denied (`repeatable`). +|--deny-principal |stringSlice |Principal to deny. Format: `User:name` or `Group:name`. Can be specified multiple times. +|--deny-role |stringSlice |Role for which these permissions will be denied (`repeatable`). +|--group |stringSlice |Group to grant ACLs for (`repeatable`). +|--operation |stringSlice |Operation to allow or deny: `all`, `read`, `write`, `create`, `delete`, `alter`, `describe`, `clusteraction`, `describeconfigs`, `alterconfigs`, `idempotentwrite`. +|--registry-global |bool |Whether to grant ACLs for the schema registry. +|--registry-subject |stringSlice |Schema Registry subjects to grant ACLs for (`repeatable`). +|--resource-pattern-type |string |Pattern type: `literal` (exact match), `prefixed` (prefix match), `match` (either literal or prefixed), `any`. +|--topic |stringSlice |Topic to grant ACLs for (`repeatable`). +|--transactional-id |stringSlice |Transactional IDs to grant ACLs for (`repeatable`). +|=== -|--transactional-id |strings |Transactional IDs to grant ACLs for -(repeatable). +== 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 `~/.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:manage:security/authorization/acl.adoc[Configure Access Control Lists] // end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-security/rpk-security-acl-delete.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-delete.adoc index a47ceba0c1..c36f2d44bb 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-acl-delete.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-delete.adoc @@ -1,50 +1,33 @@ = rpk security acl delete +:description: pass:q[Delete ACLs. See the `rpk security acl` help text for a full write up on ACLs.] :page-aliases: reference:rpk/rpk-acl/rpk-acl-delete.adoc -// tag::single-source[] +: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[] Delete ACLs. -See the `rpk security acl` help text for a full write up on ACLs. Delete flags work in a -similar multiplying effect as creating ACLs, but delete is more advanced: -deletion works on a filter basis. Any unspecified flag defaults to matching -everything (all operations, or all allowed principals, etc). To ensure that you -do not accidentally delete more than you intend, this command prints everything -that matches your input filters and prompts for a confirmation before the -delete request is issued. Anything matching more than 10 ACLs doubly confirms. +See the `rpk security acl` help text for a full write up on ACLs. Delete flags +work in a similar multiplying effect as creating ACLs, but delete is more +advanced: deletion works on a filter basis. Any unspecified flag defaults to +matching everything (all operations, or all allowed principals, etc). To ensure +that you do not accidentally delete more than you intend, this command prints +everything that matches your input filters and prompts for a confirmation before +the delete request is issued. Anything matching more than 10 ACLs doubly +confirms. As mentioned, not specifying flags matches everything. If no resources are specified, all resources are matched. If no operations are specified, all -operations are matched. You can also opt in to matching everything with "any": ---operation any matches any operation. +operations are matched. You can also opt in to matching everything with `any`: +`--operation` any matches any operation. -The --resource-pattern-type, defaulting to "any", configures how to filter +The `--resource-pattern-type`, defaulting to `any`, configures how to filter. resource names: - -* "any" returns exact name matches of either prefixed or literal pattern type -* "match" returns wildcard matches, prefix patterns that match your input, and literal matches -* "prefix" returns prefix patterns that match your input (prefix "fo" matches "foo") -* "literal" returns exact name matches - -== Examples - -Delete all permissions to user bar on topic `foo` and group `g`: - -```bash -rpk security acl delete --allow-principal bar --operation all --topic foo --group g -``` - -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: - -```bash -rpk security acl create --topic foo --operation all --allow-role red-role -rpk security acl create --topic bar --operation all --deny-role red-role -``` - -It's possible to delete one of the roles: - -```bash -rpk security acl delete --topic foo --operation all --allow-role red-role -``` + * `any` returns exact name matches of either prefixed or literal pattern type + * `match` returns wildcard matches, prefix patterns that match your input, and literal matches + * `prefix` returns prefix patterns that match your input (prefix `fo` matches `foo`) + * `literal` returns exact name matches == Usage @@ -53,62 +36,75 @@ rpk security acl delete --topic foo --operation all --allow-role red-role rpk security acl delete [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--allow-host |strings |Allowed host ACLs to remove (repeatable). - -|--allow-principal |strings |Allowed principal ACLs to remove -(repeatable). - -|--allow-role |strings |Allowed role to remove this ACL from (repeatable). -|--cluster |- |Whether to remove ACLs to the cluster. -|--deny-host |strings |Denied host ACLs to remove (repeatable). -|--deny-principal |strings |Denied principal ACLs to remove -(repeatable). - -|--deny-role |strings |Denied role for ACLs to remove (repeatable). - -|-d, --dry |- |Dry run: validate what would be deleted. - -|--group |strings |Group to remove ACLs for (repeatable). +== Examples -|-h, --help |- |Help for delete. +This section provides examples of how to use `rpk security acl delete`. -|--no-confirm |- |Disable confirmation prompt. +=== Delete all permissions for a user -|--operation |strings |Operation to remove (repeatable). +Delete all permissions to user bar on topic `foo` and group `g`: -|-f, --print-filters |- |Print the filters that were requested (failed -filters are always printed). +[,bash] +---- +rpk security acl delete --allow-principal bar --operation all --topic foo --group g +---- -|--registry-global |- |Whether to remove ACLs for the schema registry. +=== Delete specific ACL from a role -|--registry-subject |strings |Schema Registry subjects to remove ACLs for (repeatable). +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: -|--resource-pattern-type |string |Pattern to use when matching resource -names (any, match, literal, or prefixed) (default "any"). +[,bash] +---- +rpk security acl create --topic foo --operation all --allow-role red-role +rpk security acl create --topic bar --operation all --deny-role red-role +---- -|--topic |strings |Topic to remove ACLs for (repeatable). +It's possible to delete one of the roles: -|--transactional-id |strings |Transactional IDs to remove ACLs for -(repeatable). +[,bash] +---- +rpk security acl delete --topic foo --operation all --allow-role red-role +---- -|--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 + +|--allow-host |stringSlice |Allowed host ACLs to remove (`repeatable`). +|--allow-principal |stringSlice |Allowed principal ACLs to remove (`repeatable`). +|--allow-role |stringSlice |Allowed role to remove this ACL from (`repeatable`). +|--cluster |bool |Whether to remove ACLs for the cluster. +|--deny-host |stringSlice |Hosts from which access will be denied (`repeatable`). +|--deny-principal |stringSlice |Denied principal ACLs to remove (`repeatable`). +|--deny-role |stringSlice |Denied role to remove this ACL from (`repeatable`). +|-d, --dry |bool |Dry run: validate what would be deleted. +|--group |stringSlice |Group to remove ACLs for (`repeatable`). +|--no-confirm |bool |Disable confirmation prompt. +|--operation |stringSlice |Operation to remove (`repeatable`). +|-f, --print-filters |bool |Print the filters that were requested (failed filters are always printed). +|--registry-global |bool |Whether to remove ACLs for the schema registry. +|--registry-subject |stringSlice |Schema Registry subjects to remove ACLs for (`repeatable`). +|--resource-pattern-type |string |Pattern to use when matching resource names (`any`, match, literal, or prefixed). +|--topic |stringSlice |Topic to remove ACLs for (`repeatable`). +|--transactional-id |stringSlice |Transactional IDs to remove ACLs 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 `~/.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-security/rpk-security-acl-list.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-list.adoc index 473cccee68..25eb29220a 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-acl-list.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-acl-list.adoc @@ -1,131 +1,126 @@ = rpk security acl list +:description: pass:q[List ACLs. See the `rpk security acl` help text for a full write up on ACLs.] :page-aliases: reference:rpk/rpk-acl/rpk-acl-list.adoc -// tag::single-source[] +: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 ACLs. -See the `rpk security acl` help text for a full write up on ACLs. List flags work in a -similar multiplying effect as creating ACLs, but list is more advanced: -listing works on a filter basis. Any unspecified flag defaults to matching -everything (all operations, or all allowed principals, etc). +See the `rpk security acl` help text for a full write up on ACLs. List flags +work in a similar multiplying effect as creating ACLs, but list is more +advanced: listing works on a filter basis. Any unspecified flag defaults to +matching everything (all operations, or all allowed principals, etc). As mentioned, not specifying flags matches everything. If no resources are specified, all resources are matched. If no operations are specified, all -operations are matched. You can also opt in to matching everything with "any": ---operation any matches any operation. +operations are matched. You can also opt in to matching everything with `any`: +`--operation` any matches any operation. -The --resource-pattern-type, defaulting to "any", configures how to filter +The `--resource-pattern-type`, defaulting to `any`, configures how to filter. resource names: + * `any` returns exact name matches of either prefixed or literal pattern type + * `match` returns wildcard matches, prefix patterns that match your input, and literal matches + * `prefix` returns prefix patterns that match your input (prefix `fo` matches `foo`) + * `literal` returns exact name matches -* "any" returns exact name matches of either prefixed or literal pattern type -* "match" returns wildcard matches, prefix patterns that match your input, and literal matches -* "prefix" returns prefix patterns that match your input (prefix "fo" matches "foo") -* "literal" returns exact name matches +The list command lists ACLs for both Kafka and Schema Registry. To limit the +results to a specific subsystem, use the `--subsystem` flag with either `kafka` or +`registry`. +== Usage -The list command lists ACLs for both Kafka and Schema Registry. To limit the results to a specific subsystem, use the `--subsystem` flag with either `kafka` or `registry`. +[,bash] +---- +rpk security acl list [flags] +---- -== Examples -List all ACLs: -```bash -rpk security acl list -``` +== Aliases -List all Schema Registry ACLs: +[,bash] +---- +rpk security acl ls +rpk security acl describe +---- -```bash -rpk security acl list --subsystem registry -``` +== Examples -List all ACLs for topic "foo": +This section provides examples of how to use `rpk security acl list`. -```bash -rpk security acl list --topic foo -``` +List all ACLs. -List all ACLs for user "bar" on topic "foo": +[,bash] +---- +rpk security acl list +---- -```bash -rpk security acl list --allow-principal bar --topic foo -``` +List all Schema Registry ACLs. -List all ACLs for role "admin" on schema registry subject "foo-value": +[,bash] +---- +rpk security acl list --subsystem registry +---- -```bash -rpk security acl list --allow-role admin --registry-subject foo-value -``` +List all ACLs for topic "foo". -== Usage +[,bash] +---- +rpk security acl list --topic foo +---- + +List all ACLs for user "bar" on topic "foo". [,bash] ---- -rpk security acl list [flags] +rpk security acl list --allow-principal bar --topic foo ---- -== Aliases +List all ACLs for role "admin" on schema registry subject "foo-value". [,bash] ---- -list, ls, describe +rpk security acl list --allow-role admin --registry-subject foo-value ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--allow-host |strings |Allowed host ACLs to match (repeatable). - -|--allow-principal |strings |Allowed principal ACLs to match -(repeatable). - -|--allow-role |strings |Allowed role for ACLs to match (repeatable). - -|--cluster |- |Whether to match ACLs to the cluster. - -|--deny-host |strings |Denied host ACLs to match (repeatable). - -|--deny-principal |strings |Denied principal ACLs to match (repeatable). - -|--deny-role |strings |Denied role for ACLs to match (repeatable). - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|--group |strings |Group to match ACLs for (repeatable). - -|-h, --help |- |Help for list. - -|--operation |strings |Operation to match (repeatable). - -|-f, --print-filters |- |Print the filters that were requested (failed -filters are always printed). - -|--registry-global |- |Whether to grant ACLs for the schema registry. - -|--registry-subject |strings |Schema Registry subjects to grant ACLs for (repeatable). - -|--resource-pattern-type |string |Pattern to use when matching resource -names (any, match, literal, or prefixed) (default "any"). - -|--subsystem |strings |Subsystem to match ACLs for. Possible values: `kafka`, `registry`, `kafka,registry` (both). Default: `kafka,registry`. - -|--topic |strings |Topic to match ACLs for (repeatable). - -|--transactional-id |strings |Transactional IDs to match ACLs 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`. - -|-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 + +|--allow-host |stringSlice |Allowed host ACLs to match (`repeatable`). +|--allow-principal |stringSlice |Allowed principal ACLs to match (`repeatable`). +|--allow-role |stringSlice |Allowed role ACLs to match (`repeatable`). +|--cluster |bool |Whether to match ACLs to the cluster. +|--deny-host |stringSlice |Denied host ACLs to match (`repeatable`). +|--deny-principal |stringSlice |Denied principal ACLs to match (`repeatable`). +|--deny-role |stringSlice |Denied role ACLs to match (`repeatable`). +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|--group |stringSlice |Group to match ACLs for (`repeatable`). +|--operation |stringSlice |Operation to match (`repeatable`). +|-f, --print-filters |bool |Print the filters that were requested (failed filters are always printed). +|--registry-global |bool |Whether to match ACLs for the schema registry. +|--registry-subject |stringSlice |Schema registry subjects to match ACLs for (`repeatable`). +|--resource-pattern-type |string |Pattern to use when matching resource names (`any`, match, literal, or prefixed). +|--subsystem |stringSlice |The subsystem to match ACLs for (`kafka`, registry, or both). +|--topic |stringSlice |Topic to match ACLs for (`repeatable`). +|--transactional-id |stringSlice |Transactional IDs to match ACLs 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 `~/.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-security/rpk-security-acl.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-acl.adoc index ce61498880..809f58a1a9 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-acl.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-acl.adoc @@ -1,33 +1,12 @@ = rpk security acl +:description: Manage Kafka ACLs (Access Control Lists) for authorization. ACLs control which principals can perform operations on resources. :page-aliases: reference:rpk/rpk-acl.adoc, reference:rpk/rpk-acl/rpk-acl.adoc -// tag::single-source[] -:description: These commands let you create SASL users and create, list, and delete ACLs. - -Manage ACLs and SASL users. - -These commands let you create SASL users and create, list, and delete ACLs. The help text below is specific to ACLs. To learn about SASL users, -see the help text under the `user` command. - -When using SASL, ACLs allow or deny you access to certain requests. The -`create`, `delete`, and `list` commands help you manage your ACLs. +:page-platforms: linux,darwin -An ACL is made up of five components: +// 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 -* a principal (the user) or role -* a host, which the principal (or role) is allowed or denied requests from -* what resource to access (such as topic name, group ID) -* the operation (such as read, write) -* the permission (whether to allow or deny the above) - -ACL commands work on a multiplicative basis. If creating, specifying two -principals and two permissions creates four ACLs: both permissions for the -first principal, as well as both permissions for the second principal. Adding -two resources further doubles the ACLs created. - -It is recommended to be as specific as possible when granting ACLs. Granting -more ACLs than necessary per principal may inadvertently allow clients to do -things they should not, such as deleting topics or joining the wrong consumer -group. +// tag::single-source[] +Manage Kafka ACLs (Access Control Lists) for authorization. ACLs control which principals can perform operations on resources. include::shared:partial$rpk-acl-tip.adoc[] @@ -35,55 +14,31 @@ include::shared:partial$rpk-acl-tip.adoc[] 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". -When 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. +When 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. == Hosts -Hosts 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. +Hosts 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. == Roles -You 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. +You 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. -When 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. For example `rpk security acl create --allow-role '*' ...` will produce an error. +When 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. == Resources -A 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. +A 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. -Resources combine with the operation that is allowed or denied on that -resource. The next section describes which operations are required for which -requests, and further fleshes out the concept of a 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). +Resources 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). == Operations -Pairing with resources, operations are the actions that are allowed or denied. -Redpanda has the following operations: - +Pairing with resources, operations are the actions that are allowed or denied. Redpanda has the following operations: -[cols=",",] +[cols="1,2a"] |=== -|*Operation* |*Description* +|Operation |Description |`all` |Allows all operations below. |`read` |Allows reading a given resource. @@ -96,11 +51,7 @@ Redpanda has the following operations: |`alter_configs` |Allows altering configurations. |=== - -You 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`): +You 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`): `rpk security acl create --operation write,read,describe --topic [topics]` @@ -110,49 +61,61 @@ invoke `rpk security acl create` three times with the following (including your == Permissions -A 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. +A 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. == Management -Creating 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. +Creating 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. -Using 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. +Using 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. == Usage [,bash] ---- -rpk security acl [command] [flags] +rpk security acl [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-security/rpk-security-acl-create.adoc[`rpk security acl create`] +|Create ACLs. Following the multiplying effect of combining flags, the create command works on a straightforward basis: every ACL combination is a created ACL. -|-h, --help |- |Help for acl. +|xref:reference:rpk/rpk-security/rpk-security-acl-delete.adoc[`rpk security acl delete`] +|Delete ACLs. See the `rpk security acl` help text for a full write up on ACLs. + +|xref:reference:rpk/rpk-security/rpk-security-acl-list.adoc[`rpk security acl list`] +|List ACLs. See the `rpk security acl` help text for a full write up on ACLs. + +|=== -|--help-operations |- |Print more help about ACL operations. +== 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. +|--help-operations |bool |Print more help about ACL operations. +|=== -|--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 `~/.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-security/rpk-security-role-assign.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-assign.adoc index 539819277b..0055d07d6e 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-assign.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-assign.adoc @@ -1,71 +1,84 @@ = rpk security role assign -// tag::single-source[] +:description: pass:q[Assign a Redpanda role to a principal. The `--principal` flag accepts principals with the format ':'.] +:page-platforms: linux,darwin -Assign a Redpanda role to a principal. +// 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 -The `--principal` flag accepts principals with the format `:`. If `PrincipalPrefix` is not provided, then defaults to `User:`. +// tag::single-source[] +Assign a Redpanda role to a principal. -== Examples +The `--principal` flag accepts principals with the format +':'. If 'PrincipalPrefix' is not provided, then +defaults to 'User:'. -Assign role `redpanda-admin` to user `red`: +== Usage -```bash -rpk security role assign redpanda-admin --principal red -``` +[,bash] +---- +rpk security role assign --principal [flags] +---- -Assign role `redpanda-admin` to users `red` and `panda`: -```bash -rpk security role assign redpanda-admin --principal red,panda -``` -Assign role `topic-reader` to group `analytics`: +== Aliases -```bash -rpk security role assign topic-reader --principal Group:analytics -``` +[,bash] +---- +rpk security role add +---- -Assign role `ops-admin` to both a user and a group: +== Examples -```bash -rpk security role assign ops-admin --principal alice,Group:sre -``` +This section provides examples of how to use `rpk security role assign`. -== Usage +Assign role `redpanda-admin` to user `red`. [,bash] ---- -rpk security role assign [ROLE] --principal [PRINCIPALS...] [flags] +rpk security role assign redpanda-admin --principal red ---- -== Aliases +Assign role `redpanda-admin` to users `red` and `panda`. [,bash] ---- -assign, add +rpk security role assign redpanda-admin --principal red,panda ---- -== Flags +Assign role `topic-reader` to group `analytics`. -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* +[,bash] +---- +rpk security role assign topic-reader --principal Group:analytics +---- -|-h, --help |- |Help for assign. +Assign role `ops-admin` to both a user and a group. -|--principal |strings |Principal to assign the role to (repeatable). +[,bash] +---- +rpk security role assign ops-admin --principal alice,Group:sre +---- -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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`. +|--principal |stringSlice |Principal to assign the role to (`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 `~/.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-security/rpk-security-role-create.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-create.adoc index 2d0c8ef038..5927fa741c 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-create.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-create.adoc @@ -1,36 +1,37 @@ = rpk security role create -// tag::single-source[] +:description: pass:q[Create a role in Redpanda. After creating a role you may bind ACLs to the role using the `--allow-role` flag in the `rpk security acl create` 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[] Create a role in Redpanda. -After creating a role you may bind ACLs to the role using the `--allow-role` flag in the `rpk security acl create` command. +After creating a role you may bind ACLs to the role using the `--allow-role` +flag in the `rpk security acl create` command. == Usage [,bash] ---- -rpk security role create [ROLE] [flags] +rpk security role create [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for create. -|--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; `-X help` for detail or `-X list` for terser detail. +== Global flags -|--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. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-security/rpk-security-role-delete.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-delete.adoc index bb9611f0e4..fbf5119f08 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-delete.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-delete.adoc @@ -1,6 +1,10 @@ = rpk security role delete -// tag::single-source[] +:description: Delete a role in Redpanda. This action will remove all associated ACLs from the role and unassign members. +: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[] Delete a role in Redpanda. This action will remove all associated ACLs from the role and unassign members. @@ -11,30 +15,32 @@ The flag `--no-confirm` can be used to avoid the confirmation prompt. [,bash] ---- -rpk security role delete [ROLE] [flags] +rpk security role delete [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. -|--no-confirm |- |Disable confirmation prompt. -|--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`. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|--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 `~/.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-security/rpk-security-role-describe.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-describe.adoc index 14a8f3d8c2..b899d38e9d 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-describe.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-describe.adoc @@ -1,69 +1,78 @@ = rpk security role describe -// tag::single-source[] +:description: Describe a Redpanda role. This command describes a role, including the ACLs associated to the role, and lists members who are assigned the role. +: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 a Redpanda role. -This command describes a role, including the ACLs associated to the role, and lists members who are assigned the role. +This command describes a role, including the ACLs associated to the role, and +lists members who are assigned the role. -== Examples +== Usage -Describe the role `red` (print members and ACLs): +[,bash] +---- +rpk security role describe [flags] +---- -```bash -rpk security role describe red -``` -Print only the members of role `red`: -```bash -rpk security role describe red --print-members -``` +== Aliases -Print only the ACL associated to the role `red`: +[,bash] +---- +rpk security role info +---- -```bash -rpk security role describe red --print-permissions -``` +== Examples -== Usage +This section provides examples of how to use `rpk security role describe`. + +Describe the role `red` (print members and ACLs). [,bash] ---- -rpk security role describe [ROLE] [flags] +rpk security role describe red ---- -== Aliases +Print only the members of role `red`. [,bash] ---- -describe, info +rpk security role describe red --print-members +---- + +Print only the ACL associated to the role `red`. + +[,bash] +---- +rpk security role describe red --print-permissions ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|-h, --help |- |Help for describe. - -|-a, --print-all |- |Print all sections. - -|-m, --print-members |- |Print the members section. - -|-p, --print-permissions |- |Print the role permissions section. - -|--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`. +|-a, --print-all |bool |Print all sections. +|-m, --print-members |bool |Print the members section. +|-p, --print-permissions |bool |Print the role permissions section. +|=== -|--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 `~/.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-security/rpk-security-role-list.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-list.adoc index a4d7385bec..1532b4a005 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-list.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-list.adoc @@ -1,71 +1,81 @@ = rpk security role list -// tag::single-source[] +:description: List roles created in 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[] List roles created in Redpanda. -== Examples +== Usage -List all roles in Redpanda: +[,bash] +---- +rpk security role list [flags] +---- -```bash -rpk security role list -``` -List all roles assigned to the user `red`: -```bash -rpk security role list --principal red -``` +== Aliases -List all roles with the prefix `agent-`: +[,bash] +---- +rpk security role ls +---- -```bash -rpk security role list --prefix "agent-" -``` +== Examples -List all roles assigned to the group `analytics`: +This section provides examples of how to use `rpk security role list`. -```bash -rpk security role list --principal Group:analytics -``` +List all roles in Redpanda. -== Usage +[,bash] +---- +rpk security role list +---- + +List all roles assigned to the user `red`. [,bash] ---- -rpk security role list [flags] +rpk security role list --principal red ---- -== Aliases +List all roles with the prefix `agent-`. [,bash] ---- -list, ls +rpk security role list --prefix "agent-" +---- + +List all roles assigned to the group `analytics`. + +[,bash] +---- +rpk security role list --principal Group:analytics ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for list. +|Value |Type |Description |--prefix |string |Return the roles matching the specified prefix. - |--principal |string |Return the roles matching the specified principal; if no principal prefix is given, `User:` is used. +|=== -|--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. +== 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 `~/.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-security/rpk-security-role-unassign.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role-unassign.adoc index f7e6f05930..496ee97ae6 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role-unassign.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role-unassign.adoc @@ -1,67 +1,77 @@ = rpk security role unassign -// tag::single-source[] +:description: pass:q[Unassign a Redpanda role from a principal. The `--principal` flag accepts principals with the format ':'.] +: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[] Unassign a Redpanda role from a principal. -The `--principal` flag accepts principals with the format `:`. +The `--principal` flag accepts principals with the format +':'. If 'PrincipalPrefix' is not provided, then +defaults to 'User:'. -Command defaults to `User:` if `PrincipalPrefix` is not provided. +== Usage -== Examples +[,bash] +---- +rpk security role unassign --principal [flags] +---- -Unassign role `redpanda-admin` from user `red`: -```bash -rpk security role unassign redpanda-admin --principal red -``` -Unassign role `redpanda-admin` from users `red` and `panda`: +== Aliases -```bash -rpk security role unassign redpanda-admin --principal red,panda -``` +[,bash] +---- +rpk security role remove +---- -Unassign role `topic-reader` from group `contractors`: +== Examples -```bash -rpk security role unassign topic-reader --principal Group:contractors -``` +This section provides examples of how to use `rpk security role unassign`. -== Usage +Unassign role `redpanda-admin` from user `red`. [,bash] ---- -rpk security role unassign [ROLE] --principal [PRINCIPALS...] [flags] +rpk security role unassign redpanda-admin --principal red ---- -== Aliases +Unassign role `redpanda-admin` from users `red` and `panda`. + +[,bash] +---- +rpk security role unassign redpanda-admin --principal red,panda +---- + +Unassign role `topic-reader` from group `contractors`. [,bash] ---- -unassign, remove +rpk security role unassign topic-reader --principal Group:contractors ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for unassign. - -|--principal |strings |Principal to unassign the role from (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`. +|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. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|--principal |stringSlice |Principal to unassign the role from (`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 `~/.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-security/rpk-security-role.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-role.adoc index d20e07dc83..37ad7ea98a 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-role.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-role.adoc @@ -1,41 +1,75 @@ = rpk security role -// tag::single-source[] +:description: Manage Redpanda roles. +: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 roles. == Usage [,bash] ---- -rpk security role [command] [flags] +rpk security role [flags] ---- + + == Aliases [,bash] ---- -role, access, roles +rpk security access +rpk security roles ---- -== Flags +== Subcommands -[cols="1m,1a,2a"] +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-security/rpk-security-role-assign.adoc[`rpk security role assign`] +|Assign a Redpanda role to a principal. The `--principal` flag accepts principals with the format ':'. + +|xref:reference:rpk/rpk-security/rpk-security-role-create.adoc[`rpk security role create`] +|Create a role in Redpanda. After creating a role you may bind ACLs to the role using the `--allow-role` flag in the `rpk security acl create` command. + +|xref:reference:rpk/rpk-security/rpk-security-role-delete.adoc[`rpk security role delete`] +|Delete a role in Redpanda. This action will remove all associated ACLs from the role and unassign members. -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|xref:reference:rpk/rpk-security/rpk-security-role-describe.adoc[`rpk security role describe`] +|Describe a Redpanda role. This command describes a role, including the ACLs associated to the role, and lists members who are assigned the role. -|-h, --help |- |Help for role. +|xref:reference:rpk/rpk-security/rpk-security-role-list.adoc[`rpk security role list`] +|List roles created in Redpanda. -|--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-security/rpk-security-role-unassign.adoc[`rpk security role unassign`] +|Unassign a Redpanda role from a principal. The `--principal` flag accepts principals with the format ':'. -|-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 + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--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 `~/.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-security/rpk-security-user-create.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-user-create.adoc index a86f471cc1..53fa2b07ed 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-user-create.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-user-create.adoc @@ -1,18 +1,22 @@ = rpk security user create +:description: pass:q[Create a SASL user. This command creates a single SASL user with the given password, optionally with a custom `mechanism`.] :page-aliases: reference:rpk/rpk-acl/rpk-acl-user-create.adoc, reference:rpk/rpk-security/rpk-security-acl-user-create.adoc -// tag::single-source[] +: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[] Create a SASL user. This command creates a single SASL user with the given password, optionally -with a custom mechanism. SASL consists of three parts: a username, a +with a custom `mechanism`. SASL consists of three parts: a username, a password, and a mechanism. The mechanism determines which authentication flow the client will use for this user/pass. Redpanda currently supports two mechanisms: SCRAM-SHA-256, the default, and SCRAM-SHA-512, which is the same flow but uses sha512 rather than sha256. -Using SASL requires setting `enable_sasl: true` in the redpanda section of your +Using SASL requires setting "enable_sasl: true" in the redpanda section of your `redpanda.yaml`. Before a created SASL account can be used, you must also create ACLs to grant the account access to certain resources in your cluster. See the acl help text for more info. @@ -21,35 +25,33 @@ acl help text for more info. [,bash] ---- -rpk security user create [USER] -p [PASS] [flags] +rpk security user create -p [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for create. -|--mechanism |string |SASL mechanism to use for the user you are -creating (`scram-sha-256`, `scram-sha-512`, case insensitive) (default: -`scram-sha-256`). -|--password |string |New user's password (NOTE: if using --password for -the admin API, use --new-password). -|--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`. +|--mechanism |string |SASL mechanism to use for the user you are creating (`scram-sha-256`, `scram-sha-512`, case insensitive). +|--password |string |New user's password (NOTE: if using `--password` for the admin API, use `--new-password`). +|=== -|--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 `~/.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-security/rpk-security-user-delete.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-user-delete.adoc index e55e4e467a..fc6b67ca8f 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-user-delete.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-user-delete.adoc @@ -1,7 +1,11 @@ = rpk security user delete +:description: Delete a SASL user. This command deletes the specified SASL account from Redpanda. :page-aliases: reference:rpk/rpk-acl/rpk-acl-user-delete.adoc, reference:rpk/rpk-security/rpk-security-acl-user-delete.adoc -// tag::single-source[] +: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[] Delete a SASL user. This command deletes the specified SASL account from Redpanda. This does not @@ -11,28 +15,24 @@ delete any ACLs that may exist for this user. [,bash] ---- -rpk security user delete [USER] [flags] +rpk security user delete [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for delete. -|--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 -|--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. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-security/rpk-security-user-list.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-user-list.adoc index 99f6109b7b..54b42c873e 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-user-list.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-user-list.adoc @@ -1,7 +1,11 @@ = rpk security user list +:description: List SASL users. :page-aliases: reference:rpk/rpk-acl/rpk-acl-user-list.adoc, reference:rpk/rpk-security/rpk-security-acl-user-list.adoc -// tag::single-source[] +: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 SASL users. == Usage @@ -11,32 +15,27 @@ List SASL users. rpk security user list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk security user 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 `~/.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-security/rpk-security-user-update.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-user-update.adoc index 560a7200b6..977fd2f70f 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-user-update.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-user-update.adoc @@ -1,41 +1,44 @@ = rpk security user update +:description: Update SASL user credentials. :page-aliases: reference:rpk/rpk-acl/rpk-acl-user-update.adoc, reference:rpk/rpk-security/rpk-security-acl-user-update.adoc -// tag::single-source[] +:page-platforms: linux,darwin -Update SASL user credentials +// 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 -CAUTION: The default value for the `--mechanism` flag is `SCRAM-SHA-256`. Set the flag when using a different mechanism to avoid unexpected changes. +// tag::single-source[] +Update SASL user credentials. == Usage [,bash] ---- -rpk security user update [USER] --new-password [PW] --mechanism [MECHANISM] [flags] +rpk security user update --new-password --mechanism [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for update. - -|--mechanism |string |SASL mechanism to use for the user you are updating. Case insensitive. Acceptable values: `SCRAM-SHA-256`, `SCRAM-SHA-512`. +|Value |Type |Description +|--mechanism |string |SASL mechanism to use for the user you are updating (SCRAM-SHA-256, SCRAM-SHA-512, case insensitive). |--new-password |string |New user's password. +|=== -|--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. +== 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 `~/.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-security/rpk-security-user.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security-user.adoc index b22d90d37e..9c628393a8 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security-user.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security-user.adoc @@ -1,41 +1,69 @@ = rpk security user +:description: Manage SASL users. If SASL is enabled, a SASL user is what you use to talk to Redpanda, and ACLs control what your user has access to. :page-aliases: reference:rpk/rpk-acl/rpk-acl-user.adoc, reference:rpk/rpk-security/rpk-security-acl-user.adoc -// tag::single-source[] +: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 -Manage SCRAM users. +// tag::single-source[] +Manage SASL users. -If SCRAM is enabled, a SCRAM user is what you use to talk to Redpanda, and ACLs -control what your user has access to. See `rpk security acl --help` for more information -about ACLs, and `rpk security user create --help` for more information about -creating SCRAM users. Using SCRAM requires setting `kafka_enable_authorization: true` and `authentication_method: sasl` in the -redpanda section of your `redpanda.yaml`, and setting `sasl_mechanisms` with `SCRAM` for your Redpanda cluster. +If SASL is enabled, a SASL user is what you use to talk to Redpanda, and ACLs +control what your user has access to. See `rpk security acl --help` for more +information about ACLs, and `rpk security acl user create --help` for more +information about creating SASL users. Using SASL requires setting "enable_sasl: +true" in the redpanda section of your `redpanda.yaml`. == Usage [,bash] ---- -rpk security user [command] [flags] +rpk security user [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for user. +|xref:reference:rpk/rpk-security/rpk-security-user-create.adoc[`rpk security user create`] +|Create a SASL user. This command creates a single SASL user with the given password, optionally with a custom `mechanism`. -|--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-security/rpk-security-user-delete.adoc[`rpk security user delete`] +|Delete a SASL user. This command deletes the specified SASL account from Redpanda. -|-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-security/rpk-security-user-list.adoc[`rpk security user list`] +|List SASL users. -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|xref:reference:rpk/rpk-security/rpk-security-user-update.adoc[`rpk security user update`] +|Update SASL user credentials. -|--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. +== Flags + +[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 `~/.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-security/rpk-security.adoc b/modules/reference/pages/rpk/rpk-security/rpk-security.adoc index be18c63f24..9f81b30f76 100644 --- a/modules/reference/pages/rpk/rpk-security/rpk-security.adoc +++ b/modules/reference/pages/rpk/rpk-security/rpk-security.adoc @@ -1,38 +1,60 @@ = rpk security +:description: Manage Redpanda security. +: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 create SASL users and create, list, and delete ACLs and RBAC. +Manage Redpanda security. == Usage [,bash] ---- -rpk security [command] [flags] +rpk security [flags] ---- + + == Aliases [,bash] ---- -security, sec +rpk sec ---- -== Flags +== Subcommands -[cols="1m,1a,2a"] +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for security. +|xref:reference:rpk/rpk-security/rpk-security-acl.adoc[`rpk security acl`] +|Manage Kafka ACLs (Access Control Lists) for authorization. ACLs control which principals can perform operations on resources. -|--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-security/rpk-security-role.adoc[`rpk security role`] +|Manage Redpanda roles. -|-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-security/rpk-security-secret.adoc[`rpk security secret`] +|Manage secrets for Redpanda Cloud clusters. This command allows you to manage secrets for your cloud clusters. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-security/rpk-security-user.adoc[`rpk security user`] +|Manage SASL users. If SASL is enabled, a SASL user is what you use to talk to Redpanda, and ACLs control what your user has access to. -|--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 `~/.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-shadow/rpk-shadow-config-generate.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config-generate.adoc index 8e9353a531..8c281cb4b3 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config-generate.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config-generate.adoc @@ -1,20 +1,30 @@ = rpk shadow config generate +:description: Generate a configuration file for creating a Shadow Link. By default, this command creates a sample configuration file with placeholder values that you can customize for your environment. +: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[] +Generate a configuration file for creating a Shadow Link. + +By default, this command creates a sample configuration file with placeholder +values that you can customize for your environment. If you are generating a +Shadow Link for Redpanda Cloud, use the `--for-cloud` flag. -Generate a configuration file for creating a shadow link. +Use the `--print-template` flag to generate a configuration template with detailed +field documentations. -By default, this command creates a sample configuration file with placeholder values that you customize for your environment. +By default, this command prints the configuration to standard output. Use the +`--output` flag to save the configuration to a file. + +After you generate the configuration file, update the placeholder values with +your actual connection details and settings. Then use `rpk shadow create` to +create the Shadow Link. ifdef::env-cloud[] Use the `--for-cloud` flag when generating your configuration. endif::[] -Use the `--print-template` flag to generate a configuration template with detailed field documentations. - -By default, this command prints the configuration to standard output. Use the `--output` flag to save the configuration to a file. - -After you generate the configuration file, update the placeholder values with your actual connection details and settings. Then use xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`] to create the shadow link. - == Usage [,bash] @@ -22,8 +32,13 @@ After you generate the configuration file, update the placeholder values with yo rpk shadow config generate [flags] ---- + + + == Examples +This section provides examples of how to use `rpk shadow config generate`. + Generate a sample configuration and print it to standard output: [,bash] ---- @@ -31,51 +46,50 @@ rpk shadow config generate ---- Generate a configuration template with all the field documentation: - [,bash] ---- rpk shadow config generate --print-template ---- Save the sample configuration to a file: - [,bash] ---- -rpk shadow config generate -o shadow-link.yaml +rpk shadow config generate -o `shadow-link.yaml` ---- Save the template with documentation to a file: - [,bash] ---- -rpk shadow config generate --print-template -o shadow-link.yaml +rpk shadow config generate --print-template -o `shadow-link.yaml` ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -ifdef::env-cloud[] -|--for-cloud |- |Generate configuration suitable for Cloud deployments. - -endif::[] -|-o, --output |string |File path identifying where to save the generated configuration file. If not specified, prints to standard output. +|Value |Type |Description -|--print-template |- |Generate a configuration template with field documentation instead of a sample configuration. +|--for-cloud |bool |Generate configuration suitable for Redpanda Cloud. +|-o, --output |string |File path to save the generated configuration file. If not specified, prints to standard output. +|--print-template |bool |Generate a configuration template with field descriptions instead of a sample configuration. +|=== -|-h, --help |- |Help for generate. +== 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 `~/.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-shadow/rpk-shadow-create.adoc[`rpk shadow create`] // end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config.adoc new file mode 100644 index 0000000000..4be162c883 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config.adoc @@ -0,0 +1,45 @@ += rpk shadow config +:description: Generate a Redpanda Shadow Link configuration file. +: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[] +Generate a Redpanda Shadow Link configuration file. + +== Usage + +[,bash] +---- +rpk shadow config [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] +|Generate a configuration file for creating a Shadow Link. By default, this command creates a sample configuration file with placeholder values that you can customize for your environment. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-shadow/rpk-shadow-create.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-create.adoc index 73843ff846..5d950c00cd 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-create.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-create.adoc @@ -1,11 +1,28 @@ = rpk shadow create +:description: Create a Redpanda Shadow Link. This command creates a Shadow Link using a configuration file that defines the connection details and synchronization settings. +: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[] +Create a Redpanda Shadow Link. -Creates a Redpanda shadow link. +This command creates a Shadow Link using a configuration file that defines the +connection details and synchronization settings. -This command creates a shadow link using a configuration file that defines the connection details and synchronization settings. +Before you create a Shadow Link, generate a configuration file with `rpk shadow +config generate` and update it with your source cluster details. The command +prompts you to confirm the creation. Use the `--no-confirm` flag to skip the +confirmation prompt. -Before you create a shadow link, generate a configuration file with xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] and update it with your source cluster details. The command prompts you to confirm the creation. Use the `--no-confirm` flag to skip the confirmation prompt. +When creating a Shadow Link for Redpanda Cloud, make sure to login and select +the cluster where you want to create the Shadow Link before running this +command. See `rpk cloud login` and `rpk cloud select`. For SCRAM authentication, +store your password in the secrets store. See `rpk security secret --help` for +more details. + +After you create the Shadow Link, use `rpk shadow status` to monitor the +replication progress. ifdef::env-cloud[] When creating a shadow link in Redpanda Cloud, use the `--for-cloud` flag. @@ -13,6 +30,8 @@ When creating a shadow link in Redpanda Cloud, use the `--for-cloud` flag. First 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. endif::[] +Before you create a shadow link, generate a configuration file with xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] and update it with your source cluster details. + After you create the shadow link, use xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] to monitor the replication progress. == Usage @@ -22,16 +41,21 @@ After you create the shadow link, use xref:reference:rpk/rpk-shadow/rpk-shadow-s rpk shadow create [flags] ---- + + + == Examples -Create a shadow link using a configuration file: +This section provides examples of how to use `rpk shadow create`. + +Create a shadow link using a configuration file. [,bash] ---- rpk shadow create --config-file shadow-link.yaml ---- -Create a shadow link without a confirmation prompt: +Create a shadow link without a confirmation prompt. [,bash] ---- @@ -42,23 +66,23 @@ rpk shadow create -c shadow-link.yaml --no-confirm [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description |-c, --config-file |string |Path to configuration file to use for the shadow link; use `--help` for details. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|--no-confirm |- |Disable confirmation prompt. - -|-h, --help |- |Help for create. - -|--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 `~/.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-shadow/rpk-shadow-delete.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-delete.adoc index 4069a14e66..9a561301b9 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-delete.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-delete.adoc @@ -1,38 +1,53 @@ = rpk shadow delete -// tag::single-source[] +:description: Delete a Redpanda Shadow Link. This command deletes a Shadow Link by name. +: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 -Delete a Redpanda shadow link. +// tag::single-source[] +Delete a Redpanda Shadow Link. -This command deletes a shadow link by name. By default, you cannot delete a shadow link that has active shadow topics. Use xref:reference:rpk/rpk-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`] first to deactivate topics before deletion, or use the `--force` flag to delete the shadow link and failover all its active shadow topics. +This command deletes a Shadow Link by name. By default, you cannot delete a +Shadow Link that has active shadow topics. Use `rpk shadow failover` first to +deactivate topics before deletion, or use the `--force` flag to delete the Shadow +Link and failover all its active shadow topics. -The command prompts you to confirm the deletion. Use the `--no-confirm` flag to skip the confirmation prompt. The `--force` flag automatically disables the confirmation prompt. +The command prompts you to confirm the deletion. Use the `--no-confirm` flag to +skip the confirmation prompt. The `--force` flag automatically disables the +confirmation prompt. -WARNING: Deleting a shadow link with `--force` permanently removes all shadow topics and stops replication. This operation cannot be undone. +WARNING: Deleting a Shadow Link with `--force` permanently removes all shadow +topics and stops replication. This operation cannot be undone. == Usage [,bash] ---- -rpk shadow delete [LINK_NAME] [flags] +rpk shadow delete [flags] ---- + + + == Examples -Delete a shadow link: +This section provides examples of how to use `rpk shadow delete`. + +Delete a shadow link. [,bash] ---- rpk shadow delete my-shadow-link ---- -Delete a shadow link without confirmation: +Delete a shadow link without confirmation. [,bash] ---- rpk shadow delete my-shadow-link --no-confirm ---- -Force delete a shadow link with active shadow topics: +Force delete a shadow link with active shadow topics. [,bash] ---- @@ -43,23 +58,28 @@ rpk shadow delete my-shadow-link --force [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|-f, --force |- |If set, forces a delete while there are active shadow topics; disables confirmation prompts as well. - -|--no-confirm |- |Disable confirmation prompt. +|-f, --force |bool |If set, forces a delete while there are active shadow topics; disables confirmation prompt as well. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|-h, --help |- |Help for delete. +== 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 `~/.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-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`] // end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adoc index c2bd0e4462..6efb771901 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adoc @@ -1,13 +1,11 @@ = rpk shadow describe -// tag::single-source[] - -Describes a Redpanda shadow link. +:description: pass:q[Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to.] +:page-platforms: linux,darwin -This command shows the shadow link configuration, including connection settings, synchronization options, and filters. Use the flags to display specific sections or all sections of the configuration. +// 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, the command displays the overview and client configuration sections. Use the flags to display additional sections such as topic synchronization, consumer offset synchronization, and security synchronization settings. - -Using the `--format` flag with JSON or YAML will output the full configuration in the specified format, ignoring section flags. +// tag::single-source[] +Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to. ifdef::env-cloud[] 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. @@ -17,79 +15,71 @@ endif::[] [,bash] ---- -rpk shadow describe [LINK_NAME] [flags] +rpk shadow describe [flags] ---- + + + == Examples -Describe a shadow link with default sections (overview and client): +This section provides examples of how to use `rpk shadow describe`. + +Describe a shadow link with default sections (overview and client). [,bash] ---- rpk shadow describe my-shadow-link ---- -Display all configuration sections: +Display all configuration sections. [,bash] ---- rpk shadow describe my-shadow-link --print-all ---- -Display specific sections: +Display specific sections. [,bash] ---- rpk shadow describe my-shadow-link --print-overview --print-topic ---- -Display only the client configuration: +Display only the client configuration. [,bash] ---- rpk shadow describe my-shadow-link -c ---- -Display output as JSON: - -[,bash] ----- -rpk shadow describe my-shadow-link --format json ----- - == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|-a, --print-all |- |Print all sections. - -|-c, --print-client |- |Print the client configuration section. - -|-r, --print-consumer |- |Print the detailed consumer offset configuration section. - -|-o, --print-overview |- |Print the overview section. - -|-y, --print-registry |- |Print the detailed schema registry configuration section. - -|-s, --print-security |- |Print the detailed security configuration section. - -|-t, --print-topic |- |Print the detailed topic configuration section. - -|-h, --help |- |Help for describe. - -|--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 + +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-a, --print-all |bool |Print all sections. +|-c, --print-client |bool |Print the client configuration section. +|-r, --print-consumer |bool |Print the detailed consumer offset configuration section. +|-o, --print-overview |bool |Print the overview section. +|-y, --print-registry |bool |Print the detailed schema registry configuration section. +|-s, --print-security |bool |Print the detailed security configuration section. +|-t, --print-topic |bool |Print the detailed topic configuration section. +|=== -|--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 `~/.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-shadow/rpk-shadow-failover.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-failover.adoc index 4fb5f09ce9..be3d0be03d 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-failover.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-failover.adoc @@ -1,40 +1,57 @@ = rpk shadow failover -// tag::single-source[] +:description: Failover a Redpanda Shadow Link. This command performs a failover operation for a Shadow Link. +: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 -Failover a Redpanda shadow link. +// tag::single-source[] +Failover a Redpanda Shadow Link. -Failover converts shadow topics into regular topics on the shadow cluster, allowing producers and consumers to interact with them directly. After failover, the shadow link stops replicating data from the source cluster. +This command performs a failover operation for a Shadow Link. Failover converts +shadow topics into regular topics on the shadow cluster, allowing producers +and consumers to interact with them directly. After failover, the Shadow Link +stops replicating data from the source cluster. -Use the `--all` flag to failover all shadow topics associated with the shadow link, or use the `--topic` flag to failover a specific topic. You must specify either `--all` or `--topic`. +Use the `--all` flag to failover all shadow topics associated with the Shadow +Link, or use the `--topic` flag to failover a specific topic. You must specify +either `--all` or `--topic`. -The command prompts you to confirm the failover operation. Use the `--no-confirm` flag to skip the confirmation prompt. +The command prompts you to confirm the failover operation. Use the `--no-confirm` +flag to skip the confirmation prompt. -WARNING: Failover is a critical operation. After failover, shadow topics become regular topics and replication stops. Ensure your applications are ready to connect to the shadow cluster before performing a failover. +WARNING: Failover is a critical operation. After failover, shadow topics become +regular topics and replication stops. Ensure your applications are ready to +connect to the shadow cluster before performing a failover. == Usage [,bash] ---- -rpk shadow failover [LINK_NAME] [flags] +rpk shadow failover [flags] ---- + + + == Examples -Failover all topics for a shadow link: +This section provides examples of how to use `rpk shadow failover`. + +Failover all topics for a shadow link. [,bash] ---- rpk shadow failover my-shadow-link --all ---- -Failover a specific topic: +Failover a specific topic. [,bash] ---- rpk shadow failover my-shadow-link --topic my-topic ---- -Failover without confirmation: +Failover without confirmation. [,bash] ---- @@ -45,25 +62,24 @@ rpk shadow failover my-shadow-link --all --no-confirm [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--all |- |Failover all shadow topics associated with the shadow link. +|Value |Type |Description -|--no-confirm |- |Disable confirmation prompt. - -|--topic |string |Specific topic to failover. If `--all` is not set, at least one topic must be provided. - -|-h, --help |- |Help for failover. - -|--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. +|--all |bool |Failover all shadow topics associated with the Shadow Link. +|--no-confirm |bool |Disable confirmation prompt. +|--topic |string |Specific topic to failover. If `--all` is not set, at least a topic must be provided. +|=== -|--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 `~/.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-shadow/rpk-shadow-list.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-list.adoc index 88833b3954..17497f5d9e 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-list.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-list.adoc @@ -1,9 +1,15 @@ = rpk shadow list -// tag::single-source[] +:description: List Redpanda Shadow Links. This command lists all Shadow Links on the shadow cluster, showing their names, unique identifiers, and current states. +: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 -Lists Redpanda shadow links. +// tag::single-source[] +List Redpanda Shadow Links. -This command lists all shadow links on the shadow cluster, showing their names, unique identifiers, and current states. Use this command to get an overview of all configured shadow links and their operational status. +This command lists all Shadow Links on the shadow cluster, showing their +names, unique identifiers, and current states. Use this command to get an +overview of all configured Shadow Links and their operational status. == Usage @@ -12,25 +18,39 @@ This command lists all shadow links on the shadow cluster, showing their names, rpk shadow list [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. -|-h, --help |- |Help for list. +== Examples + +This section provides examples of how to use `rpk shadow list`. + +List all Shadow Links: +[,bash] +---- +rpk shadow list +---- + +== 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. +|--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 `~/.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-shadow/rpk-shadow-status.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-status.adoc index dfb95e7bc2..b6f8ffaede 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-status.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-status.adoc @@ -1,29 +1,34 @@ = rpk shadow status -// tag::single-source[] - -Shows the status of a Redpanda shadow link. +:description: pass:q[Display the status of a shadow link. When using `--format json` or `--format yaml`, the command outputs all sections by default.] +:page-platforms: linux,darwin -This command shows the current status of a shadow link, including the overall state, task statuses, and per-topic replication progress. Use this command to monitor replication health and track how closely shadow topics follow the source cluster. +// 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, the command displays all status sections. Use the `--print-*` flags to select specific sections (overview, task status, or topic status). The `--format json|yaml` flag changes only the output format, not which sections are included. +// tag::single-source[] +Display the status of a shadow link. When using `--format json` or `--format yaml`, the command outputs all sections by default. == Usage [,bash] ---- -rpk shadow status [LINK_NAME] [flags] +rpk shadow status [flags] ---- + + + == Examples -Display the status of a shadow link: +This section provides examples of how to use `rpk shadow status`. + +Display the status of a shadow link. [,bash] ---- rpk shadow status my-shadow-link ---- -Display specific sections: +Display specific sections. [,bash] ---- @@ -34,29 +39,26 @@ rpk shadow status my-shadow-link --print-overview --print-topic [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-a, --print-all |- |Print all sections. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|Value |Type |Description -|-o, --print-overview |- |Print the overview section. - -|-k, --print-task |- |Print the task status section. - -|-t, --print-topic |- |Print the detailed topic status section. - -|-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. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-a, --print-all |bool |Print all sections. +|-o, --print-overview |bool |Print the overview section. +|-k, --print-task |bool |Print the task status section. +|-t, --print-topic |bool |Print the detailed topic status section. +|=== -|--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 `~/.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-shadow/rpk-shadow-update.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-update.adoc index c1cbb602a3..274088d758 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-update.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow-update.adoc @@ -1,47 +1,55 @@ = rpk shadow update -// tag::single-source[] +:description: Update a Shadow Link. This command opens your default editor with the current Shadow Link configuration. +: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 -Updates a shadow link. +// tag::single-source[] +Update a Shadow Link. -This command opens your default editor with the current shadow link configuration, and allows you to update the fields you want to change, save the file, and close the editor. The command applies only the changed fields to the shadow link. +This command opens your default editor with the current Shadow Link +configuration. Update the fields you want to change, save the file, and close +the editor. The command applies only the changed fields to the Shadow Link. -You cannot change the shadow link name. If you need to rename a shadow link, delete it and create a new one with the desired name. +You cannot change the Shadow Link name. If you need to rename a Shadow Link, +delete it and create a new one with the desired name. -The editor respects your EDITOR environment variable. If EDITOR is not set, the command uses 'vi' on Unix-like systems. +The editor respects your EDITOR environment variable. If EDITOR is not set, the +command uses `vi` on Unix-like systems. == Usage [,bash] ---- -rpk shadow update [LINK_NAME] [flags] +rpk shadow update [flags] ---- + + + == Examples -Update a shadow link configuration: +This section provides examples of how to use `rpk shadow update`. + +Update a shadow link configuration. [,bash] ---- rpk shadow update my-shadow-link ---- -== Flags + +== Global flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for update. - -|--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 `~/.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-shadow/rpk-shadow.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc index d27e049d86..d8642e7922 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc @@ -1,36 +1,72 @@ = rpk shadow -:description: These commands let you manage shadow links for disaster recovery. -// tag::single-source[] +:description: Manage Redpanda Shadow Links. Shadowing is Redpanda's enterprise-grade disaster recovery solution that establishes asynchronous, offset-preserving replication between two distinct Redpanda clusters. +: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 -Manage Redpanda shadow links. +// tag::single-source[] +Manage Redpanda Shadow Links. -Shadowing is Redpanda's enterprise-grade disaster recovery solution that establishes asynchronous, offset-preserving replication between two distinct Redpanda clusters. A cluster is able to create a dedicated client that continuously replicates source cluster data, including offsets, timestamps, and cluster metadata. +Shadowing is Redpanda's enterprise-grade disaster recovery solution that +establishes asynchronous, offset-preserving replication between two distinct +Redpanda clusters. A cluster is able to create a dedicated client that +continuously replicates source cluster data, including offsets, timestamps, and +cluster metadata. == Usage [,bash] ---- -rpk shadow [command] [flags] +rpk shadow [flags] ---- -== Flags -[cols="1m,1a,2a"] + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-shadow/rpk-shadow-config.adoc[`rpk shadow config`] +|Generate a Redpanda Shadow Link configuration file. + +|xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`] +|Create a Redpanda Shadow Link. This command creates a Shadow Link using a configuration file that defines the connection details and synchronization settings. -|-h, --help |- |Help for shadow. +|xref:reference:rpk/rpk-shadow/rpk-shadow-delete.adoc[`rpk shadow delete`] +|Delete a Redpanda Shadow Link. This command deletes a Shadow Link by name. -|--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-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`] +|Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to. -|-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-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`] +|Failover a Redpanda Shadow Link. This command performs a failover operation for a Shadow Link. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] +|List Redpanda Shadow Links. This command lists all Shadow Links on the shadow cluster, showing their names, unique identifiers, and current states. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] +|Display the status of a shadow link. When using `--format json` or `--format yaml`, the command outputs all sections by default. + +|xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`] +|Update a Shadow Link. This command opens your default editor with the current Shadow Link configuration. + +|=== + + +== 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 `~/.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-topic/rpk-topic-add-partitions.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-add-partitions.adoc index 7152e7e824..e585c02aac 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-add-partitions.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-add-partitions.adoc @@ -1,6 +1,10 @@ = rpk topic add-partitions -// tag::single-source[] +:description: Add partitions to existing topics. +: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 partitions to existing topics. NOTE: Existing topic data is not redistributed to the newly-added partitions. @@ -9,31 +13,33 @@ NOTE: Existing topic data is not redistributed to the newly-added partitions. [,bash] ---- -rpk topic add-partitions [TOPICS...] --num [#] [flags] +rpk topic add-partitions --num [#] [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-f, --force |- |Force change the partition count in internal topics. -For example, the internal topic __consumer_offsets. - -|-h, --help |- |Help for add-partitions. +|Value |Type |Description +|-f, --force |bool |Force change the partition count in internal topics, for example, `__consumer_offsets`. |-n, --num |int |Number of partitions to add to each topic. +|=== -|--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 `~/.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-topic/rpk-topic-alter-config.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-alter-config.adoc index ec30dd2fbe..bce62d0d56 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-alter-config.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-alter-config.adoc @@ -1,6 +1,10 @@ = rpk topic alter-config -// tag::single-source[] +:description: Set, delete, add, and remove key/value configs for a topic. This command allows you to incrementally alter the configuration for multiple topics at a time. +: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[] Set, delete, add, and remove key/value configs for a topic. This command allows you to incrementally alter the configuration for multiple @@ -9,49 +13,49 @@ topics at a time. Incremental altering supports four operations: . Setting a key=value pair -. Deleting a key's value -. Appending a new value to a list-of-values key -. Subtracting (removing) an existing value from a list-of-values key + . Deleting a key's value + . Appending a new value to a list-of-values key + . Subtracting (`removing`) an existing value from a list-of-values key. The `--dry` option will validate whether the requested configuration change is valid, but does not apply it. +Use the flag `--no-confirm` to avoid the confirmation prompt. == Usage [,bash] ---- -rpk topic alter-config [TOPICS...] --set key=value --delete key2,key3 [flags] +rpk topic alter-config --set key=value --delete key2,key3 [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--append |stringArray |key=value; Value to append to a list-of-values -key (repeatable). - -|-d, --delete |stringArray |Key to delete (repeatable). -|--dry |- |Dry run: validate the alter request, but do not apply. -|-h, --help |- |Help for alter-config. -|-s, --set |stringArray |key=value; Pair to set (repeatable). - -|--subtract |stringArray |key=value; Value to remove from list-of-values -key (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 + +|--append |stringArray |key=value; Value to append to a list-of-values key (`repeatable`). +|-d, --delete |stringArray |Key to delete (`repeatable`). +|--dry |bool |Dry run: validate the alter request, but do not apply. +|--no-confirm |bool |Disable confirmation prompt. +|-s, --set |stringArray |key=value; Pair to set (`repeatable`). +|--subtract |stringArray |key=value; Value to remove from list-of-values key (`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 `~/.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-topic/rpk-topic-analyze.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-analyze.adoc index 1a69e63c7d..9664678253 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-analyze.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-analyze.adoc @@ -1,106 +1,132 @@ = rpk topic analyze -:description: rpk topic analyze -// tag::single-source[] +:description: Analyze topics. This command consumes records from the specified topics to determine topic characteristics such as batch rate and batch size. +: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[] Analyze topics. This command consumes records from the specified topics to determine -topic characteristics, such as batch rate and batch size. +topic characteristics such as batch rate and batch size. -Use the `--format` flag with either JSON or YAML to print all of the metadata collected. +To print all of the metadata collected, use the `--format` flag with either JSON or YAML. -== Specify topics +== Usage -List individual topics or use the `--regex` flag (`-r`) for filtering. +[,bash] +---- +rpk topic analyze [flags] +---- -For example, - analyze logins transactions # analyze topics logins and transactions - analyze -r '^l.*' '.*s$' # analyze all topics starting with l and all topics ending in s - analyze -r '*' # analyze all topics - analyze -r . # analyze any one-character topics +=== Topics -== Time range +Topics can either be listed individually or by regex via the `--regex` flag (`-r`). -Use the `--time-range` flag to specify the time range from which to consume records. Use the following format: +For example, - t1:t2 consume from timestamp t1 until timestamp t2 -There are a few options for the timestamp syntax. `rpk` evaluates each option -until one succeeds: +[cols="1m,1a"] +|=== +|Value |Description - 13 digits parsed as a Unix millisecond - 9 digits parsed as a Unix second - YYYY-MM-DD parsed as a day, UTC - YYYY-MM-DDTHH:MM:SSZ parsed as RFC3339, UTC; fractional seconds optional (.MMM) - end for t2 in @t1:t2, the current end of the partition - -dur a negative duration from now or from a timestamp - dur a positive duration from now or from a timestamp +|analyze foo bar |# analyze topics foo and bar +|analyze `-r` '^f.*' '.*r$' |# analyze all topics starting with f and all topics ending in r +|analyze `-r` '*' |# analyze all topics +|analyze `-r` . |# analyze any one-character topics +|=== -Durations can be relative to the current time or relative to a timestamp. -- If a duration is used for `t1`, that duration is relative to now. -- If a duration is used for `t2`, and `t1` is a timestamp, then `t2` is relative to `t1`. -- If a duration is used for `t2`, and `t1` is a duration, then `t2` is relative to now. +=== Time Range -Durations are parsed simply: +The `--time-range` flag specifies the time range to consume from. +Use the following format: - 3ms three milliseconds - 10s ten seconds - 9m nine minutes - 1h one hour - 1m3ms one minute and three milliseconds + t1:t2 consume from timestamp t1 until timestamp t2 -For example: +There are a few options for the timestamp syntax. `rpk` evaluates each option +until one succeeds: - -t 2022-02-14:1h consume 1h of time on Valentine's Day 2022 - -t -48h:-24h consume from 2 days ago to 1 day ago - -t -1m:end consume from 1m ago until now -== Usage +[cols="1m,1a"] +|=== +|Value |Description + +|13 digits |parsed as a Unix millisecond +|9 digits |parsed as a Unix second +|YYYY-MM-DD |parsed as a day, UTC +|YYYY-MM-DDTHH:MM:SSZ |parsed as RFC3339, UTC; fractional seconds optional (.MMM) +|end |for t2 in @t1:t2, the current end of the partition +|-dur |a negative duration from now or from a timestamp +|dur |a positive duration from now or from a timestamp +|=== -[,bash] ----- -rpk topic analyze [TOPIC] [flags] ----- -== Flags +Durations can be relative to the current time or relative to a timestamp. +If a duration is used for t1, that duration is relative to now. +If a duration is used for t2, and t1 is a timestamp, then t2 is relative to t1. +If a duration is used for t2, and t1 is a duration, then t2 is relative to now. -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* +Durations are parsed simply: -|--batches |int |Minimum number of batches to consume per partition (default `10`). -|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`) (default `text`). +[cols="1m,1a"] +|=== +|Value |Description -|-h, --help |- |Help for the analyze subcommand. +|3ms |three milliseconds +|10s |ten seconds +|9m |nine minutes +|1h |one hour +|1m3ms |one minute and three milliseconds +|=== -|-a, --print-all |- |Print all sections. -|--print-partition-batch-rate |- |Print the detailed partitions batch rate section. +For example, -|--print-partition-batch-size |- |Print the detailed partitions batch size section. -|-s, --print-summary |- |Print the summary section. +[cols="1m,1a"] +|=== +|Value |Description -|--print-topics |- |Print the topics section. +|`-t` 2022-02-14:1h |consume 1h of time on Valentine's Day 2022 +|`-t` -48h:-24h |consume from 2 days ago to 1 day ago +|`-t` -1m:end |consume from 1m ago until now +|=== -|-r, --regex |- |Parse arguments as regex. Analyze any topic that matches any input topic expression. -|-t, --time-range |string |Time range to consume from (`-24h:end`, `-48h:-24h`, `2022-02-14:1h`) (default `-1m:end`). -|--timeout |duration |Specifies how long the command should run before timing out (default `10s`). -|--config |string |Redpanda or rpk configuration 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. Use `-X help` for more details or `-X list` for terser detail. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--batches |int |Minimum number of batches to consume per partition. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-a, --print-all |bool |Print all sections. +|--print-partition-batch-rate |bool |Print the detailed partitions batch rate section. +|--print-partition-batch-size |bool |Print the detailed partitions batch size section. +|-s, --print-summary |bool |Print the summary section. +|--print-topics |bool |Print the topics section. +|-r, --regex |bool |Parse arguments as regex; analyze any topic that matches any input topic expression. +|-t, --time-range |string |Time range to consume from (-24h:end, -48h:-24h, 2022-02-14:1h). +|--timeout |duration |Maximum duration for the command to run before timing out. +|=== -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-topic/rpk-topic-consume.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc index 4060f2def1..390ef8f28b 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc @@ -1,23 +1,26 @@ = rpk topic consume -// tag::single-source[] +:description: pass:q[Consume records from topics. Consuming records reads from any amount of input topics, formats each record according to `--format`, and prints them to `STDOUT`.] +:page-platforms: linux,darwin -Consume records from topics. +// 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 -Consuming records reads from any amount of input topics, formats each record -according to `--format`, and prints them to `STDOUT`. The output formatter -understands a wide variety of formats. +// tag::single-source[] +Consume records from topics. Consuming records reads from any amount of input topics, formats each record according to `--format`, and prints them to `STDOUT`. -The default output format `--format json` is a special format that outputs each -record as JSON. +The output formatter understands a wide variety of formats. The default output format `--format json` is a special format that outputs each record as JSON. include::reference:partial$topic-format.adoc[] -== Attributes +== Usage + +[,bash] +---- +rpk topic consume TOPICS... [flags] +---- + +=== Attributes -Each record (or batch of records) has a set of possible attributes. Internally, -these are packed into bit flags. Printing an attribute requires first selecting -which attribute you want to print, and then optionally specifying how you want -it to be printed: +Each record (or batch of records) has a set of possible attributes. Internally, these are packed into bit flags. Printing an attribute requires first selecting which attribute you want to print, and then optionally specifying how you want it to be printed: [,bash] ---- @@ -27,9 +30,7 @@ it to be printed: %a{compression;hex8} ---- -Compression is by default printed as text (`none`, `gzip`, ...). Compression -can be printed as a number with `;number`, where number is any number -formatting option described above. No compression is `0`, gzip is `1`, etc. +Compression is by default printed as text (`none`, `gzip`, ...). Compression can be printed as a number with `;number`, where number is any number formatting option described above. No compression is `0`, gzip is `1`, etc. [,bash] ---- @@ -39,9 +40,9 @@ formatting option described above. No compression is `0`, gzip is `1`, etc. The record's timestamp type prints as: -* `-1` for very old records (before timestamps existed) -* `0` for client-generated timestamps -* `1` for broker-generated timestamps +* `-1` for very old records (before timestamps existed) +* `0` for client-generated timestamps +* `1` for broker-generated timestamps NOTE: Number formatting can be controlled with `;number`. @@ -61,208 +62,183 @@ Prints `1` if the record is a part of a transaction or `0` if it is not. Prints `1` if the record is a commit marker or `0` if it is not. -== Text +=== Text -Text fields without modifiers default to writing the raw bytes. Alternatively, -there are the following modifiers: +Text fields without modifiers default to writing the raw bytes. Alternatively, there are the following modifiers: -[cols=",",] +[cols="1m,2a"] |=== |Modifier |Description -|`%t\{hex}` |Hex encoding - -|`%k\{base64}` |Base64 standard encoding - -|`%k\{base64raw}` |Base64 encoding raw - -|`%v{unpack[iIqQc.$]}` |The unpack modifier has a further internal -specification, similar to timestamps above. +|%t\{hex} |Hex encoding +|%k\{base64} |Base64 standard encoding +|%k\{base64raw} |Base64 encoding raw +|%v{unpack[iIqQc.$]} |The unpack modifier has a further internal specification, similar to timestamps above. |=== -Unpacking 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. +Unpacking 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. -== Headers +=== Headers Headers are formatted with percent encoding inside of the modifier: -``` +[,bash] +---- %h{%k=%v{hex}} -``` +---- -This 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. +This 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. -== Values +=== Values Values for consumed records can be omitted by using the `--meta-only` flag. Tombstone 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. -== Offsets +=== Offsets -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. +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. -[cols=",",] +[cols="1m,2a"] |=== |Offset |Description -|`start` |Consume from the beginning -|`end` |Consume from the end -|`:end` |Consume until the current end -|`+oo` |Consume oo after the current start offset -|`-oo` |Consume oo before the current end offset -|`oo` |Consume after an exact offset -|`oo:` |Alias for oo -|`:oo` |Consume until an exact offset -|`o1:o2` |Consume from exact offset o1 until exact offset o2 -|`@t` |Consume starting from a given timestamp -|`@t:` |alias for @t -|`@:t` |Consume until a given timestamp -|`@t1:t2` |Consume from timestamp t1 until timestamp t2 +|start |Consume from the beginning +|end |Consume from the end +|:end |Consume until the current end +|+oo |Consume oo after the current start offset +|-oo |Consume oo before the current end offset +|oo |Consume after an exact offset +|oo: |Alias for oo +|:oo |Consume until an exact offset +|o1:o2 |Consume from exact offset o1 until exact offset o2 +|@t |Consume starting from a given timestamp +|@t: |Alias for @t +|@:t |Consume until a given timestamp +|@t1:t2 |Consume from timestamp t1 until timestamp t2 |=== Each timestamp option is evaluated until one succeeds. -[cols=",",] +[cols="1m,2a"] |=== |Timestamp |Description |13 digits |Parsed as a unix millisecond - |9 digits |Parsed as a unix second - |YYYY-MM-DD |Parsed as a day, UTC - -|YYYY-MM-DDTHH:MM:SSZ |Parsed as RFC3339, UTC; fractional seconds -optional (.MMM) - +|YYYY-MM-DDTHH:MM:SSZ |Parsed as RFC3339, UTC; fractional seconds optional (.MMM) |-dur |Duration; from now (as t1) or from t1 (as t2) - |dur |For t2 in @t1:t2, relative duration from t1 - |end |For t2 in @t1:t2, the current end of the partition |=== Durations are parsed simply: -``` +[,bash] +---- 3ms three milliseconds 10s ten seconds 9m nine minutes 1h one hour 1m3ms one minute and three milliseconds -``` - -For example: - -``` --o @2022-02-14:1h consume 1h of time on Valentine's Day 2022 --o @-48h:-24h consume from 2 days ago to 1 day ago --o @-1m:end consume from 1m ago until now --o @:-1hr consume from the start until an hour ago -``` - -== Examples +---- -A key and value, separated by a space and ending in newline: -``` --f '%k %v\n' -``` -A key length as four big endian bytes and the key as hex: -``` --f '%K{big32}%k{hex}' -``` +== Examples -A little endian uint32 and a string unpacked from a value: +This section provides examples of how to use `rpk topic consume`. -``` --f '%v{unpack[is$]}' -``` +=== Format examples -== Usage +A key and value, separated by a space and ending in newline [,bash] ---- -rpk topic consume TOPICS... [flags] +rpk topic consume my-topic -f '%k %v\n' ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-b, --balancer |string |Group balancer to use if group consuming -(range, roundrobin, sticky, cooperative-sticky) (default -"cooperative-sticky"). - -|--fetch-max-bytes |int32 |Maximum amount of bytes per fetch request per -broker (default 1048576). - -|--fetch-max-wait |duration |Maximum amount of time to wait when -fetching from a broker before the broker replies (default 5s). - -|-f, --format |string |Output format (see --help for details) (default -"json"). - -|-g, --group |string |Group to use for consuming (incompatible with -p). - -|-h, --help |- |Help for consume. - -|--meta-only |- |Print all record info except the record value (for -f -json). +A key length as four big endian bytes and the key as hex -|-n, --num |int |Quit after consuming this number of records (0 is -unbounded). +[,bash] +---- +rpk topic consume my-topic -f '%K{big32}%k{hex}' +---- -|-o, --offset |string |Offset to consume from / to (start, end, 47, +2, --3) (default "start"). +A little endian uint32 and a string unpacked from a value -|-p, --partitions |int32 |int32Slice Comma delimited list of specific -partitions to consume (default []). +[,bash] +---- +rpk topic consume my-topic -f '%v{unpack[is$]}' +---- -|--pretty-print |- |Pretty print each record over multiple lines (for -f -json) (default true). +=== Offset examples -|--print-control-records |- |Opt in to printing control records. +Consume 1 hour of data on Valentine's Day 2022 -|--rack |string |Rack to use for consuming, which opts into follower -fetching. +[,bash] +---- +rpk topic consume my-topic -o @2022-02-14:1h +---- -|--read-committed |- |Opt in to reading only committed offsets. +Consume from 2 days ago to 1 day ago -|-r, --regex |- |Parse topics as regex; consume any topic that matches -any expression. +[,bash] +---- +rpk topic consume my-topic -o @-48h:-24h +---- -|--use-schema-registry |strings |[=key,value] If present, `rpk` will decode the key and the value with the schema registry. Also accepts `use-schema-registry=key` or `use-schema-registry=value`. +Consume from 1 minute ago until now -|--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`. +[,bash] +---- +rpk topic consume my-topic -o @-1m:end +---- -|-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. +Consume from the start until an hour ago -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[,bash] +---- +rpk topic consume my-topic -o @:-1hr +---- -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +== Flags -|-v, --verbose |- |Enable verbose logging. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|-b, --balancer |string |Group balancer to use when consuming with a consumer group (`range`, `roundrobin`, `sticky`, `cooperative-sticky`). +|--fetch-max-bytes |int32 |Maximum number of bytes per fetch request per broker. +|--fetch-max-partition-bytes |int32 |Maximum number of bytes to fetch for a single partition per fetch request. +|--fetch-max-wait |duration |Maximum amount of time to wait when fetching from a broker before the broker replies. +|-f, --format |string |Output format (see `--help` for details). +|-g, --group |string |Group to use for consuming (incompatible with `-p`). +|--meta-only |bool |Print all record info except the record value (for `-f json`). +|-n, --num |int |Quit after consuming this number of records (0 is unbounded). +|-o, --offset |string |Offset to consume from / to (`start`, end, 47, +2, -3). +|-p, --partitions |int32Slice |Comma delimited list of specific partitions to consume. +|--pretty-print |bool |Pretty print each record over multiple lines (for `-f json`). +|--print-control-records |bool |Opt in to printing control records. +|--rack |string |Rack to use for consuming, which opts into follower fetching. +|--read-committed |bool |Opt in to reading only committed offsets. +|-r, --regex |bool |Parse topics as regex; consume any topic that matches any expression. +|--use-schema-registry |stringSlice |Decode record keys and values using schemas from the schema registry. Use `=key` or `=value` to decode only the key or value. |=== -== Connection behavior +== Global flags -By default, `rpk topic consume` runs continuously, waiting for new records to arrive. It does not exit after consuming existing records. To stop consuming, press kbd:[Ctrl+C]. You can also use `--num` to exit after a fixed number of records, or use `--offset` (for example, `-o :end`) to stop at a specific offset. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -Records are formatted according to `--format`. The default, `--format json`, prints each record as a JSON object. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-topic/rpk-topic-create.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc index 0a78810884..2bc6221cfe 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc @@ -1,78 +1,47 @@ = rpk topic create -// tag::single-source[] +:description: Create one or more Kafka topics with configurable partitions, replication factor, and topic-level settings. +: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 -Create topics. +// tag::single-source[] +Create one or more Kafka topics with configurable partitions, replication factor, and topic-level settings. -Topics created with this command will have the same number of partitions, -replication factor, and key/value configs. +[IMPORTANT] +==== +include::shared:partial$tristate-behavior-change-25-3.adoc[] +==== ifndef::env-cloud[] For more information about topics, see xref:reference:rpk/rpk-topic/rpk-topic-describe.adoc[`rpk topic describe`]. - endif::[] == Usage [,bash] ---- -rpk topic create [TOPICS...] [flags] +rpk topic create [flags] ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|-d, --dry |- |Dry run: validate the topic creation request; do not -create topics. - -|-h, --help |- |Help for create. - -|--if-not-exists |- |Only create the topic if it does not already exist. -|-p, --partitions |int32 |Number of partitions to create per topic; `-1` -defaults to the cluster property `default_topic_partitions` (default `-1`). -|-r, --replicas |int16 |Replication factor (must be odd); -1 defaults to -the cluster's default_topic_replications (default -1). In Redpanda Cloud, the replication factor is set to 3. - -|-c, --topic-config |string (repeatable) |Topic properties can be set by using `=`. For example `-c cleanup.policy=compact`. This flag is repeatable, so you can set multiple parameters in a single command. - -|--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. -|=== - -ifndef::env-cloud[] -NOTE: For the full list of properties, see xref:reference:topic-properties.adoc[Topic Properties] - -endif::[] - -[IMPORTANT] -==== -include::shared:partial$tristate-behavior-change-25-3.adoc[] -==== == Examples +This section provides examples of how to use `rpk topic create`. + === Create a topic -Create a topic named `my-topic`: +Create a topic named `my-topic` [,bash] ---- rpk topic create my-topic ---- -Output: -[,bash] +Output: + +[.no-wrap,bash] ---- TOPIC STATUS my-topic OK @@ -80,7 +49,7 @@ my-topic OK === Create multiple topics -Create two topics (`my-topic-1`, `my-topic-2`) at the same time with one command: +Create two topics (`my-topic-1`, `my-topic-2`) at the same time with one command [,bash] ---- @@ -89,7 +58,7 @@ rpk topic create my-topic-1 my-topic-2 Output: -[,bash] +[.no-wrap,bash] ---- TOPIC STATUS my-topic-1 OK @@ -98,7 +67,7 @@ my-topic-2 OK === Set a topic property -Create topic `my-topic-3` with the topic property `cleanup.policy=compact`: +Create topic `my-topic-3` with the topic property `cleanup.policy=compact` [,bash] ---- @@ -107,7 +76,7 @@ rpk topic create my-topic-3 -c cleanup.policy=compact Output: -[,bash] +[.no-wrap,bash] ---- TOPIC STATUS my-topic-3 OK @@ -115,7 +84,7 @@ my-topic-3 OK === Create topic with multiple partitions -Create topic `my-topic-4` with 20 partitions: +Create topic `my-topic-4` with 20 partitions [,bash] ---- @@ -124,7 +93,7 @@ rpk topic create my-topic-4 -p 20 Output: -[,bash] +[.no-wrap,bash] ---- TOPIC STATUS my-topic-4 OK @@ -134,7 +103,7 @@ my-topic-4 OK IMPORTANT: The replication factor must be a positive, odd number (such as 3), and it must be equal to or less than the number of available brokers. -Create topic `my-topic-5` with 3 replicas: +Create topic `my-topic-5` with 3 replicas [,bash] ---- @@ -143,7 +112,7 @@ rpk topic create my-topic-5 -r 3 Output: -[,bash] +[.no-wrap,bash] ---- TOPIC STATUS my-topic-5 OK @@ -151,7 +120,7 @@ my-topic-5 OK === Combine flags -You can combine flags in any way you want. This example creates two topics, `topic-1` and `topic-2`, each with 20 partitions, 3 replicas, and the cleanup policy set to compact: +You can combine flags in any way you want. This example creates two topics, `topic-1` and `topic-2`, each with 20 partitions, 3 replicas, and the cleanup policy set to compact [,bash] ---- @@ -160,11 +129,41 @@ rpk topic create -c cleanup.policy=compact -r 3 -p 20 topic-1 topic-2 Output: -[,bash] +[.no-wrap,bash] ---- -TOPIC STATUS +TOPIC STATUS topic-1 OK topic-2 OK ---- -// end::single-source[] \ No newline at end of file +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|-d, --dry |bool |Validate the topic creation request without actually creating the topic. Useful for testing configuration. +|--if-not-exists |bool |Only create the topic if it does not already exist. +|-p, --partitions |int32 |Number of partitions for the topic. More partitions enable higher parallelism but increase resource usage. Default is 1. +|-r, --replicas |int16 |Replication factor (must be odd); -1 defaults to the cluster's default_topic_replications. +|-c, --topic-config |stringArray |Topic configuration properties in the format `key=value`. Can be specified multiple times. Example: `--topic-config retention.ms=86400000`. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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[] +NOTE: For the full list of properties, see xref:reference:topic-properties.adoc[Topic Properties] +endif::[] + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-topic/rpk-topic-delete.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-delete.adoc index b193b10af0..d71fd2f22e 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-delete.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-delete.adoc @@ -1,72 +1,71 @@ = rpk topic delete +:description: Delete one or more Kafka topics. This operation is irreversible and removes all data in the topics. +: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[] +Delete one or more Kafka topics. This operation is irreversible and removes all data in the topics. -Delete topics. +== Usage + +[,bash] +---- +rpk topic delete [flags] +---- -This command deletes all requested topics, printing the success or fail status -per topic. -The `--regex` or `-r` flag opts into parsing the input topics as regular expressions -and deleting 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 (which also prevents accidental delete-everything mistakes). -The topic list command accepts the same input regex format as this delete -command. If you want to check what your regular expressions will delete before -actually deleting them, you can check the output of `rpk topic list -r`. == Examples -Deletes topics foo and bar: +This section provides examples of how to use `rpk topic delete`. -[,bash] ----- -rpk topic delete foo bar ----- +=== Delete specific topics -Deletes any topic starting with `f` and any topics ending in `r`: +Delete topics `foo` and `bar` [,bash] ---- -rpk topic delete -r '^f.*' '.*r$' +rpk topic delete foo bar ---- -Deletes all topics: +=== Delete with regex + +Delete topics starting with 'f' or ending in 'r' [,bash] ---- -rpk topic delete -r '.*' +rpk topic delete -r '^f.*' '.*r$' ---- -Deletes any one-character topics: - -== Usage +Delete all topics (use with caution) [,bash] ---- -rpk topic delete [TOPICS...] [flags] +rpk topic delete -r '.*' ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for delete. - -|-r, --regex |- |Parse topics as regex; delete any topic that matches -any input topic expression. +|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. +|-r, --regex |bool |Treat topic names as regular expressions and delete all matching topics. Use with caution. +|=== -|--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 `~/.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-topic/rpk-topic-describe-storage.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe-storage.adoc index bb1dcf643b..a0b5954191 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe-storage.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe-storage.adoc @@ -1,73 +1,79 @@ = rpk topic describe-storage +:description: Describe the cloud storage status of a topic, including storage mode, offset availability, segment sizes, and synchronization state. +:page-platforms: linux,darwin -Describe the topic storage status. +// 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 commands prints detailed information about the cloud storage status of a -given topic. The information is divided into four sections: +// tag::single-source[] +Describe the cloud storage status of a topic, including storage mode, offset availability, segment sizes, and synchronization state. + +== Usage + +[,bash] +---- +rpk topic describe-storage [flags] +---- + + +=== Summary -* *Summary* -+ The summary section contains general information about the topic, the cloud -storage mode (one of disabled, write_only, read_only, full, and read_replica), +storage mode (one of disabled, write_only, read_only, full, read_replica, +cloud_topic, and cloud_topic_read_replica), and the delta in milliseconds since the last upload of either the partition manifest or a segment. -* *Offset* -+ -The offset section contains the start and last offsets (inclusive) per +=== Offset + +The offset section contains the start and last offsets (`inclusive`) per partition of data available in both the cloud and on local disk. -* *Size* -+ -The size section contains the total bytes per partition in the cloud and on -local disk, the total size of the log of each partition (excluding cloud and -local overlap), and the number of segments in the cloud and on local disk. The -cloud segment count does not include segments queued for deletion. +=== Size + +For tiered storage topics, the size section contains the total bytes per +partition in the cloud and on local disk, the total size of the log of each +partition (excluding cloud and local overlap), and the number of segments in +the cloud and on local disk. The cloud segment count does not include segments +queued for deletion. + +For cloud topics, the size section shows the L0 (level zero) and L1 (level +one) byte breakdown, the total bytes, and the number of L1 extents. + +=== Sync -* *Sync* -+ The sync section contains the state of cloud synchronization: milliseconds since the last upload of the partition manifest, milliseconds since the last segment upload, milliseconds since the last manifest sync (for read replicas), and whether the remote metadata has a pending update to include all uploaded segments. -== Usage -[,bash] ----- -rpk topic describe-storage [TOPIC] [flags] ----- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for describe-storage. - -|-H, --human-readable |- |Print the times and bytes in a human-readable -form. - -|-a, --print-all |- |Print all cloud storage status. - -|-o, --print-offset |- |Print the offset section. - -|-z, --print-size |- |Print the log size section. - -|-s, --print-summary |- |Print the summary section. - -|-y, --print-sync |- |Print the sync section. - -|--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 + +|-H, --human-readable |bool |Print times (in milliseconds) and byte values in human-readable units (for example, 1.2 GiB, 3m 20s). +|-a, --print-all |bool |Print all cloud storage status. +|-o, --print-offset |bool |Print the offset section. +|-z, --print-size |bool |Print the log size section. +|-s, --print-summary |bool |Print the summary section. +|-y, --print-sync |bool |Print the sync section. +|=== -|--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 `~/.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-topic/rpk-topic-describe.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe.adoc index eb222a01fe..6a4d3bec47 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-describe.adoc @@ -1,8 +1,11 @@ = rpk topic describe -// tag::single-source[] +:description: Print detailed information about topics. There are three potential views: a summary of the topic, the topic configurations, and a detailed partitions section. +: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 -This command prints 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. +// tag::single-source[] +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. Using the `--format` flag with either JSON or YAML prints all the topic information. @@ -12,48 +15,44 @@ The `--regex` flag (`-r`) parses arguments as regular expressions and describes [,bash] ---- -rpk topic describe [TOPICS] [flags] +rpk topic describe [flags] ---- + + == Aliases [,bash] ---- -describe, info +rpk topic info ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for describe. - -|-a, --print-all |- |Print all sections. - -|-c, --print-configs |- |Print the config section. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. - -|-p, --print-partitions |- |Print the detailed partitions section. - -|-s, --print-summary |- |Print the summary section. - -|-r, --regex |- |Parse arguments as regex; describe any topic that matches any input topic expression. - -|--stable |- |Include the stable offsets column in the partitions -section; only relevant if you produce to this topic transactionally. - -|--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 + +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-a, --print-all |bool |Print all topic configuration properties, including defaults and read-only values. +|-c, --print-configs |bool |Print the config section. +|-p, --print-partitions |bool |Print the detailed partitions section. +|-s, --print-summary |bool |Print the summary section. +|-r, --regex |bool |Parse arguments as regex; describe any topic that matches any input topic expression. +|--stable |bool |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. +|=== -|--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 `~/.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-topic/rpk-topic-list.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-list.adoc index 26f85bbbe9..27ef391dfd 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-list.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-list.adoc @@ -1,23 +1,19 @@ = rpk topic list -// tag::single-source[] +:description: List topics, optionally listing specific topics. This command lists all topics that you have access to by default. +: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 -List topics, optionally listing specific topics. +// tag::single-source[] +List topics, optionally listing specific topics. This command lists all topics that you have access to by default. -This command lists all topics that you have access to by default. 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. +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. -Alternatively, 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. +Alternatively, 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. -The `--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. Regular expressions cannot be used to match internal topics, -as such, specifying both `-i` and `-r` will exit with failure. +The `--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. -Lastly, `--detailed` or `-d` flag opts in to printing extra per-partition information. +NOTE: Regular expressions cannot be used to match internal topics. Specifying both `-i` and `-r` will exit with failure. == Usage @@ -26,39 +22,38 @@ Lastly, `--detailed` or `-d` flag opts in to printing extra per-partition inform rpk topic list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk topic ls ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-d, --detailed |- |Print per-partition information for topics. - -|--format |string |Output format. Possible values: `json`, `yaml`, `text`, `wide`, `help`. Default: `text`. +|Value |Type |Description -|-h, --help |- |Help for list. - -|-i, --internal |- |Print internal topics. - -|-r, --regex |- |Parse topics as regex; list any topic that matches any -input topic expression. - -|--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. +|-d, --detailed |bool |Print per-partition information for topics. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). +|-i, --internal |bool |Include internal topics (those starting with `__`) in the output. +|-r, --regex |bool |Filter topics using regular expressions. Expressions are automatically anchored with `^` and `$`, so they must match the full topic name. +|=== -|--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 `~/.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-topic/rpk-topic-produce.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc index e761b643e8..78cfd4d0d7 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc @@ -1,26 +1,28 @@ = rpk topic produce -// tag::single-source[] +:description: pass:q[Produce records to a topic. Producing records reads from `STDIN`, parses input according to `--format`, and produces records to Redpanda.] +:page-platforms: linux,darwin -Produce records to a topic. +// 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 -Producing records reads from `STDIN`, parses input according to `--format`, and -produce records to Redpanda. The input formatter understands a wide variety of -formats. +// tag::single-source[] +Produce records to a topic. Producing records reads from `STDIN`, parses input according to `--format`, and produces records to Redpanda. -Parsing input operates on either sizes or on delimiters, both of which can be -specified in the same formatting options. If using sizes to specify something, -the size must come before what it is specifying. Delimiters match on an exact -text basis. This command will quit with an error if any input fails to match -your specified format. +The input formatter understands a wide variety of formats. Parsing input operates on either sizes or on delimiters, both of which can be specified in the same formatting options. include::reference:partial$topic-format.adoc[] +== Usage + +[,bash] +---- +rpk topic produce [flags] +---- -== Schema registry +=== Schema registry -Records can be encoded using a specified schema from our schema registry. Use the `--schema-id` or `--schema-key-id` flags to define the schema ID, `rpk` will retrieve the schemas and encode the record accordingly. +Records can be encoded using a specified schema from your schema registry. Use the `--schema-id` or `--schema-key-id` flags to define the schema ID, and `rpk` will retrieve the schemas and encode the record accordingly. -Additionally, utilizing `topic` in the mentioned flags allows for the use of the Topic Name Strategy. This strategy identifies a schema subject name based on the topic itself. For example: +Additionally, using `topic` in these flags allows for the use of the Topic Name Strategy. This strategy identifies a schema subject name based on the topic itself. For example: Produce to `foo`, encode using the latest schema in the subject `foo-value`: @@ -29,133 +31,128 @@ Produce to `foo`, encode using the latest schema in the subject `foo-value`: rpk topic produce foo --schema-id=topic ---- +For protobuf schemas, you can specify the fully qualified name of the message you want the record to be encoded with. Use the `--schema-type` flag or `--schema-key-type`. If the schema contains only one message, specifying the message name is unnecessary. For example: -For protobuf schemas, you can specify the fully qualified name of the message you want the record to be encoded with. Use the `schema-type` flag or `schema-key-type`. If the schema contains only one message, specifying the message name is unnecessary. For example: - -Produce to `foo`, using schema ID 1, message FQN Person.Name: +Produce to `foo`, using schema ID 1, message FQN `Person.Name`: [,bash] ---- rpk topic produce foo --schema-id 1 --schema-type Person.Name ---- -== Tombstones +=== Tombstones By default, records produced without a value will have an empty-string value, `""`. The below example produces a record with the key `not_a_tombstone_record` and the value `""`: -```bash +[,bash] +---- rpk topic produce foo -k not_a_tombstone_record [Enter] -``` - +---- + Tombstone records (records with a `null` value) can be produced by using the `-Z` flag and creating empty-string value records. Using the same example from above, but adding the `-Z` flag will produce a record with the key `tombstone_record` and the value `null`: -```bash -rpk topic produce foo -k tombstone_record -Z +[,bash] +---- +rpk topic produce foo -k tombstone_record -Z [Enter] -``` +---- -It is important to note that records produced with values of string `"null"` are not considered tombstones by Redpanda. +Records produced with values of string `"null"` are not considered tombstones by Redpanda. -== Examples +=== Miscellaneous -In the below examples, we can parse many records at once. The produce command -reads input and tokenizes based on your specified format. Every time the format -is completely matched, a record is produced and parsing begins anew. - -* A key and value, separated by a space and ending in newline: -`-f '%k %v\n'` -* A four byte topic, four byte key, and four byte value: -`+-f '%T{4}%K{4}%V{4}%t%k%v'+` -* A value to a specific partition, if using a non-negative --partition flag: -`-f '%p %v\n'` -* A big-endian uint16 key size, the text " foo ", and then that key: -`+-f '%K{big16} foo %k'+` -* A value that can be two or three characters followed by a newline: -`+-f '%v{re#...?#}\n'+` -* A key and a json value, separated by a space: -`+-f '%k %v{json}'+` - -== Miscellaneous - -Producing requires a topic to produce to. The topic can be specified either -directly on as an argument, or in the input text through %t. A parsed topic -takes precedence over the default passed in topic. If no topic is specified -directly and no topic is parsed, this command will quit with an error. - -The input format can parse partitions to produce directly to with %p. Doing so -requires specifying a non-negative --partition flag. Any parsed partition -takes precedence over the --partition flag; specifying the flag is the main -requirement for being able to directly control which partition to produce to. - -You can also specify an output format to write when a record is produced -successfully. The output format follows the same formatting rules as the topic -consume command. See that command's help text for a detailed description. +Producing requires a topic to produce to. The topic can be specified either directly as an argument, or in the input text through `%t`. A parsed topic takes precedence over the default passed in topic. If no topic is specified directly and no topic is parsed, this command will quit with an error. -== Usage +The input format can parse partitions to produce directly to with `%p`. Doing so requires specifying a non-negative `--partition` flag. Any parsed partition takes precedence over the `--partition` flag; specifying the flag is the main requirement for being able to directly control which partition to produce to. -[,bash] ----- -rpk topic produce [TOPIC] [flags] ----- +You can also specify an output format to write when a record is produced successfully. The output format follows the same formatting rules as the topic consume command. See that command's help text for a detailed description. -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|--acks |int |Number of acks required for producing (-1=all, 0=none, -1=leader) (default -1). -|--allow-auto-topic-creation |- |Auto-create non-existent topics; -requires auto_create_topics_enabled on the broker. +== Examples -|-z, --compression |string |Compression to use for producing batches -(none, gzip, snappy, lz4, zstd) (default "snappy"). +This section provides examples of how to use `rpk topic produce`. -|--delivery-timeout |duration |Per-record delivery timeout, if non-zero, -min 1s. +=== Format examples -|-f, --format |string |Input record format (default "%v\n"). +A key and value, separated by a space and ending in newline -|-H, --header |stringArray |Headers in format key:value to add to each -record (repeatable). +[,bash] +---- +rpk topic produce my-topic -f '%k %v\n' +---- -|-h, --help |- |Help for produce. +A four byte topic, four byte key, and four byte value -|-k, --key |string |A fixed key to use for each record (parsed input -keys take precedence). +[,bash] +---- +rpk topic produce -f '%T{4}%K{4}%V{4}%t%k%v' +---- -|--max-message-bytes |int32 |If non-negative, maximum size of a record -batch before compression (default -1). +A value to a specific partition (requires non-negative `--partition` flag) -|-o, --output-format |string |what to write to stdout when a record is -successfully produced (default "Produced to partition %p at offset %o -with timestamp %d.\n"). +[,bash] +---- +rpk topic produce my-topic -p 0 -f '%p %v\n' +---- -|-p, --partition |int32 |Partition to directly produce to, if -non-negative (also allows %p parsing to set partitions) (default -1). +A big-endian uint16 key size, the text " foo ", and then that key -|--schema-id |string |Schema ID to encode the record value with, use `topic` for TopicName strategy. +[,bash] +---- +rpk topic produce my-topic -f '%K{big16} foo %k' +---- -|--schema-key-id |string |Schema ID to encode the record key with, use `topic` for TopicName strategy. +A value that can be two or three characters followed by a newline -|--schema-key-type |string |Name of the protobuf message type to be used to encode the record key using schema registry. +[,bash] +---- +rpk topic produce my-topic -f '%v{re#...?#}\n' +---- -|--schema-type |string |Name of the protobuf message type to be used to encode the record value using schema registry. +A key and a JSON value, separated by a space -|-Z, --tombstone |- |Produce empty values as tombstones. +[,bash] +---- +rpk topic produce my-topic -f '%k %v{json}' +---- -|--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 + +|--acks |int |Number of acknowledgments required before a produce request is considered successful (`-1` = all in-sync replicas, `0` = no acknowledgment, `1` = leader only). +|--allow-auto-topic-creation |bool |Auto-create non-existent topics; requires auto_create_topics_enabled on the broker. +|-z, --compression |string |Compression algorithm to use when producing batches (`none`, `gzip`, `snappy`, `lz4`, `zstd`). +|--delivery-timeout |duration |Per-record delivery timeout, if non-zero, min 1s. +|-f, --format |string |Input record format. +|-H, --header |stringArray |Headers in format key:value to add to each record (`repeatable`). +|-k, --key |string |A fixed key to use for each record (parsed input keys take precedence). +|--max-message-bytes |int32 |If non-negative, maximum size of a record batch before compression. +|-o, --output-format |string |Output to write to stdout when a record is successfully produced. +|-p, --partition |int32 |Partition to directly produce to, if non-negative (also allows `%p` parsing to set partitions). +|--schema-id |string |Schema ID to encode the record value with, use `topic` for TopicName strategy. +|--schema-key-id |string |Schema ID to encode the record key with, use `topic` for TopicName strategy. +|--schema-key-type |string |Name of the protobuf message type to be used to encode the record key using schema registry. +|--schema-type |string |Name of the protobuf message type to be used to encode the record value using schema registry. +|-Z, --tombstone |bool |Produce empty values as tombstones. +|=== -|--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 `~/.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-topic/rpk-topic-trim-prefix.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-trim-prefix.adoc index c15f601d27..712d59cb2c 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-trim-prefix.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-trim-prefix.adoc @@ -1,95 +1,53 @@ = rpk topic trim-prefix -// tag::single-source[] - -Trim records from topics - -This command allows you to trim records from topics, where Redpanda -sets 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. - -The `--offset/-o` flag allows you to indicate which index you want to set the -partition's low watermark (start offset) to. It can be a single integer value -denoting the offset, or it can be a timestamp if you prefix the offset with an '@'. You can select which partition to trim the offset from using the `--partitions/-p` flag. - -The `--from-file` option allows to trim the offsets specified in a text file with -the following format: - ----- -[TOPIC] [PARTITION] [OFFSET] -[TOPIC] [PARTITION] [OFFSET] -... ----- +: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. +:page-platforms: linux,darwin -or the equivalent keyed JSON/YAML file. +// 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[] include::shared:partial$warning-delete-records.adoc[] -== Examples +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. -* Trim records in 'foo' topic to offset 120 in partition 1: -+ -[,bash] ----- -rpk topic trim-prefix foo --offset 120 --partitions 1 ----- - -* Trim records in all partitions of topic foo previous to an specific timestamp: -+ -[,bash] ----- -rpk topic trim-prefix foo -o "@1622505600" ----- +== Usage -* Trim records from a JSON file: -+ [,bash] ---- -rpk topic trim-prefix --from-file /tmp/to_trim.json +rpk topic trim-prefix [flags] ---- -== Usage -[,bash] ----- -rpk topic trim-prefix [TOPIC] [flags] ----- == Aliases [,bash] ---- -trim-prefix, trim +rpk topic trim ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-f, --from-file |string |File of topic/partition/offset for which to -trim offsets for. - -|-h, --help |- |Help for trim-prefix. +|Value |Type |Description -|--no-confirm |- |Disable confirmation prompt. - -|-o, --offset |string |Offset to set the partition's start offset to, -either as an integer or timestamp (`@`). - -|-p, --partitions |int32 |int32Slice Comma-separated list of partitions -to trim records from (default to all) (default []). - -|--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, --from-file |string |Path to a file specifying topic, partition, and offset values to trim. +|--no-confirm |bool |Disable confirmation prompt. +|-o, --offset |string |Offset to set the partition's start offset to (`end`, 47, @). +|-p, --partitions |int32Slice |Comma-separated list of partitions to trim records from (default to all). +|=== -|--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 `~/.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-topic/rpk-topic.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic.adoc index cf3dc342c1..2f8888ceab 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic.adoc @@ -1,51 +1,110 @@ = rpk topic +:description: Manage Kafka topics, including creating, deleting, and configuring topics. Also includes commands for producing and consuming messages. :page-aliases: reference:rpk/rpk-topic.adoc -// tag::single-source[] -:description: These commands let you manage your topics, including creating, producing, and consuming new messages. +: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 -Create, delete, produce to and consume from Redpanda topics. +// tag::single-source[] +Manage Kafka topics, including creating, deleting, and configuring topics. Also includes commands for producing and consuming messages. == Usage [,bash] ---- -rpk topic [flags] [command] +rpk topic [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-topic/rpk-topic-add-partitions.adoc[`rpk topic add-partitions`] +|Add partitions to existing topics. + +|xref:reference:rpk/rpk-topic/rpk-topic-alter-config.adoc[`rpk topic alter-config`] +|Set, delete, add, and remove key/value configs for a topic. This command allows you to incrementally alter the configuration for multiple topics at a time. + +|xref:reference:rpk/rpk-topic/rpk-topic-analyze.adoc[`rpk topic analyze`] +|Analyze topics. This command consumes records from the specified topics to determine topic characteristics such as batch rate and batch size. -|-h, --help |- |Help for topic. +|xref:reference:rpk/rpk-topic/rpk-topic-consume.adoc[`rpk topic consume`] +|Consume records from topics. Consuming records reads from any amount of input topics, formats each record according to `--format`, and prints them to `STDOUT`. -|--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-topic/rpk-topic-create.adoc[`rpk topic create`] +|Create one or more Kafka topics with configurable partitions, replication factor, and topic-level settings. -|-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-topic/rpk-topic-delete.adoc[`rpk topic delete`] +|Delete one or more Kafka topics. This operation is irreversible and removes all data in the topics. -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-topic/rpk-topic-describe.adoc[`rpk topic describe`] +|Print detailed information about topics. There are three potential views: a summary of the topic, the topic configurations, and a detailed partitions section. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-topic/rpk-topic-describe-storage.adoc[`rpk topic describe-storage`] +|Describe the cloud storage status of a topic, including storage mode, offset availability, segment sizes, and synchronization state. + +|xref:reference:rpk/rpk-topic/rpk-topic-list.adoc[`rpk topic list`] +|List topics, optionally listing specific topics. This command lists all topics that you have access to by default. + +|xref:reference:rpk/rpk-topic/rpk-topic-produce.adoc[`rpk topic produce`] +|Produce records to a topic. Producing records reads from `STDIN`, parses input according to `--format`, and produces records to Redpanda. + +|xref:reference:rpk/rpk-topic/rpk-topic-trim-prefix.adoc[`rpk topic trim-prefix`] +|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. -|-v, --verbose |- |Enable verbose logging. |=== -ifndef::env-cloud[] -== See also -- xref:reference:rpk/rpk-topic/rpk-topic-create.adoc[Create a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-produce.adoc[Produce records to a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-list.adoc[List topics] -- xref:reference:rpk/rpk-topic/rpk-topic-consume.adoc[Consume records from a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-delete.adoc[Delete a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-describe.adoc[Describe a topic and its configuration] -- xref:reference:rpk/rpk-topic/rpk-topic-describe-storage.adoc[Describe the storage status of a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-alter-config.adoc[Modify topic configuration] -- xref:reference:rpk/rpk-topic/rpk-topic-trim-prefix.adoc[Trim existing records in a topic] -- xref:reference:rpk/rpk-topic/rpk-topic-add-partitions.adoc[Add partitions to an existing topic] +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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 + +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-create.adoc[Create a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-produce.adoc[Produce records to a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-list.adoc[List topics] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-consume.adoc[Consume records from a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-delete.adoc[Delete a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-describe.adoc[Describe a topic and its configuration] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-describe-storage.adoc[Describe the storage status of a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-alter-config.adoc[Modify topic configuration] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-trim-prefix.adoc[Trim existing records in a topic] +endif::[] +ifndef::env-cloud[] +* xref:reference:rpk/rpk-topic/rpk-topic-add-partitions.adoc[Add partitions to an existing topic] endif::[] -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-transform/rpk-transform-build.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-build.adoc index 87ce305c6e..6218a53afd 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-build.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-build.adoc @@ -1,24 +1,25 @@ = rpk transform build +:description: pass:q[Build a transform. This command looks in the current working directory for a `transform.yaml` file.] :page-aliases: labs:data-transform/rpk-transform-build.adoc -// tag::single-source[] +: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 -Build a data transform. +// tag::single-source[] +Build a transform. -This command looks in the current working directory for a `transform.yaml` file. It installs the appropriate build plugin, then builds a `.wasm` file. +This command looks in the current working directory for a `transform.yaml` file. +It installs the appropriate build plugin, then builds a `.wasm` file. When invoked, it passes extra arguments directly to the underlying toolchain. -For example, to add debug symbols and use the `asyncify` scheduler for `tinygo`: +For example to add debug symbols for tinygo: [,bash] ---- -rpk transform build -- -scheduler=asyncify -no-debug=false +rpk transform build -- -no-debug=false ---- -Language-specific details: - -TinyGo - By default, TinyGo are release builds (-opt=2) and goroutines are disabled, for maximum performance. - == Usage [,bash] @@ -26,23 +27,25 @@ TinyGo - By default, TinyGo are release builds (-opt=2) and goroutines are disab rpk transform build [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* +=== Languages + +Tinygo - By default tinygo are release builds (-opt=2) for maximum performance. -|-h, --help |- |Help for build. -|--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. +== 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 `~/.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-transform/rpk-transform-delete.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-delete.adoc index 585529fac2..17b7db1b4d 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-delete.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-delete.adoc @@ -1,35 +1,43 @@ = rpk transform delete +:description: Delete a data transform. :page-aliases: labs:data-transform/rpk-transform-delete.adoc -// tag::single-source[] +: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[] Delete a data transform. == Usage [,bash] ---- -rpk transform delete [NAME] [flags] +rpk transform delete [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for delete. -|--no-confirm |- |Disable confirmation prompt. +== Flags -|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, 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. +|--no-confirm |bool |Disable confirmation prompt. +|=== -|--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 `~/.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-transform/rpk-transform-deploy.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-deploy.adoc index 8526e8c913..1a8552085b 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-deploy.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-deploy.adoc @@ -1,67 +1,65 @@ = rpk transform deploy +:description: pass:q[Deploy a transform. When run in the same directory as a `transform.yaml`, this reads the configuration file, then looks for a `.wasm` file with the same name as your project.] :page-aliases: labs:data-transform/rpk-transform-deploy.adoc -// tag::single-source[] - -Deploy a data transform. - -When run in the same directory as a `transform.yaml`, this reads the configuration file, then looks for a `.wasm` file with the same name as your project. If the input and output topics are specified in the configuration file, those are used. Otherwise, the topics can be specified on the command line using the `--input-topic` and `--output-topic` flags. - -You can specify environment variables for the transform using the `--var` flag. Variables are separated by an equal sign. For example: `--var=KEY=VALUE`. The `--var` flag can be repeated to specify multiple variables. +:page-platforms: linux,darwin -You can specify the `--from-offset` flag to identify where on the input topic the transform should begin processing. Expressed as: +// 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 -- `@T` - Begin reading records with committed timestamp >= T (UNIX time, ms from epoch) - -- `+N` - Begin reading N records from the start of each input partition - -- `-N` - Begin reading N records prior to the end of each input partition +// tag::single-source[] +Deploy a transform. -Note that the broker will only respect `--from-offset` on the first deploy for a given transform. Re-deploying the transform will cause processing to pick up at the last committed offset. This state is maintained until the transform is deleted. +When run in the same directory as a `transform.yaml`, this reads the configuration +file, then looks for a `.wasm` file with the same name as your project. If the +input and output topics are specified in the configuration file, those are used. +Otherwise, the topics can be specified on the command line using the +`--input-topic` and `--output-topic` flags. -== Usage +To deploy Wasm files directly without a `transform.yaml` file: [,bash] ---- -rpk transform deploy [flags] +rpk transform deploy --file transform.wasm --name myTransform \ +--input-topic my-topic-1 \ +--output-topic my-topic-2 \ +--output-topic my-topic-3 ---- -== Flags - -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* - -|--compression |string |Output batch compression type. - -|--file |string |The WebAssembly module to deploy. - -|--from-offset |string |Process an input topic partition from a relative offset. - -|-h, --help |- |Help for deploy. +Environment variables can be specified for the transform using the `--var` flag, these +are separated by an equals for example: `--var=KEY=VALUE`. -|-i, --input-topic |string |The input topic to apply the transform to. +The `--var` flag can be repeated to specify multiple variables like so: -|--name |string |The name of the transform. +[,bash] +---- +rpk transform deploy --var FOO=BAR --var FIZZ=BUZZ +---- -|-o, --output-topic |strings |The output topic to write the transform results to (repeatable). +The `--from-offset` flag can be used to specify where on the input topic the transform +should begin processing. Expressed as: -|--var |environmentVariable |Specify an environment variable in the form of KEY=VALUE. +* `@T` - Begin reading records with committed timestamp >= T (UNIX time, ms from epoch) +* `+N` - Begin reading N records from the start of each input partition +* `-N` - Begin reading N records prior to the end of each input partition -|--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`. +Note that the broker will only respect from-offset on the first deploy for a given +transform. Re-deploying the transform will cause processing to pick up at the last +committed offset. Recall that this state is maintained until the transform is deleted. -|-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. +== Usage -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +[,bash] +---- +rpk transform deploy [flags] +---- -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. -|-v, --verbose |- |Enable verbose logging. -|=== == Examples -Deploy Wasm files directly without a `transform.yaml` file: +This section provides examples of how to use `rpk transform deploy`. + +Deploy Wasm files directly without a `transform.yaml` file. [,bash] ---- @@ -71,34 +69,52 @@ rpk transform deploy --file transform.wasm --name myTransform \ --output-topic my-topic-3 ---- -Deploy a transformation with multiple environment variables: +Deploy a transformation with multiple environment variables. [,bash] ---- rpk transform deploy --var FOO=BAR --var FIZZ=BUZZ ---- -Configure compression for batches output by data transforms. The default setting is `none` but you can choose from the following options: - - -* none -* gzip -* snappy -* lz4 -* zstd - -Configure this at deployment using `rpk` with the `--compression` flag: +Configure compression for batches output by data transforms. The default setting is `none` but you can choose from `none`, `gzip`, `snappy`, `lz4`, or `zstd`. [,bash] ---- rpk transform deploy --compression ---- +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--compression |string |Output batch compression type. Valid values: `none`, `gzip`, `snappy`, `lz4`, `zstd`. Defaults to `none`. +|--file |string |The WebAssembly module to deploy. +|--from-offset |string |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. +|-i, --input-topic |string |The input topic to apply the transform to. +|--name |string |The name of the transform. +|-o, --output-topic |stringSlice |The output topic to write the transform results to (`repeatable`). +|--var |environmentVariable |Specify an environment variable in the form of KEY=VALUE. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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[] Enabling compression may increase computation costs and could impact latency at the output topic. -For more details, see xref:deploy:deployment-option/self-hosted/manual/sizing.adoc[]. +For more details, see xref:deploy:deployment-option/self-hosted/manual/sizing.adoc[Sizing for Production]. endif::[] - -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-transform/rpk-transform-init.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-init.adoc index e17181d06f..ee6ecd08b0 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-init.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-init.adoc @@ -1,52 +1,45 @@ = rpk transform init +:description: Initialize a new data transform project. Creates a new directory with the required project files. :page-aliases: labs:data-transform/rpk-transform-init.adoc -// tag::single-source[] - -Initialize a transform. +:page-platforms: linux,darwin -Create a new data transform using a template in the current directory. +// 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 -== Example +// tag::single-source[] +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. -Specify a new directory to create by specifying it in the command: +== Usage [,bash] ---- -rpk transform init foobar +rpk transform init [flags] ---- -This initializes a transform project in the foobar directory. -== Usage -[,bash] ----- -rpk transform init [DIRECTORY] [flags] ----- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for `rpk transform init`` - -|--install-deps |- |If dependencies should be installed for the project (default prompt). +|Value |Type |Description +|--install-deps |bool |Install project dependencies automatically after initialization. |-l, --language |string |The language used to develop the transform. - |--name |string |The name of the transform. +|=== -|--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. +== 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 `~/.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-transform/rpk-transform-list.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-list.adoc index ee90c72736..02ad2b7707 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-list.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-list.adoc @@ -1,14 +1,21 @@ = rpk transform list +:description: pass:q[List data transforms. This command lists all data transforms in a cluster, as well as showing the state of a individual transform processor, such as if it's errored or how many records are pending to be processed (`lag`).] :page-aliases: labs:data-transform/rpk-transform-list.adoc -// tag::single-source[] +: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 data transforms. -This command lists all data transforms in a cluster, as well as showing the state of a individual transform processor, such as if it's errored or how many records are pending to be processed (lag). +This command lists all data transforms in a cluster, as well as showing the +state of a individual transform processor, such as if it's errored or how many +records are pending to be processed (`lag`). -There is a processor assigned to each partition on the input topic, and each processor is a separate entity that can make progress or fail independently. +There is a processor assigned to each partition on the input topic, and each +processor is a separate entity that can make progress or fail independently. -The `--detailed/-d` flag opts in to printing extra per-processor information. +The `--detailed` flag (`-d`) opts in to printing extra per-processor information. == Usage @@ -17,34 +24,36 @@ The `--detailed/-d` flag opts in to printing extra per-processor information. rpk transform list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk transform ls ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-d, --detailed |- |Print per-partition information for data transforms. +|Value |Type |Description -|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. - -|-h, --help |- |Help for list. - -|--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. +|-d, --detailed |bool |Print per-partition information for data transforms. +|--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 `~/.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-transform/rpk-transform-logs.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-logs.adoc index fa6facde5a..01c12a83b0 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-logs.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-logs.adoc @@ -1,40 +1,51 @@ = rpk transform logs -// tag::single-source[] +:description: View logs for a data transform. Streams STDOUT and STDERR output captured during runtime to your terminal. +:page-platforms: linux,darwin -View logs for a transform. +// 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 -Data transform's STDOUT and STDERR are captured during runtime and written to an internally managed topic `_redpanda.transform_logs`. +// tag::single-source[] +View logs for a data transform. Streams STDOUT and STDERR output captured during runtime to your terminal. -This command outputs logs for a single transform over a period of time and printing them to STDOUT. The logs can be printed in various formats. +== Usage + +[,bash] +---- +rpk transform logs NAME [flags] +---- -By default, only logs that have been emitted are displayed. Use the `--follow` flag to stream new logs continuously. -## Filtering +=== Filtering -The `--head` and `--tail` flags are mutually exclusive and limit the number of log entries from the beginning or end of the range, respectively. +The `--head` and `--tail` flags are mutually exclusive and limit the number of log +entries from the beginning or end of the range, respectively. -The `--since` and `--until` flags define a time range. Use one or both flags to limit the log output to a desired period of time. +The `--since` and `--until` flags define a time range. Use one of both flags to +limit the log output to a desired period of time. Both flags accept values in the following formats: + [cols="1m,1a"] |=== -|*Value* |*Description* +|Value |Description -|now |the current time, useful for --since=now +|now |the current time, useful for `--since=now` |13 digits |parsed as a Unix millisecond |9 digits |parsed as a Unix second |YYYY-MM-DD |parsed as a day, UTC |YYYY-MM-DDTHH:MM:SSZ |parsed as RFC3339, UTC; fractional seconds optional (.MMM) -|-dur |a negative duration from now +|-dur |a negative duration from now |dur |a positive duration from now |=== + Durations are parsed simply: + [cols="1m,1a"] |=== -|*Value* |*Description* +|Value |Description |3ms |three milliseconds |10s |ten seconds @@ -43,79 +54,77 @@ Durations are parsed simply: |1m3ms |one minute and three milliseconds |=== -## Formatting - -Logs can be displayed in a variety of formats using `--format`. - -The default `--format=text` prints the log record's body line by line. -When `--format=wide` is specified, the output includes a prefix that is the date of the log line and a level for the record. The INFO level corresponds to being emitted on the transform's STDOUT, while the WARN level is used for STDERR. +For example, -The `--format=json` flag emits logs in the JSON encoded version of the Open Telemetry LogRecord protocol buffer. -## Examples -Reads logs within the last hour: - -```bash -rpk transform logs --since=-1h -``` +[,bash] +---- +--since=-1h reads logs within the last hour \ +--until=-30m reads logs prior to 30 minutes ago +---- -Reads logs prior to 30 minutes ago: -```bash -rpk transform logs --until=-30m -``` The following command reads logs between noon and 1pm on March 12th: -```bash -rpk transform logs my-transform --since=2024-03-12T12:00:00Z --until=2024-03-12T13:00:00Z -``` -== Usage [,bash] ---- -rpk transform logs NAME [flags] +rpk transform logs my-transform --since=2024-03-12T12:00:00Z --until=2024-03-12T13:00:00Z ---- + + +=== Formatting + +Logs can be displayed in a variety of formats using `--format`. + +The default `--format=text` prints the log record's body line by line. + +When `--format=wide` is specified, the output includes a prefix that is the +date of the log line and a level for the record. The INFO level corresponds +to being emitted on the transform's STDOUT, while the WARN level is used +for STDERR. + +The `--format=json` flag emits logs in the JSON encoded version of +the Open Telemetry LogRecord protocol buffer. + + == Aliases [,bash] ---- -logs, log +rpk transform log ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-f, --follow |- |Specify if the logs should be streamed. - -|--format |string |Output format (json,yaml,text,wide,help) (default "text"). +|Value |Type |Description +|-f, --follow |bool |Specify if the logs should be streamed. +|--format |string |Output format (`json`,`yaml`,`text`,`wide`,`help`). |--head |int |The number of log entries to fetch from the start. - -|-h, --help |- |Help for logs. - -|--since |timestamp |Start reading logs after this time (now, -10m, 2024-02-10). See <> for format details. - +|--since |timequery |Start reading logs after this time (`now`, -10m, 2024-02-10). |--tail |int |The number of log entries to fetch from the end. +|--until |timequery |Read logs up unto this time (-1h, 2024-02-10T13:00:00Z). +|=== -|--until |timestamp |Read logs up unto this time (-1h, 2024-02-10T13:00:00Z). See <> for format details. - -|--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; '-X help' for detail or '-X list' for terser detail. - -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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-transform/rpk-transform-pause.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-pause.adoc index e9f0ca9b8c..d6a69a1532 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-pause.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-pause.adoc @@ -1,11 +1,19 @@ = rpk transform pause -:description: rpk transform pause +:description: Pause a data transform. This command suspends execution of the specified transform without removing it from the system. +: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[] Pause a data transform. -This command suspends execution of the specified transform without removing it from the system. In this way, a transform may resume at a later time, with each new processor picking up processing from the last committed offset on the corresponding input partition. +This command suspends execution of the specified transform without removing +it from the system. In this way, a transform may resume at a later time, with +each new processor picking up processing from the last committed offset on the +corresponding input partition. -Subsequent `rpk transform list` operations will show transform processors as `inactive`. +Subsequent `rpk transform list` operations will show transform processors as +`inactive`. To resume a paused transform, use `rpk transform resume`. @@ -13,24 +21,24 @@ To resume a paused transform, use `rpk transform resume`. [,bash] ---- -rpk transform pause [NAME] [flags] +rpk transform pause [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for pause. -|--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. +== 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 `~/.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-transform/rpk-transform-resume.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform-resume.adoc index e485f7fb7f..0451c6995c 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform-resume.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform-resume.adoc @@ -1,34 +1,41 @@ = rpk transform resume -:description: rpk transform resume +:description: Resume a data transform. This command resumes execution of the specified data transform, if it was previously paused. +: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[] Resume a data transform. -This command resumes execution of the specified data transform, if it was previously paused. Transform processors are restarted and resume processing from the last committed offset on the corresponding input partition. +This command resumes execution of the specified data transform, if it was +previously paused. Transform processors are restarted and resume processing +from the last committed offset on the corresponding input partition. -Subsequent `rpk transform list` operations will show transform processors as `running`. +Subsequent `rpk transform list` operations will show transform processors as +`running`. == Usage [,bash] ---- -rpk transform resume [NAME] [flags] +rpk transform resume [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for resume. -|--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. +== 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 `~/.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-transform/rpk-transform.adoc b/modules/reference/pages/rpk/rpk-transform/rpk-transform.adoc index 784da0e6fe..89757785c7 100644 --- a/modules/reference/pages/rpk/rpk-transform/rpk-transform.adoc +++ b/modules/reference/pages/rpk/rpk-transform/rpk-transform.adoc @@ -1,41 +1,74 @@ = rpk transform +:description: Develop, build, deploy, and manage WebAssembly (Wasm) data transforms for Redpanda. :page-aliases: labs:data-transform/rpk-transform.adoc -// tag::single-source[] -:description: pass:q[These commands let you build and manage data transforms with WebAssembly.] +: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 -Develop, deploy, and manage Redpanda data transforms. +// tag::single-source[] +Develop, build, deploy, and manage WebAssembly (Wasm) data transforms for Redpanda. == Usage [,bash] ---- -rpk transform [command] [flags] +rpk transform [flags] ---- + + == Aliases [,bash] ---- -transform, wasm, transfrom +rpk wasm +rpk transfrom ---- -== Flags +== Subcommands -[cols="1m,1a,2a"] +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-transform/rpk-transform-build.adoc[`rpk transform build`] +|Build a transform. This command looks in the current working directory for a `transform.yaml` file. + +|xref:reference:rpk/rpk-transform/rpk-transform-delete.adoc[`rpk transform delete`] +|Delete a data transform. -|-h, --help |- |Help for transform. +|xref:reference:rpk/rpk-transform/rpk-transform-deploy.adoc[`rpk transform deploy`] +|Deploy a transform. When run in the same directory as a `transform.yaml`, this reads the configuration file, then looks for a `.wasm` file with the same name as your project. -|--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-transform/rpk-transform-init.adoc[`rpk transform init`] +|Initialize a new data transform project. Creates a new directory with the required project files. -|-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-transform/rpk-transform-list.adoc[`rpk transform list`] +|List data transforms. This command lists all data transforms in a cluster, as well as showing the state of a individual transform processor, such as if it's errored or how many records are pending to be processed (`lag`). -|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. +|xref:reference:rpk/rpk-transform/rpk-transform-logs.adoc[`rpk transform logs`] +|View logs for a data transform. Streams STDOUT and STDERR output captured during runtime to your terminal. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-transform/rpk-transform-pause.adoc[`rpk transform pause`] +|Pause a data transform. This command suspends execution of the specified transform without removing it from the system. + +|xref:reference:rpk/rpk-transform/rpk-transform-resume.adoc[`rpk transform resume`] +|Resume a data transform. This command resumes execution of the specified data transform, if it was previously paused. + +|=== + + +== 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 `~/.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-version.adoc b/modules/reference/pages/rpk/rpk-version.adoc index f42f36f2b3..0ac4a9e68c 100644 --- a/modules/reference/pages/rpk/rpk-version.adoc +++ b/modules/reference/pages/rpk/rpk-version.adoc @@ -1,12 +1,19 @@ = rpk version +:description: pass:q[Prints the current `rpk` and Redpanda version. This command prints the current `rpk` version and allows you to list the Redpanda version running on each node in your 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[] -:description: pass:q[This command checks the current version of `rpk`.] +Prints the current `rpk` and Redpanda version. -Prints the current `rpk` and Redpanda version and allows you to list the Redpanda version running on each broker in your cluster. +This command prints the current `rpk` version and allows you to list the Redpanda +version running on each node in your cluster. -To list the Redpanda version of each broker in your cluster you may pass the Admin API hosts via flags, profile, or environment variables. +To list the Redpanda version of each node in your cluster you may pass the +Admin API hosts using flags, profile, or environment variables. -To get only the rpk version, use `rpk --version`. +To get only the `rpk version`, use `rpk --version`. == Usage @@ -15,23 +22,21 @@ To get only the rpk version, use `rpk --version`. rpk version [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for version. -|--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. - -|--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 `~/.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-x-options.adoc b/modules/reference/pages/rpk/rpk-x-options.adoc index 6286a8db33..273c918db8 100644 --- a/modules/reference/pages/rpk/rpk-x-options.adoc +++ b/modules/reference/pages/rpk/rpk-x-options.adoc @@ -242,7 +242,7 @@ The SASL mechanism to use for authentication. NOTE: With Redpanda, the Admin API can be configured to require basic authentication with your Kafka API SASL credentials. This defaults to `SCRAM-SHA-256` if no mechanism is specified. -For `OAUTHBEARER`, set `pass` to an OIDC access token (raw value, or prefixed with `token:`) instead of a SASL password, and leave `user` unset. Support for `OAUTHBEARER` was added in rpk v26.1.7 (also backported to v25.3.x and v25.2.x). For end-to-end steps, see xref:manage:security/authentication.adoc#oidc-rpk[Connect to Redpanda with OIDC using rpk]. +For `OAUTHBEARER`, set `pass` to an OIDC access token (raw value, or prefixed with `token:`) instead of a SASL password, and leave `user` unset. `rpk` uses this mechanism and token for its Kafka API, Admin API, and Schema Registry clients, so the same token authenticates all three when the corresponding listeners have OIDC enabled. Support for `OAUTHBEARER` was added in rpk v26.1.7 (also backported to v25.3.x and v25.2.x). For end-to-end steps, see xref:manage:security/authentication.adoc#oidc-rpk[Connect to Redpanda with OIDC using rpk]. *Example*: `sasl.mechanism=SCRAM-SHA-256` @@ -255,7 +255,7 @@ rpk topic list -X sasl.mechanism= === user -The SASL username to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. +The SASL username to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. The `OAUTHBEARER` mechanism does not use `user`; leave it unset and pass the token through <>. *Type*: string @@ -272,7 +272,7 @@ rpk topic list -X user= === pass -The SASL password to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. +The SASL password to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. For the `OAUTHBEARER` mechanism, set `pass` to an OIDC access token (a raw token, or one prefixed with `token:`) rather than a SASL password. See <>. *Type*: string diff --git a/modules/reference/pages/rpk/rpk.adoc b/modules/reference/pages/rpk/rpk.adoc new file mode 100644 index 0000000000..07ca353537 --- /dev/null +++ b/modules/reference/pages/rpk/rpk.adoc @@ -0,0 +1,96 @@ += rpk +:description: pass:q[`rpk` is the Redpanda CLI and toolbox for managing Redpanda clusters, topics, consumer groups, and streaming pipelines.] +: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[] +`rpk` is the Redpanda CLI and toolbox for managing Redpanda clusters, topics, consumer groups, and streaming pipelines. + +== Usage + +[,bash] +---- +rpk [flags] +---- + + + + +== Subcommands + +[cols="1,2a"] +|=== +|Command |Description + +|xref:reference:rpk/rpk-cloud/rpk-cloud.adoc[`rpk cloud`] +|Interact with Redpanda Cloud. + +|xref:reference:rpk/rpk-cluster/rpk-cluster.adoc[`rpk cluster`] +|Manage and inspect Redpanda cluster configuration, health, and maintenance operations. + +|xref:reference:rpk/rpk-connect/rpk-connect.adoc[`rpk connect`] +|Run and manage Redpanda Connect streaming pipelines. Redpanda Connect is a high-performance stream processor for mundane data engineering tasks. + +|xref:reference:rpk/rpk-container/rpk-container.adoc[`rpk container`] +|Manage a local Redpanda container cluster for development and testing. Creates containers using Docker or Podman. + +|xref:reference:rpk/rpk-debug/rpk-debug.adoc[`rpk debug`] +|Debug the local Redpanda process. + +|xref:reference:rpk/rpk-generate/rpk-generate.adoc[`rpk generate`] +|Generate a configuration template for related services. + +|xref:reference:rpk/rpk-group/rpk-group.adoc[`rpk group`] +|Manage Kafka consumer groups, including listing groups, viewing lag, and resetting offsets. + +|xref:reference:rpk/rpk-help.adoc[`rpk help`] +|Help provides help for any command in the application. Simply type `rpk help` [path to command] for full details. + +|xref:reference:rpk/rpk-iotune.adoc[`rpk iotune`] +|Measure filesystem performance and create IO configuration file. + +|xref:reference:rpk/rpk-plugin/rpk-plugin.adoc[`rpk plugin`] +|List, download, update, and remove `rpk` plugins. Plugins augment `rpk` with new commands. + +|xref:reference:rpk/rpk-profile/rpk-profile.adoc[`rpk profile`] +|Manage `rpk` configuration profiles. Profiles store connection settings for different clusters, making it easy to switch between environments. + +|xref:reference:rpk/rpk-redpanda/rpk-redpanda.adoc[`rpk redpanda`] +|Interact with a local Redpanda process. + +|xref:reference:rpk/rpk-registry/rpk-registry.adoc[`rpk registry`] +|Commands to interact with the schema registry. + +|xref:reference:rpk/rpk-security/rpk-security.adoc[`rpk security`] +|Manage Redpanda security. + +|xref:reference:rpk/rpk-shadow/rpk-shadow.adoc[`rpk shadow`] +|Manage Redpanda Shadow Links. Shadowing is Redpanda's enterprise-grade disaster recovery solution that establishes asynchronous, offset-preserving replication between two distinct Redpanda clusters. + +|xref:reference:rpk/rpk-topic/rpk-topic.adoc[`rpk topic`] +|Manage Kafka topics, including creating, deleting, and configuring topics. Also includes commands for producing and consuming messages. + +|xref:reference:rpk/rpk-transform/rpk-transform.adoc[`rpk transform`] +|Develop, build, deploy, and manage WebAssembly (Wasm) data transforms for Redpanda. + +|xref:reference:rpk/rpk-version.adoc[`rpk version`] +|Prints the current `rpk` and Redpanda version. This command prints the current `rpk` version and allows you to list the Redpanda version running on each node in your cluster. + +|=== + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/properties/broker-properties.adoc b/modules/reference/partials/properties/broker-properties.adoc index b34738c0a9..7e29063e96 100644 --- a/modules/reference/partials/properties/broker-properties.adoc +++ b/modules/reference/partials/properties/broker-properties.adoc @@ -545,7 +545,7 @@ endif::[] // tag::category-redpanda[] === cloud_storage_cache_directory -Directory for archival cache. Set when the xref:reference:properties/cluster-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] cluster property is enabled. If not specified, Redpanda uses a default path within the data directory. +Directory for archival cache. Set when the xref:reference:properties/object-storage-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] cluster property is enabled. If not specified, Redpanda uses a default path within the data directory. [cols="1s,2a"] |=== @@ -590,7 +590,7 @@ redpanda: Replace `` with the full path to your desired cache directory. | Related topics -|xref:reference:properties/cluster-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] +|xref:reference:properties/object-storage-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] |=== @@ -2493,7 +2493,7 @@ endif::[] // tag::category-redpanda[] === rack -A label that identifies a failure zone. Apply the same label to all brokers in the same failure zone. When xref:./cluster-properties.adoc#enable_rack_awareness[enable_rack_awareness] is set to `true` at the cluster level, the system uses the rack labels to spread partition replicas across different failure zones. +A label that identifies a failure zone. Apply the same label to all brokers in the same failure zone. When xref:reference:properties/cluster-properties.adoc#enable_rack_awareness[enable_rack_awareness] is set to `true` at the cluster level, the system uses the rack labels to spread partition replicas across different failure zones. [cols="1s,2a"] |=== @@ -2940,7 +2940,7 @@ endif::[] // tag::category-schema-registry[] === schema_registry_replication_factor -Replication factor for internal `_schemas` topic. If unset, defaults to the xref:../cluster-properties.adoc#default_topic_replication[`default_topic_replication`] cluster property. +Replication factor for internal `_schemas` topic. If unset, defaults to the xref:reference:properties/cluster-properties.adoc#default_topic_replication[`default_topic_replication`] cluster property. [cols="1s,2a"] |=== @@ -2989,7 +2989,7 @@ pandaproxy: ---- | Related topics -|xref:../cluster-properties.adoc#default_topic_replication[`default_topic_replication`] +|xref:reference:properties/cluster-properties.adoc#default_topic_replication[`default_topic_replication`] |=== diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index 8da5b42d14..6ed482a500 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -3454,6 +3454,51 @@ endif::[] |=== +=== controller_log_learner_recovery_rate_enabled + +ifndef::env-cloud[] +*Introduced in v26.1.11* +endif::[] + +Whether the controller raft group (raft0) honors xref:reference:properties/cluster-properties.adoc#raft_learner_recovery_rate[`raft_learner_recovery_rate`]. When `false` (default) the controller log replicates to new learners without throttling. When `true`, controller-log recovery is subject to the same per-node recovery bucket as user partitions. + +[cols="1s,2a"] +|=== +| Property | Value + +| Type +| `boolean` + + + +| Default +| +ifdef::env-cloud[] +Available in the Redpanda Cloud Console +endif::[] +ifndef::env-cloud[] +`false` +endif::[] + +| Nullable +| No + +| Requires restart +| Yes + +ifndef::env-cloud[] +| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore] +| Yes +endif::[] + +ifndef::env-cloud[] +| Visibility +| Tunable +endif::[] + +|=== + + === controller_snapshot_max_age_sec Maximum amount of time before Redpanda attempts to create a controller snapshot after a new controller command appears. @@ -5150,11 +5195,9 @@ endif::[] === delete_topic_enable -ifndef::env-cloud[] -*Introduced in v26.1.1* -endif::[] +Controls whether topics can be deleted through the Kafka DeleteTopics API. When set to `false`, all topic deletion requests are rejected for all users, including superusers. Use this as a cluster-wide safety setting to prevent accidental topic deletion in production environments. -Enable or disable topic deletion via the Kafka DeleteTopics API. When set to false, all topic deletion requests are rejected with error code 73 (TOPIC_DELETION_DISABLED). This is a cluster-wide safety setting that cannot be overridden by superusers. Topics in kafka_nodelete_topics are always protected regardless of this setting. +For per-topic deletion protection, see xref:reference:properties/cluster-properties.adoc#kafka_nodelete_topics[`kafka_nodelete_topics`]. ifndef::env-cloud[] .Enterprise license required @@ -5200,6 +5243,12 @@ ifndef::env-cloud[] | User endif::[] +| Related topics +| +* xref:reference:properties/cluster-properties.adoc#kafka_nodelete_topics[`kafka_nodelete_topics`] + +* xref:get-started:licensing/index.adoc[enterprise license] + |=== @@ -5419,7 +5468,7 @@ Raft election timeout expressed in milliseconds. | Property | Value | Type -| `string` +| `integer` @@ -5429,7 +5478,7 @@ ifdef::env-cloud[] Available in the Redpanda Cloud Console endif::[] ifndef::env-cloud[] -`null` +`1500` endif::[] | Nullable @@ -6270,6 +6319,10 @@ endif::[] === features_auto_finalization +ifndef::env-cloud[] +*Introduced in v26.1.9* +endif::[] + Controls whether Redpanda advances the cluster's active logical version automatically after you upgrade all nodes (`true`), or only when you explicitly request finalization through the Admin API (`false`). When set to `false`, you can downgrade to the previous version until you request finalization. Note: If you performed the upgrade with this set to `false` and the cluster is ready to finalize, setting this property to `true` does not reliably trigger finalization. Keep this set to `false` and use the Admin API to finalize. After the upgrade completes, you can set this back to `true` to restore automatic finalization for future upgrades. ifndef::env-cloud[] @@ -7752,10 +7805,16 @@ endif::[] // end::redpanda-cloud[] +// tag::redpanda-cloud[] === iceberg_dlq_table_suffix The suffix added to Iceberg table names when creating dead-letter queue (DLQ) tables for invalid records. Choose a suffix that won't conflict with existing table names. This is especially important for catalogs that don't support the tilde (~) character in table names. Don't change this value after creating DLQ tables. +ifdef::env-cloud[] +NOTE: This property is available only in Redpanda Cloud BYOC deployments. +endif::[] + + [cols="1s,2a"] |=== | Property | Value @@ -7768,7 +7827,7 @@ The suffix added to Iceberg table names when creating dead-letter queue (DLQ) ta | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `~dlq` @@ -7792,6 +7851,7 @@ endif::[] |=== +// end::redpanda-cloud[] // tag::redpanda-cloud[] === iceberg_enabled @@ -7968,7 +8028,7 @@ endif::[] // tag::redpanda-cloud[] === iceberg_rest_catalog_authentication_mode -The authentication mode for client requests made to the Iceberg catalog. Choose from: `none`, `bearer`, `oauth2`, and `aws_sigv4`. In `bearer` mode, the token specified in `iceberg_rest_catalog_token` is used unconditonally, and no attempts are made to refresh the token. In `oauth2` mode, the credentials specified in `iceberg_rest_catalog_client_id` and `iceberg_rest_catalog_client_secret` are used to obtain a bearer token from the URI defined by `iceberg_rest_catalog_oauth2_server_uri`. In `aws_sigv4` mode, the same AWS credentials used for cloud storage (see `cloud_storage_region`, `cloud_storage_access_key`, `cloud_storage_secret_key`, and `cloud_storage_credentials_source`) are used to sign requests to AWS Glue catalog with SigV4. +The authentication mode for client requests made to the Iceberg catalog. Choose from: `none`, `bearer`, `oauth2`, `aws_sigv4`, and `gcp`. In `bearer` mode, the token specified in `iceberg_rest_catalog_token` is used unconditionally, and no attempts are made to refresh the token. In `oauth2` mode, the credentials specified in `iceberg_rest_catalog_client_id` and `iceberg_rest_catalog_client_secret` are used to obtain a bearer token from the URI defined by `iceberg_rest_catalog_oauth2_server_uri`. In `aws_sigv4` mode, the same AWS credentials used for cloud storage (see `cloud_storage_region`, `cloud_storage_access_key`, `cloud_storage_secret_key`, and `cloud_storage_credentials_source`) are used to sign requests to AWS Glue catalog with SigV4. In `gcp` mode, GCP VM instance metadata credentials are used to authenticate with the Iceberg REST catalog. ifdef::env-cloud[] NOTE: This property is available only in Redpanda Cloud BYOC deployments. @@ -8611,10 +8671,16 @@ endif::[] // end::redpanda-cloud[] +// tag::redpanda-cloud[] === iceberg_rest_catalog_gcp_user_project The GCP project that is billed for charges associated with Iceberg REST Catalog requests. +ifdef::env-cloud[] +NOTE: This property is available only in Redpanda Cloud BYOC deployments. +endif::[] + + [cols="1s,2a"] |=== | Property | Value @@ -8627,7 +8693,7 @@ The GCP project that is billed for charges associated with Iceberg REST Catalog | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `null` @@ -8651,6 +8717,7 @@ endif::[] |=== +// end::redpanda-cloud[] // tag::redpanda-cloud[] === iceberg_rest_catalog_oauth2_scope @@ -8994,6 +9061,59 @@ endif::[] // end::redpanda-cloud[] +=== iceberg_schema_case_insensitive + +ifndef::env-cloud[] +*Introduced in v26.1.10* +endif::[] + +Schema field name comparison mode when matching Redpanda's schema against the one returned by the Iceberg catalog. Some catalogs (for example, AWS Glue) return field names with inconsistent casing, requiring case-insensitive comparison. `auto` enables case-insensitive comparison when the catalog is AWS Glue, and exact comparison otherwise. + +[cols="1s,2a"] +|=== +| Property | Value + +| Type +| `string` (enum) + +| Accepted values +| +ifndef::env-cloud[] +`auto`, `no`, `yes` +endif::[] +ifdef::env-cloud[] +`auto`, `no`, `yes` +endif::[] + + +| Default +| +ifdef::env-cloud[] +Available in the Redpanda Cloud Console +endif::[] +ifndef::env-cloud[] +`auto` +endif::[] + +| Nullable +| No + +| Requires restart +| Yes + +ifndef::env-cloud[] +| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore] +| Yes +endif::[] + +ifndef::env-cloud[] +| Visibility +| User +endif::[] + +|=== + + === iceberg_target_backlog_size Average size per partition of the datalake translation backlog that the backlog controller tries to maintain. When the backlog size is larger than the set point, the backlog controller will increase the translation scheduling group priority. @@ -9525,7 +9645,7 @@ endif::[] === kafka_batch_max_bytes -The default maximum batch size for topics if the topic property xref:reference:properties/topic-properties.adoc[`message.max.bytes`] is not set. If the batch is compressed, the limit applies to the compressed batch size. +The default maximum batch size for topics if the topic property xref:reference:properties/topic-properties.adoc[`max.message.bytes`] is not set. If the batch is compressed, the limit applies to the compressed batch size. [cols="1s,2a"] |=== @@ -9568,7 +9688,7 @@ ifndef::env-cloud[] endif::[] | Related topics -|xref:reference:properties/topic-properties.adoc[`message.max.bytes`] +|xref:reference:properties/topic-properties.adoc[`max.message.bytes`] |=== @@ -14180,13 +14300,103 @@ endif::[] |=== +=== oidc_http_proxy_password + +ifndef::env-cloud[] +*Introduced in v26.1.10* +endif::[] + +Password for HTTP Basic authentication to the OIDC forward proxy (`oidc_http_proxy_url`). Leave unset for an unauthenticated proxy. Both username and password must be set for credentials to be sent. + +[cols="1s,2a"] +|=== +| Property | Value + +| Type +| `string` + + + +| Default +| +ifdef::env-cloud[] +Available in the Redpanda Cloud Console +endif::[] +ifndef::env-cloud[] +`null` +endif::[] + +| Nullable +| Yes + +| Requires restart +| No + +ifndef::env-cloud[] +| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore] +| Yes +endif::[] + +ifndef::env-cloud[] +| Visibility +| User +endif::[] + +|=== + + === oidc_http_proxy_url ifndef::env-cloud[] *Introduced in v26.1.7* endif::[] -URL of the HTTP forward proxy used for OIDC discovery and JWKS fetches. Accepts http://host:port or https://host:port. When set, oidc_discovery_url must use https:// — plaintext OIDC origins cannot be routed through a forward proxy. +URL of the HTTP forward proxy used for OIDC discovery and JWKS fetches. Accepts `http://host:port` or `https://host:port`. When set, `oidc_discovery_url` must use `https://`. Plaintext OIDC origins cannot be routed through a forward proxy. + +[cols="1s,2a"] +|=== +| Property | Value + +| Type +| `string` + + + +| Default +| +ifdef::env-cloud[] +Available in the Redpanda Cloud Console +endif::[] +ifndef::env-cloud[] +`null` +endif::[] + +| Nullable +| Yes + +| Requires restart +| No + +ifndef::env-cloud[] +| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore] +| Yes +endif::[] + +ifndef::env-cloud[] +| Visibility +| User +endif::[] + +|=== + + +=== oidc_http_proxy_username + +ifndef::env-cloud[] +*Introduced in v26.1.10* +endif::[] + +Username for HTTP Basic authentication to the OIDC forward proxy (`oidc_http_proxy_url`). Leave unset for an unauthenticated proxy. Both username and password must be set for credentials to be sent. [cols="1s,2a"] |=== @@ -14992,6 +15202,55 @@ endif::[] |=== +// tag::exclude-from-docs[] +=== raft_election_timeout_ms + +Election timeout expressed in milliseconds. + +[cols="1s,2a"] +|=== +| Property | Value + +| Type +| `integer` + + + +| Range +| [`-17592186044416`, `17592186044415`] + +| Default +| +ifdef::env-cloud[] +Available in the Redpanda Cloud Console +endif::[] +ifndef::env-cloud[] +`1500` (1500 milliseconds) +endif::[] + +| Nullable +| No + +| Unit +| Milliseconds + +| Requires restart +| No + +ifndef::env-cloud[] +| Restored on xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore] +| Yes +endif::[] + +ifndef::env-cloud[] +| Visibility +| Tunable +endif::[] + +|=== + +// end::exclude-from-docs[] + === raft_enable_longest_log_detection Enables an additional step in leader election where a candidate is allowed to wait for all the replies from the broker it requested votes from. This may introduce a small delay when recovering from failure, but it prevents truncation if any of the replicas have more data than the majority. @@ -18983,7 +19242,7 @@ ifdef::env-cloud[] Available in the Redpanda Cloud Console endif::[] ifndef::env-cloud[] -`DEFAULT_TOPIC_MEMORY_PER_PARTITION` +`200 KiB (204800)` endif::[] | Nullable diff --git a/modules/reference/partials/properties/object-storage-properties.adoc b/modules/reference/partials/properties/object-storage-properties.adoc index 11de3b2f0d..13c572fcb3 100644 --- a/modules/reference/partials/properties/object-storage-properties.adoc +++ b/modules/reference/partials/properties/object-storage-properties.adoc @@ -867,7 +867,7 @@ endif::[] === cloud_storage_cache_size_percent -Maximum size of the cache as a percentage, minus the space that Redpanda avoids using defined by the xref:reference:cluster-properties.adoc#disk_reservation_percent[`disk_reservation_percent`] cluster property. This is calculated at startup and dynamically updated if either this property, `disk_reservation_percent`, or <> changes. +Maximum size of the cache as a percentage, minus the space that Redpanda avoids using defined by the xref:reference:properties/cluster-properties.adoc#disk_reservation_percent[`disk_reservation_percent`] cluster property. This is calculated at startup and dynamically updated if either this property, `disk_reservation_percent`, or <> changes. This property works together with <> to define cache behavior: @@ -921,7 +921,7 @@ endif::[] `20.0` | Related topics -|xref:reference:cluster-properties.adoc#disk_reservation_percent[`disk_reservation_percent`] +|xref:reference:properties/cluster-properties.adoc#disk_reservation_percent[`disk_reservation_percent`] |=== @@ -2237,7 +2237,7 @@ ifndef::env-cloud[] endif::[] | Related topics -|xref:properties/topic-properties.adoc#redpanda-remote-allowgaps[`redpanda.remote.allowgaps`] +|xref:reference:properties/topic-properties.adoc#redpanda-remote-allowgaps[`redpanda.remote.allowgaps`] |=== diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 4f180a60fe..d3261d2762 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -29,7 +29,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_cleanup_policy[log_cleanup_policy] +| xref:reference:cluster-properties.adoc#log_cleanup_policy[log_cleanup_policy] | Default | @@ -126,7 +126,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_compression_type[log_compression_type] +| xref:reference:cluster-properties.adoc#log_compression_type[log_compression_type] | Default | @@ -337,7 +337,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[tombstone_retention_ms] +| xref:reference:cluster-properties.adoc#tombstone_retention_ms[tombstone_retention_ms] | Default | @@ -384,7 +384,7 @@ The maximum bytes not fsynced per partition. If this configured threshold is rea | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#raft_replica_max_pending_flush_bytes[raft_replica_max_pending_flush_bytes] +| xref:reference:cluster-properties.adoc#raft_replica_max_pending_flush_bytes[raft_replica_max_pending_flush_bytes] | Default | @@ -425,7 +425,7 @@ The maximum delay (in ms) between two subsequent fsyncs. After this delay, the l | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#raft_replica_max_flush_delay_ms[raft_replica_max_flush_delay_ms] +| xref:reference:cluster-properties.adoc#raft_replica_max_flush_delay_ms[raft_replica_max_flush_delay_ms] | Default | @@ -515,7 +515,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#initial_retention_local_target_bytes_default[initial_retention_local_target_bytes_default] +| xref:reference:cluster-properties.adoc#initial_retention_local_target_bytes_default[initial_retention_local_target_bytes_default] | Default | @@ -568,7 +568,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#initial_retention_local_target_ms_default[initial_retention_local_target_ms_default] +| xref:reference:cluster-properties.adoc#initial_retention_local_target_ms_default[initial_retention_local_target_ms_default] | Default | @@ -615,7 +615,7 @@ The maximum amount of time (in ms) that a log segment can remain unaltered befor | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#max_compaction_lag_ms[max_compaction_lag_ms] +| xref:reference:cluster-properties.adoc#max_compaction_lag_ms[max_compaction_lag_ms] | Default | @@ -666,7 +666,7 @@ Set an upper limit for `max.message.bytes` using the cluster property config_ref | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#kafka_batch_max_bytes[kafka_batch_max_bytes] +| xref:reference:cluster-properties.adoc#kafka_batch_max_bytes[kafka_batch_max_bytes] | Default | @@ -715,7 +715,7 @@ The maximum allowable timestamp difference between the broker's timestamp and a | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_message_timestamp_after_max_ms[log_message_timestamp_after_max_ms] +| xref:reference:cluster-properties.adoc#log_message_timestamp_after_max_ms[log_message_timestamp_after_max_ms] | Default | @@ -759,7 +759,7 @@ The maximum allowable timestamp difference between the broker's timestamp and a | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_message_timestamp_before_max_ms[log_message_timestamp_before_max_ms] +| xref:reference:cluster-properties.adoc#log_message_timestamp_before_max_ms[log_message_timestamp_before_max_ms] | Default | @@ -810,7 +810,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_message_timestamp_type[log_message_timestamp_type] +| xref:reference:cluster-properties.adoc#log_message_timestamp_type[log_message_timestamp_type] | Default | @@ -860,7 +860,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[min_cleanable_dirty_ratio] +| xref:reference:cluster-properties.adoc#min_cleanable_dirty_ratio[min_cleanable_dirty_ratio] | Default | @@ -904,7 +904,7 @@ The minimum amount of time (in ms) that a log segment must remain unaltered befo | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#min_compaction_lag_ms[min_compaction_lag_ms] +| xref:reference:cluster-properties.adoc#min_compaction_lag_ms[min_compaction_lag_ms] | Default | @@ -1001,7 +1001,7 @@ Whether the corresponding Iceberg table is deleted upon deleting the topic. | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#iceberg_delete[iceberg_delete] +| xref:reference:cluster-properties.adoc#iceberg_delete[iceberg_delete] | Default | @@ -1047,7 +1047,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#iceberg_invalid_record_action[iceberg_invalid_record_action] +| xref:reference:cluster-properties.adoc#iceberg_invalid_record_action[iceberg_invalid_record_action] | Default | @@ -1126,7 +1126,7 @@ The link:https://iceberg.apache.org/docs/nightly/partitioning/[partitioning^] sp | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#iceberg_default_partition_spec[iceberg_default_partition_spec] +| xref:reference:cluster-properties.adoc#iceberg_default_partition_spec[iceberg_default_partition_spec] | Default | @@ -1293,7 +1293,7 @@ If the cluster configuration property config_ref:enable_rack_awareness,true,prop | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#default_leaders_preference[default_leaders_preference] +| xref:reference:cluster-properties.adoc#default_leaders_preference[default_leaders_preference] | Default | @@ -1336,7 +1336,7 @@ No description available. | Corresponding cluster property -| xref:reference:properties/object-storage-properties.adoc#cloud_storage_enable_remote_allow_gaps[cloud_storage_enable_remote_allow_gaps] +| xref:reference:cluster-properties.adoc#cloud_storage_enable_remote_allow_gaps[cloud_storage_enable_remote_allow_gaps] | Default | @@ -1415,7 +1415,7 @@ A flag for enabling Redpanda to fetch data for a topic from object storage to lo | Corresponding cluster property -| xref:reference:properties/object-storage-properties.adoc#cloud_storage_enable_remote_read[cloud_storage_enable_remote_read] +| xref:reference:cluster-properties.adoc#cloud_storage_enable_remote_read[cloud_storage_enable_remote_read] | Default | @@ -1536,7 +1536,7 @@ A flag for enabling Redpanda to upload data for a topic from local storage to ob | Corresponding cluster property -| xref:reference:properties/object-storage-properties.adoc#cloud_storage_enable_remote_write[cloud_storage_enable_remote_write] +| xref:reference:cluster-properties.adoc#cloud_storage_enable_remote_write[cloud_storage_enable_remote_write] | Default | @@ -1602,7 +1602,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#default_redpanda_storage_mode[default_redpanda_storage_mode] +| xref:reference:cluster-properties.adoc#default_redpanda_storage_mode[default_redpanda_storage_mode] | Default | @@ -1831,7 +1831,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#retention_bytes[retention_bytes] +| xref:reference:cluster-properties.adoc#retention_bytes[retention_bytes] | Default | @@ -1884,7 +1884,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes_default[retention_local_target_bytes_default] +| xref:reference:cluster-properties.adoc#retention_local_target_bytes_default[retention_local_target_bytes_default] | Default | @@ -1937,7 +1937,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[retention_local_target_ms_default] +| xref:reference:cluster-properties.adoc#retention_local_target_ms_default[retention_local_target_ms_default] | Default | @@ -1993,7 +1993,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_retention_ms[log_retention_ms] +| xref:reference:cluster-properties.adoc#log_retention_ms[log_retention_ms] | Default | @@ -2045,7 +2045,7 @@ When `segment.bytes` is set to a positive value, it overrides the cluster proper | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_segment_size[log_segment_size] +| xref:reference:cluster-properties.adoc#log_segment_size[log_segment_size] | Default | @@ -2108,7 +2108,7 @@ This property supports three states: | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#log_segment_ms[log_segment_ms] +| xref:reference:cluster-properties.adoc#log_segment_ms[log_segment_ms] | Default | @@ -2166,7 +2166,7 @@ endif::[] | Corresponding cluster property -| xref:reference:properties/cluster-properties.adoc#write_caching_default[write_caching_default] +| xref:reference:cluster-properties.adoc#write_caching_default[write_caching_default] | Default | diff --git a/modules/reference/partials/rpk-ai-agentic-cluster.adoc b/modules/reference/partials/rpk-ai-agentic-cluster.adoc new file mode 100644 index 0000000000..3f71ccf7ce --- /dev/null +++ b/modules/reference/partials/rpk-ai-agentic-cluster.adoc @@ -0,0 +1 @@ +NOTE: The `rpk ai` commands require an Agentic Data Plane cluster. For more information, see xref:agentic-data-plane:home:index.adoc[]. diff --git a/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-card.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-card.adoc new file mode 100644 index 0000000000..86bc587b76 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-card.adoc @@ -0,0 +1,39 @@ += rpk ai agent a2a card +:description: pass:q[Fetch the A2A agent card — the JSON discovery document describing the agent's identity, skills, supported transports and capabilities. Use `-o json` to feed the raw card to other tools.] +:page-platforms: linux + +// 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[] +Fetch the A2A agent card — the JSON discovery document describing the +agent's identity, skills, supported transports and capabilities. + +Use `-o json` to feed the raw card to other tools. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a card [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a-send.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-send.adoc new file mode 100644 index 0000000000..759ad4d961 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-send.adoc @@ -0,0 +1,99 @@ += rpk ai agent a2a send +:description: Send a text message to an agent over A2A and print the reply. The message comes from the positional argument, or from stdin when the argument is omitted or "-" (so you can pipe a prompt in). +:page-platforms: linux + +// 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[] +Send a text message to an agent over A2A and print the reply. + +The message comes from the positional argument, or from stdin when the +argument is omitted or "-" (so you can pipe a prompt in). + +By default the call blocks until the agent replies. Replies that spawn a +long-running task print the task id so you can follow up with +`rpai agent a2a task get|watch|cancel`. For work that may outlive +`--timeout` (default 5m), prefer `--stream` or `--no-block` so the task id is +in hand from the start. + +Conversation state: every reply prints a context-id (stderr in the +default format, part of the JSON in `-o json`). Pass it back via +`--context-id` to continue the same conversation. When a task ends in +state input-required, answer it by sending again with both `--task-id` +and `--context-id` from the reply. + +Output: the agent's reply text goes to stdout; ids and state go to +stderr as `key: value` lines so pipes stay clean. Use `-o json` for the +full A2A response (message or task object). With `--stream`, `json` and +`yaml` both emit one JSON event per line (JSONL). + +Exit codes: 0 success or input-required, 4 task failed/canceled/ +rejected, 1 anything else. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a send [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk ai agent a2a send`. + +Ask and wait for the answer +[,bash] +---- +rpk ai agent a2a send financial-advisor "What moved the S&P 500 today?" +---- + +Continue the conversation from a previous reply's context-id +[,bash] +---- +rpk ai agent a2a send financial-advisor --context-id CTX "Why?" +---- + +Answer a task that ended in input-required +[,bash] +---- +rpk ai agent a2a send financial-advisor --task-id TASK --context-id CTX "Account A-17" +---- + +Pipe the prompt from a file, get the full JSON reply +[,bash] +---- +cat prompt.txt | rpk ai agent a2a send financial-advisor `-o json` +---- + +Stream events as they happen +[,bash] +---- +rpk ai agent a2a send financial-advisor --stream "Give me a market summary" +---- + +Fire-and-forget: submit, then poll with `task get` +[,bash] +---- +rpk ai agent a2a send financial-advisor --no-block "Deep analysis please" +---- + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a-task-cancel.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-cancel.adoc new file mode 100644 index 0000000000..f18758d85b --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-cancel.adoc @@ -0,0 +1,47 @@ += rpk ai agent a2a task cancel +:description: Ask the agent to cancel a running task and print the task's resulting state. Cancellation is cooperative — the agent may already have finished, in which case the terminal state is returned unchanged. +:page-platforms: linux + +// 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[] +Ask the agent to cancel a running task and print the task's resulting +state. Cancellation is cooperative — the agent may already have +finished, in which case the terminal state is returned unchanged. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a task cancel [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk ai agent a2a task cancel`. + +[,bash] +---- +rpk ai agent a2a task cancel financial-advisor TASK_ID +---- + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a-task-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-get.adoc new file mode 100644 index 0000000000..20ed2dea23 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-get.adoc @@ -0,0 +1,47 @@ += rpk ai agent a2a task get +:description: pass:q[Fetch a task's current state, status message, artifacts and (optionally truncated) message history. Use `-o json` for the full task object.] +:page-platforms: linux + +// 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[] +Fetch a task's current state, status message, artifacts and (optionally +truncated) message history. Use `-o json` for the full task object. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a task get [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk ai agent a2a task get`. + +[,bash] +---- +rpk ai agent a2a task get financial-advisor TASK_ID +rpk ai agent a2a task get financial-advisor TASK_ID --history 10 `-o json` +---- + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a-task-watch.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-watch.adoc new file mode 100644 index 0000000000..486f4e93df --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task-watch.adoc @@ -0,0 +1,52 @@ += rpk ai agent a2a task watch +:description: pass:q[Reattach to a running task's event stream (A2A tasks/resubscribe) and print events until the task reaches a terminal state. Use after a disconnected `--stream` send or a `--no-block` send.] +:page-platforms: linux + +// 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[] +Reattach to a running task's event stream (A2A tasks/resubscribe) and +print events until the task reaches a terminal state. Use after a +disconnected `--stream` send or a `--no-block` send. + +Watch waits as long as the task runs (no timeout by default; bound it +with `--timeout`). Exit codes match send: 0 success or input-required, +4 task failed/canceled/rejected, 1 anything else. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a task watch [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk ai agent a2a task watch`. + +[,bash] +---- +rpk ai agent a2a task watch financial-advisor TASK_ID +rpk ai agent a2a task watch financial-advisor TASK_ID `-o json` # one JSON event per line +---- + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a-task.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task.adoc new file mode 100644 index 0000000000..dc1871961e --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a-task.adoc @@ -0,0 +1,36 @@ += rpk ai agent a2a task +:description: pass:q[Manage tasks created by agent-to-agent (A2A) conversations. Task IDs come from `rpk ai agent a2a send` replies.] +:page-platforms: linux + +// 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 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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a task [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-a2a.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a.adoc new file mode 100644 index 0000000000..2f1a65ab03 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-a2a.adoc @@ -0,0 +1,89 @@ += rpk ai agent a2a +:description: Interact with an agent over the A2A (Agent-to-Agent) protocol. The AGENT argument is either a registry agent name (resolved to the agent's A2A endpoint via its runtime status) or a full A2A endpoint URL (anything starting with http:// or https://). +:page-platforms: linux + +// 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[] +Interact with an agent over the A2A (Agent-to-Agent) protocol. + +The AGENT argument is either a registry agent name (resolved to the +agent's A2A endpoint via its runtime status) or a full A2A endpoint URL +(anything starting with http:// or https://). + +Authentication: your profile's bearer token is attached when the target +is a registry agent or an explicit URL on the profile's dataplane host. +Explicit URLs on other hosts are called without credentials so your +token never leaves the platform (a note on stderr says so when this +happens). + +Output formats: table (`default`, human-readable) and `-o json` / `-o yaml`. +Streams (`--stream`, task watch) emit one JSON event per line under both +`json` and `yaml`. + +Exit codes: 0 success (including tasks waiting for more input), 4 task +ended failed/canceled/rejected, 1 anything else. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent a2a [flags] +---- + + + + +== Examples + +This section provides examples of how to use `rpk ai agent a2a`. + +Discover what an agent can do +[,bash] +---- +rpk ai agent a2a card financial-advisor +---- + +Ask a question (waits for the reply) +[,bash] +---- +rpk ai agent a2a send financial-advisor "How did tech stocks do today?" +---- + +Continue the same conversation +[,bash] +---- +rpk ai agent a2a send financial-advisor --context-id CTX "And yesterday?" +---- + +Stream the reply as it is produced +[,bash] +---- +rpk ai agent a2a send financial-advisor --stream "Summarize the market" +---- + +Inspect, watch, or cancel a long-running task +[,bash] +---- +rpk ai agent a2a task get financial-advisor TASK_ID +rpk ai agent a2a task watch financial-advisor TASK_ID +rpk ai agent a2a task cancel financial-advisor TASK_ID +---- + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-apply.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-apply.adoc new file mode 100644 index 0000000000..cc55852419 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-apply.adoc @@ -0,0 +1,48 @@ += rpk ai agent apply +:description: Reconcile agents from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. +:page-platforms: linux + +// 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[] +Reconcile agents from one or more YAML manifests. + +For each manifest: create the resource if absent, otherwise update only the +fields that are present in the manifest AND differ from the live resource. +Fields you omit are left untouched; to clear a field, write it explicitly. +Lists, maps and oneof variants replace wholesale. Fields that can only be set +at creation time are immutable; changing one is an error. + +Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to +read stdin. + +This does not delete resources absent from the manifests (no prune), and drift +is detected only for the fields a manifest names — see `diff --help`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent apply [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-create.adoc new file mode 100644 index 0000000000..4020d55ee2 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-create.adoc @@ -0,0 +1,36 @@ += rpk ai agent create +:description: Create an agent. +:page-platforms: linux + +// 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[] +Create an agent. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-credential-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-create.adoc new file mode 100644 index 0000000000..9af24c72d4 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-create.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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[] +Create a client ID and secret pair for an agent. The client secret is shown once and cannot be retrieved again. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent credential create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-credential-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-delete.adoc new file mode 100644 index 0000000000..db992e2142 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-delete.adoc @@ -0,0 +1,36 @@ += rpk ai agent credential delete +:description: pass:q[Delete a credential. Specify the full resource name as shown by `rpk ai agent credential list`, for example `agents/my-agent/credentials/abc123`.] +:page-platforms: linux + +// 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[] +Delete a credential. Specify the full resource name as shown by `rpk ai agent credential list`, for example `agents/my-agent/credentials/abc123`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent credential delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-credential-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-list.adoc new file mode 100644 index 0000000000..d8de39f0cc --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential-list.adoc @@ -0,0 +1,36 @@ += rpk ai agent credential list +:description: List an agent's credentials. +:page-platforms: linux + +// 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 an agent's credentials. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent credential list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-credential.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential.adoc new file mode 100644 index 0000000000..07d265ac0a --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-credential.adoc @@ -0,0 +1,36 @@ += rpk ai agent credential +:description: pass:q[Manage an agent's credentials (`create`, list, delete).] +:page-platforms: linux + +// 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 an agent's credentials (`create`, list, delete). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent credential [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-delete.adoc new file mode 100644 index 0000000000..501142b972 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-delete.adoc @@ -0,0 +1,36 @@ += rpk ai agent delete +:description: Delete an agent. +:page-platforms: linux + +// 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[] +Delete an agent. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-diff.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-diff.adoc new file mode 100644 index 0000000000..5f877d1dc2 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-diff.adoc @@ -0,0 +1,42 @@ += rpk ai agent diff +:description: Dry-run of apply for agents. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. +:page-platforms: linux + +// 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[] +Dry-run of apply for agents. Prints, per manifest, whether apply would +create, update (and which fields), or leave the resource unchanged. Exits +non-zero when any change is pending, so CI can gate on `no drift`. + +NOTE: diff proves only that the fields a manifest names match live. It does not +detect resources that exist live but are absent from the manifests (no prune), +nor drift in fields a manifest omits. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent diff [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-get.adoc new file mode 100644 index 0000000000..e6cdcd0cb1 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-get.adoc @@ -0,0 +1,36 @@ += rpk ai agent get +:description: Get an agent. +:page-platforms: linux + +// 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[] +Get an agent. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-list.adoc new file mode 100644 index 0000000000..3e7197cd4c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-list.adoc @@ -0,0 +1,36 @@ += rpk ai agent list +:description: List agents. +:page-platforms: linux + +// 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 agents. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-start.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-start.adoc new file mode 100644 index 0000000000..af45ccf911 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-start.adoc @@ -0,0 +1,36 @@ += rpk ai agent start +:description: Start a managed agent, setting its desired state to running. +:page-platforms: linux + +// 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 managed agent, setting its desired state to running. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent start [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-stop.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-stop.adoc new file mode 100644 index 0000000000..8406694bd1 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-stop.adoc @@ -0,0 +1,36 @@ += rpk ai agent stop +:description: Stop a managed agent, setting its desired state to stopped. +:page-platforms: linux + +// 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 a managed agent, setting its desired state to stopped. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent stop [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-transcript-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript-get.adoc new file mode 100644 index 0000000000..95f889fbb4 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript-get.adoc @@ -0,0 +1,36 @@ += rpk ai agent transcript get +:description: Get a single conversation transcript with its turns. +:page-platforms: linux + +// 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[] +Get a single conversation transcript with its turns. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent transcript get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-transcript-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript-list.adoc new file mode 100644 index 0000000000..149f56ff6f --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript-list.adoc @@ -0,0 +1,36 @@ += rpk ai agent transcript list +:description: List an agent's conversation transcripts. +:page-platforms: linux + +// 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 an agent's conversation transcripts. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent transcript list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-transcript.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript.adoc new file mode 100644 index 0000000000..a8114416dd --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-transcript.adoc @@ -0,0 +1,36 @@ += rpk ai agent transcript +:description: pass:q[Inspect an agent's conversation transcripts (`list`, get).] +:page-platforms: linux + +// 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[] +Inspect an agent's conversation transcripts (`list`, get). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent transcript [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent-update.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent-update.adoc new file mode 100644 index 0000000000..f34ba05c25 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent-update.adoc @@ -0,0 +1,36 @@ += rpk ai agent update +:description: Update an agent. +:page-platforms: linux + +// 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[] +Update an agent. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent update [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-agent.adoc b/modules/reference/partials/rpk-ai/rpk-ai-agent.adoc new file mode 100644 index 0000000000..ab0d38a3a1 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-agent.adoc @@ -0,0 +1,46 @@ += rpk ai agent +:description: Manage agents registered with the Redpanda AI platform. Agents are either managed (adp runs them; configured via a model, LLM provider, system prompt and MCP servers) or self-managed (a metadata-only record tracking a user-hosted agent). +:page-platforms: linux + +// 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 agents registered with the Redpanda AI platform. + +Agents are either managed (adp runs them; configured via a model, LLM +provider, system prompt and MCP servers) or self-managed (a metadata-only +record tracking a user-hosted agent). `create` makes a managed agent by +default; pass `--self-managed` for the metadata-only variant. + +The `credential` subcommand provisions client-id/secret pairs an agent +uses to authenticate against the gateway. The `a2a` subcommand talks to +a running agent over the A2A protocol (fetch its card, send messages, +manage tasks). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai agent [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-auth-login.adoc b/modules/reference/partials/rpk-ai/rpk-ai-auth-login.adoc new file mode 100644 index 0000000000..4718258d01 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-auth-login.adoc @@ -0,0 +1,36 @@ += rpk ai auth login +:description: 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. +:page-platforms: linux + +// 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 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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai auth login [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-auth-logout.adoc b/modules/reference/partials/rpk-ai/rpk-ai-auth-logout.adoc new file mode 100644 index 0000000000..a5fafd2058 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-auth-logout.adoc @@ -0,0 +1,36 @@ += rpk ai auth logout +:description: Delete stored credentials for the current profile (or all). +:page-platforms: linux + +// 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[] +Delete stored credentials for the current profile (or all). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai auth logout [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-auth-status.adoc b/modules/reference/partials/rpk-ai/rpk-ai-auth-status.adoc new file mode 100644 index 0000000000..30cae7074d --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-auth-status.adoc @@ -0,0 +1,36 @@ += rpk ai auth status +:description: Show the authentication state for the current profile. +:page-platforms: linux + +// 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[] +Show the authentication state for the current profile. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai auth status [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-auth-token.adoc b/modules/reference/partials/rpk-ai/rpk-ai-auth-token.adoc new file mode 100644 index 0000000000..dc5353038a --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-auth-token.adoc @@ -0,0 +1,36 @@ += rpk ai auth token +:description: Print the current bearer access token to stdout (refreshes if expired). +:page-platforms: linux + +// 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[] +Print the current bearer access token to stdout (refreshes if expired). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai auth token [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-auth.adoc b/modules/reference/partials/rpk-ai/rpk-ai-auth.adoc new file mode 100644 index 0000000000..cdff4a3f84 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-auth.adoc @@ -0,0 +1,36 @@ += rpk ai auth +:description: pass:q[Manage `rpk` ai authentication (`login`, logout, token, status).] +:page-platforms: linux + +// 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 `rpk` ai authentication (`login`, logout, token, status). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai auth [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-add.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-add.adoc new file mode 100644 index 0000000000..a5baf93551 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-add.adoc @@ -0,0 +1,36 @@ += rpk ai env add +:description: pass:q[Add a manual `rpk` ai environment with explicit URLs.] +:page-platforms: linux + +// 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 a manual `rpk` ai environment with explicit URLs. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env add [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-delete.adoc new file mode 100644 index 0000000000..c9fd955309 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-delete.adoc @@ -0,0 +1,36 @@ += rpk ai env delete +:description: Delete an environment from config and credentials files. +:page-platforms: linux + +// 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[] +Delete an environment from config and credentials files. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-list.adoc new file mode 100644 index 0000000000..08e89ada70 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-list.adoc @@ -0,0 +1,36 @@ += rpk ai env list +:description: List environments (local + live ADP environments, merged). +:page-platforms: linux + +// 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 environments (local + live ADP environments, merged). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-rename.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-rename.adoc new file mode 100644 index 0000000000..ddd6fb44b2 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-rename.adoc @@ -0,0 +1,36 @@ += rpk ai env rename +:description: Rename an environment in both config and credentials files. +:page-platforms: linux + +// 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[] +Rename an environment in both config and credentials files. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env rename [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-show.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-show.adoc new file mode 100644 index 0000000000..62ba281ac2 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-show.adoc @@ -0,0 +1,36 @@ += rpk ai env show +:description: Show the effective resolved environment as YAML (tokens redacted). +:page-platforms: linux + +// 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[] +Show the effective resolved environment as YAML (tokens redacted). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env show [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env-use.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env-use.adoc new file mode 100644 index 0000000000..8d60aae149 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env-use.adoc @@ -0,0 +1,36 @@ += rpk ai env use +:description: Switch to a local environment, or select an ADP environment by name or id. +:page-platforms: linux + +// 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[] +Switch to a local environment, or select an ADP environment by name or id. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env use [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-env.adoc b/modules/reference/partials/rpk-ai/rpk-ai-env.adoc new file mode 100644 index 0000000000..0882a4317d --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-env.adoc @@ -0,0 +1,36 @@ += rpk ai env +:description: pass:q[Manage `rpk` ai environments (`list`, use, add, show, rename, delete).] +:page-platforms: linux + +// 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 `rpk` ai environments (`list`, use, add, show, rename, delete). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai env [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-install.adoc b/modules/reference/partials/rpk-ai/rpk-ai-install.adoc new file mode 100644 index 0000000000..685947ddbb --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-install.adoc @@ -0,0 +1,49 @@ += rpk ai install +:description: Install the Redpanda AI CLI. This command installs the latest version by default. +: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[] +Install the Redpanda AI CLI. + +This command installs the latest version by default. + +Alternatively, you may specify an `rpk` ai version using the `--ai-version` flag. + +You may force the installation using the `--force` flag. + +== Usage + +[,bash] +---- +rpk ai install [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--ai-version |string |Redpanda AI CLI version to install (for example, 0.1.2). +|--force |bool |Force install of the Redpanda AI CLI. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-apply.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-apply.adoc new file mode 100644 index 0000000000..f4d1003bee --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-apply.adoc @@ -0,0 +1,48 @@ += rpk ai llm apply +:description: Reconcile LLM providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. +:page-platforms: linux + +// 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[] +Reconcile LLM providers from one or more YAML manifests. + +For each manifest: create the resource if absent, otherwise update only the +fields that are present in the manifest AND differ from the live resource. +Fields you omit are left untouched; to clear a field, write it explicitly. +Lists, maps and oneof variants replace wholesale. Fields that can only be set +at creation time are immutable; changing one is an error. + +Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to +read stdin. + +This does not delete resources absent from the manifests (no prune), and drift +is detected only for the fields a manifest names — see `diff --help`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm apply [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-check.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-check.adoc new file mode 100644 index 0000000000..51cc23166e --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-check.adoc @@ -0,0 +1,36 @@ += rpk ai llm check +:description: Run a lightweight probe against the configured LLM provider to verify credentials and reachability. +:page-platforms: linux + +// 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 lightweight probe against the configured LLM provider to verify credentials and reachability. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm check [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-create.adoc new file mode 100644 index 0000000000..39caa433a6 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-create.adoc @@ -0,0 +1,36 @@ += rpk ai llm create +:description: Create an LLM provider. +:page-platforms: linux + +// 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[] +Create an LLM provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-delete.adoc new file mode 100644 index 0000000000..515be0d1f0 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-delete.adoc @@ -0,0 +1,36 @@ += rpk ai llm delete +:description: Delete an LLM provider. +:page-platforms: linux + +// 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[] +Delete an LLM provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-diff.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-diff.adoc new file mode 100644 index 0000000000..6b2d97518f --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-diff.adoc @@ -0,0 +1,42 @@ += rpk ai llm diff +:description: Dry-run of apply for LLM providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. +:page-platforms: linux + +// 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[] +Dry-run of apply for LLM providers. Prints, per manifest, whether apply would +create, update (and which fields), or leave the resource unchanged. Exits +non-zero when any change is pending, so CI can gate on `no drift`. + +NOTE: diff proves only that the fields a manifest names match live. It does not +detect resources that exist live but are absent from the manifests (no prune), +nor drift in fields a manifest omits. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm diff [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-get.adoc new file mode 100644 index 0000000000..5745adfb19 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-get.adoc @@ -0,0 +1,36 @@ += rpk ai llm get +:description: Get an LLM provider. +:page-platforms: linux + +// 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[] +Get an LLM provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-list.adoc new file mode 100644 index 0000000000..4a96d51be5 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-list.adoc @@ -0,0 +1,36 @@ += rpk ai llm list +:description: List LLM providers. +:page-platforms: linux + +// 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 LLM providers. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm-update.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm-update.adoc new file mode 100644 index 0000000000..d8a6b38553 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm-update.adoc @@ -0,0 +1,36 @@ += rpk ai llm update +:description: Update an LLM provider. +:page-platforms: linux + +// 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[] +Update an LLM provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm update [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-llm.adoc b/modules/reference/partials/rpk-ai/rpk-ai-llm.adoc new file mode 100644 index 0000000000..d6b714cc4e --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-llm.adoc @@ -0,0 +1,42 @@ += rpk ai llm +:description: Manage LLM providers registered with the Redpanda AI gateway. Supported provider types: openai, anthropic, google, bedrock. +:page-platforms: linux + +// 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 LLM providers registered with the Redpanda AI gateway. + +Supported provider types: openai, anthropic, google, bedrock. + +Aliases: `llm-provider` (compat with aigwctl), `provider`, `lp`. + +Supported provider types: `openai`, `anthropic`, `google`, `bedrock`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai llm [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-apply.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-apply.adoc new file mode 100644 index 0000000000..d0ba493a60 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-apply.adoc @@ -0,0 +1,48 @@ += rpk ai mcp apply +:description: Reconcile MCP servers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. +:page-platforms: linux + +// 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[] +Reconcile MCP servers from one or more YAML manifests. + +For each manifest: create the resource if absent, otherwise update only the +fields that are present in the manifest AND differ from the live resource. +Fields you omit are left untouched; to clear a field, write it explicitly. +Lists, maps and oneof variants replace wholesale. Fields that can only be set +at creation time are immutable; changing one is an error. + +Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to +read stdin. + +This does not delete resources absent from the manifests (no prune), and drift +is detected only for the fields a manifest names — see `diff --help`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp apply [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-create.adoc new file mode 100644 index 0000000000..0258863602 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-create.adoc @@ -0,0 +1,36 @@ += rpk ai mcp create +:description: Create an MCP server. +:page-platforms: linux + +// 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[] +Create an MCP server. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-delete.adoc new file mode 100644 index 0000000000..a3d2e258f3 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-delete.adoc @@ -0,0 +1,36 @@ += rpk ai mcp delete +:description: Delete an MCP server. +:page-platforms: linux + +// 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[] +Delete an MCP server. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-diff.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-diff.adoc new file mode 100644 index 0000000000..856ae3c3eb --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-diff.adoc @@ -0,0 +1,42 @@ += rpk ai mcp diff +:description: Dry-run of apply for MCP servers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. +:page-platforms: linux + +// 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[] +Dry-run of apply for MCP servers. Prints, per manifest, whether apply would +create, update (and which fields), or leave the resource unchanged. Exits +non-zero when any change is pending, so CI can gate on `no drift`. + +NOTE: diff proves only that the fields a manifest names match live. It does not +detect resources that exist live but are absent from the manifests (no prune), +nor drift in fields a manifest omits. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp diff [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-get.adoc new file mode 100644 index 0000000000..118d0e6377 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-get.adoc @@ -0,0 +1,36 @@ += rpk ai mcp get +:description: Get an MCP server. +:page-platforms: linux + +// 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[] +Get an MCP server. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-list.adoc new file mode 100644 index 0000000000..3022620e32 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-list.adoc @@ -0,0 +1,36 @@ += rpk ai mcp list +:description: List MCP servers. +:page-platforms: linux + +// 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 MCP servers. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-tools-call.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools-call.adoc new file mode 100644 index 0000000000..920554911a --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools-call.adoc @@ -0,0 +1,61 @@ += rpk ai mcp tools call +:description: pass:q[Invoke a tool on an MCP server through the aigw MCP proxy. The server's /mcp/v1/ endpoint is reached with the same bearer token used by the rest of `rpk ai`; aigw resolves user-delegated OAuth tokens from the vault when the MCP server is configured with `--user-oauth-provider`.] +:page-platforms: linux + +// 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[] +Invoke a tool on an MCP server through the aigw MCP proxy. + +The server's /mcp/v1/ endpoint is reached with the same bearer token +used by the rest of `rpk ai`; aigw resolves user-delegated OAuth tokens from the +vault when the MCP server is configured with `--user-oauth-provider`. + +Arguments passed to the tool are a JSON object supplied via `--args`. Example: + +`rpk` ai mcp tools call gf-servicenow-sand2 listtablerecords \. + +[,bash] +---- +--args '{"tableName":"incident","sysparm_limit":3}' +---- + +With `--code-mode` the call targets the virtual code-mode sibling endpoint +(/mcp/v1/-code). That endpoint exposes search (tool catalog for the +primary) and execute (runs JavaScript in a sandbox with call_tool bound to +the primary's tools). Example: + +`rpk` ai mcp tools call pg-garrett execute `--code-mode` \. + +[,bash] +---- +--args '{"code":"var r = call_tool({name:\"query\", arguments:{query:\"SELECT 1\"}}); JSON.stringify(r);"}' +---- + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp tools call [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-tools-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools-list.adoc new file mode 100644 index 0000000000..ce5011a592 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools-list.adoc @@ -0,0 +1,48 @@ += rpk ai mcp tools list +:description: List tools on an MCP server by calling tools/list through the aigw MCP proxy. Hits the server's /mcp/v1/ endpoint, so the same auth and token-vault path used by tools/call is exercised here. +:page-platforms: linux + +// 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 tools on an MCP server by calling tools/list through the aigw MCP proxy. + +Hits the server's /mcp/v1/ endpoint, so the same auth and token-vault +path used by tools/call is exercised here. Useful for checking that a managed +MCP's tool schema loaded correctly and that a user-delegated server is +reachable with the caller's vault token. + +With `--code-mode` the session targets the virtual code-mode sibling endpoint +(/mcp/v1/-code), which exposes the sandbox meta-tools (`search`, +execute). To see the parent's tool catalog from the sandbox, invoke the +search tool explicitly: + +`rpk` ai mcp tools call search `--code-mode`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp tools list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-tools.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools.adoc new file mode 100644 index 0000000000..a5f188cad5 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-tools.adoc @@ -0,0 +1,36 @@ += rpk ai mcp tools +:description: Interact with tools on an MCP server. +:page-platforms: linux + +// 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[] +Interact with tools on an MCP server. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp tools [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-types.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-types.adoc new file mode 100644 index 0000000000..9574563a7c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-types.adoc @@ -0,0 +1,36 @@ += rpk ai mcp types +:description: List available managed MCP types. +:page-platforms: linux + +// 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 available managed MCP types. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp types [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp-update.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp-update.adoc new file mode 100644 index 0000000000..648a2f6587 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp-update.adoc @@ -0,0 +1,36 @@ += rpk ai mcp update +:description: Update an MCP server. +:page-platforms: linux + +// 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[] +Update an MCP server. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp update [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-mcp.adoc b/modules/reference/partials/rpk-ai/rpk-ai-mcp.adoc new file mode 100644 index 0000000000..05a6e73694 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-mcp.adoc @@ -0,0 +1,36 @@ += rpk ai mcp +:description: pass:q[Manage MCP servers (`create`, get, list, update, delete, types).] +:page-platforms: linux + +// 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 MCP servers (`create`, get, list, update, delete, types). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai mcp [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-model-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-model-get.adoc new file mode 100644 index 0000000000..9ba3b24917 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-model-get.adoc @@ -0,0 +1,36 @@ += rpk ai model get +:description: Get model details from the catalog. +:page-platforms: linux + +// 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[] +Get model details from the catalog. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai model get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-model-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-model-list.adoc new file mode 100644 index 0000000000..fa013b6b5a --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-model-list.adoc @@ -0,0 +1,36 @@ += rpk ai model list +:description: List available models in the catalog. +:page-platforms: linux + +// 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 available models in the catalog. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai model list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-model.adoc b/modules/reference/partials/rpk-ai/rpk-ai-model.adoc new file mode 100644 index 0000000000..62d9e807c1 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-model.adoc @@ -0,0 +1,44 @@ += rpk ai model +:description: pass:q[Discover the models the Redpanda AI gateway exposes. The catalog is read-only — `model list` and `model get` are the only verbs.] +:page-platforms: linux + +// 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[] +Discover the models the Redpanda AI gateway exposes. + +The catalog is read-only — `model list` and `model get` are the only verbs. The +catalog is populated from each LLM provider's metadata plus any extras the +operator has pinned to a tenant. + +Aliases: `models`, `m`. + +The catalog is read-only. The catalog is populated from each LLM provider's metadata plus any extras the operator has pinned to a tenant. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai model [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-apply.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-apply.adoc new file mode 100644 index 0000000000..35df4a25d6 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-apply.adoc @@ -0,0 +1,48 @@ += rpk ai oauth-client apply +:description: Reconcile OAuth clients from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. +:page-platforms: linux + +// 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[] +Reconcile OAuth clients from one or more YAML manifests. + +For each manifest: create the resource if absent, otherwise update only the +fields that are present in the manifest AND differ from the live resource. +Fields you omit are left untouched; to clear a field, write it explicitly. +Lists, maps and oneof variants replace wholesale. Fields that can only be set +at creation time are immutable; changing one is an error. + +Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to +read stdin. + +This does not delete resources absent from the manifests (no prune), and drift +is detected only for the fields a manifest names — see `diff --help`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client apply [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-create.adoc new file mode 100644 index 0000000000..7efb84972c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-create.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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[] +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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-get.adoc new file mode 100644 index 0000000000..0314cfedff --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-get.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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[] +Show the Dynamic Client Registration (DCR) settings for the current tenant, including whether DCR is enabled and the configured admission mode. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.adoc new file mode 100644 index 0000000000..9177f9e40c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-client dcr iat list +:description: List Initial Access Tokens (plaintext is never shown). +:page-platforms: linux + +// 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 Initial Access Tokens (plaintext is never shown). + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr iat list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.adoc new file mode 100644 index 0000000000..9dffd21c55 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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[] +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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr iat mint [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.adoc new file mode 100644 index 0000000000..b8814d034d --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.adoc @@ -0,0 +1,38 @@ += rpk ai oauth-client dcr iat revoke +:description: Revoke an unconsumed Initial Access Token so it can no longer be exchanged at the registration endpoint. Idempotent — revoking an already-revoked or consumed token returns 0. +:page-platforms: linux + +// 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[] +Revoke an unconsumed Initial Access Token so it can no longer be +exchanged at the registration endpoint. Idempotent — revoking an +already-revoked or consumed token returns 0. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr iat revoke [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat.adoc new file mode 100644 index 0000000000..e9bedb6fc2 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-iat.adoc @@ -0,0 +1,39 @@ += rpk ai oauth-client dcr iat +:description: Manage Initial Access Tokens (IATs) — one-shot bearer credentials a caller presents to the public registration endpoint when the tenant's admission mode is initial-access-token. The plaintext is printed exactly once on mint; only a hash is stored. +:page-platforms: linux + +// 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 Initial Access Tokens (IATs) — one-shot bearer credentials a +caller presents to the public registration endpoint when the tenant's +admission mode is initial-access-token. The plaintext is printed +exactly once on mint; only a hash is stored. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr iat [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr-update.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-update.adoc new file mode 100644 index 0000000000..52097dbdbb --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr-update.adoc @@ -0,0 +1,50 @@ += rpk ai oauth-client dcr update +:description: Update the tenant's DCR settings. Only the flags you pass change; everything else keeps its current value (the CLI reads the current settings and writes back the merged result). +:page-platforms: linux + +// 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[] +Update the tenant's DCR settings. Only the flags you pass change; +everything else keeps its current value (the CLI reads the current +settings and writes back the merged result). + +Enable open self-registration: + +`rpk` ai oauth-client dcr update `--enabled` `--admission-mode` open. + +Require admin-minted Initial Access Tokens instead: + +`rpk` ai oauth-client dcr update `--admission-mode` initial-access-token. + +Turn the endpoint off again: + +`rpk` ai oauth-client dcr update `--enabled=false`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr update [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-dcr.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr.adoc new file mode 100644 index 0000000000..a6236f03c0 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-dcr.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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 Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client dcr [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-delete.adoc new file mode 100644 index 0000000000..d1feba9e95 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-delete.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-client delete +:description: Delete an OAuth client. +:page-platforms: linux + +// 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[] +Delete an OAuth client. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-diff.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-diff.adoc new file mode 100644 index 0000000000..b12b69c3bf --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-diff.adoc @@ -0,0 +1,42 @@ += rpk ai oauth-client diff +:description: Dry-run of apply for OAuth clients. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. +:page-platforms: linux + +// 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[] +Dry-run of apply for OAuth clients. Prints, per manifest, whether apply would +create, update (and which fields), or leave the resource unchanged. Exits +non-zero when any change is pending, so CI can gate on `no drift`. + +NOTE: diff proves only that the fields a manifest names match live. It does not +detect resources that exist live but are absent from the manifests (no prune), +nor drift in fields a manifest omits. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client diff [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-get.adoc new file mode 100644 index 0000000000..d93041f52c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-get.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-client get +:description: Get an OAuth client. +:page-platforms: linux + +// 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[] +Get an OAuth client. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-list.adoc new file mode 100644 index 0000000000..635575337c --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-list.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-client list +:description: List OAuth clients. +:page-platforms: linux + +// 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 OAuth clients. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client-revoke-tokens.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-revoke-tokens.adoc new file mode 100644 index 0000000000..b684b098e3 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client-revoke-tokens.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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[] +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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client revoke-tokens [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-client.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client.adoc new file mode 100644 index 0000000000..dfae1b5514 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-client.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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 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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-client [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-apply.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-apply.adoc new file mode 100644 index 0000000000..c178c5325b --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-apply.adoc @@ -0,0 +1,48 @@ += rpk ai oauth-provider apply +:description: Reconcile OAuth providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. +:page-platforms: linux + +// 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[] +Reconcile OAuth providers from one or more YAML manifests. + +For each manifest: create the resource if absent, otherwise update only the +fields that are present in the manifest AND differ from the live resource. +Fields you omit are left untouched; to clear a field, write it explicitly. +Lists, maps and oneof variants replace wholesale. Fields that can only be set +at creation time are immutable; changing one is an error. + +Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to +read stdin. + +This does not delete resources absent from the manifests (no prune), and drift +is detected only for the fields a manifest names — see `diff --help`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider apply [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-create.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-create.adoc new file mode 100644 index 0000000000..8f8826f1c3 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-create.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-provider create +:description: Create an OAuth provider. +:page-platforms: linux + +// 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[] +Create an OAuth provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider create [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-delete.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-delete.adoc new file mode 100644 index 0000000000..4f7bee5481 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-delete.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-provider delete +:description: Delete an OAuth provider. +:page-platforms: linux + +// 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[] +Delete an OAuth provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider delete [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-diff.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-diff.adoc new file mode 100644 index 0000000000..fa0838189b --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-diff.adoc @@ -0,0 +1,42 @@ += rpk ai oauth-provider diff +:description: Dry-run of apply for OAuth providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. +:page-platforms: linux + +// 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[] +Dry-run of apply for OAuth providers. Prints, per manifest, whether apply would +create, update (and which fields), or leave the resource unchanged. Exits +non-zero when any change is pending, so CI can gate on `no drift`. + +NOTE: diff proves only that the fields a manifest names match live. It does not +detect resources that exist live but are absent from the manifests (no prune), +nor drift in fields a manifest omits. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider diff [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-get.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-get.adoc new file mode 100644 index 0000000000..2899ca32f8 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-get.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-provider get +:description: Get an OAuth provider. +:page-platforms: linux + +// 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[] +Get an OAuth provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider get [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-list.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-list.adoc new file mode 100644 index 0000000000..3ceead9d1e --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-list.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-provider list +:description: List OAuth providers. +:page-platforms: linux + +// 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 OAuth providers. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider list [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider-update.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-update.adoc new file mode 100644 index 0000000000..d0ef857686 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider-update.adoc @@ -0,0 +1,36 @@ += rpk ai oauth-provider update +:description: Update an OAuth provider. +:page-platforms: linux + +// 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[] +Update an OAuth provider. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider update [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-oauth-provider.adoc b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider.adoc new file mode 100644 index 0000000000..f207fdadb5 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-oauth-provider.adoc @@ -0,0 +1,36 @@ += 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. +:page-platforms: linux + +// 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 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. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai oauth-provider [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-run-claude.adoc b/modules/reference/partials/rpk-ai/rpk-ai-run-claude.adoc new file mode 100644 index 0000000000..df9bb2bd86 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-run-claude.adoc @@ -0,0 +1,85 @@ += rpk ai run claude +:description: pass:q[Launch Anthropic's Claude Code CLI with its model traffic routed through the Redpanda AI gateway for the active `rpk` ai profile. `rpk` ai points ANTHROPIC_BASE_URL at the gateway's Anthropic Messages endpoint for the chosen provider and wires the gateway auth for the life of the session.] +:page-platforms: linux + +// 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[] +Launch Anthropic's Claude Code CLI with its model traffic +routed through the Redpanda AI gateway for the active `rpk` ai profile. + +`rpk` ai points ANTHROPIC_BASE_URL at the gateway's Anthropic Messages endpoint for +the chosen provider and wires the gateway auth for the life of the session. No +token is ever written to disk. + +Both auth modes run in your REAL Claude Code config home, so your workspace +trust, onboarding, theme, and MCP servers all apply. `rpk` ai writes nothing into +`~/.claude` in either mode: + +* managed (api key): the gateway apiKeyHelper (`rpai auth token`, which Claude + Code re-runs to refresh the bearer; aigw injects the upstream Anthropic key) + is passed via `claude --settings` as a JSON string — off disk, merged on top + of your settings, your `~/.claude/settings.json` untouched. + +* passthrough (enterprise/Max subscription): your existing subscription login + (stored under your config home) is used. `rpk` ai only sets the gateway base URL + and the X-Redpanda-Cloud-Token header (minted fresh at launch) in the + environment; your subscription OAuth flows through aigw to Anthropic untouched. + +Pass `--claude-config-dir` to run against an isolated config home instead of your +real one (`rpk` ai still never writes into it). + +In passthrough mode the X-Redpanda-Cloud-Token gateway JWT is set in the +launched process environment, so Claude Code's tool subprocesses (Bash, hooks, +MCP) inherit it — the same Redpanda Cloud token any process running as you can +already mint with `rpai auth token`, and Claude Code has no documented mechanism +to scrub it from those subprocesses. + +Because passthrough uses your real config home, any auth configured in your +`~/.claude/settings.json` (an apiKeyHelper, or env.ANTHROPIC_AUTH_TOKEN) still +applies and outranks the subscription OAuth aigw needs to relay — `rpk` ai scrubs +only the inherited shell env, not your on-disk settings. + +Anthropic and Bedrock providers are supported. A bedrock provider launches +Claude Code in its native Bedrock mode pointed at the same gateway prefix; aigw +signs the upstream call with the provider's AWS credentials (SigV4), so no AWS +keys ever reach your machine and the managed apiKeyHelper auth works exactly as +above (passthrough does not apply — there is no Bedrock analog of a Claude +subscription). Pass `-m` an inference-profile id from the provider's model +allowlist (Bedrock Anthropic models 4.6+ carry a us./eu./apac./global. prefix). +Claude Code's background (small/fast) model defaults to a Haiku-class inference +profile in Bedrock mode; if the provider`s allowlist doesn`t include it, export +ANTHROPIC_SMALL_FAST_MODEL with an allowlisted id. + +Pass Claude Code's own flags after a literal --: + +`rpk` ai run claude `-L` anthropic `-m` claude-sonnet-4-6 -- `--permission-mode` plan + `rpk` ai run claude `-L` bedrock `-m` us.anthropic.claude-sonnet-4-6 -- `-p` `hi`. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai run claude [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-run-codex.adoc b/modules/reference/partials/rpk-ai/rpk-ai-run-codex.adoc new file mode 100644 index 0000000000..abab42a751 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-run-codex.adoc @@ -0,0 +1,52 @@ += rpk ai run codex +:description: pass:q[Launch the OpenAI Codex CLI with its model traffic routed through the Redpanda AI gateway for the active `rpk` ai profile. `rpk` ai generates a throwaway Codex config in a temporary CODEX_HOME, points it at the gateway's OpenAI-compatible Responses endpoint for the chosen provider, and wires Codex's bearer to `rpai auth token` so it refreshes itself for the life of the session.] +:page-platforms: linux + +// 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[] +Launch the OpenAI Codex CLI with its model traffic routed +through the Redpanda AI gateway for the active `rpk` ai profile. + +`rpk` ai generates a throwaway Codex config in a temporary CODEX_HOME, points it at +the gateway's OpenAI-compatible Responses endpoint for the chosen provider, and +wires Codex's bearer to `rpai auth token` so it refreshes itself for the +life of the session. Your own `~/.codex` config is never read or modified, and no +token is written to disk. + +The launch directory is auto-trusted under a workspace-write sandbox +(approval_policy=on-request) so the fresh CODEX_HOME doesn't prompt for trust on +every run; pass `--no-auto-trust` to keep Codex's normal first-run trust prompt. + +Only openai / openai_compatible providers are supported (Codex speaks the OpenAI +Responses API). Pass Codex's own flags after a literal --: + +`rpk` ai run codex `-L` openai `-m` gpt-5.3-codex `-e` high -- `--ask-for-approval` never. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai run codex [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-run.adoc b/modules/reference/partials/rpk-ai/rpk-ai-run.adoc new file mode 100644 index 0000000000..3c616e3a00 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-run.adoc @@ -0,0 +1,38 @@ += rpk ai run +:description: pass:q[Launch a third-party coding agent configured to send its model traffic through the Redpanda AI gateway for the active profile, reusing `rpk ai`'s login and auto-refreshing token.] +:page-platforms: linux + +// 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[] +Launch a third-party coding agent configured to send its model traffic +through the Redpanda AI gateway for the active profile, reusing `rpk ai`'s +login and auto-refreshing token. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai run [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-uninstall.adoc b/modules/reference/partials/rpk-ai/rpk-ai-uninstall.adoc new file mode 100644 index 0000000000..a971a80c43 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-uninstall.adoc @@ -0,0 +1,34 @@ += rpk ai uninstall +:description: Uninstall the Redpanda AI CLI. +: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 AI CLI. + +== Usage + +[,bash] +---- +rpk ai uninstall [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-upgrade.adoc b/modules/reference/partials/rpk-ai/rpk-ai-upgrade.adoc new file mode 100644 index 0000000000..6f23e1f03e --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-upgrade.adoc @@ -0,0 +1,42 @@ += rpk ai upgrade +:description: Upgrade to the latest Redpanda AI CLI 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 AI CLI version. + +== Usage + +[,bash] +---- +rpk ai upgrade [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--no-confirm |bool |Disable confirmation prompt for major version upgrades. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai-version.adoc b/modules/reference/partials/rpk-ai/rpk-ai-version.adoc new file mode 100644 index 0000000000..767562c213 --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai-version.adoc @@ -0,0 +1,36 @@ += rpk ai version +:description: pass:q[Print `rpk` ai version and commit.] +:page-platforms: linux + +// 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[] +Print `rpk` ai version and commit. + +NOTE: This command is only available on Linux. + +== Usage + +[,bash] +---- +rpk ai version [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-ai/rpk-ai.adoc b/modules/reference/partials/rpk-ai/rpk-ai.adoc new file mode 100644 index 0000000000..a12672247b --- /dev/null +++ b/modules/reference/partials/rpk-ai/rpk-ai.adoc @@ -0,0 +1,36 @@ += rpk ai +:description: Manage the Redpanda AI Gateway. +: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[] +include::partial$rpk-ai-agentic-cluster.adoc[] + +Manage the Redpanda AI Gateway. + +== Usage + +[,bash] +---- +rpk ai [flags] +---- + + + + + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-cloud/rpk-cloud-auth-delete.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-delete.adoc index 9a31c73d01..d80d121bff 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-auth-delete.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-delete.adoc @@ -1,36 +1,42 @@ = rpk cloud auth delete -// tag::single-source[] +:description: pass:q[Delete an `rpk` cloud authentication. Deleting a cloud authentication removes it from the `rpk.yaml` file.] +: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 -Delete an `rpk` cloud authentication (auth). +// tag::single-source[] +Delete an `rpk` cloud authentication. -Deleting a cloud authentication removes it from the `rpk.yaml` file. If the deleted -authentication was the current authentication, `rpk` will use a default SSO authentication the next time -you try to login, and if the login is successful, it will save the authentication. +Deleting a cloud authentication removes it from the `rpk.yaml` file. If the +deleted auth was the current authentication, `rpk` will use a default SSO auth the +next time you try to login and save that auth. -If you delete an authentication that is used by profiles, affected profiles have their authentication cleared and you will only be able to access the profile's cluster using SASL credentials. +If you delete an authentication that is used by profiles, affected profiles have +their authentication cleared and you will only be able to access the profile's +cluster using SASL credentials. == Usage [,bash] ---- -rpk cloud auth delete [NAME] [flags] +rpk cloud auth delete [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for delete. -|--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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-auth-list.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-list.adoc index a177ace1b1..21b62680a6 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-auth-list.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-list.adoc @@ -1,7 +1,11 @@ = rpk cloud auth list -// tag::single-source[] +:description: pass:q[List `rpk` cloud authentications.] +: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 -List `rpk` cloud authentications (auths). +// tag::single-source[] +List `rpk` cloud authentications. == Usage @@ -10,28 +14,27 @@ List `rpk` cloud authentications (auths). rpk cloud auth list [flags] ---- + + == Aliases [,bash] ---- -list, ls +rpk cloud auth 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. - -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-auth-token.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-token.adoc index 4736d7944b..d30b861523 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-auth-token.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-token.adoc @@ -1,7 +1,15 @@ = rpk cloud auth token +:description: Print the cloud auth token of the current profile. This command prints the auth token for the currently selected cloud authentication to stdout. +: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[] +Print the cloud auth token of the current profile. -The `rpk cloud auth token` command prints the auth token for the currently selected cloud authentication to stdout. This is useful for piping the token into other commands or scripts that need to authenticate with Redpanda Cloud. For an example, see xref:sql:connect-to-sql/authenticate.adoc[Authenticate to Redpanda SQL]. +This command prints the auth token for the currently selected cloud +authentication to stdout. This is useful for piping the token into other +commands or scripts that need to authenticate with Redpanda Cloud. == Usage @@ -10,21 +18,21 @@ The `rpk cloud auth token` command prints the auth token for the currently selec rpk cloud auth token [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for token. -|--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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-auth-use.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-use.adoc index 5dd3bb628d..5492c9fe06 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-auth-use.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-auth-use.adoc @@ -1,32 +1,39 @@ = rpk cloud auth use -// tag::single-source[] +:description: pass:q[Select the `rpk` cloud authentication to use. This swaps the current cloud authentication to the specified cloud authentication.] +: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 -Select the `rpk` cloud authentication (auth) to use. +// tag::single-source[] +Select the `rpk` cloud authentication to use. -This swaps the current cloud authentication to the specified cloud authentication. If your current profile is a cloud profile, this unsets the current profile (because the authorization is now different). If your current profile is for a Redpanda Streaming cluster, the profile is kept. +This swaps the current cloud authentication to the specified cloud +authentication. If your current profile is a cloud profile, this unsets the +current profile (since the authentication is now different). If your current +profile is for a self hosted cluster, the profile is kept. == Usage [,bash] ---- -rpk cloud auth use [NAME] [flags] +rpk cloud auth use [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-h, --help |- |Help for use. -|--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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-auth.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-auth.adoc index fede2fdb2b..8a41fbbbfb 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-auth.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-auth.adoc @@ -1,37 +1,61 @@ = rpk cloud auth -// tag::single-source[] +:description: pass:q[Manage `rpk` cloud authentications. An `rpk` cloud authentication allows you to talk to Redpanda Cloud.] +: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 -Manage `rpk` cloud authentications (auths). +// tag::single-source[] +Manage `rpk` cloud authentications. An `rpk` cloud authentication allows you to talk to Redpanda Cloud. Most likely, you will only ever need to use a single SSO based login and you will not need this command space. Multiple authentications can be useful if you have multiple -Redpanda Cloud accounts for different organizations and you want to swap between -them, or if you use both SSO and client credentials. Redpanda Data recommends -using only a single SSO based login. +Redpanda Cloud accounts for different organizations and want to swap between +them, or if you use SSO as well as client credentials. It is recommended to +only use a single SSO based login. == Usage [,bash] ---- -rpk cloud auth [command] [flags] +rpk cloud auth [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|-h, --help |- |Help for auth. +|xref:reference:rpk/rpk-cloud/rpk-cloud-auth-delete.adoc[`rpk cloud auth delete`] +|Delete an `rpk` cloud authentication. Deleting a cloud authentication removes it from the `rpk.yaml` file. -|--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-cloud/rpk-cloud-auth-list.adoc[`rpk cloud auth list`] +|List `rpk` cloud authentications. -|-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-cloud/rpk-cloud-auth-token.adoc[`rpk cloud auth token`] +|Print the cloud auth token of the current profile. This command prints the auth token for the currently selected cloud authentication to stdout. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-cloud/rpk-cloud-auth-use.adoc[`rpk cloud auth use`] +|Select the `rpk` cloud authentication to use. This swaps the current cloud authentication to the specified cloud authentication. + +|=== + + +== 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 `~/.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/partials/rpk-cloud/rpk-cloud-byoc-install.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-install.adoc index 559560c92c..48deb4cc61 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-install.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-install.adoc @@ -1,16 +1,16 @@ = rpk cloud byoc install -// tag::single-source[] +:description: Install the BYOC plugin This command downloads the BYOC managed plugin if necessary. The plugin is installed by default if you try to run a non-install command, but this command exists if you want to download the plugin ahead of time. +:page-platforms: linux,darwin -Install the BYOC plugin. +// 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 -include::reference:partial$rpk-cloud-byoc-concept.adoc[] +// tag::single-source[] +Install the BYOC plugin. -This command downloads the BYOC managed plugin, if necessary. The plugin is -installed by default if you run a non-install command. This command +This command downloads the BYOC managed plugin if necessary. The plugin is +installed by default if you try to run a non-install command, but this command exists if you want to download the plugin ahead of time. -To define your `client_id` and `client_secret` use the `-X` flag. - == Example [,bash] @@ -25,23 +25,29 @@ rpk cloud byoc install -X cloud.client_id= -X cloud.client_secre rpk cloud byoc install [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for install. - -|--redpanda-id |string |The redpanda ID of the cluster you are creating. +|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`. +|--redpanda-id |string |The Redpanda ID of the cluster you are creating. +|=== -|-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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-byoc-uninstall.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-uninstall.adoc index a73c90d2a4..b0c73fd9c2 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-uninstall.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc-uninstall.adoc @@ -1,13 +1,15 @@ = rpk cloud byoc uninstall -// tag::single-source[] +:description: Uninstall the BYOC plugin This command deletes your locally downloaded BYOC managed plugin if it exists. Often, you only need to download the plugin to create your cluster once, and then you never need the plugin again. +:page-platforms: linux,darwin -Uninstall the BYOC plugin. +// 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 -include::reference:partial$rpk-cloud-byoc-concept.adoc[] +// tag::single-source[] +Uninstall the BYOC plugin. -This command deletes your locally-downloaded BYOC managed plugin, if it exists. -You generally only need to download the plugin one time to create your cluster, and -then you never need the plugin again. You can uninstall it to save a small bit of +This command deletes your locally downloaded BYOC managed plugin if it exists. +Often, you only need to download the plugin to create your cluster once, and +then you never need the plugin again. You can uninstall to save a small bit of disk space. == Usage @@ -17,21 +19,21 @@ disk space. rpk cloud byoc 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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-byoc.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc.adoc index fc76a034d3..4060693f42 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-byoc.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-byoc.adoc @@ -1,40 +1,67 @@ = rpk cloud byoc -// tag::single-source[] +:description: Manage a Redpanda Cloud BYOC agent For BYOC, Redpanda installs an agent service in your owned cluster. The agent then proceeds to provision further infrastructure and eventually, a full 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[] Manage a Redpanda Cloud BYOC agent. -include::reference:partial$rpk-cloud-byoc-concept.adoc[] +For BYOC, Redpanda installs an agent service in your owned cluster. The agent +then proceeds to provision further infrastructure and eventually, a full +Redpanda cluster. + +The BYOC command runs Terraform to create and start the agent. You first need +a redpanda-id (or cluster ID); this is used to get the details of how your +agent should be provisioned. You can create a BYOC cluster in our cloud UI +and then come back to this command to complete the process. == Usage [,bash] ---- -rpk cloud byoc [command] [flags] +rpk cloud byoc [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description -|--client-id |string |The client ID of the organization in Redpanda -Cloud. +|xref:reference:rpk/rpk-cloud/rpk-cloud-byoc-install.adoc[`rpk cloud byoc install`] +|Install the BYOC plugin This command downloads the BYOC managed plugin if necessary. The plugin is installed by default if you try to run a non-install command, but this command exists if you want to download the plugin ahead of time. -|--client-secret |string |The client secret of the organization in -Redpanda Cloud. +|xref:reference:rpk/rpk-cloud/rpk-cloud-byoc-uninstall.adoc[`rpk cloud byoc uninstall`] +|Uninstall the BYOC plugin This command deletes your locally downloaded BYOC managed plugin if it exists. Often, you only need to download the plugin to create your cluster once, and then you never need the plugin again. -|-h, --help |- |Help for byoc. +|=== + +== Flags -|--redpanda-id |string |The redpanda ID of the cluster you are creating. +[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`. +|--client-id |string |The client ID of the organization in Redpanda Cloud. +|--client-secret |string |The client secret of the organization in Redpanda Cloud. +|--redpanda-id |string |The Redpanda ID of the cluster you are creating. +|=== -|-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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-cluster-select.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-cluster-select.adoc index eb4115646f..05fd052414 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-cluster-select.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-cluster-select.adoc @@ -1,49 +1,64 @@ = rpk cloud cluster select -// tag::single-source[] +:description: pass:q[Update your rpk profile to talk to the requested cluster. This command is essentially an alias for the following command: [,bash] ---- rpk profile create --from-cloud=${NAME} ---- If you want to name this profile rather than creating or updating values in the default cloud-dedicated profile, you can use the `--profile` 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 -Update your rpk profile to communicate with the requested cluster. +// tag::single-source[] +Update your rpk profile to talk to the requested cluster. This command is essentially an alias for the following command: -```bash +[,bash] +---- rpk profile create --from-cloud=${NAME} -``` +---- -If you want to name this profile rather than creating or updating values in the default cloud-dedicated profile, you can use the `--profile` flag. +If you want to name this profile rather than creating or updating values in +the default cloud-dedicated profile, you can use the `--profile` flag. -For Serverless clusters that support both public and private networking, you are prompted to select a network type unless you specify `--serverless-network`. To avoid prompts in automation, explicitly set `--serverless-network` to `public` or `private`. +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`. == Usage [,bash] ---- -rpk cloud cluster select [NAME] [flags] +rpk cloud cluster select [flags] ---- + + == Aliases [,bash] ---- -select, use +rpk cloud cluster use ---- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for select. - -|--profile |string |Name of a profile to create or update (avoids updating "rpk-cloud"). +|Value |Type |Description -|--serverless-network |string |Networking type for Serverless clusters: `public` or `private` (if not specified, will prompt if both are available). +|--profile |string |Name of a profile to create or update (avoids updating `rpk-cloud`). +|--serverless-network |string |Networking type for serverless clusters: `public` or `private` (if not specified, will prompt if both are available). +|=== -|--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`. +== Global flags -|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-cloud/rpk-cloud-cluster.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-cluster.adoc index f98e6330e1..9374b833ac 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-cluster.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-cluster.adoc @@ -1,32 +1,48 @@ = rpk cloud cluster -// tag::single-source[] +:description: pass:q[Manage `rpk` cloud clusters. This command allows you to manage cloud clusters, as well as easily switch between which cluster you are talking to.] +: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 -Manage rpk cloud clusters. +// tag::single-source[] +Manage `rpk` cloud clusters. -This command allows you to manage cloud clusters, and to easily switch between the clusters you are communicating with. +This command allows you to manage cloud clusters, as well as easily switch +between which cluster you are talking to. == Usage [,bash] ---- -rpk cloud cluster [command] [flags] +rpk cloud cluster [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-cloud/rpk-cloud-cluster-select.adoc[`rpk cloud cluster select`] +|Update your rpk profile to talk to the requested cluster. This command is essentially an alias for the following command: [,bash] ---- rpk profile create --from-cloud=${NAME} ---- If you want to name this profile rather than creating or updating values in the default cloud-dedicated profile, you can use the `--profile` flag. -|-h, --help |- |Help for 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`. -|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-cloud/rpk-cloud-login.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-login.adoc index e887e73ca6..c36777d605 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-login.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-login.adoc @@ -1,72 +1,78 @@ = rpk cloud login -// tag::single-source[] +:description: Log in to the Redpanda Cloud This command checks for an existing Redpanda Cloud API token and, if present, ensures it is still valid. If no token is found or the token is no longer valid, this command will login and save your token along with the client ID used to request the token. +:page-platforms: linux,darwin -Log in to Redpanda Cloud. +// 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 checks for an existing Redpanda Cloud API token and, if present, -ensures it is still valid. If no token is found or the token is no longer valid, -this command will login and save your token along with the client ID used to -request the token. +// tag::single-source[] +Log in to the Redpanda Cloud. -== Login credentials +This command checks for an existing Redpanda Cloud API token and, if present, +ensures it is still valid. If no token is found or the token is no longer valid, +this command will login and save your token along with the client ID used to +request the token. You may use either SSO or client credentials to log in. -=== SSO +== Usage + +[,bash] +---- +rpk cloud login [flags] +---- + -This will automatically launch your default web browser and prompt you to -authenticate via our Redpanda Cloud page. Once you have successfully -authenticated, you will be ready to use `rpk cloud` commands. +=== Sso -=== Client credentials +This will automatically launch your default web browser and prompt you to +authenticate via our Redpanda Cloud page. Once you have successfully +authenticated, you will be ready to use `rpk` cloud commands. -Cloud client credentials can be used to login to Redpanda, they can be created -in the Clients tab of the Users section in the Redpanda Cloud online interface. +You may opt out of auto-opening the browser by passing the `--no-browser` flag. + +=== Client Credentials + +Cloud client credentials can be used to login to Redpanda, they can be created +in the Clients tab of the Users section in the Redpanda Cloud online interface. client credentials can be provided in three ways, in order of preference: -* In your `rpk cloud auth`, `client_id` and `client_secret` fields -* Through `RPK_CLOUD_CLIENT_ID` and `RPK_CLOUD_CLIENT_SECRET` environment variables +* In your `rpk` cloud auth, `client_id` and `client_secret` fields + +* Through RPK_CLOUD_CLIENT_ID and RPK_CLOUD_CLIENT_SECRET environment variables + * Through the `--client-id` and `--client-secret` flags -If none of these are provided, `rpk` will use the SSO method to login. +If none of these are provided, `rpk` will use the SSO method to login. If you specify environment variables or flags, they will not be synced to the -`rpk.yaml` file unless the `--save` flag is passed. The cloud authorization +`rpk.yaml` file unless the `--save` flag is passed. The cloud authorization token and client ID is always synced. -== Usage -[,bash] ----- -rpk cloud login [flags] ----- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--client-id |string |The client ID of the organization in Redpanda -Cloud. +|Value |Type |Description -|--client-secret |string |The client secret of the organization in -Redpanda Cloud. - -|-h, --help |- |Help for login. - -|--no-profile |- |Skip automatic profile creation and any associated -prompts. - -|--save |- |Save environment or flag specified client ID and client -secret to the configuration file. - -|--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`. +|--client-id |string |The client ID of the organization in Redpanda Cloud. +|--client-secret |string |The client secret of the organization in Redpanda Cloud. +|--no-browser |bool |Opt out of auto-opening authentication URL. +|--no-profile |bool |Skip automatic profile creation and any associated prompts. +|--save |bool |Save environment or flag specified client ID and client secret to the configuration file. +|=== -|-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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-logout.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-logout.adoc index 05f05625d3..dce86df402 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-logout.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-logout.adoc @@ -1,11 +1,18 @@ = rpk cloud logout -// tag::single-source[] +:description: pass:q[Log out from Redpanda Cloud This command deletes your cloud auth token. If you want to log out entirely and switch to a different organization, you can use the `--clear-credentials` flag to additionally clear your client ID and client secret.] +: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 -Log out from Redpanda cloud. +// tag::single-source[] +Log out from Redpanda Cloud. -This command deletes your cloud authentication token. If you want to log out entirely and +This command deletes your cloud auth token. If you want to log out entirely and switch to a different organization, you can use the `--clear-credentials` flag to -additionally clear your client ID and client secret. You can use the --all flag to log out of all organizations you may be logged into. +additionally clear your client ID and client secret. + +You can use the `--all` flag to log out of all organizations you may be logged +into. == Usage @@ -14,26 +21,30 @@ additionally clear your client ID and client secret. You can use the --all flag rpk cloud logout [flags] ---- -== Flags -[cols="1m,1a,2a"] -|=== -|*Value* |*Type* |*Description* -|-a, --all |- |Log out of all organizations you may be logged into, rather than just the current authentication's organization. -|-c, --clear-credentials |- |Clear the client ID and client secret in -addition to the authentication token. +== Flags -|-h, --help |- |Help for logout. +[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`. +|-a, --all |bool |Log out of all organizations you may be logged into, rather than just the current auth's organization. +|-c, --clear-credentials |bool |Clear the client ID and client secret in addition to the auth token. +|=== -|-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 -|--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 `~/.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/partials/rpk-cloud/rpk-cloud-mcp-install.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-install.adoc index 9318d5dc09..cabec012dd 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-install.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-install.adoc @@ -1,5 +1,8 @@ = rpk cloud mcp install -:description: Install the local MCP server for Redpanda Cloud configuration. +:description: Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud. This 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. +: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[] Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud. @@ -8,46 +11,54 @@ This command generates and installs the necessary configuration files for your M Supports Claude Desktop and Claude Code. -== Usage +== Examples + +This section provides examples of how to use `rpk cloud mcp install`. + +Install configuration for Claude Code: [,bash] ---- -rpk cloud mcp install [flags] +rpk cloud mcp install --client claude-code ---- -== Examples - -Install configuration for Claude Code: +== Usage [,bash] ---- -rpk cloud mcp install --client claude-code +rpk cloud mcp install [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|--allow-delete |- |Allow delete operations (RPCs). Off by default. +|Value |Type |Description +|--allow-delete |bool |Allow delete RPCs. |--client |string |Name of the MCP client to configure. Supported values: `claude` or `claude-code`. +|=== -|-h, --help |- |Help for install. - -|--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 -|--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 `~/.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:ai-agents:mcp/local/quickstart.adoc[] * xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[] -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-proxy.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-proxy.adoc new file mode 100644 index 0000000000..5698a1a66a --- /dev/null +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-proxy.adoc @@ -0,0 +1,51 @@ += rpk cloud mcp proxy +:description: Proxy MCP requests to a remote Redpanda Cloud MCP server. This command connects to a specific cluster and MCP server running in that cluster, then proxies MCP requests from stdio to the remote MCP server over HTTP. +: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[] +Proxy MCP requests to a remote Redpanda Cloud MCP server. + +This command connects to a specific cluster and MCP server running in that cluster, +then proxies MCP requests from stdio to the remote MCP server over HTTP. + +Use `--install` to configure the MCP client instead of serving stdio. + +== Usage + +[,bash] +---- +rpk cloud mcp proxy [flags] +---- + + + + +== Flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--client |string |Name of the MCP client to configure (required with `--install`). +|--cluster-id |string |Cluster ID to connect to. +|--install |bool |Install MCP proxy configuration instead of serving stdio. +|--mcp-server-id |string |MCP Server ID to proxy to. +|--serverless-cluster-id |string |Serverless cluster ID to connect to. +|=== + +== Global flags + +[cols="1m,1a,2a"] +|=== +|Value |Type |Description + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-cloud/rpk-cloud-mcp-stdio.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-stdio.adoc index 64a0d5ed39..9cc3a975ed 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-stdio.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp-stdio.adoc @@ -1,51 +1,63 @@ = rpk cloud mcp stdio -:description: Communicate with local MCP server for Redpanda Cloud using the stdio protocol. -// tag::single-source[] +:description: Communicate with the local MCP server for Redpanda Cloud using the stdio protocol. This command provides a direct stdio interface for communicating with the local MCP server for Redpanda Cloud. +: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[] Communicate with the local MCP server for Redpanda Cloud using the stdio protocol. This 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. Most users should use xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install`] instead, which automatically configures your MCP client. -== Usage +== Examples + +This section provides examples of how to use `rpk cloud mcp stdio`. + +Start the local MCP server for Redpanda Cloud using the stdio protocol: [,bash] ---- -rpk cloud mcp stdio [flags] +rpk cloud mcp stdio ---- -== Examples - -Start the local MCP server for Redpanda Cloud using the stdio protocol: +== Usage [,bash] ---- -rpk cloud mcp stdio +rpk cloud mcp stdio [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|--allow-delete |- |Allow delete operations (RPCs). Off by default. - -|-h, --help |- |Help for stdio. - -|--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`. +|--allow-delete |bool |Allow delete RPCs. Off by default. +|=== -|-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 -|--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 `~/.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-cloud/rpk-cloud-mcp-install.adoc[] * xref:ai-agents:mcp/local/overview.adoc[] -// end::single-source[] \ No newline at end of file +// end::single-source[] diff --git a/modules/reference/partials/rpk-cloud/rpk-cloud-mcp.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp.adoc index 04998de61c..f778286ce0 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud-mcp.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud-mcp.adoc @@ -1,50 +1,51 @@ = rpk cloud mcp -:description: Manage connections to MCP servers in Redpanda Cloud. -// tag::single-source[] +:description: Manage Redpanda Cloud MCP server. +:page-platforms: linux,darwin -Manage connections to the local MCP server for Redpanda Cloud. +// 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 -These commands help you connect AI assistants like Claude to the local MCP server for Redpanda Cloud, which runs on your local machine and provides access to your Redpanda Cloud account and clusters. +// tag::single-source[] +Manage Redpanda Cloud MCP server. == Usage [,bash] ---- rpk cloud mcp [flags] - rpk cloud mcp [command] ---- + + + == Subcommands -[cols="1m,2a"] +[cols="1,2a"] |=== |Command |Description -|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[install] |Install the local MCP server for Redpanda Cloud configuration. +|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install`] +|Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud. This 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. -|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[stdio] |Communicate with the local MCP server for Redpanda Cloud using the stdio protocol. -|=== +|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-proxy.adoc[`rpk cloud mcp proxy`] +|Proxy MCP requests to a remote Redpanda Cloud MCP server. This command connects to a specific cluster and MCP server running in that cluster, then proxies MCP requests from stdio to the remote MCP server over HTTP. -== Flags +|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[`rpk cloud mcp stdio`] +|Communicate with the local MCP server for Redpanda Cloud using the stdio protocol. This command provides a direct stdio interface for communicating with the local MCP server for Redpanda Cloud. -[cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for mcp. - -|--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. -|--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 -== Suggested reading - -* xref:ai-agents:mcp/local/quickstart.adoc[] -* xref:ai-agents:mcp/local/overview.adoc[] +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-cloud/rpk-cloud.adoc b/modules/reference/partials/rpk-cloud/rpk-cloud.adoc index f152ad6a71..9c54cfb163 100644 --- a/modules/reference/partials/rpk-cloud/rpk-cloud.adoc +++ b/modules/reference/partials/rpk-cloud/rpk-cloud.adoc @@ -1,31 +1,60 @@ = rpk cloud -// tag::single-source[] -:description: These commands let you interact with Repanda Cloud. +:description: Interact with Redpanda Cloud. +: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[] Interact with Redpanda Cloud. == Usage [,bash] ---- -rpk cloud [flags] [command] +rpk cloud [flags] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-cloud/rpk-cloud-auth.adoc[`rpk cloud auth`] +|Manage `rpk` cloud authentications. An `rpk` cloud authentication allows you to talk to Redpanda Cloud. -|-h, --help |- |Help for cloud. +|xref:reference:rpk/rpk-cloud/rpk-cloud-byoc.adoc[`rpk cloud byoc`] +|Manage a Redpanda Cloud BYOC agent For BYOC, Redpanda installs an agent service in your owned cluster. The agent then proceeds to provision further infrastructure and eventually, a full Redpanda 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-cloud/rpk-cloud-cluster.adoc[`rpk cloud cluster`] +|Manage `rpk` cloud clusters. This command allows you to manage cloud clusters, as well as easily switch between which cluster you are talking to. -|-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-cloud/rpk-cloud-login.adoc[`rpk cloud login`] +|Log in to the Redpanda Cloud This command checks for an existing Redpanda Cloud API token and, if present, ensures it is still valid. If no token is found or the token is no longer valid, this command will login and save your token along with the client ID used to request the token. -|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. +|xref:reference:rpk/rpk-cloud/rpk-cloud-logout.adoc[`rpk cloud logout`] +|Log out from Redpanda Cloud This command deletes your cloud auth token. If you want to log out entirely and switch to a different organization, you can use the `--clear-credentials` flag to additionally clear your client ID and client secret. + +|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp.adoc[`rpk cloud mcp`] +|Manage Redpanda Cloud MCP server. + +|=== + + +== 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 `~/.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/partials/rpk-security/rpk-security-secret-create.adoc b/modules/reference/partials/rpk-security/rpk-security-secret-create.adoc index 83164ff0e4..97d79f30b9 100644 --- a/modules/reference/partials/rpk-security/rpk-security-secret-create.adoc +++ b/modules/reference/partials/rpk-security/rpk-security-secret-create.adoc @@ -1,14 +1,14 @@ = rpk security secret create -// tag::single-source[] - -Create a new secret for your cluster. +:description: Create a new secret for your Redpanda Cloud cluster. Scopes define the areas where the secret can be used. +:page-platforms: linux,darwin -Scopes define the areas where the secret can be used. Available scopes are: +// 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 -- `redpanda_connect` -- `redpanda_cluster` +// tag::single-source[] +Create a new secret for your Redpanda Cloud cluster. -You can set one or both scopes on a secret. +Scopes define the areas where the secret can be used. Available options are: +`redpanda_connect`, `redpanda_cluster`. == Usage @@ -17,23 +17,32 @@ You can set one or both scopes on a secret. rpk security secret create [flags] ---- + + + == Examples -To create a secret and set its scope to `redpanda_connect`: +This section provides examples of how to use `rpk security secret create`. + +=== Create a secret with a single scope + +Create a secret and set its scope to `redpanda_connect`: [,bash] ---- rpk security secret create --name NETT --value value --scopes redpanda_connect ---- -To set the scope to both `redpanda_connect` and `redpanda_cluster`: +=== Create a secret with multiple scopes + +Set the scope to both `redpanda_connect` and `redpanda_cluster`: [,bash] ---- rpk security secret create --name NETT2 --value value --scopes redpanda_connect,redpanda_cluster ---- -You can also pass the scopes as a string: +You can also pass the scopes as a quoted string: [,bash] ---- @@ -44,23 +53,24 @@ rpk security secret create --name NETT2 --value value --scopes "redpanda_connect [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for create. - -|--name |string |Name of the secret (required). Must be in uppercase and can only contain letters, digits, and underscores. - -|--scopes |stringArray |Scope(s) of the secret, for example, `redpanda_connect` (required). +|Value |Type |Description -|--value |string |Value of the secret (required). - -|--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`. +|--name |string |Name of the secret, must be uppercase and can only contain letters, digits, and underscores. +|--scopes |stringSlice |Scope of the secret (for example, `redpanda_connect`). +|--value |string |Value of the secret. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or run `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-security/rpk-security-secret-delete.adoc b/modules/reference/partials/rpk-security/rpk-security-secret-delete.adoc index f9e3c097cb..2716682196 100644 --- a/modules/reference/partials/rpk-security/rpk-security-secret-delete.adoc +++ b/modules/reference/partials/rpk-security/rpk-security-secret-delete.adoc @@ -1,9 +1,11 @@ = rpk security secret delete -// tag::single-source[] +:description: Delete an existing secret from your Redpanda Cloud cluster. +:page-platforms: linux,darwin -Delete an existing secret from your cluster. +// 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 -Deleting a secret is irreversible. Ensure you have backups or no longer need the secret before proceeding. +// tag::single-source[] +Delete an existing secret from your Redpanda Cloud cluster. == Usage @@ -12,23 +14,29 @@ Deleting a secret is irreversible. Ensure you have backups or no longer need the rpk security secret delete [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|-h, --help |- |Help for delete. - -|--name |string |Name of the secret to delete (required). - -|--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`. +|--name |string |Name of the secret to delete, must be uppercase and can only contain letters, digits, and underscores. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or run `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-security/rpk-security-secret-list.adoc b/modules/reference/partials/rpk-security/rpk-security-secret-list.adoc index be5f917396..fb78a240ae 100644 --- a/modules/reference/partials/rpk-security/rpk-security-secret-list.adoc +++ b/modules/reference/partials/rpk-security/rpk-security-secret-list.adoc @@ -1,7 +1,11 @@ = rpk security secret list -// tag::single-source[] +:description: List all secrets in your Redpanda Cloud 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 -List all secrets in your cluster. +// tag::single-source[] +List all secrets in your Redpanda Cloud cluster. == Usage @@ -10,23 +14,29 @@ List all secrets in your cluster. rpk security secret list [flags] ---- + + + == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* +|Value |Type |Description -|-h, --help |- |Help for list. - -|--name-contains |string |Filter secrets whose names contain the specified substring. - -|--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`. +|--name-contains |string |Substring match on secret name. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or run `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-security/rpk-security-secret-update.adoc b/modules/reference/partials/rpk-security/rpk-security-secret-update.adoc index 7e4c350a48..513c082f36 100644 --- a/modules/reference/partials/rpk-security/rpk-security-secret-update.adoc +++ b/modules/reference/partials/rpk-security/rpk-security-secret-update.adoc @@ -1,14 +1,14 @@ = rpk security secret update -// tag::single-source[] - -Update an existing secret for your cluster. +:description: Update an existing secret for your Redpanda Cloud cluster. Scopes define the areas where the secret can be used. +:page-platforms: linux,darwin -Scopes define the areas where the secret can be used. Available scopes are: +// 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 -- `redpanda_connect` -- `redpanda_cluster` +// tag::single-source[] +Update an existing secret for your Redpanda Cloud cluster. -You can set one or both scopes on a secret. Updating a secret's scopes will overwrite its current scopes. +Scopes define the areas where the secret can be used. Updating a secret will +overwrite its scopes. Available scope options are: `redpanda_connect`, `redpanda_cluster`. == Usage @@ -17,43 +17,31 @@ You can set one or both scopes on a secret. Updating a secret's scopes will over rpk security secret update [flags] ---- -== Examples -To update the value of the secret: -[,bash] ----- -rpk security secret update --name NETT --value new_value ----- - -To update the scope of a secret to both `redpanda_connect` and `redpanda_cluster`: - -[,bash] ----- -rpk security secret update --name NETT2 --value value --scopes redpanda_connect,redpanda_cluster ----- == Flags [cols="1m,1a,2a"] |=== -|*Value* |*Type* |*Description* - -|-h, --help |- |Help for update. - -|--name |string |Name of the secret. The name must be in uppercase and can only contain letters, digits, and underscores. You cannot update the name of an existing secret. - -|--scopes |stringArray |Scope(s) of the secret (for example, `redpanda_connect`). +|Value |Type |Description -|--value |string |New value of the secret. - -|--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`. +|--name |string |Name of the secret, must be uppercase and can only contain letters, digits, and underscores. +|--scopes |stringSlice |Scope of the secret (for example, `redpanda_connect`). +|--value |string |New secret value of the secret. +|=== -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or run `rpk -X help` for inline detail or `rpk -X list` for terser detail. +== Global flags -|--profile |string |rpk profile to use. +[cols="1m,1a,2a"] +|=== +|Value |Type |Description -|-v, --verbose |- |Enable verbose logging. +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.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/partials/rpk-security/rpk-security-secret.adoc b/modules/reference/partials/rpk-security/rpk-security-secret.adoc index ba8f37e581..32ba7fff14 100644 --- a/modules/reference/partials/rpk-security/rpk-security-secret.adoc +++ b/modules/reference/partials/rpk-security/rpk-security-secret.adoc @@ -1,31 +1,56 @@ = rpk security secret +:description: Manage secrets for Redpanda Cloud clusters. This command allows you to manage secrets for your cloud clusters. +: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 secrets for Redpanda Cloud clusters. -Manage secrets for your cluster. +This command allows you to manage secrets for your cloud clusters. == Usage [,bash] ---- rpk security secret [flags] - rpk security secret [command] ---- -== Flags -[cols="1m,1a,2a"] + + +== Subcommands + +[cols="1,2a"] |=== -|*Value* |*Type* |*Description* +|Command |Description + +|xref:reference:rpk/rpk-security/rpk-security-secret-create.adoc[`rpk security secret create`] +|Create a new secret for your Redpanda Cloud cluster. Scopes define the areas where the secret can be used. -|-h, --help |- |Help for secret. +|xref:reference:rpk/rpk-security/rpk-security-secret-delete.adoc[`rpk security secret delete`] +|Delete an existing secret from your Redpanda Cloud 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-security/rpk-security-secret-list.adoc[`rpk security secret list`] +|List all secrets in your Redpanda Cloud cluster. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or run `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|xref:reference:rpk/rpk-security/rpk-security-secret-update.adoc[`rpk security secret update`] +|Update an existing secret for your Redpanda Cloud cluster. Scopes define the areas where the secret can be used. -|--profile |string |rpk profile to use. +|=== + + +== 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 `~/.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/troubleshoot/partials/errors-and-solutions.adoc b/modules/troubleshoot/partials/errors-and-solutions.adoc index 1f592f86d4..dc9b613f51 100644 --- a/modules/troubleshoot/partials/errors-and-solutions.adoc +++ b/modules/troubleshoot/partials/errors-and-solutions.adoc @@ -21,6 +21,7 @@ Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.y This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the https://github.com/helm/helm/issues/30880[Helm GitHub issue^]. //end::deployment-helm-3-18[] //tag::deployment-pod-pending[] + === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. diff --git a/modules/upgrade/pages/k-upgrade-operator.adoc b/modules/upgrade/pages/k-upgrade-operator.adoc index 56e802324c..66eec0eaa8 100644 --- a/modules/upgrade/pages/k-upgrade-operator.adoc +++ b/modules/upgrade/pages/k-upgrade-operator.adoc @@ -9,6 +9,11 @@ For complete upgrade instructions, including how to upgrade both the Redpanda Op In some cases, you might need to upgrade only the Redpanda Operator without upgrading your Redpanda cluster. For example, you might need to apply a patch release that fixes an operator bug. +[NOTE] +==== +An operator-only upgrade still restarts your broker Pods, even though the Redpanda version does not change. The Redpanda Operator injects its own container images (the configurator init container and the sidecar) into each broker Pod, and these image references track the operator version. When you upgrade the operator, the broker Pod template changes and the brokers roll one at a time. For why this happens and how to plan or stage it, see <>. +==== + To upgrade only the operator: . https://github.com/redpanda-data/redpanda-operator/releases[Review the Redpanda Operator release notes^] and xref:upgrade:k-compatibility.adoc[the Kubernetes compatibility matrix]. @@ -51,3 +56,52 @@ kubectl --namespace rollout status --watch deployment/redpanda-contr deployment "redpanda-controller-operator" successfully rolled out ---- ==== + +[[broker-restarts]] +== Broker restarts during operator upgrades + +Upgrading the Redpanda Operator restarts your broker Pods, even when the Redpanda version itself does not change. Plan for a rolling restart of every broker on each managed cluster whenever you upgrade the operator version. + +=== Why brokers restart + +The Redpanda Operator renders the broker StatefulSet from its own templates. The configurator init container and the sidecar container that run inside each broker Pod use an image whose tag tracks the operator version by default. When you upgrade the operator, those image references change, which changes the broker Pod template. Kubernetes detects the change and the operator performs a rolling restart to bring the Pods in line with the new Pod template. + +This restart is safe: the operator places each broker into maintenance mode, restarts it, and waits for the cluster to report healthy before moving to the next broker. + +A roll also occurs when a new operator version changes any other part of the broker Pod template, such as adding a sidecar argument, container, or volume mount. These changes are independent of the image tag. + +=== Plan the upgrade + +Treat every operator upgrade as a broker-restarting change: + +* Upgrade one cluster at a time, during a maintenance window. +* Size each window from the number of brokers. The operator restarts each broker sequentially and waits for the cluster to become healthy between brokers, so allow a few minutes per broker plus a buffer. +* Always test the upgrade in a non-production cluster first, and confirm the cluster returns to a healthy state. + +[[stage-broker-restart]] +=== Stage the broker restart separately (advanced) + +To apply an operator control-plane fix without immediately restarting your brokers, you can pin the configurator and sidecar image so that upgrading the operator does not change the broker Pod template. You then update the pinned image in a later, separately scheduled change, which is when the brokers restart. + +Pin the image to your current operator version before you upgrade the control plane, by passing the operator's image flags through the chart's `additionalCmdFlags` value: + +[source,bash] +---- +helm upgrade redpanda-controller redpanda/operator \ + --namespace \ + --version \ + --set crds.enabled=true \ + --set "additionalCmdFlags={--configurator-base-image=docker.redpanda.com/redpandadata/redpanda-operator,--configurator-tag=}" +---- + +Replace `` with the operator version your brokers are currently running. The operator control plane upgrades to `` and its fixes take effect, but the broker Pod template keeps the pinned image, so the brokers do not restart. To restart the brokers on the new image later, repeat the upgrade with `--configurator-tag` set to `` (or remove the override so the tag tracks the operator version again). + +[WARNING] +==== +This staging technique has important limitations: + +* It only avoids the restart for releases whose *only* broker Pod template change is the image tag. If the new operator version also changes the broker Pod template in another way, such as adding a sidecar argument or container, the brokers restart regardless of the pinned image. +* While the image is pinned, the operator control plane and the broker sidecar or configurator run different versions. Keep the gap small and reconcile the pinned image with the operator version promptly. Do not run a mismatched control plane and sidecar long term. Review the https://github.com/redpanda-data/redpanda-operator/releases[release notes^] for each version before staging. + +Verify the behavior in a non-production cluster before relying on it in production. +==== diff --git a/modules/upgrade/pages/rolling-upgrade.adoc b/modules/upgrade/pages/rolling-upgrade.adoc index 9b30052bb6..eff68e5ead 100644 --- a/modules/upgrade/pages/rolling-upgrade.adoc +++ b/modules/upgrade/pages/rolling-upgrade.adoc @@ -7,6 +7,8 @@ To benefit from Redpanda's new features and enhancements, upgrade to the latest version. Redpanda Data recommends that you perform a glossterm:rolling upgrade[] on production clusters, which requires all brokers to be placed into maintenance mode and restarted separately, one after the other. +include::deploy:partial$linux/repo-migration-note.adoc[] + include::partial$versioning.adoc[] include::partial$rolling-upgrades/upgrade-limitations.adoc[] diff --git a/modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc b/modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc index b7f74e7378..64dd9078b2 100644 --- a/modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc +++ b/modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc @@ -102,10 +102,10 @@ The combination of the `--watch` and `--exit-when-healthy` flags tell rpk to mon [NOTE] ==== ifdef::rolling-upgrade[] -You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling upgrade: +You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before retrying the rolling upgrade: endif::[] ifdef::rolling-restart[] -You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling restart: +You can also evaluate xref:manage:monitoring.adoc[metrics] to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before retrying the rolling restart: endif::[] ```bash diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000000..d20297be3d --- /dev/null +++ b/netlify.toml @@ -0,0 +1,11 @@ +[build.environment] +NODE_VERSION = "22" +NODE_OPTIONS = "--max-old-space-size=6144" + +[dev] + publish = "docs/" + framework = "#static" + +[[edge_functions]] +path = "/api/*" +function = "proxy-api-docs" diff --git a/netlify/edge-functions/proxy-api-docs.js b/netlify/edge-functions/proxy-api-docs.js new file mode 100644 index 0000000000..e73f7441c1 --- /dev/null +++ b/netlify/edge-functions/proxy-api-docs.js @@ -0,0 +1,309 @@ +import { DOMParser } from "https://deno.land/x/deno_dom@v0.1.56/deno-dom-wasm.ts"; + +export default async (request, context) => { + const url = new URL(request.url); + const originalOrigin = url.origin; + + // Frame/partial requests (for example, ?partial=true) return HTML fragments, + // not the full document. They must never share a CDN cache entry with the + // root page, or a cached fragment gets served as the root document (and vice + // versa). Handled by the cache-control / Netlify-Vary headers on the HTML + // response below. + const isPartialRequest = url.searchParams.has("partial"); + + // Redirects from old API paths to new ones + const redirects = { + "/api/doc": "/api", + "/api/admin-api": "/api/doc/admin/", + "/api/http-proxy-api": "/api/doc/http-proxy/", + "/api/schema-registry-api": "/api/doc/schema-registry/", + "/api/cloud-controlplane-api": "/api/doc/cloud-controlplane/", + "/api/cloud-dataplane-api": "/api/doc/cloud-dataplane/", + "/api/cloud-api": "/api/doc/cloud-controlplane/", + }; + + const normalizedPath = url.pathname.endsWith("/") + ? url.pathname.slice(0, -1) + : url.pathname; + + if (redirects[normalizedPath]) { + return Response.redirect(`${url.origin}${redirects[normalizedPath]}`, 301); + } + + // Content negotiation: redirect to .md URL if markdown is explicitly requested + // Only match text/markdown per agent-friendly docs spec (text/plain is too broad) + const acceptHeader = request.headers.get('accept') || ''; + const wantsMarkdown = acceptHeader.includes('text/markdown'); + + if (wantsMarkdown && !url.pathname.endsWith('.md')) { + // Construct markdown URL - append .md to the path + const mdPath = normalizedPath + '.md'; + return Response.redirect(`${url.origin}${mdPath}`, 302); + } + + // Map paths to header background colors (8% component color mixed with white) + const headerColors = { + "/api/doc/admin": "color-mix(in srgb, #9F1239 8%, white)", // self-managed (rose) + "/api/doc/cloud-controlplane": "color-mix(in srgb, #1D4ED8 8%, white)", // cloud (blue) + "/api/doc/cloud-dataplane": "color-mix(in srgb, #1D4ED8 8%, white)", // cloud (blue) + }; + + const matchedPath = Object.keys(headerColors).find((path) => + normalizedPath.startsWith(path) + ); + const headerColor = headerColors[matchedPath] || "color-mix(in srgb, #1D4ED8 8%, white)"; // default to cloud + + // Build the proxied Bump.sh URL + const bumpUrl = new URL(request.url); + bumpUrl.host = "bump.sh"; + bumpUrl.pathname = `/redpanda/hub/redpanda${bumpUrl.pathname.replace("/api", "")}`; + + const secret = Netlify.env.get("BUMP_PROXY_SECRET"); + + // Validate secret exists + if (!secret) { + console.error("❌ BUMP_PROXY_SECRET environment variable not set"); + return new Response("Service temporarily unavailable", { + status: 503, + headers: { + "content-type": "text/plain; charset=utf-8", + "cache-control": "public, max-age=60", + } + }); + } + + try { + const bumpRes = await fetchWithRetry(bumpUrl, { + headers: { + "X-BUMP-SH-PROXY": secret, + "X-BUMP-SH-EMBED": "true", + "User-Agent": "Redpanda-Docs-Proxy/1.0", + }, + }); + + // Handle non-successful responses + if (!bumpRes.ok) { + console.error(`❌ Bump.sh returned ${bumpRes.status}: ${bumpRes.statusText}`); + throw new Error(`Bump.sh API error: ${bumpRes.status}`); + } + + const contentType = bumpRes.headers.get("content-type") || ""; + + if (!contentType.includes("text/html")) { + // If requesting .md file, ensure correct content-type for markdown + if (url.pathname.endsWith('.md')) { + const body = await bumpRes.text(); + return new Response(body, { + status: bumpRes.status, + headers: { + "content-type": "text/markdown; charset=utf-8", + "cache-control": bumpRes.headers.get("cache-control") || "public, max-age=300", + }, + }); + } + return bumpRes; + } + + // Load Bump.sh page and widgets + const [ + originalHtml, + headScript, + headerWidget, + footerWidget, + chatPanelWidget, + ] = await Promise.all([ + bumpRes.text(), + fetchWidget(`${originalOrigin}/assets/widgets/head-bump.html`, "head-bump"), + fetchWidget(`${originalOrigin}/assets/widgets/header.html`, "header"), + fetchWidget(`${originalOrigin}/assets/widgets/footer.html`, "footer"), + fetchWidget(`${originalOrigin}/assets/widgets/chat-panel-bump.html`, "chat-panel"), + ]); + + let document; + try { + document = new DOMParser().parseFromString(originalHtml, "text/html"); + } catch (error) { + console.error("❌ Failed to initialize DOMParser (WASM issue):", error); + // Return unmodified HTML if DOM parsing fails + return new Response(originalHtml, { + status: 200, + headers: { "content-type": "text/html; charset=utf-8" }, + }); + } + + if (!document) { + console.error("❌ Failed to parse Bump.sh HTML."); + return new Response(originalHtml, { + status: 200, + headers: { "content-type": "text/html; charset=utf-8" }, + }); + } + + // Inject head script + const head = document.querySelector("head"); + if (head && headScript) { + const temp = document.createElement("div"); + temp.innerHTML = headScript; + for (const node of temp.childNodes) { + head.appendChild(node); + } + } + + // Inject header with dynamic background color + const topBody = document.querySelector("#embed-top-body"); + if (topBody && headerWidget) { + // Add background color to the navbar element + const coloredHeader = headerWidget.replace( + /]*class="[^"]*navbar[^"]*")/, + `

For the complete documentation index, see . Component-specific:

`; + + // Insert directive at the beginning of body - same pattern as footer injection + const wrapper = document.createElement("div"); + wrapper.innerHTML = directiveHtml; + + // Insert all child nodes from wrapper at start of body + const firstChild = body.firstChild; + while (wrapper.firstChild) { + body.insertBefore(wrapper.firstChild, firstChild); + } + + // Add CSS to visually hide the directive + if (head) { + const style = document.createElement("style"); + style.textContent = ".llms-directive{position:absolute;left:-10000px;width:1px;height:1px;overflow:hidden}"; + head.appendChild(style); + } + + // Inject CSS fixes for chat panel and dark mode on Bump.sh pages + if (head) { + const fixStyle = document.createElement("style"); + fixStyle.textContent = ` + /* Fix chat panel top offset - account for fixed navbar */ + .chat-panel { top: var(--navbar-height, 70px) !important; height: calc(100vh - var(--navbar-height, 70px)) !important; } + + /* Fix chat head icons - ensure SVGs are visible */ + .chat-head-btn svg { stroke: currentColor !important; } + .chat-head-icon svg { fill: currentColor !important; } + + /* Dark mode fixes using html[data-theme="dark"] selector (Bump pages use this, not .dark-theme) */ + html[data-theme="dark"] .navbar { background: #0f172a !important; } + html[data-theme="dark"] .chat-panel { background: #1a2332 !important; color: #e8eef6 !important; border-left-color: rgba(255,255,255,0.08) !important; } + html[data-theme="dark"] .chat-head { border-bottom-color: rgba(255,255,255,0.08) !important; } + html[data-theme="dark"] .chat-head-name { color: #e8eef6 !important; } + html[data-theme="dark"] .chat-head-sub { color: #7c8ca8 !important; } + html[data-theme="dark"] .chat-head-btn { color: #7c8ca8 !important; } + html[data-theme="dark"] .chat-head-btn:hover { background: rgba(255,255,255,0.05) !important; color: #e8eef6 !important; } + html[data-theme="dark"] .chat-foot { color: #7c8ca8 !important; border-top-color: rgba(255,255,255,0.08) !important; } + html[data-theme="dark"] #chat-panel-kapa-root { color: #e8eef6 !important; } + html[data-theme="dark"] #chat-panel-kapa-root .welcome-icon { background: linear-gradient(135deg, #312e81 0%, #3730a3 100%) !important; color: #a5b4fc !important; } + html[data-theme="dark"] #chat-panel-kapa-root .welcome-title { color: #e8eef6 !important; } + html[data-theme="dark"] #chat-panel-kapa-root .welcome-description { color: #7c8ca8 !important; } + html[data-theme="dark"] #chat-panel-kapa-root .suggestion-card { background: #232f3e !important; border-color: rgba(255,255,255,0.1) !important; color: #aab8ca !important; } + html[data-theme="dark"] #chat-panel-kapa-root .suggestion-card:hover { background: #2a3a4d !important; border-color: rgba(255,255,255,0.15) !important; color: #e8eef6 !important; } + html[data-theme="dark"] #chat-panel-kapa-root .chat-input-wrapper { background: #232f3e !important; border-color: rgba(255,255,255,0.1) !important; } + html[data-theme="dark"] #chat-panel-kapa-root .chat-input-wrapper .chat-input { background: transparent !important; color: #e8eef6 !important; } + html[data-theme="dark"] #chat-panel-kapa-root .disclaimer { color: #7c8ca8 !important; background: #1a2332 !important; } + `.replace(/\s+/g, ' ').trim(); + head.appendChild(fixStyle); + } + } + + const htmlOutput = document.documentElement?.outerHTML || originalHtml; + return new Response(htmlOutput, { + status: 200, + headers: { + "content-type": "text/html; charset=utf-8", + // Vary the CDN cache key on the query string so frame/partial requests + // can never collide with the root document. Additionally, don't store + // partial fragments in the shared cache at all (defense in depth). + "cache-control": isPartialRequest ? "no-store" : "public, max-age=300", // root docs: cache 5 minutes + "netlify-vary": "query", + }, + }); + + } catch (error) { + console.error("❌ Failed to fetch from Bump.sh after retries:", error); + + // Return a graceful fallback response with short cache to avoid hammering + return new Response( + `API Documentation Temporarily Unavailable

API Documentation Temporarily Unavailable

Please try again later.

`, + { + status: 503, + headers: { + "content-type": "text/html; charset=utf-8", + "cache-control": "public, max-age=60", // Cache errors briefly to reduce load + } + } + ); + } +}; + +// Fetch with retry logic and exponential backoff +async function fetchWithRetry(url, options, maxRetries = 3) { + for (let attempt = 1; attempt <= maxRetries; attempt++) { + try { + const response = await fetch(url, { + ...options, + signal: AbortSignal.timeout(10000), // 10 second timeout + }); + return response; + } catch (error) { + const errorMsg = error instanceof Error ? error.message : String(error); + console.warn(`Attempt ${attempt} failed for ${url}:`, errorMsg); + + if (attempt === maxRetries) { + throw error; + } + + // Exponential backoff: wait 2^attempt seconds + const delay = Math.pow(2, attempt) * 1000; + await new Promise(resolve => setTimeout(resolve, delay)); + } + } +} + +// Helper function to fetch widget content with fallback +async function fetchWidget(url, label) { + try { + const res = await fetchWithRetry(url, {}, 2); // 2 retries for widgets + if (res.ok) return await res.text(); + console.warn(`⚠️ Failed to load ${label} widget from ${url}`); + return ""; + } catch (err) { + console.error(`❌ Error fetching ${label} widget:`, err); + return ""; + } +} diff --git a/package-lock.json b/package-lock.json index 27ae0c080e..19de49d19a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@antora/cli": "3.1.2", "@antora/site-generator": "3.1.2", "@asciidoctor/tabs": "^1.0.0-beta.5", - "@redpanda-data/docs-extensions-and-macros": "^5.0.0", + "@redpanda-data/docs-extensions-and-macros": "^5.1.2", "@sntke/antora-mermaid-extension": "^0.0.6" }, "devDependencies": { @@ -2691,9 +2691,9 @@ "license": "MIT" }, "node_modules/@redpanda-data/docs-extensions-and-macros": { - "version": "5.0.4", - "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-5.0.4.tgz", - "integrity": "sha512-jYaiRaZCkJbdHkiJZxk1l9lbrhIL6aQypwTPVeamfwHoaPSKv/utb406e+GBrHvU5hLM/Q6/NLPnb7fV9yXaGQ==", + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-5.1.2.tgz", + "integrity": "sha512-M7vU7C4/kHmn2Z7eeirJFC0nLdoIu+dlHhibpwkxhbx90xZfWJxjnPAkL7nsXlAVorMLwIoc/I/QLLTCDHBr+w==", "license": "ISC", "dependencies": { "@asciidoctor/tabs": "^1.0.0-beta.6", @@ -2703,7 +2703,7 @@ "@octokit/plugin-retry": "^7.1.1", "@octokit/rest": "^21.1.1", "@redocly/cli": "^2.2.0", - "ajv": "^8.12.0", + "ajv": "^8.20.0", "algoliasearch": "^4.17.0", "chalk": "4.1.2", "cheerio": "^1.1.2", @@ -2736,6 +2736,22 @@ "doc-tools-mcp": "bin/doc-tools-mcp.js" } }, + "node_modules/@redpanda-data/docs-extensions-and-macros/node_modules/ajv": { + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", + "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, "node_modules/@redpanda-data/docs-extensions-and-macros/node_modules/commander": { "version": "14.0.2", "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.2.tgz", diff --git a/package.json b/package.json index d386c7aaeb..700dfb3715 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "@antora/cli": "3.1.2", "@antora/site-generator": "3.1.2", "@asciidoctor/tabs": "^1.0.0-beta.5", - "@redpanda-data/docs-extensions-and-macros": "^5.0.0", + "@redpanda-data/docs-extensions-and-macros": "^5.1.2", "@sntke/antora-mermaid-extension": "^0.0.6" }, "devDependencies": {