Beta #1478
Beta #1478
Conversation
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Gellért Peresztegi-Nagy <gellert.nagy@redpanda.com>
Co-authored-by: Paulo Borges <paulohtb6@gmail.com>
Co-authored-by: Michele Cyran <michele@redpanda.com> Co-authored-by: Mike Boquard <michael@redpanda.com> Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Co-authored-by: Trevor Blackford <trevor.blackford@redpanda.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
…1446) Co-authored-by: Ben Pope <BenPope@users.noreply.github.com> Co-authored-by: Michele Cyran <michele@redpanda.com>
Co-authored-by: IoannisRP <ioannis.kavvadias@redpanda.com> Co-authored-by: Paulo Borges <paulohtb6@gmail.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis pull request updates documentation to support Redpanda v25.3, a pre-release version. Key changes include: version bumps in build files (antora.yml) and playbook configuration; a new Shadowing feature for disaster recovery with comprehensive setup, monitoring, and failover documentation; replacement of AWS Glue Iceberg integration with GCP BigLake documentation; introduction of ConnectRPC Admin API endpoints; new cluster and topic properties for timestamp validation, Iceberg, TLS ciphers, and shadowing; new rpk shadow commands (create, delete, failover, status, etc.); updates to rpk cluster config commands (--all flag removal); and extensive environment-aware (cloud vs non-cloud) documentation guidance. Additionally, several existing pages are reorganized or removed, cross-references are updated, and new navigation aliases are added to reflect the evolving product structure. Sequence Diagram(s)sequenceDiagram
participant User as User/Admin
participant CLI as rpk/Console
participant ShadowCluster as Shadow Cluster<br/>(Read-Only)
participant SourceCluster as Source Cluster<br/>(Primary)
rect rgb(230, 245, 250)
Note over User,SourceCluster: Normal Shadowing Operations
User->>CLI: Monitor shadow status
CLI->>SourceCluster: Query replication lag, task status
SourceCluster-->>CLI: Return shadow metrics
CLI-->>User: Display dashboard
end
rect rgb(255, 235, 205)
Note over User,SourceCluster: Disaster Detected
User->>User: Assess situation<br/>Verify source unavailable
end
rect rgb(255, 200, 200)
Note over User,ShadowCluster: Failover Procedure
User->>CLI: rpk shadow failover --all
CLI->>ShadowCluster: Initiate failover<br/>(FAILOVER_IN_PROGRESS)
ShadowCluster->>ShadowCluster: Stop replication<br/>Convert topics to writable<br/>(REPLICA state → CONTROLLED)
ShadowCluster-->>CLI: Failover complete
CLI-->>User: Return success/status
end
rect rgb(200, 230, 200)
Note over User,ShadowCluster: Post-Failover Actions
User->>User: Update app connections<br/>Point to shadow cluster
User->>User: Verify functionality<br/>Check consumer groups
User->>User: Document incident<br/>Plan recovery
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Areas requiring extra attention during review:
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
…1452) Co-authored-by: Paulo Borges <paulohtb6@gmail.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 16
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
tests/setup-tests/fetch-versions-and-rpk.json (1)
15-52: Fix missing doc-tools dependency and command mismatches in shell commands.The fallback logic will fail in two ways:
doc-tools is not a project dependency —
doc-toolsis referenced in package-lock.json but missing from package.json. It must be added to devDependencies fornpx doc-toolscommands to work.Lines 28 and 48 call wrong subcommands — These steps invoke incorrect doc-tools commands:
- Line 28:
get-console-docker-repocallsget-console-versionbut greps forCONSOLE_DOCKER_REPO=(mismatch)- Line 48:
get-redpanda-docker-repocallsget-redpanda-versionbut greps forREDPANDA_DOCKER_REPO=(mismatch)The commands should call appropriate doc-tools subcommands that output the Docker repo variables, or the grep patterns should match the actual output.
🧹 Nitpick comments (12)
modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc (1)
102-102: Standardize Kubernetes-specific notation formatting across flag descriptions.The flags table uses inconsistent formatting for platform-specific limitations:
- Line 102 (
--label-selector): "(k8s only)" inline in description- Line 111 (
--logs-until): "+\nNot supported in Kubernetes" on separate line- Line 123 (
--namespace): "+\nKubernetes only" on separate lineFor consistency and clarity in the rendered documentation, adopt a single formatting pattern across all platform-specific annotations. Recommend using the separate-line format (lines 111, 123) consistently, and also normalize the wording to either "Kubernetes only" or "Not supported in Kubernetes" across all occurrences.
Apply this diff to standardize the formatting:
|-l, --label-selector |stringArray |Comma-separated label selectors to filter your resources. e.g: <label>=<value>,<label>=<value> (k8s only) (default ` [app.kubernetes.io/name=redpanda]`). +|-l, --label-selector |stringArray |Comma-separated label selectors to filter your resources. e.g: <label>=<value>,<label>=<value> (default ` [app.kubernetes.io/name=redpanda]`). + +*Kubernetes only*.Also applies to: 111-111, 123-123
modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc (1)
32-33: Well-integrated flag documentation.The
--if-not-existsflag is correctly added to the flags table with clear, concise description and consistent formatting. The placement between--helpand--partitionsis appropriate, and the table structure follows established patterns.Minor suggestion: Consider adding a usage example demonstrating the
--if-not-existsflag (e.g.,rpk topic create my-topic --if-not-exists) to parallel other documented flags like--dryand--partitions. This would help users quickly understand the flag's practical application, particularly given the PR's focus on topic lifecycle controls.tests/docker-compose/docker-compose.yml (1)
95-97: Consider adding health conditions todepends_onfor consistency.The
depends_onsections for redpanda-1 and redpanda-2 use a short list form without service health conditions, while redpanda-0 specifiescondition: service_healthyfor its minio dependency (line 59-60). During cluster startup, redpanda-1 and redpanda-2 may begin before their dependencies (redpanda-0 and minio) are actually healthy, potentially causing transient failures.Consider updating to the long form with explicit health conditions to ensure orderly, healthy startup:
redpanda-1: ... depends_on: - - redpanda-0 - - minio + redpanda-0: + condition: service_healthy + minio: + condition: service_healthyApply the same change to redpanda-2.
Also applies to: 132-134
modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc (1)
56-56: Flag descriptions are clear; consider clarifying mutual dependency.The --id and --schema-version flags are well-documented with default values and clear descriptions. However, line 62's note that --schema-version "requires
--id" could be more prominent. Consider whether a mutual dependency notice or a shared section explaining the import mode workflow would help users understand when and how to use these flags together.Consider adding a shared note or callout at the top of the Flags section or as a separate "Import Mode" subsection explaining that --id and --schema-version are only applicable when the registry is in IMPORT mode (as documented in rpk-registry-mode-set.adoc), to improve discoverability.
Also applies to: 62-62
tests/setup-tests/fetch-versions-and-rpk.json (1)
18-18: Quote variables in echo statements for robustness.The variables in echo commands lack quotes, which can cause issues if values contain spaces or special characters. While version strings typically don't have these issues, this is a shell best practice.
- "command": "if [ -n \"$REDPANDA_CONSOLE_VERSION\" ]; then echo $REDPANDA_CONSOLE_VERSION; else npx doc-tools get-console-version --from-antora | grep CONSOLE_VERSION= | cut -d'=' -f2; fi" + "command": "if [ -n \"$REDPANDA_CONSOLE_VERSION\" ]; then echo \"$REDPANDA_CONSOLE_VERSION\"; else npx doc-tools get-console-version --from-antora | grep CONSOLE_VERSION= | cut -d'=' -f2; fi"Apply the same fix to lines 28, 38, and 48 for
$CONSOLE_DOCKER_REPO,$REDPANDA_VERSION, and$REDPANDA_DOCKER_REPOrespectively.Also applies to: 28-28, 38-38, 48-48
modules/manage/pages/schema-reg/schema-reg-api.adoc (1)
1034-1038: Inconsistent code block formatting in Set global mode section.Lines 1034-1038 show another curl example that appears to have formatting issues. The curl command uses
<mode>placeholder but doesn't indicate it's a variable placeholder clearly. This mirrors the pattern in the GET endpoint but should clarify syntax for users.Update the example to clarify the placeholder and show actual values:
- Curl:: - + - ```bash - curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"mode": <mode>}' http://localhost:8081/mode - ``` + Curl:: + + + ```bash + curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"mode": "READONLY"}' http://localhost:8081/mode + ```modules/manage/pages/cluster-maintenance/disk-utilization.adoc (1)
110-110: Caution about MirrorMaker2 and Shadowing requires clearer guidance.Line 110 warns that "it is particularly important for users of MirrorMaker2 and Shadowing to enable this feature flag on their destination clusters," because "active clusters created by MirrorMaker2 that are running versions prior to v25.3 will have retention enforced from the date of cluster creation rather than the date of the data."
This is critical but the consequence description is unclear. Clarify:
- Does "date of cluster creation" mean retention will be calculated from when MM2 started, not when the data was created?
- Will this cause premature data deletion or retention blocking?
- Should users verify data retention behavior after enabling the flag?
Expand the caution with a concrete example showing the retention timing difference and expected behavior after enabling the flag.
modules/reference/pages/properties/object-storage-properties.adoc (1)
581-596: Clarify distinction between cloud_storage_credentials_host and cloud_storage_credentials_source.Lines 581-596 (cloud_storage_credentials_host) and lines 599-615 (cloud_storage_credentials_source) are very similar, both with:
- Same accepted values list
- Both Require restart: Yes
- Both Gets restored during cluster restore: No
- Only difference is Visibility (tunable vs user)
The descriptions should clarify:
- When to use
credentials_hostvscredentials_source- what is the semantic difference?- Line 583 says credentials_host is "Derived from... if not set" - does this mean it's optional when credentials_source is set?
- Are both required, or is only one needed?
Add a note clarifying the relationship:
cloud_storage_credentials_sourcespecifies the credential provider type, whilecloud_storage_credentials_hostoptionally overrides the host for credential retrieval. Ifcredentials_hostis not set, it is automatically derived from thecredentials_sourcevalue.modules/reference/pages/properties/cluster-properties.adoc (2)
543-555: Consider adding "Related topics" section.This property controls cluster reconciliation concurrency. It might benefit from referencing cluster-maintenance or configuration documentation. Check if related topics should be included.
2781-2795: Add warning about cluster metadata consistency foriceberg_topic_name_dot_replacement.Line 2783 warns "Don't change this value after creating any Iceberg topics with dots in their names." This is important but could be emphasized more clearly. Consider adding a CAUTION or IMPORTANT block to make this constraint more visible, similar to how you've treated breaking changes elsewhere in the PR.
modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc (1)
25-29: Clarify platform-specific config file search paths.Line 29 lists default search paths including
/var/lib/redpanda/.config/rpk/rpk.yaml. Per learnings from a prior review (PR 1358), macOS uses~/Library/Application Support/rpk/rpk.yamlwhile Linux uses/var/lib/redpanda/.config/rpk/rpk.yaml.Consider updating the description to clarify these are Linux paths, or explicitly document platform differences for completeness and user clarity, especially since
rpkis cross-platform.modules/manage/pages/disaster-recovery/index.adoc (1)
1-6: Verify index page content structure.This new index page contains only metadata (lines 1-6) but no body content with links to sub-pages. Index pages typically include navigation to child topics. Verify that:
- Child pages (shadowing overview, topic recovery, whole-cluster restore, etc.) properly include this index in their xref: navigation
- Navigation structure is correctly defined in the documentation build configuration (antora.yml, nav.adoc, etc.)
- Users can discover disaster-recovery sub-topics from this index
Consider adding introductory text and a list of child topics to help users navigate the disaster recovery documentation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (3)
modules/console/images/broker-overview.pngis excluded by!**/*.pngmodules/console/images/overview.pngis excluded by!**/*.pngmodules/console/images/topic.pngis excluded by!**/*.png
📒 Files selected for processing (89)
antora.yml(2 hunks)local-antora-playbook.yml(2 hunks)modules/ROOT/nav.adoc(8 hunks)modules/console/pages/index.adoc(1 hunks)modules/deploy/pages/console/linux/deploy.adoc(1 hunks)modules/deploy/pages/redpanda/manual/production/production-readiness.adoc(2 hunks)modules/deploy/partials/high-availability.adoc(1 hunks)modules/develop/pages/config-topics.adoc(1 hunks)modules/develop/partials/http-proxy.adoc(1 hunks)modules/get-started/pages/install-beta.adoc(4 hunks)modules/get-started/pages/licensing/overview.adoc(2 hunks)modules/get-started/pages/quick-start.adoc(11 hunks)modules/get-started/pages/release-notes/redpanda.adoc(1 hunks)modules/manage/pages/cluster-maintenance/compaction-settings.adoc(1 hunks)modules/manage/pages/cluster-maintenance/configure-client-connections.adoc(3 hunks)modules/manage/pages/cluster-maintenance/disk-utilization.adoc(1 hunks)modules/manage/pages/cluster-maintenance/manage-throughput.adoc(3 hunks)modules/manage/pages/disaster-recovery/index.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/failover.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/index.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/monitor.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/overview.adoc(1 hunks)modules/manage/pages/disaster-recovery/shadowing/setup.adoc(1 hunks)modules/manage/pages/disaster-recovery/topic-recovery.adoc(1 hunks)modules/manage/pages/disaster-recovery/whole-cluster-restore.adoc(1 hunks)modules/manage/pages/high-availability.adoc(1 hunks)modules/manage/pages/iceberg/iceberg-topics-aws-glue.adoc(1 hunks)modules/manage/pages/iceberg/iceberg-topics-databricks-unity.adoc(1 hunks)modules/manage/pages/iceberg/iceberg-topics-gcp-biglake.adoc(1 hunks)modules/manage/pages/iceberg/query-iceberg-topics.adoc(1 hunks)modules/manage/pages/iceberg/specify-iceberg-schema.adoc(6 hunks)modules/manage/pages/kubernetes/tiered-storage/k-whole-cluster-restore.adoc(1 hunks)modules/manage/pages/remote-read-replicas.adoc(1 hunks)modules/manage/pages/schema-reg/schema-reg-api.adoc(2 hunks)modules/manage/pages/security/index.adoc(1 hunks)modules/manage/pages/topic-recovery.adoc(0 hunks)modules/manage/pages/use-admin-api.adoc(1 hunks)modules/manage/pages/whole-cluster-restore.adoc(0 hunks)modules/manage/partials/authentication.adoc(2 hunks)modules/manage/partials/monitor-health.adoc(2 hunks)modules/manage/partials/security-report.adoc(1 hunks)modules/manage/partials/whole-cluster-restore.adoc(2 hunks)modules/migrate/pages/data-migration.adoc(1 hunks)modules/reference/pages/api-reference.adoc(1 hunks)modules/reference/pages/properties/cluster-properties.adoc(21 hunks)modules/reference/pages/properties/object-storage-properties.adoc(1 hunks)modules/reference/pages/properties/topic-properties.adoc(3 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-force-reset.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-get.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-lint.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-status.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config.adoc(0 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-connections-list.adoc(1 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-connections.adoc(1 hunks)modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc(1 hunks)modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc(1 hunks)modules/reference/pages/rpk/rpk-debug/rpk-debug-remote-bundle-start.adoc(1 hunks)modules/reference/pages/rpk/rpk-group/rpk-group-describe.adoc(2 hunks)modules/reference/pages/rpk/rpk-profile/rpk-profile-create.adoc(1 hunks)modules/reference/pages/rpk/rpk-profile/rpk-profile-print.adoc(1 hunks)modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc(1 hunks)modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-set.adoc(1 hunks)modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc(1 hunks)modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc(1 hunks)modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc(1 hunks)modules/reference/pages/rpk/rpk-registry/rpk-registry-mode-set.adoc(1 hunks)modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc(2 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-config-generate.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-create.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-delete.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-failover.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-list.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-status.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow-update.adoc(1 hunks)modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc(1 hunks)modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc(1 hunks)modules/reference/partials/rpk-cloud/rpk-cloud-cluster-select.adoc(2 hunks)modules/reference/partials/rpk-cloud/rpk-cloud-mcp-install.adoc(1 hunks)modules/shared/partials/emergency-shadowing-callout.adoc(1 hunks)modules/shared/partials/shadow-link-management-tip.adoc(1 hunks)modules/upgrade/pages/deprecated/index.adoc(4 hunks)modules/upgrade/pages/iceberg-schema-changes-and-migration-guide.adoc(1 hunks)modules/upgrade/partials/iceberg-breaking-changes.adoc(1 hunks)modules/upgrade/partials/incompat-changes.adoc(1 hunks)tests/docker-compose/docker-compose.yml(2 hunks)tests/setup-tests/fetch-versions-and-rpk.json(1 hunks)
💤 Files with no reviewable changes (8)
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config.adoc
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-lint.adoc
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-get.adoc
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-force-reset.adoc
- modules/manage/pages/whole-cluster-restore.adoc
- modules/manage/pages/topic-recovery.adoc
- modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-status.adoc
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1349
File: modules/manage/pages/cluster-maintenance/manage-throughput.adoc:0-0
Timestamp: 2025-09-03T16:34:58.323Z
Learning: For Redpanda documentation, use absolute URLs (https://docs.redpanda.com/api/...) rather than relative URLs (/api/...) when linking to API documentation. Relative API links break in Netlify previews because Bump only serves from docs.redpanda.com, causing the relative URLs to be appended to the preview URL where Bump doesn't serve content.
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
📚 Learning: 2025-09-16T13:51:26.524Z
Learnt from: JakeSCahill
Repo: redpanda-data/docs PR: 1358
File: modules/reference/partials/rpk-cloud/rpk-cloud-mcp-proxy.adoc:57-63
Timestamp: 2025-09-16T13:51:26.524Z
Learning: rpk config file search paths are platform-specific: macOS uses "~/Library/Application Support/rpk/rpk.yaml" while Linux uses "/var/lib/redpanda/.config/rpk/rpk.yaml". The documentation should account for platform differences rather than assuming Linux-only paths.
Applied to files:
modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adocmodules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-config-print.adoc
📚 Learning: 2025-05-07T01:06:00.937Z
Learnt from: kbatuigas
Repo: redpanda-data/docs PR: 1113
File: modules/manage/partials/iceberg/use-iceberg-catalogs.adoc:100-107
Timestamp: 2025-05-07T01:06:00.937Z
Learning: In AsciiDoc documentation for Redpanda, the syntax `+` and `--` around content blocks within a `[tabs]` section are valid AsciiDoc formatting elements for tabbed content. The `+` after a tab name (like `rpk::`) indicates that the following block belongs to that tab, and the `--` markers enclose the content for that tab. These are not diff artifacts and should not be removed.
Applied to files:
modules/reference/pages/rpk/rpk-shadow/rpk-shadow-list.adocmodules/reference/pages/rpk/rpk-shadow/rpk-shadow-describe.adocmodules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc
📚 Learning: 2025-08-25T21:00:26.626Z
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1334
File: modules/manage/partials/rbac-dp.adoc:93-98
Timestamp: 2025-08-25T21:00:26.626Z
Learning: In cloud documentation (env-cloud), Security is at the top level navigation, so ACL references should use `security:authorization/rbac/acl.adoc`. In self-managed documentation, Security is nested under Manage, so ACL references use `manage:security/authorization/acl.adoc`. The different xref paths in conditional blocks reflect these different navigation structures.
Applied to files:
modules/deploy/pages/redpanda/manual/production/production-readiness.adocmodules/manage/pages/security/index.adocmodules/ROOT/nav.adoc
📚 Learning: 2025-07-16T19:33:20.420Z
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
Applied to files:
modules/manage/pages/iceberg/specify-iceberg-schema.adocmodules/manage/pages/cluster-maintenance/disk-utilization.adocmodules/get-started/pages/licensing/overview.adocmodules/reference/pages/properties/topic-properties.adocmodules/ROOT/nav.adocmodules/manage/partials/whole-cluster-restore.adocmodules/reference/pages/properties/cluster-properties.adocmodules/upgrade/partials/iceberg-breaking-changes.adocmodules/upgrade/pages/deprecated/index.adoc
📚 Learning: 2025-07-14T19:28:43.296Z
Learnt from: Feediver1
Repo: redpanda-data/docs PR: 1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Applied to files:
modules/get-started/pages/release-notes/redpanda.adocmodules/upgrade/partials/incompat-changes.adocmodules/upgrade/partials/iceberg-breaking-changes.adocantora.ymlmodules/get-started/pages/install-beta.adoc
📚 Learning: 2025-08-19T19:26:57.364Z
Learnt from: paulohtb6
Repo: redpanda-data/docs PR: 1324
File: modules/deploy/partials/high-availability.adoc:537-537
Timestamp: 2025-08-19T19:26:57.364Z
Learning: In AsciiDoc documentation, page aliases (`:page-aliases:`) should never be removed as they serve as old redirects to maintain backward compatibility when pages are moved or renamed. They preserve SEO and prevent broken links for users.
Applied to files:
modules/manage/pages/high-availability.adocmodules/manage/pages/remote-read-replicas.adoc
📚 Learning: 2025-07-15T20:38:27.458Z
Learnt from: paulohtb6
Repo: redpanda-data/docs PR: 0
File: :0-0
Timestamp: 2025-07-15T20:38:27.458Z
Learning: In Redpanda documentation, "Redpanda Data" refers to the company name, while "Redpanda" refers to the product name. These terms should be used appropriately based on context.
Applied to files:
modules/get-started/pages/quick-start.adoc
📚 Learning: 2025-09-03T16:34:58.323Z
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1349
File: modules/manage/pages/cluster-maintenance/manage-throughput.adoc:0-0
Timestamp: 2025-09-03T16:34:58.323Z
Learning: For Redpanda documentation, use absolute URLs (https://docs.redpanda.com/api/...) rather than relative URLs (/api/...) when linking to API documentation. Relative API links break in Netlify previews because Bump only serves from docs.redpanda.com, causing the relative URLs to be appended to the preview URL where Bump doesn't serve content.
Applied to files:
local-antora-playbook.yml
| == Authenticate with HTTP Proxy | ||
|
|
||
| HTTP Proxy supports authentication using SCRAM credentials or OIDC tokens. | ||
| The authentication method depends on | ||
| ifndef::env-cloud[] | ||
| the xref:reference:properties/broker-properties.adoc#http_proxy_auth_method[`authentication_method`] broker property and | ||
| endif::[] | ||
| the cluster's xref:reference:properties/cluster-properties.adoc#http_authentication[`http_authentication`] settings. | ||
|
|
||
| === SCRAM Authentication | ||
|
|
||
| If HTTP Proxy is configured to support SASL, you can provide the SCRAM username and password as part of the Basic Authentication header in your request. For example, to list topics as an authenticated user: | ||
|
|
||
| [tabs] | ||
| ===== | ||
| curl:: | ||
| + | ||
| -- | ||
| [,bash] | ||
| ---- | ||
| curl -s -u "<username>:<password>" "<host-address>:8082/topics" | ||
| ---- | ||
| -- | ||
| NodeJS:: | ||
| + | ||
| -- | ||
| [,javascript] | ||
| ---- | ||
| let options = { | ||
| auth: { username: "<username>", password: "<password>" }, | ||
| }; | ||
| axios | ||
| .get(`${base_uri}/topics`, options) | ||
| .then(response => console.log(response.data)) | ||
| .catch(error => console.error(error)); | ||
| ---- | ||
| -- | ||
| Python:: | ||
| + | ||
| -- | ||
| [,python] | ||
| ---- | ||
| auth = ("<username>", "<password>") | ||
| res = requests.get(f"{base_uri}/topics", auth=auth).json() | ||
| pretty(res) | ||
| ---- | ||
| -- | ||
| ===== | ||
|
|
||
| === OIDC Authentication | ||
|
|
||
| If HTTP Proxy is configured to support OIDC, you can provide an OIDC token in the Authorization header. For example: | ||
|
|
||
| [tabs] | ||
| ===== | ||
| curl:: | ||
| + | ||
| -- | ||
| [,bash] | ||
| ---- | ||
| curl -s -H "Authorization: Bearer <oidc-token>" "<host-address>:8082/topics" | ||
| ---- | ||
| -- | ||
| NodeJS:: | ||
| + | ||
| -- | ||
| [,javascript] | ||
| ---- | ||
| let options = { | ||
| headers: { Authorization: `Bearer <oidc-token>` }, | ||
| }; | ||
| axios | ||
| .get(`${base_uri}/topics`, options) | ||
| .then(response => console.log(response.data)) | ||
| .catch(error => console.error(error)); | ||
| ---- | ||
| -- | ||
| Python:: | ||
| + | ||
| -- | ||
| [,python] | ||
| ---- | ||
| headers = {"Authorization": "Bearer <oidc-token>"} | ||
| res = requests.get(f"{base_uri}/topics", headers=headers).json() | ||
| pretty(res) | ||
| ---- | ||
| -- | ||
| ===== | ||
|
|
||
| ifndef::env-cloud[] | ||
| For details about configuring OIDC authentication, see xref:manage:security/authentication.adoc#oidc-http[OIDC Authentication]. | ||
| endif::[] |
There was a problem hiding this comment.
Critical: Duplicate authentication section with broken curl examples.
The "Authenticate with HTTP Proxy" section appears twice in this file:
- First occurrence (lines 76-240): Comprehensive with proper environment-aware port configuration (8082 vs 30082)
- Second occurrence (lines 1047-1146): Exact duplicate with simplified version but BROKEN curl examples
The curl examples in the duplicate section (lines 1067, 1111) are missing the http:// protocol, making them non-functional:
curl -s -u "<username>:<password>" "<host-address>:8082/topics" // ❌ BROKEN
curl -s -H "Authorization: Bearer <oidc-token>" "<host-address>:8082/topics" // ❌ BROKEN
Should be:
curl -s -u "<username>:<password>" "http://<host-address>:8082/topics" // ✅ CORRECT
curl -s -H "Authorization: Bearer <oidc-token>" "http://<host-address>:8082/topics" // ✅ CORRECT
Action items:
- Remove the duplicate authentication section (lines 1047-1146) OR clarify if it should exist
- If it must exist, fix the curl protocol errors
- Verify the final state of the authentication documentation is not duplicated
🤖 Prompt for AI Agents
modules/develop/partials/http-proxy.adoc lines 1047-1146: this block is a
duplicate of the earlier "Authenticate with HTTP Proxy" section and contains
broken curl examples missing the "http://" protocol; remove the duplicate block
entirely (preferred) or, if it must remain, update the two curl examples to
include the protocol (e.g., "http://<host-address>:<port>/topics"), ensure the
port selection matches the environment-aware ports used in the first occurrence
(8082 vs 30082), and then search the file to verify only a single authentication
section remains.
| === New rpk shadow commands | ||
|
|
||
| See also: xref:manage:security/authentication.adoc#sasl[Configure Authentication] and xref:manage:security/authorization/acl.adoc[] | ||
| This release introduces new xref:reference:rpk/rpk-shadow/rpk-shadow.adoc[`rpk shadow`] commands for managing Redpanda Shadow Links: | ||
|
|
||
| == Schema Registry Authorization | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] - Generate configuration files for shadow links | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`] - Create new shadow links | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`] - Update existing shadow link configurations | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] - List all shadow links | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`] - View shadow link configuration details | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] - Monitor shadow link replication status | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`] - Perform emergency failover operations | ||
| * xref:reference:rpk/rpk-shadow/rpk-shadow-delete.adoc[`rpk shadow delete`] - Delete shadow links |
There was a problem hiding this comment.
Remove duplicate rpk shadow commands list from "New commands" section.
The rpk shadow commands are documented twice: once in the "New rpk shadow commands" section (lines 24-35) and again in the "New commands" section (lines 71-80). This duplication violates the DRY principle and creates a maintenance burden.
Remove the duplicate rpk shadow commands list from lines 73-80 in the "New commands" section, leaving only the unique commands (rpk cluster connections and rpk redpanda config print):
== New commands
Redpanda v25.3 introduces the following xref:reference:rpk/rpk-shadow/rpk-shadow.adoc[`rpk shadow`] commands for managing Redpanda shadow links:
-* xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`] - Generate configuration files for shadow links
-* xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`] - Create new shadow links
-* xref:reference:rpk/rpk-shadow/rpk-shadow-update.adoc[`rpk shadow update`] - Update existing shadow link configurations
-* xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] - List all shadow links
-* xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`] - View shadow link configuration details
-* xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] - Monitor shadow link replication status
-* xref:reference:rpk/rpk-shadow/rpk-shadow-failover.adoc[`rpk shadow failover`] - Perform emergency failover operations
-* xref:reference:rpk/rpk-shadow/rpk-shadow-delete.adoc[`rpk shadow delete`] - Delete shadow links
-
In addition, the following commands have been added:
* xref:reference:rpk/rpk-cluster/rpk-cluster-connections.adoc[`rpk cluster connections`] - Monitor cluster connections and client statistics.
* xref:reference:rpk/rpk-redpanda/rpk-redpanda-config-print.adoc[`rpk redpanda config print`] - Display node configuration.Alternatively, restructure to reference the earlier section: "For rpk shadow commands, see New rpk shadow commands above. In addition, the following commands have been added:"
Also applies to: 71-80
🤖 Prompt for AI Agents
In modules/get-started/pages/release-notes/redpanda.adoc around lines 24-35 and
71-80, the list of rpk shadow commands is duplicated; remove the duplicate list
in the "New commands" section (lines ~73-80) and keep only the unique entries
(`rpk cluster connections` and `rpk redpanda config print`), or alternatively
replace those duplicate lines with a single sentence pointing readers to the
"New rpk shadow commands" section above (e.g., "For `rpk shadow` commands, see
New rpk shadow commands above.") to avoid repetition.
| * Connected client monitoring | ||
|
|
||
| == HTTP Proxy authentication changes | ||
| Existing Admin API endpoints from versions earlier than 25.3 remain supported, and you can continue to use them as usual. See xref:manage:use-admin-api.adoc[Manage Redpanda with the Admin API] to learn more about Admin API, and the link:/api/doc/admin/v2/[Admin API reference] to view the new endpoints. |
There was a problem hiding this comment.
Replace relative API URL with absolute URL for Netlify preview compatibility.
Line 52 uses a relative URL path (/api/doc/admin/v2/) which breaks in Netlify previews because Bump only serves content from docs.redpanda.com. Based on learnings, use an absolute URL instead.
Apply this diff:
-See xref:manage:use-admin-api.adoc[Manage Redpanda with the Admin API] to learn more about Admin API, and the link:/api/doc/admin/v2/[Admin API reference] to view the new endpoints.
+See xref:manage:use-admin-api.adoc[Manage Redpanda with the Admin API] to learn more about Admin API, and the https://docs.redpanda.com/api/doc/admin/v2/[Admin API reference] to view the new endpoints.Based on learnings from PR 1349.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Existing Admin API endpoints from versions earlier than 25.3 remain supported, and you can continue to use them as usual. See xref:manage:use-admin-api.adoc[Manage Redpanda with the Admin API] to learn more about Admin API, and the link:/api/doc/admin/v2/[Admin API reference] to view the new endpoints. | |
| Existing Admin API endpoints from versions earlier than 25.3 remain supported, and you can continue to use them as usual. See xref:manage:use-admin-api.adoc[Manage Redpanda with the Admin API] to learn more about Admin API, and the https://docs.redpanda.com/api/doc/admin/v2/[Admin API reference] to view the new endpoints. |
🤖 Prompt for AI Agents
modules/get-started/pages/release-notes/redpanda.adoc around line 52: the page
uses a relative URL link:/api/doc/admin/v2/ which breaks in Netlify previews;
replace the relative path with an absolute URL such as
link:https://docs.redpanda.com/api/doc/admin/v2/ so the Admin API reference
resolves correctly in previews, keeping the rest of the AsciiDoc link syntax and
descriptive text unchanged.
| == Security report | ||
|
|
||
| - xref:reference:properties/topic-properties.adoc#max.compaction.lag.ms[`max.compaction.lag.ms`] | ||
| - xref:reference:properties/topic-properties.adoc#min.compaction.lag.ms[`min.compaction.lag.ms`] | ||
| You can now generate a security report for your Redpanda cluster using the link:api/doc/admin/operation/operation-get_security_report[`/v1/security/report`] Admin API endpoint. The report provides detailed information about TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces (Kafka, RPC, Admin, Schema Registry, HTTP Proxy). |
There was a problem hiding this comment.
Fix malformed Admin API link format.
Line 63 contains a malformed link reference: link:api/doc/admin/operation/operation-get_security_report[...]. This link is missing a leading / and doesn't follow standard AsciiDoc link syntax. Verify the intended endpoint path and correct the format.
Please clarify the correct Admin API endpoint path and format. The link should likely be one of:
- Absolute URL:
https://docs.redpanda.com/api/doc/admin/operation/operation-get_security_report - Relative path:
/api/doc/admin/v2/operation/operation-get_security_report
Provide the corrected link and I can generate the fix.
| ifdef::env-cloud[] | ||
| :monitor-doc: manage:monitor-cloud.adoc#throughput | ||
| :connected-clients-api-doc-ref: link:/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections | ||
| endif::[] | ||
| ifndef::env-cloud[] | ||
| :monitor-doc: manage:monitoring.adoc#throughput | ||
| :connected-clients-api-doc-ref: link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections | ||
| endif::[] |
There was a problem hiding this comment.
Use absolute URLs for API documentation links to prevent Netlify preview breakage.
Lines 8 and 12 set attribute variables for API documentation with root-relative URLs like /api/doc/admin/v2/.... Per previous learnings in Redpanda docs (PR 1349), relative URLs break in Netlify previews because Bump only serves from docs.redpanda.com.
Change these to absolute URLs:
- Cloud:
https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections - Non-cloud:
https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections
Apply this diff to fix the API documentation URLs:
ifdef::env-cloud[]
:monitor-doc: manage:monitor-cloud.adoc#throughput
-:connected-clients-api-doc-ref: link:/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections
+:connected-clients-api-doc-ref: link:https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections
endif::[]
ifndef::env-cloud[]
:monitor-doc: manage:monitoring.adoc#throughput
-:connected-clients-api-doc-ref: link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections
+:connected-clients-api-doc-ref: link:https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections
endif::[]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ifdef::env-cloud[] | |
| :monitor-doc: manage:monitor-cloud.adoc#throughput | |
| :connected-clients-api-doc-ref: link:/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections | |
| endif::[] | |
| ifndef::env-cloud[] | |
| :monitor-doc: manage:monitoring.adoc#throughput | |
| :connected-clients-api-doc-ref: link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections | |
| endif::[] | |
| ifdef::env-cloud[] | |
| :monitor-doc: manage:monitor-cloud.adoc#throughput | |
| :connected-clients-api-doc-ref: link:https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections | |
| endif::[] | |
| ifndef::env-cloud[] | |
| :monitor-doc: manage:monitoring.adoc#throughput | |
| :connected-clients-api-doc-ref: link:https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections | |
| endif::[] |
🤖 Prompt for AI Agents
In modules/manage/pages/cluster-maintenance/manage-throughput.adoc around lines
6 to 13, the :connected-clients-api-doc-ref: attribute values use root-relative
URLs which break in Netlify previews; update the two attribute assignments to
use the absolute URLs provided (for cloud use
https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-monitoringservice_listkafkaconnections
and for non-cloud use
https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections)
so both conditional blocks reference the full https://docs.redpanda.com paths.
|
|
||
| |-p, --partition |stringArray |Comma-separated partition IDs. When provided, `rpk` saves extra Admin API requests for those partitions. See the help for extended usage. | ||
|
|
||
| |--wait |- |Wait for completion of remote bundle before returning. |
There was a problem hiding this comment.
Use consistent hyphenation for "remote-bundle" across flag descriptions.
Line 50 uses "remote bundle" (without hyphen) while line 52 uses "remote-bundle" (with hyphen). Since the command itself is rpk debug remote-bundle start, maintain the hyphen for consistency throughout the documentation.
Apply this diff to fix the inconsistency:
-|--wait |- |Wait for completion of remote bundle before returning.
+|--wait |- |Wait for completion of remote-bundle before returning.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| |--wait |- |Wait for completion of remote bundle before returning. | |
| |--wait |- |Wait for completion of remote-bundle before returning. |
🤖 Prompt for AI Agents
In modules/reference/pages/rpk/rpk-debug/rpk-debug-remote-bundle-start.adoc
around line 50, the flag description uses "remote bundle" without a hyphen while
elsewhere (line 52) it uses "remote-bundle"; update the text on line 50 to use
"remote-bundle" so the term matches the command name and other descriptions,
ensuring consistent hyphenation across the document.
| * 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. | ||
| * 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`. |
There was a problem hiding this comment.
Add missing --serverless-network flag documentation to the Flags table.
Line 19 mentions and recommends using the --serverless-network flag, but this flag is not documented in the Flags table below (lines 46–75). This creates an inconsistency where users learn about the flag in the prose but cannot find its documentation in the reference section.
The companion file modules/reference/partials/rpk-cloud/rpk-cloud-cluster-select.adoc documents this flag correctly in its Flags table (line 40), establishing the expected documentation pattern.
Add the --serverless-network flag documentation to the Flags table. Insert it after the --from-rpk-container row:
|--from-rpk-container |- |Create and switch to a new profile generated from a running cluster created with `rpk` container.
+|--serverless-network |string |Networking type for Serverless clusters: `public` or `private` (if not specified, will prompt if both are available).
+
|-h, --help |- |Help for create.Also applies to: 46-75
| |--node-tuner-state-path |string |Alternative path to read the node tuner state file from (if exists). | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Critical: Flag description inconsistent across rpk command documentation.
The --node-tuner-state-path flag description in this file states "read the node tuner state file from (if exists)", but the same flag in rpk-redpanda-tune.adoc (line 87) and rpk-redpanda-tune-list.adoc (line 44) describes it as "write the tuner state file to" with a default path. These descriptions are contradictory—the flag cannot both read from and write to a path.
Verify the actual flag behavior and ensure all three documentation pages use the correct and consistent description.
I'll verify the flag description inconsistency by examining the documentation files and searching for the actual implementation.
🏁 Script executed:
#!/bin/bash
# Check the exact descriptions of --node-tuner-state-path flag in all three files
echo "=== rpk-redpanda-start.adoc (lines 99-100) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | sed -n '99,100p'
echo -e "\n=== rpk-redpanda-tune.adoc (line 87) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc | sed -n '87p'
echo -e "\n=== rpk-redpanda-tune-list.adoc (line 44) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc | sed -n '44p'
# Expand context to see full descriptions
echo -e "\n=== rpk-redpanda-start.adoc (lines 98-102) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | sed -n '98,102p'
echo -e "\n=== rpk-redpanda-tune.adoc (lines 85-90) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune.adoc | sed -n '85,90p'
echo -e "\n=== rpk-redpanda-tune-list.adoc (lines 42-47) ==="
cat modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-tune-list.adoc | sed -n '42,47p'Length of output: 1428
🏁 Script executed:
#!/bin/bash
# Search for --node-tuner-state-path in codebase to find implementation/usage
echo "=== Searching for --node-tuner-state-path in codebase ==="
rg -n "node-tuner-state-path" --type-list | head -20
echo -e "\n=== Context around --node-tuner-state-path occurrences ==="
rg -n "node-tuner-state-path" -C 3 | head -50
# Also search for node tuner state file references
echo -e "\n=== Searching for node tuner state file ==="
rg -n "node.tuner.state" -C 2 | head -50Length of output: 4754
Update flag descriptions to be consistent across all three rpk command documentation pages.
The --node-tuner-state-path flag has contradictory descriptions:
rpk-redpanda-start.adocline 99: "read the node tuner state file from"rpk-redpanda-tune.adocline 87: "write the tuner state file to"rpk-redpanda-tune-list.adocline 44: "write the tuner state file to"
A flag cannot both read from and write to a path. Verify the actual flag behavior in the command implementations and update the incorrect documentation to match the correct behavior.
🤖 Prompt for AI Agents
In modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc around lines
99-100, the description for --node-tuner-state-path contradicts the other two
pages; verify the flag's actual behavior in the rpk command implementation
(whether it reads from or writes to the tuner state file) and then update this
page (and the other two if necessary) so all three descriptions match the real
behavior — change the text to either "path to read the node tuner state file
from" or "path to write the node tuner state file to" accordingly and keep the
phrasing consistent across rpk-redpanda-start.adoc, rpk-redpanda-tune.adoc, and
rpk-redpanda-tune-list.adoc.
|
|
||
| |--schema-version |int |Optional schema version to use when creating the schema in import mode (requires `--id` and the default is `-1`). | ||
|
|
||
|
|
There was a problem hiding this comment.
Remove extraneous blank line in Flags table.
Line 64 contains an extra blank line between the --schema-version and --type flag rows, breaking the table structure. This should be removed to maintain consistent table formatting.
Apply this diff to remove the extraneous blank line:
|--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.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| |--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. |
🤖 Prompt for AI Agents
In modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc
around line 64, there is an extraneous blank line between the --schema-version
and --type flag rows that breaks the Flags table; remove that blank empty line
so the two flag rows are adjacent and the table markup remains continuous, then
verify table renders correctly.
| | Redpanda has deprecated these cipher suites in accordance with security policy guidelines and now defaults to a more secure set of cipher suites provided by OpenSSL. If your Kafka API, Admin API, HTTP Proxy, or Schema Registry clients rely on any of the deprecated cipher suites, update them to use more secure alternatives. These cipher suites also apply to services that Redpanda connects to, such as S3. | ||
|
|
||
| You can configure available cipher suites by specifying xref:reference:cluster-properties.adoc#tls_v1_2_cipher_suites[`tls_v1_2_cipher_suites`] or xref:reference:cluster-properties.adoc#tls_v1_3_cipher_suites[`tls_v1_3_cipher_suites`] cluster properties in OpenSSL 3.0 format. |
There was a problem hiding this comment.
🧩 Analysis chain
Verify OpenSSL 3.0 format cipher suite syntax compatibility.
Line 52 states that cipher suites should be "specified... in OpenSSL 3.0 format." However, the list above (lines 33-48) uses traditional OpenSSL name format (e.g., AES256-GCM-SHA384), not OpenSSL 3.0 IANA format. Clarify whether users should convert these names or provide examples of the expected OpenSSL 3.0 format.
🌐 Web query:
What is the OpenSSL 3.0 format for TLS cipher suite configuration?
💡 Result:
Short answer
- OpenSSL 3.0 uses the SSL_CONF configuration options in openssl.cnf: use CipherString to control TLS 1.2 and older suites, and Ciphersuites to control TLS 1.3 suites. Values are strings (see below). [1][2]
Key points / syntax
- CipherString — controls TLSv1.2 and earlier. It is a colon/comma/space‑separated list of cipher‑string terms that may be:
- named groups (DEFAULT, HIGH, ALL, e.g. DEFAULT:@SECLEVEL=2)
- individual cipher names (ECDHE-RSA-AES128-GCM-SHA256)
- modifiers: ! (remove permanently), - (remove), + (move to end), @strength (sort), @SECLEVEL=n (set security level). Multiple terms combine left→right. [2][3]
- Ciphersuites — controls TLS 1.3; it is a colon-separated ordered list of TLS 1.3 cipher suite names (e.g. TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256). These are applied in preference order. [1][2]
- Other useful ssl_conf settings: MinProtocol / MaxProtocol, Options (e.g. ServerPreference, PrioritizeChaCha), and provider activation sections in openssl.cnf. [1][2]
Example openssl.cnf fragment
[default_conf]
ssl_conf = ssl_section
[ssl_section]
system_default = system_default_section
[system_default_section]
MinProtocol = TLSv1.2
CipherString = DEFAULT:@SECLEVEL=2
Ciphersuites = TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256
Options = ServerPreference,PrioritizeChaCha
References
- OpenSSL 3.0 SSL_CONF_cmd / configuration documentation. [docs.openssl.org].
- OpenSSL Cookbook — example ssl_conf and CipherString/Ciphersuites usage. [Feistyduck OpenSSL Cookbook].
- OpenSSL ciphers / cipher string format (man page). [openssl manpages].
🏁 Script executed:
#!/bin/bash
# Search for documentation or configuration handling of tls_v1_2_cipher_suites and tls_v1_3_cipher_suites
rg -i "tls_v1_[23]_cipher_suites" -A 3 -B 3 --type adoc --type md -g "!node_modules"Length of output: 28
🏁 Script executed:
#!/bin/bash
# Look for the deprecated cipher list mentioned in lines 33-48
rg -i "AES256-GCM-SHA384|deprecated.*cipher|cipher.*deprecated" -A 2 -B 2 --type adoc -g "modules/upgrade/pages/deprecated/index.adoc"Length of output: 28
🏁 Script executed:
#!/bin/bash
# Search for any format specification or examples of cipher suite values
rg -i "OpenSSL.*format|cipher.*format|IANA.*format" -A 2 -B 2 --type adoc --type md -g "!node_modules"Length of output: 28
🏁 Script executed:
#!/bin/bash
# Check the actual file to see full context around lines 33-52
cat modules/upgrade/pages/deprecated/index.adoc | head -60 | tail -40Length of output: 2102
🏁 Script executed:
#!/bin/bash
# Search for cluster-properties.adoc file
fd -type f "cluster-properties" Length of output: 170
🏁 Script executed:
#!/bin/bash
# Search for tls_v1_2_cipher_suites and tls_v1_3_cipher_suites definitions without file type
rg "tls_v1_2_cipher_suites|tls_v1_3_cipher_suites" -A 5 -B 2Length of output: 3882
🏁 Script executed:
#!/bin/bash
# Look for references to OpenSSL format in documentation
rg "OpenSSL.*3\.0|IANA.*cipher|cipher.*IANA" -A 3 -B 1Length of output: 1978
Clarify that "OpenSSL 3.0 format" encompasses both traditional and IANA cipher suite naming conventions.
The statement "in OpenSSL 3.0 format" on line 52 is technically correct—OpenSSL 3.0 accepts traditional cipher names (e.g., AES256-GCM-SHA384) for TLS 1.2 via CipherString configuration and IANA format names (e.g., TLS_AES_128_CCM_8_SHA256) for TLS 1.3 via Ciphersuites configuration. However, the documentation could be clearer that:
tls_v1_2_cipher_suitesexpects traditional OpenSSL format (colon-separated, e.g.,AES256-GCM-SHA384:AES128-GCM-SHA256)tls_v1_3_cipher_suitesexpects IANA format (colon-separated, e.g.,TLS_AES_128_CCM_8_SHA256)
Consider adding brief clarification that these formats differ between TLS versions, or reference the cluster-properties documentation for specifics.
🤖 Prompt for AI Agents
In modules/upgrade/pages/deprecated/index.adoc around lines 50–52, clarify that
"OpenSSL 3.0 format" covers two different naming conventions:
tls_v1_2_cipher_suites expects traditional OpenSSL cipher names
(colon-separated, e.g., AES256-GCM-SHA384:AES128-GCM-SHA256) while
tls_v1_3_cipher_suites expects IANA-style names (colon-separated, e.g.,
TLS_AES_128_CCM_8_SHA256); update the paragraph to state this distinction
concisely and/or add a short pointer to the cluster-properties docs for exact
syntax and examples.
Description
Resolves https://redpandadata.atlassian.net/browse/
Review deadline:
Page previews
Checks