[25.2] Clean up API doc xrefs to new Bump URLs #1311
Conversation
- Convert xref:api:ROOT:admin-api.adoc to link:/api/doc/admin/ - Convert xref:api:ROOT:pandaproxy-rest.adoc to link:/api/doc/http-proxy/ - Convert xref:api:ROOT:pandaproxy-schema-registry.adoc to link:/api/doc/schema-registry/ - Convert xref:api:ROOT:cloud-controlplane-api.adoc to link:/api/doc/cloud-controlplane/ - Convert xref:api:ROOT:cloud-dataplane-api.adoc to link:/api/doc/cloud-dataplane/ Updated files include navigation, authentication docs, API references, schema registry documentation, Iceberg configuration, and cluster management documentation.
📝 WalkthroughWalkthroughThis PR updates documentation links from internal xrefs to direct API doc URLs across multiple files (Admin, HTTP Proxy, Schema Registry, Cloud Control Plane/Data Plane). It also adds detailed procedural content: Kubernetes and non-Kubernetes connectivity examples (ports, TLS/mTLS/SASL), recovery mode activation/verification/exit with Admin API partition controls, partition-recovery force_replicas workflow, and expanded Iceberg/Open Catalog and Snowflake integration steps (secrets, cluster updates, topic config, schema registration, validation). Navigation and reference pages are aligned to the new link format. Sequence Diagram(s)sequenceDiagram
autonumber
actor Operator
participant Client as Admin API Client (curl/rpk)
participant RP as Redpanda Cluster
note over Operator,RP: Partition recovery - force replicas
Operator->>Client: POST /debug/partitions/kafka/<topic>/<partition>/force_replicas { replicas:[4,5] }
Client->>RP: Force replicas request
RP-->>Client: 202 Accepted / 200 OK
Client-->>Operator: Response status
note over RP: Controller reassigns replicas to brokers 4 and 5
sequenceDiagram
autonumber
actor Operator
participant Ctrl as Cloud/Control Plane API
participant DP as Data Plane API
participant RP as Redpanda Cluster
note over Operator,RP: Iceberg + Open Catalog setup (high level)
Operator->>DP: POST /v1/secrets (catalog creds, scope)
DP-->>Operator: Secret created
Operator->>Ctrl: PATCH /v1/clusters/<id> (enable Iceberg, ref secret)
Ctrl-->>Operator: Update accepted
Operator->>RP: rpk topic create / alter-config redpanda.iceberg.mode=...
RP-->>Operator: Config applied
Operator->>RP: rpk registry schema create ...
RP-->>Operator: Subject/version created
sequenceDiagram
autonumber
actor Operator
participant K8s as Kubernetes/Helm
participant RP as Redpanda Brokers
note over Operator,RP: Recovery mode lifecycle
Operator->>K8s: Set recovery_mode_enabled: true (YAML/Helm)
K8s->>RP: Rollout with recovery mode
RP-->>Operator: rpk cluster health (nodes in recovery mode)
Operator->>RP: Admin API disable/enable partitions (optional)
Operator->>K8s: Set recovery_mode_enabled: false
K8s->>RP: Rollout to normal mode
RP-->>Operator: rpk cluster health (normal)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (9)
modules/manage/partials/mountable-topics.adoc (1)
372-374: Fix Admin API cancel endpoint path (missing/migrations/)The cancel example omits the
migrationssegment; earlier examples in this doc and the API surface use/v1/migrations/<migration-id>. This is likely to mislead users.Apply:
-curl -X POST http://localhost:9644/v1/<migration-id>/?action=cancel +curl -X POST http://localhost:9644/v1/migrations/<migration-id>/?action=cancelmodules/manage/pages/cluster-maintenance/partition-recovery.adoc (1)
58-76: Fix curl line continuation and invalid JSON body for force_replicasThe example as written will fail:
- Missing trailing backslash on Line 59 causes the
-dline to run as a separate (invalid) shell command.- The JSON body is invalid: an object literal wrapping a bare array without a key. Most likely the endpoint expects either a top-level array of replicas or a named property containing the array.
Proposed fix (top-level array variant):
-curl -X POST http://localhost:9644/v1/debug/partitions/kafka/test/0/force_replicas \ - -H 'Content-Type: application/json' - -d '{ - [ - { - "node_id": 1, - "core": 1 - }, - { - "node_id": 4, - "core": 1 - }, - { - "node_id": 5, - "core": 0 - } - ] - }' +curl -X POST http://localhost:9644/v1/debug/partitions/kafka/test/0/force_replicas \ + -H 'Content-Type: application/json' \ + -d '[ + { "node_id": 1, "core": 1 }, + { "node_id": 4, "core": 1 }, + { "node_id": 5, "core": 0 } + ]'modules/manage/partials/iceberg/use-iceberg-catalogs.adoc (1)
156-161: Secret payload must be Base64-encoded; fix example to prevent API errorsThe text states the secret must be Base64-encoded, but the example uses a raw
<secret-value>. This discrepancy will cause request failures or invalid secrets.Minimal correction (keep placeholders explicit):
-curl -X POST "https://<dataplane-api-url>/v1/secrets" \ - -H 'accept: application/json'\ - -H 'authorization: Bearer <token>'\ - -H 'content-type: application/json' \ - -d '{"id":"<secret-name>","scopes":["SCOPE_REDPANDA_CLUSTER"],"secret_data":"<secret-value>"}' +curl -X POST "https://<dataplane-api-url>/v1/secrets" \ + -H 'accept: application/json' \ + -H 'authorization: Bearer <token>' \ + -H 'content-type: application/json' \ + -d '{"id":"<secret-name>","scopes":["SCOPE_REDPANDA_CLUSTER"],"secret_data":"<base64-secret-value>"}'Optionally, show how to produce a Base64 value without newlines:
- macOS/Linux:
printf %s '<secret-value>' | base64(usebase64 -w0where available to avoid line wraps)Also ensure the Base64 output does not include trailing newlines.
Also applies to: 165-171
modules/manage/partials/iceberg/about-iceberg-topics.adoc (2)
280-289: Fix invalid Avro schema example: stray character and incorrect logical type usageTwo issues:
- Line 280: stray
.after the closing brace breaks JSON.logicalType: "date"cannot be applied to a string; Avrodateis anintlogical type, and timestamps are typicallylongwithtimestamp-millis/timestamp-micros.If you want an ISO 8601 timestamp, keep it as a plain string without logicalType. If you want a typed timestamp, use
longwithtimestamp-millis. Example fix (typed timestamp):- } - . - { + }, + { "name": "ts", - "type": [ - "null", - { "type": "string", "logicalType": "date" } - ], + "type": [ + "null", + { "type": "long", "logicalType": "timestamp-millis" } + ], "default": null # Default value for the new field }
298-299: Fix invalid ISO 8601 example: remove double 'Z'The timestamp has
ZZ. Use a singleZ.-echo '{"user_id":858, "event_type":"BUTTON_CLICK", "ts":{"string":"2025-02-26T20:05:23.230ZZ"}}' | rpk topic produce demo-topic --format='%v\n' --schema-id=topic +echo '{"user_id":858, "event_type":"BUTTON_CLICK", "ts":{"string":"2025-02-26T20:05:23.230Z"}}' | rpk topic produce demo-topic --format='%v\n' --schema-id=topicmodules/manage/pages/kubernetes/networking/k-connect-to-redpanda.adoc (4)
309-309: Update remaining Schema Registry reference to new /api/doc URLThis section still points to the old AsciiDoc xref. Replace with the new schema registry API docs link for consistency with this PR.
Apply this diff:
-For all available endpoints, see xref:api:ROOT:pandaproxy-schema-registry.adoc[]. +For all available endpoints, see the link:/api/doc/schema-registry/[Schema Registry API reference].
534-545: Fix container port value in external HTTP Proxy example (8083 vs 8082)The YAML shows port: 8083, but the explanatory sentence says 8082. This will confuse readers.
Apply this diff:
-In this example, the external port on the container is 8082. The external node port on the worker node is 30082. +In this example, the external port on the container is 8083. The external node port on the worker node is 30082.
637-637: Update remaining external Schema Registry reference to new /api/doc URLThis still uses the old xref and should be migrated to the unified /api/doc link.
Apply this diff:
-For all available endpoints, see xref:api:ROOT:pandaproxy-schema-registry.adoc[]. +For all available endpoints, see the link:/api/doc/schema-registry/[Schema Registry API reference].
648-659: External Admin API section uses wrong ports and wrong YAML key (copy/paste from Schema Registry)
- The text says 8084/30081 which are Schema Registry ports, not Admin API.
- The YAML block uses listeners.schemaRegistry instead of listeners.admin.
- Admin API typical external example here should be 9645 (container) and 31644 (node port), matching the curl examples below.
Apply this diff:
-In this example, the external port on the container is 8084. The external node port on the worker node is 30081. +In this example, the external port on the container is 9645. The external node port on the worker node is 31644.-listeners: - schemaRegistry: - external: - default: - port: 9645 - advertisedPorts: - - 31644 +listeners: + admin: + external: + default: + port: 9645 + advertisedPorts: + - 31644
🧹 Nitpick comments (7)
modules/develop/pages/produce-data/configure-producers.adoc (1)
252-252: Clarify “activate feature” wording when instructing to disable broker_time_based_retention“Activate feature” can read as the opposite of “disable.” Consider making the action explicit and consistent with the feature flag name.
Apply:
-While not advised for typical use, Redpanda lets you override the use of broker timestamps for retention policy with the Admin API. Use the link:/api/doc/admin/operation/operation-put_feature[`activate feature`] API to disable the `broker_time_based_retention` property. +While not advised for typical use, Redpanda lets you override the use of broker timestamps for retention policy with the Admin API. Use the link:/api/doc/admin/operation/operation-put_feature[`put_feature`] operation to set the `broker_time_based_retention` feature to `false` (disable it).Optional example (outside this line range) that would make the instruction unambiguous:
curl -X PUT "http://<broker-address>:<admin-api-port>/v1/features/broker_time_based_retention" \ -H "content-type: application/json" \ -d '{"state":"disabled"}'modules/manage/partials/iceberg/use-iceberg-catalogs.adoc (1)
139-145: Clarify scope naming between rpk and API to avoid confusionrpk uses
--scopes redpanda_clusterwhile the API uses"SCOPE_REDPANDA_CLUSTER". Consider adding a note that these are equivalent representations in different interfaces to prevent misconfiguration.Also applies to: 165-170
modules/manage/partials/recovery-mode.adoc (1)
273-276: Optional: Include Content-Type header in curl POSTs for clarityWhile many servers infer JSON when
-dis used, explicitly adding-H 'Content-Type: application/json'avoids ambiguity and helps users behind strict proxies.-curl -X POST -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions/<partition-namespace>/<topic-name>/<partition-id> +curl -X POST -H 'Content-Type: application/json' -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions/<partition-namespace>/<topic-name>/<partition-id>(Apply similarly to the other POST examples.)
Also applies to: 294-295, 314-315, 334-335
modules/manage/partials/iceberg/about-iceberg-topics.adoc (2)
106-107: Replace lingering xref: control-plane API references with operation links for consistencyThese two references still use the old
xref:style. Suggest aligning them with the rest of the PR to use operation links.-The xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1/clusters/-cluster.id-[`PATCH /clusters/{cluster.id}`] request returns the ID of a long-running operation. The operation may take up to ten minutes to complete. You can check the status of the operation by polling the xref:api:ROOT:cloud-controlplane-api.adoc#get-/v1/operations/-id-[`GET /operations/{id}`] endpoint. +The link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request returns the ID of a long-running operation. The operation may take up to ten minutes to complete. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationsservice_getoperation[`GET /v1/operations/{id}`] endpoint.
206-214: Make JSON placeholders syntactically valid in allowed_subnet_ids exampleAs written,
<list-of-subnet-ids>isn’t valid JSON. Suggest a realistic placeholder array of strings so copy-paste works:- "allowed_subnet_ids": [ - <list-of-subnet-ids> - ] + "allowed_subnet_ids": [ + "<subnet-id-1>", + "<subnet-id-2>" + ]modules/manage/pages/schema-reg/schema-reg-authorization.adoc (1)
379-383: Migrate all remaining old-style Schema Registry API xrefsOur search uncovered 13 occurrences of
xref:api:ROOT:…schema-registry-api.adocandpandaproxy-schema-registry.adocacross the repo. For consistency, please update each to use the newlink:/api/doc/schema-registry/[Schema Registry API]format (or the appropriate fragment ID for deep links):• modules/manage/partials/authentication.adoc
– lines 1582, 1781• modules/manage/pages/schema-reg/schema-reg-authorization.adoc
– lines 29, 191• modules/manage/pages/schema-reg/schema-reg-api.adoc
– lines 10, 91, 987, 1058, 1067• modules/manage/pages/kubernetes/networking/k-connect-to-redpanda.adoc
– lines 309, 637• modules/get-started/pages/release-notes/redpanda.adoc
– lines 31, 42Remember to verify the correct fragment IDs on the new docs if you’re deep-linking to specific endpoints.
modules/manage/partials/authentication.adoc (1)
1542-1543: Update lingering Schema Registry API xrefs in authentication.adocTo keep the API references consistent with the new link style, please replace the remaining
xref:api:ROOT:pandaproxy-schema-registry.adoc[]occurrences:• modules/manage/partials/authentication.adoc, line 1582
• modules/manage/partials/authentication.adoc, line 1781Suggested diff:
- For all available endpoints, see xref:api:ROOT:pandaproxy-schema-registry.adoc[]. + For all available endpoints, see link:/api/doc/schema-registry/[Schema Registry API reference].
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (16)
modules/ROOT/nav.adoc(1 hunks)modules/develop/pages/produce-data/configure-producers.adoc(1 hunks)modules/manage/pages/cluster-maintenance/partition-recovery.adoc(2 hunks)modules/manage/pages/iceberg/redpanda-topics-iceberg-snowflake-catalog.adoc(1 hunks)modules/manage/pages/kubernetes/networking/k-connect-to-redpanda.adoc(4 hunks)modules/manage/pages/schema-reg/schema-reg-authorization.adoc(2 hunks)modules/manage/pages/schema-reg/schema-reg-overview.adoc(2 hunks)modules/manage/partials/authentication.adoc(3 hunks)modules/manage/partials/iceberg/about-iceberg-topics.adoc(2 hunks)modules/manage/partials/iceberg/use-iceberg-catalogs.adoc(2 hunks)modules/manage/partials/mountable-topics.adoc(1 hunks)modules/manage/partials/recovery-mode.adoc(2 hunks)modules/migrate/pages/kubernetes/strimzi.adoc(1 hunks)modules/reference/pages/api-reference.adoc(1 hunks)modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc(1 hunks)modules/upgrade/partials/rolling-upgrades/post-upgrade-tasks.adoc(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (23)
modules/upgrade/partials/rolling-upgrades/enable-maintenance-mode.adoc (1)
55-55: LGTM: xref → link migrated correctly to Admin API pre_restart_probeThe new path matches the convention used elsewhere in this PR.
modules/upgrade/partials/rolling-upgrades/post-upgrade-tasks.adoc (1)
16-16: LGTM: Admin API link updated to operation-post_restart_probeConsistent with the new
link:/api/doc/...pattern used across the repo.modules/migrate/pages/kubernetes/strimzi.adoc (1)
307-307: LGTM: HTTP Proxy API reference updated to new doc URLClearer wording and correct target for the full API reference.
modules/manage/partials/mountable-topics.adoc (1)
397-397: LGTM: Replace xref with Admin API delete_migration linkMatches the new
link:/api/doc/admin/operation/...convention and improves cross-doc consistency.modules/manage/pages/cluster-maintenance/partition-recovery.adoc (1)
54-60: Confirm expected request schema for force_replicasAdmin/debug endpoints often differ in payload shape. If this endpoint expects a named property (for example, {"replicas": [...]}) instead of a top-level array, adjust the body accordingly.
- If required, use:
-d '{"replicas":[{"node_id":1,"core":1},{"node_id":4,"core":1},{"node_id":5,"core":0}]}'Please verify against the Admin API docs for this specific debug endpoint.
Also applies to: 80-80
modules/manage/partials/iceberg/use-iceberg-catalogs.adoc (2)
152-152: Good: Updated to direct Data Plane API operation linkThe new link to operation-secretservice_createsecret aligns with the PR’s objective and improves consistency.
199-200: Good: Control Plane PATCH link updated to operation docThe link to operation-clusterservice_updatecluster is correct and consistent with the PR goals.
modules/manage/pages/iceberg/redpanda-topics-iceberg-snowflake-catalog.adoc (1)
145-146: Good: Added Data Plane API operation links for topic create/updateThe links to operation-topicservice_createtopic and operation-topicservice_updatetopicconfigurations are appropriate and align with the new linking scheme.
modules/manage/partials/recovery-mode.adoc (2)
245-246: Good: Switched to Admin API doc group for partitionsThe link to group/endpoint-partitions improves discoverability and is consistent with the new doc URL scheme.
381-382: Good: Added Admin API reference linkThis makes the section self-contained and consistent with the new linking approach.
modules/manage/partials/iceberg/about-iceberg-topics.adoc (1)
38-38: Good: Updated to direct Cloud Control Plane authentication linkThis matches the PR’s objective and improves consistency across docs.
modules/manage/pages/schema-reg/schema-reg-authorization.adoc (1)
370-375: Good migration to the new Schema Registry API link.The suggested reading now points to link:/api/doc/schema-registry/, which aligns with the PR objective.
modules/ROOT/nav.adoc (1)
258-260: Navigation updated to new API doc URLs — looks good.The nav now uses link:/api/doc/http-proxy/, link:/api/doc/schema-registry/, and link:/api/doc/admin/ consistently.
modules/manage/partials/authentication.adoc (2)
1357-1358: Admin API reference link change is correct.The link now points to link:/api/doc/admin/[Admin API reference]. Matches the new scheme.
1741-1742: Duplicate HTTP Proxy API reference migration looks correct.This matches the new link scheme and is consistent with earlier changes in this file.
modules/manage/pages/schema-reg/schema-reg-overview.adoc (2)
168-174: Suggested reading link updated — looks good.The link:/api/doc/schema-registry/ replacement is consistent with the PR goal.
176-180: Cloud block link updated — looks good.Consistent with the new link scheme.
modules/reference/pages/api-reference.adoc (1)
6-14: API Reference links migrated correctly.All three bullets now point to link:/api/doc/... targets and the surrounding explanatory text remains accurate. Nice cleanup.
modules/manage/pages/kubernetes/networking/k-connect-to-redpanda.adoc (5)
238-238: HTTP Proxy API link migration looks goodThe switch to link:/api/doc/http-proxy/ aligns with the PR’s objective and is correct.
369-369: Admin API link migration looks goodThe switch to link:/api/doc/admin/ matches the new standard and is correct.
580-580: HTTP Proxy API link migration looks goodThe switch to link:/api/doc/http-proxy/ is correct and consistent with other updates.
591-602: LGTM on Schema Registry external port exampleThe example ports (8084 container, 30081 node port) match the YAML.
687-687: Admin API link migration looks goodThe switch to link:/api/doc/admin/ is correct and consistent.
| Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT/config/\{subject}` in the link:/api/doc/schema-registry/[Schema Registry API]. | ||
|
|
There was a problem hiding this comment.
Fix minor endpoint typo in the updated line.
The method/path fragment shows a missing slash: it should be “PUT /config/{subject}” (with a space after the method and a slash before config).
Apply:
-Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT/config/{subject}` in the link:/api/doc/schema-registry/[Schema Registry API].
+Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT /config/{subject}` in the link:/api/doc/schema-registry/[Schema Registry API].🤖 Prompt for AI Agents
In modules/manage/pages/schema-reg/schema-reg-overview.adoc around lines 147 to
148, the endpoint text has a typo "PUT/config/{subject}"; update it to "PUT
/config/{subject}" by adding the missing space after the HTTP method and
ensuring there is a slash before "config" so the method/path fragment reads
correctly.
Description
This pull request updates documentation references to API endpoints, replacing older
xref:and.adoc-based links with new directlink:/api/doc/.../URLs pointing to the generated API documentation. This ensures consistency and accuracy in API references across the documentation, improving user navigation and reducing confusion.API Reference Link Updates
xref:or.adoclinks to the newlink:/api/doc/.../URLs throughout the documentation. This affects navigation menus, suggested reading, example instructions, and explanatory text. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15]Cloud API and Control Plane API References
link:/api/doc/cloud-controlplane/...andlink:/api/doc/cloud-dataplane/...URLs, ensuring all API documentation points to the correct generated docs. [1] [2] [3] [4] [5]Admin API Usage in Examples and Instructions
These changes collectively modernize API documentation references, making them more reliable and easier for users to follow.
Resolves https://redpandadata.atlassian.net/browse/
Review deadline:
Page previews
Checks