Bump xref cleanup #389
Bump xref cleanup #389
Conversation
📝 WalkthroughWalkthroughThis PR refactors documentation links across many pages to point to external Cloud API docs under /api/doc/*, replacing internal xref references. It removes several in-repo Cloud API pages (overview, quickstart, authentication, errors, deprecation policy). It updates numerous guides (BYOC AWS/Azure/GCP, PrivateLink/PSC, resource/secret management, RBAC, maintenance, reference, navigation) to use operation-specific links and adds new Cloud API workflow examples, JSON templates, and CLI/script blocks for provisioning networks/clusters and related steps. Sequence Diagram(s)sequenceDiagram
autonumber
actor U as User
participant Docs as Cloud Docs
participant CP as Control Plane API
participant Net as NetworkService
participant Cl as ClusterService
participant Op as OperationService
U->>Docs: Follow external API doc links
Note over Docs: Links point to /api/doc/cloud-controlplane/operation/...
U->>CP: POST /v1/networks (CreateNetwork)
CP->>Net: CreateNetwork
Net-->>CP: Operation ID
CP-->>U: 202 Accepted (operation_id)
loop Poll until done
U->>CP: GET /v1/operations/{id}
CP->>Op: GetOperation
Op-->>CP: status (DONE|RUNNING)
CP-->>U: status
end
U->>CP: POST /v1/clusters (CreateCluster)
CP->>Cl: CreateCluster
Cl-->>CP: Operation ID
CP-->>U: 202 Accepted (operation_id)
loop Poll until done
U->>CP: GET /v1/operations/{id}
CP->>Op: GetOperation
Op-->>CP: status (DONE|RUNNING)
CP-->>U: status
end
U->>CP: PATCH /v1/clusters/{id} (optional updates)
CP->>Cl: UpdateCluster -> Operation
Cl-->>CP: Operation ID
CP-->>U: 202 Accepted
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 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 rp-cloud 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: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (10)
modules/security/pages/cloud-authentication.adoc (2)
248-252: Fix Create Cluster curl: remove path parameter and stray backtickPOST /v1/clusters should not include a cluster ID in the URL. Also, there is a stray trailing backtick. This will lead to copy/paste failures.
Apply:
curl -v -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AUTH_TOKEN" \ --d "$CLUSTER_CREATE_BODY" https://api.redpanda.com/v1/clusters/<cluster-id>` +-d "$CLUSTER_CREATE_BODY" https://api.redpanda.com/v1/clusters
432-436: Fix Create Cluster (mTLS + SASL) curl: remove path parameter and stray backtickSame issue as above: POST should be to /v1/clusters without a path ID. Remove the extra backtick as well.
curl -v -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AUTH_TOKEN" \ --d "$CLUSTER_CREATE_BODY" https://api.redpanda.com/v1/clusters/<cluster-id>` +-d "$CLUSTER_CREATE_BODY" https://api.redpanda.com/v1/clustersmodules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc (2)
416-419: Environment variable mismatch: undefined REDPANDA_CLUSTER_RESOURCE_GROUP_NAMEThe JSON references ${REDPANDA_CLUSTER_RESOURCE_GROUP_NAME}, but earlier you export REDPANDA_RESOURCE_GROUP_NAME. This will render an empty value in the payload.
- "redpanda_resource_group" : { "name": "${REDPANDA_CLUSTER_RESOURCE_GROUP_NAME}" }, + "redpanda_resource_group" : { "name": "${REDPANDA_RESOURCE_GROUP_NAME}" },
449-457: Fix header line continuation and wording (“cluster ID” vs “network ID”)
- The prose says “get the network ID” but this is cluster creation and the code extracts a cluster ID.
- The curl command has a stray backslash after the accept header with a trailing space, which can break line continuation.
-. Make a Cloud API call to create a Redpanda cluster and get the network ID from the response in JSON `.operation.metadata.network_id`. +. Make a Cloud API call to create a Redpanda cluster and get the cluster ID from the response in JSON `.operation.resource_id`. @@ -export REDPANDA_ID=$(curl -X POST "https://api.redpanda.com/v1/clusters" \ - -H "accept: application/json"\ +export REDPANDA_ID=$(curl -X POST "https://api.redpanda.com/v1/clusters" \ + -H "accept: application/json" \ -H "content-type: application/json" \ -H "authorization: Bearer ${BEARER_TOKEN}" \ --data-binary @redpanda-cluster.json | jq -r '.operation.resource_id')modules/manage/partials/controlplane-api.adoc (2)
473-480: RBAC get-by-id link is correct; fix quoting in curlThe link is correct. The curl example starts a quote before the URL but never closes it until the next line, which likely breaks the command.
Apply:
-curl "https://api.redpanda.com/v1/role-bindings/<role-binding-id> \ +curl "https://api.redpanda.com/v1/role-bindings/<role-binding-id>" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json"
484-491: Get user link is correct; fix quoting in curlSame quoting issue as above.
Apply:
-curl "https://api.redpanda.com/v1/users/<user-account-id> \ +curl "https://api.redpanda.com/v1/users/<user-account-id>" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json"modules/manage/pages/api/cloud-dataplane-api.adoc (1)
215-223: Use Data Plane base URL for update-pipeline exampleThe example uses api.redpanda.com, but all Data Plane examples should use the cluster-specific .
Apply:
-curl -X PUT "https://api.redpanda.com/v1/redpanda-connect/pipelines/" \ +curl -X PUT "https://<dataplane-api-url>/v1/redpanda-connect/pipelines/<pipeline-id>" \ -H 'accept: application/json'\ -H 'content-type: application/json' \ -d '{"resources":{"cpu_shares":"8","memory_shares":"8G"}}'Also consider adding Authorization header for consistency with other examples.
modules/develop/pages/connect/configuration/resource-management.adoc (1)
179-194: Fix smart quotes in the code block attributeThe role attribute uses typographic quotes, which AsciiDoc won’t parse as expected. Use straight quotes.
Apply:
-[,bash,role=“no-placeholders”] +[,bash,role="no-placeholders"]modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc (2)
18-38: Network request body placeholders don’t match the example payload (Dedicated should not include BYOC fields)The payload for Dedicated only includes basic fields, but the placeholder list mentions BYOC-only fields like project ID, VPC name, and management bucket. This is confusing and likely incorrect for Dedicated.
Suggested fix: restrict placeholders to those actually present in the Dedicated request body.
Replace the following placeholder variables for the request body: -- - `<shared-vpc-name>`: The name for the network. - `<region>`: The GCP region where the network will be created. -- `<network-gcp-project-id>`: The ID of the GCP project where your VPC is created. -- `<network-name>`: The name of your VPC. -- `<management-bucket>`: The name of the Google Storage bucket you created for the cluster. --Alternatively, if BYOC details are intended, add the corresponding fields under
customer_managed_resources.gcpin the JSON body and gate with the appropriate env flags. Given:env-dedicated: true, the current body looks correct; the bullets should be trimmed.Also applies to: 40-48
51-56: Fix the path to the returned network ID (missing “operation.” prefix)The API response wraps metadata under
operation. Useoperation.metadata.network_id(oroperation.resource_idif you prefer).Apply:
-. Store the network ID (`metadata.network_id`) returned in the response to the Create Network request. +. Store the network ID (`operation.metadata.network_id`) returned in the response to the Create Network request. @@ -export NETWORK_ID=<metadata.network_id> +export NETWORK_ID=<operation.metadata.network_id>
🧹 Nitpick comments (17)
modules/manage/pages/maintenance.adoc (1)
126-126: Inline “See … for more information” link: add label and caret; verify consistency with line 108Mirror the same improvements here so both references have readable text and open in a new tab.
Apply this diff:
-See link:/api/doc/cloud-controlplane/topic/topic-deprecation-policy[] for more information. +See link:/api/doc/cloud-controlplane/topic/topic-deprecation-policy[Cloud Control Plane API deprecation policy^] for more information.Optionally, standardize phrasing to either “See also:” or “See … for more information.” across both occurrences for consistency.
modules/networking/partials/psc-api.adoc (1)
24-24: Good swap to external API docs; link target looks correct.The link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview target is valid and aligns with the PR-wide migration from xref to external API docs. Anchor text and the local access-token xref are intact.
For terminology consistency with other pages updated in this PR (for example, RBAC uses “Control Plane API”), consider standardizing the visible text to “Control Plane API.” No blocker.
modules/networking/pages/cloud-security-network.adoc (1)
207-207: Operation link update looks good; minor UI-label wording tweak recommended.The new link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster anchor is correct, and escaping the braces in the path is appropriate.
Optional: Per prior learning about matching UI labels verbatim, consider clarifying that the field on the Overview page is labeled “Internet gateway” to help users locate it.
Note: This suggestion references a prior learning about UI label accuracy in this doc set.
modules/develop/pages/managed-connectors/disable-kc.adoc (2)
39-39: Escape braces in link labels to avoid Asciidoctor attribute substitutionIn link labels, unescaped
{...}can be treated as attribute references by Asciidoctor, potentially rendering as empty text. Escape the opening brace for safety (you already do this elsewhere in the repo).-After you are authenticated to the Cloud API, make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request, replacing `{cluster.id}` with your actual cluster ID. +After you are authenticated to the Cloud API, make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/\{cluster.id}`] request, replacing `{cluster.id}` with your actual cluster ID. -The `PATCH` request returns the ID of a long-running operation. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /operations/{id}`] endpoint: +The `PATCH` request returns the ID of a long-running operation. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /operations/\{id}`] endpoint:Also applies to: 49-49
53-56: Prefer Accept header over Content-Type for GETFor GET requests, Content-Type is typically unnecessary. Use Accept to express expected response media type or omit headers altogether.
-curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ - -H "Authorization: Bearer $AUTH_TOKEN" \ - -H "Content-Type: application/json" +curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Accept: application/json"modules/get-started/pages/cluster-types/byoc/remote-read-replicas.adoc (2)
56-56: Escape braces in link label to prevent Asciidoctor from treating them as attributesAlign this with the escaping pattern you used later in the same file.
-. To update your source cluster to add one or more reader cluster IDs, make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request. The full list of clusters is expected on every call. If an ID is removed from the list, it is removed as a reader cluster. +. To update your source cluster to add one or more reader cluster IDs, make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/\{cluster.id}`] request. The full list of clusters is expected on every call. If an ID is removed from the list, it is removed as a reader cluster.
72-80: Header nit: Use Accept for GET requestsThe link label already escapes
{id}correctly. For the GET example, prefer Accept over Content-Type (or drop it entirely).-curl -X GET $API_HOST/v1/clusters/$SOURCE_CLUSTER_ID \ --H "Content-Type: application/json" \ --H "Authorization: Bearer $API_TOKEN" +curl -X GET $API_HOST/v1/clusters/$SOURCE_CLUSTER_ID \ +-H "Accept: application/json" \ +-H "Authorization: Bearer $API_TOKEN"modules/ROOT/nav.adoc (2)
434-437: Consider removing “.adoc” from external API doc links for consistencyElsewhere in the PR the /api/doc links omit the .adoc suffix. Aligning on one style avoids broken links if the external site doesn’t expose .adoc routes.
-*** link:/api/doc/cloud-controlplane/topic/topic-quickstart.adoc[Cloud API Quickstart] -*** link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview.adoc[Cloud API Overview] -*** link:/api/doc/cloud-controlplane/authentication.adoc[Cloud API Authentication] +*** link:/api/doc/cloud-controlplane/topic/topic-quickstart[Cloud API Quickstart] +*** link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API Overview] +*** link:/api/doc/cloud-controlplane/authentication[Cloud API Authentication]
442-444: Same .adoc suffix concern for these external linksRecommend dropping the .adoc suffix to match usage across the site and reduce the risk of 404s.
-*** link:/api/doc/cloud-controlplane/topic/topic-error-and-status-codes.adoc[Cloud API Errors and Status Codes] -*** link:/api/doc/cloud-controlplane/topic/topic-deprecation-policy.adoc[Cloud API Deprecation Policy] +*** link:/api/doc/cloud-controlplane/topic/topic-error-and-status-codes[Cloud API Errors and Status Codes] +*** link:/api/doc/cloud-controlplane/topic/topic-deprecation-policy[Cloud API Deprecation Policy]modules/develop/pages/connect/configuration/secret-management.adoc (1)
90-92: Update links are correct; minor nit on consistencyThe operation link for Update Secret is correct. Consider standardizing header capitalization in the curl examples below (Authorization, Content-Type, Accept) for consistency with other docs.
modules/manage/partials/controlplane-api.adoc (3)
86-97: Resource group creation link is correct; verify request body parity across docThis section uses a request body with a “resource_group” wrapper. See serverless section (Lines 259-266) using a flat body. Confirm whether both shapes are accepted; if not, align for consistency.
If only “resource_group” is accepted, update the serverless example for consistency. I can generate the patch once you confirm the expected schema.
257-266: Align resource group create request body with other sectionsIn the serverless RG example, the body is flat, unlike earlier sections that use “resource_group”: { name }. Ensure this shape is valid and consistent with API docs.
Proposed adjustment if the wrapper is required:
- -d '{ - "name": "<serverless-resource-group-name>" -}' -X POST https://api.redpanda.com/v1/resource-groups + -d '{ + "resource_group": { + "name": "<serverless-resource-group-name>" + } +}' -X POST https://api.redpanda.com/v1/resource-groups
326-358: Use a consistent base host for API examplesThis block uses https://api.cloud.redpanda.com while most other examples use https://api.redpanda.com. Pick one canonical host across the doc set to avoid confusion (prefer whatever your public docs endorse).
If https://api.redpanda.com is canonical, apply:
- }' -X PATCH "https://api.cloud.redpanda.com/v1/clusters/<cluster-id>" + }' -X PATCH "https://api.redpanda.com/v1/clusters/<cluster-id>"And similarly in Lines 347-358.
If both are valid, consider adding a short note clarifying equivalence.
modules/networking/pages/azure-private-link.adoc (1)
146-153: Suggest capturing operation ID explicitly for BYOC flowYou poll GET /v1/operations/{id} but only captured cluster_id. Recommend capturing operation.id in the create response to make the step actionable.
Apply:
-CLUSTER_ID=`curl -vv -X POST \ +CREATE_RESP=`curl -sS -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AUTH_TOKEN" \ - -d "$CLUSTER_POST_BODY" $PUBLIC_API_ENDPOINT/v1/clusters | jq -r .operation.metadata.cluster_id` - -echo $CLUSTER_ID + -d "$CLUSTER_POST_BODY" $PUBLIC_API_ENDPOINT/v1/clusters` +CLUSTER_ID=`echo "$CREATE_RESP" | jq -r .operation.metadata.cluster_id` +OPERATION_ID=`echo "$CREATE_RESP" | jq -r .operation.id` +echo "$CLUSTER_ID" +echo "$OPERATION_ID"Then, reference $OPERATION_ID in the poll step.
modules/networking/pages/aws-privatelink.adoc (1)
127-135: BYOC operation polling is correct; consider storing operation.idThe link is correct. Minor improvement: capture operation.id as proposed in the Azure guide for symmetry.
modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc (2)
31-31: Replace leftover xref with operation doc link and align auth link styleThis line mixes a new link with a legacy xref. Use operation docs consistently and align the authentication link path with the rest of the page.
Apply:
-* Familiarity with the Redpanda Cloud API. For example, you should be familiar with how to use the Cloud API to link:/api/doc/cloud-controlplane/authentication[authenticate] and xref:redpanda-cloud:manage:api/cloud-byoc-controlplane-api.adoc[create a cluster]. +* Familiarity with the Redpanda Cloud API. For example, you should be familiar with how to link:/api/doc/cloud-controlplane/topic/authentication[authenticate] and link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[create a cluster] using the Cloud API.
253-254: Correct likely typo in regions-and-usage-tiers linkThe path includes a duplicate “topic” segment. Recommend removing the extra “topic”.
Apply:
-TIP: See the full list of zones and tiers available with each provider in the link:/api/doc/cloud-controlplane/topic/topic-regions-and-usage-tiers[Control Plane API reference]. +TIP: See the full list of zones and tiers available with each provider in the link:/api/doc/cloud-controlplane/topic/regions-and-usage-tiers[Control Plane API reference].Please verify the exact URL is valid.
📜 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 (30)
modules/ROOT/nav.adoc(2 hunks)modules/develop/pages/connect/configuration/resource-management.adoc(3 hunks)modules/develop/pages/connect/configuration/secret-management.adoc(3 hunks)modules/develop/pages/managed-connectors/disable-kc.adoc(3 hunks)modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc(3 hunks)modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc(3 hunks)modules/get-started/pages/cluster-types/byoc/gcp/enable-rpcn-byovpc-gcp.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/gcp/enable-secrets-byovpc-gcp.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/remote-read-replicas.adoc(2 hunks)modules/get-started/pages/whats-new-cloud.adoc(4 hunks)modules/manage/pages/api/cloud-api-authentication.adoc(0 hunks)modules/manage/pages/api/cloud-api-deprecation-policy.adoc(0 hunks)modules/manage/pages/api/cloud-api-errors.adoc(0 hunks)modules/manage/pages/api/cloud-api-overview.adoc(0 hunks)modules/manage/pages/api/cloud-api-quickstart.adoc(0 hunks)modules/manage/pages/api/cloud-dataplane-api.adoc(15 hunks)modules/manage/pages/cluster-maintenance/config-cluster.adoc(4 hunks)modules/manage/pages/maintenance.adoc(2 hunks)modules/manage/pages/terraform-provider.adoc(2 hunks)modules/manage/partials/controlplane-api.adoc(21 hunks)modules/networking/pages/aws-privatelink.adoc(7 hunks)modules/networking/pages/azure-private-link.adoc(5 hunks)modules/networking/pages/byoc/gcp/enable-global-access.adoc(1 hunks)modules/networking/pages/cloud-security-network.adoc(1 hunks)modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc(4 hunks)modules/networking/pages/gcp-private-service-connect.adoc(5 hunks)modules/networking/partials/psc-api.adoc(1 hunks)modules/reference/pages/api-reference.adoc(1 hunks)modules/security/pages/authorization/rbac/rbac.adoc(1 hunks)modules/security/pages/cloud-authentication.adoc(7 hunks)
💤 Files with no reviewable changes (5)
- modules/manage/pages/api/cloud-api-deprecation-policy.adoc
- modules/manage/pages/api/cloud-api-errors.adoc
- modules/manage/pages/api/cloud-api-quickstart.adoc
- modules/manage/pages/api/cloud-api-authentication.adoc
- modules/manage/pages/api/cloud-api-overview.adoc
🧰 Additional context used
🧠 Learnings (7)
📚 Learning: 2025-07-21T21:52:17.061Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#361
File: modules/networking/pages/cloud-security-network.adoc:176-179
Timestamp: 2025-07-21T21:52:17.061Z
Learning: In Redpanda Cloud documentation, BYOVPC and BYOVNet are different product names for different cloud providers: BYOVPC is used for AWS and GCP, while BYOVNet is used for Azure. When documentation sections cover multiple cloud providers, the combined notation "BYOVPC/BYOVNet" is correct and should not be changed to use only one term.
Applied to files:
modules/manage/pages/terraform-provider.adocmodules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adocmodules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc
📚 Learning: 2025-08-07T16:36:45.111Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Applied to files:
modules/manage/pages/terraform-provider.adocmodules/networking/pages/cloud-security-network.adocmodules/networking/partials/psc-api.adocmodules/networking/pages/dedicated/gcp/configure-psc-in-api.adocmodules/networking/pages/byoc/gcp/enable-global-access.adocmodules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adocmodules/networking/pages/azure-private-link.adocmodules/networking/pages/gcp-private-service-connect.adocmodules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc
📚 Learning: 2025-06-18T21:02:38.074Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
Applied to files:
modules/get-started/pages/cluster-types/byoc/gcp/enable-rpcn-byovpc-gcp.adocmodules/networking/partials/psc-api.adocmodules/manage/pages/cluster-maintenance/config-cluster.adocmodules/reference/pages/api-reference.adocmodules/get-started/pages/cluster-types/byoc/remote-read-replicas.adocmodules/manage/partials/controlplane-api.adocmodules/networking/pages/aws-privatelink.adocmodules/networking/pages/azure-private-link.adocmodules/manage/pages/api/cloud-dataplane-api.adoc
📚 Learning: 2025-07-21T21:53:37.731Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#361
File: modules/networking/pages/cloud-security-network.adoc:193-196
Timestamp: 2025-07-21T21:53:37.731Z
Learning: In Redpanda Cloud documentation, field names and labels should match exactly what appears in the UI, even if the terminology might seem technically inconsistent. For example, the NAT gateway IP address field is labeled "Internet gateway" in the UI, so documentation should use "Internet gateway" to help users locate the correct field.
Applied to files:
modules/networking/pages/cloud-security-network.adoc
📚 Learning: 2025-08-11T22:06:05.137Z
Learnt from: david-yu
PR: redpanda-data/cloud-docs#387
File: modules/manage/pages/terraform-provider.adoc:99-102
Timestamp: 2025-08-11T22:06:05.137Z
Learning: In the Redpanda Terraform provider, modifying the `throughput_tier` attribute of a cluster resource will force cluster replacement (destroy and recreate) only when `allow_deletion` is set to `true`. If `allow_deletion` is `false`, Terraform will prevent the modification to protect against accidental cluster destruction.
Applied to files:
modules/manage/partials/controlplane-api.adocmodules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc
📚 Learning: 2025-04-25T01:42:09.318Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#267
File: modules/manage/pages/maintenance.adoc:63-64
Timestamp: 2025-04-25T01:42:09.318Z
Learning: The timeline for major upgrade notifications (180 days in advance) was intentionally removed from the Redpanda Cloud maintenance documentation, even though it was mentioned in the PR objectives.
Applied to files:
modules/manage/pages/maintenance.adoc
📚 Learning: 2025-04-25T01:41:57.162Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#267
File: modules/manage/pages/maintenance.adoc:91-92
Timestamp: 2025-04-25T01:41:57.162Z
Learning: The notification timeline for Redpanda Cloud deprecations has been deliberately removed from the documentation, even though the PR summary mentioned a 180-day advance notice period.
Applied to files:
modules/manage/pages/maintenance.adoc
⏰ 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 - rp-cloud
- GitHub Check: Header rules - rp-cloud
- GitHub Check: Pages changed - rp-cloud
🔇 Additional comments (73)
modules/manage/pages/cluster-maintenance/config-cluster.adoc (2)
60-60: Good update: correct operation link and endpoint labelThe link target and displayed verb/path look consistent for create cluster.
162-163: Verify topic link targets exist after doc site publishThese topic links look correct, but they’re new paths. Please confirm they resolve in preview/staging to avoid 404s after merge.
modules/security/pages/authorization/rbac/rbac.adoc (1)
16-16: LGTM: External Control Plane API link is consistent with the PR direction.Direct link to /api/doc/cloud-controlplane/ is appropriate; no content or formatting issues noted.
modules/get-started/pages/cluster-types/byoc/gcp/enable-secrets-byovpc-gcp.adoc (1)
87-87: No legacy xref anchors found; operation link is correctA repo-wide search for any
xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1/clusters/…patterns returned no matches. The link in modules/get-started/pages/cluster-types/byoc/gcp/enable-secrets-byovpc-gcp.adoc (line 87) is using the correct anchor and properly escapes the braces in its display text.modules/get-started/pages/cluster-types/byoc/gcp/enable-rpcn-byovpc-gcp.adoc (1)
90-90: LGTM: Updated to the operation-specific Control Plane API doc.Matches the standardized pattern; escaping of {cluster-id} is correct.
modules/manage/pages/terraform-provider.adoc (2)
28-28: Good switch to external Cloud API doc linkThe link replacement to the Cloud API overview looks correct and aligns with the PR goals.
167-167: Link target looks right; consider a quick spot-check for stabilityThe Control Plane API “regions and usage tiers” topic path looks accurate. Just recommend a quick click-through to confirm the final slug is stable.
modules/develop/pages/managed-connectors/disable-kc.adoc (2)
4-4: LGTM: Updated overview linkSwitching to the Cloud API overview on the external docs is consistent with the repo-wide change.
33-33: LGTM: Authentication linkPointing to the authentication page under the Cloud Control Plane docs is the right target.
modules/get-started/pages/cluster-types/byoc/remote-read-replicas.adoc (1)
54-54: LGTM: Mixed xref + external auth linkKeeping the local “Use the Control Plane API” guide via xref and pointing auth to the external docs is sensible here.
modules/reference/pages/api-reference.adoc (1)
4-15: LGTM: Reference links migrated to /api/doc/The four API reference entries now point to the consolidated API documentation. Looks consistent and clear.
modules/ROOT/nav.adoc (1)
461-465: LGTM: Reference section now points to external API docsThe Control Plane, Data Plane, HTTP Proxy, and Schema Registry entries are properly migrated.
modules/develop/pages/connect/configuration/secret-management.adoc (2)
39-41: Link swap to Data Plane API looks correctThe new links point to the quickstart and the specific Create Secret operation. Good alignment with the PR objective to replace xrefs.
139-141: Delete Secret operation link is correctThe move to direct operation links is accurate here as well.
modules/security/pages/cloud-authentication.adoc (5)
173-174: Good: control plane API link aligned to external docsThe overview link change matches the PR goal and looks correct.
312-313: Good: PATCH Update Cluster operation linkThe link to the update operation is correct and consistent with other files.
496-497: Good: PATCH Update Cluster (mTLS + SASL) operation linkConsistent and correct usage.
578-578: Good: PATCH Update Cluster (disable SASL) operation linkMatches the new link scheme.
701-703: Good: Added “See also” links to Cloud Control Plane docsBoth links resolve to the new API docs sections.
modules/networking/pages/byoc/gcp/enable-global-access.adoc (1)
9-9: Good: Updated intro link to Cloud API overviewThe new overview link is correct and consistent with the repo-wide changes.
modules/get-started/pages/whats-new-cloud.adoc (2)
224-225: Good: API references point to external docsThe separation into Control Plane and Data Plane references is clear and consistent.
347-348: Remove “.adoc” from API doc linksThese link targets should not include file extensions.
-The Cloud API allows you to programmatically manage clusters and resources in your Redpanda Cloud organization. For more information, see the link:/api/doc/cloud-controlplane/topic/topic-quickstart[Cloud API Quickstart], the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API Overview], and the full link:/api/doc/cloud-controlplane/[Control Plane API] and link:/api/doc/cloud-dataplane/[Data Plane API] reference documentation. +The Cloud API allows you to programmatically manage clusters and resources in your Redpanda Cloud organization. For more information, see the link:/api/doc/cloud-controlplane/topic/topic-quickstart[Cloud API Quickstart], the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API Overview], and the full link:/api/doc/cloud-controlplane/[Control Plane API] and link:/api/doc/cloud-dataplane/[Data Plane API] reference documentation.⛔ Skipped due to learnings
Learnt from: micheleRP PR: redpanda-data/cloud-docs#334 File: modules/networking/partials/psc-api2.adoc:15-16 Timestamp: 2025-06-18T21:02:38.074Z Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc (2)
30-31: Good: prerequisite uses external Cloud API overview linkMatches the new linking convention.
447-448: Good: regions and tiers link to external referenceThe link to topic-regions-and-usage-tiers is consistent with the new scheme.
modules/manage/partials/controlplane-api.adoc (11)
13-13: Good switch to canonical Control Plane API doc linkThe top-level reference now points to the centralized API docs. Looks correct.
63-67: Operation status link and usage look goodCorrect operation doc anchor and escaped path parameter. The curl example matches.
75-76: Region/tier topic link looks correctAnchor and text accurately reflect the new topic page.
103-123: Network creation references are consistent and correctCorrect operation doc link and sample payloads for env variants.
146-175: Create Cluster link and examples look goodCorrect operation doc anchor, payload, and long-running operation explanation.
207-208: Follow-up GET cluster link is correctCorrect operation doc anchor and escaped path parameter.
320-321: Serverless cluster GET link is correctGood: correct operation anchor and escaped path parameter.
367-371: Delete cluster link (dedicated/BYOC) looks correctCorrect operation doc anchor, verb, and path parameter format.
404-406: Follow-on network/resource group delete links are correctCorrect anchors and path parameter escaping.
462-469: RBAC list link looks correctCorrect operation doc link and usage. Query params example reads well.
518-531: Create service account link and example look goodOperation anchor and payload are aligned.
modules/networking/pages/azure-private-link.adoc (5)
66-76: Network creation link and guidance look correctOperation anchor and example payload are aligned. Good note to persist network_id.
102-103: Network readiness check link is correctCorrect get-network operation link and gating on STATE_READY.
104-115: Create Cluster link and placeholders look correctCorrect operation link with explicit versioned path.
168-186: Update Cluster link is correct; example payload looks fineOperation anchor and PATCH body are aligned.
194-212: Get Cluster link is correctCorrect anchor and usage to retrieve Azure Private Link details.
modules/networking/pages/aws-privatelink.adoc (7)
26-27: Correct switch to Cloud Control Plane overview linkAccurate topic link and wording.
46-79: Network creation link and flow are correctOperation doc anchor, payload, and capturing metadata.network_id look good.
81-82: Network readiness check link is correctCorrect get-network operation link and STATE_READY gating.
83-125: Create Cluster link and example look correctOperation doc anchor and BYOC/Dedicated placeholders are clear.
147-172: Update Cluster link/payload are correctOperation anchor and example PATCH body fields align with the intended feature.
176-184: Service-state check link is correctCorrect get-cluster operation link and jq filter for service_name/service_state.
375-376: Suggested reading link updated correctlyPoints to the new overview. Looks good.
modules/manage/pages/api/cloud-dataplane-api.adoc (14)
7-10: Correct switch to Data Plane API docs and overviewThe two top-level links correctly target the new API docs and overview topics.
18-25: Correct use of Control Plane GETs to discover Data Plane URLBoth cluster and serverless flows link to the right operation docs.
45-55: Create user link and example look correctOperation anchor and payload match expectations.
72-82: Create ACL link and example look correctOperation anchor and example payload are aligned.
92-101: Create topic link and example look correctAnchor and minimal request body are accurate.
109-118: Create secret link and example look correctGood: emphasizes Base64 requirement and correct endpoint.
140-149: Update secret link and example look correctCorrect operation anchor and payload constraints.
165-172: Delete secret link and example look correctCorrect operation doc link and method.
188-194: Get pipeline link looks correctAnchor and example are aligned.
197-203: Stop pipeline link looks correctAnchor and example are aligned.
206-212: Start pipeline link looks correctAnchor and example are aligned.
249-257: Kafka Connect create secret link and example look correctCorrect operation doc link and sample body.
263-274: Create connector link and example look correctOperation anchor and example configuration are aligned.
306-315: Restart connector link and example look correctAnchor and example are aligned.
modules/develop/pages/connect/configuration/resource-management.adoc (3)
142-147: Correct links to DP quickstart and list pipelinesAnchors point to the new operation/topic docs and match surrounding text.
170-173: Correct links for GET and PUT pipeline operationsAccurate operation anchors for fetch/update.
197-198: Verification step link is correctList pipelines anchor is accurate for verifying resource updates.
modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc (1)
142-144: Align Cloud Control Plane reference doc links for authentication and resource group creationPlease update the two links in modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc (lines 142–144) to point at the correct reference docs and verify the slugs against your published API docs:
• Authentication guide
Replace
link:/api/doc/cloud-controlplane/topic/authentication[Cloud API authentication guide]
with
link:/api/doc/cloud-controlplane/reference/authentication[Cloud API authentication guide]• Resource-group create operation
Replace
link:/api/doc/cloud-controlplane/group/endpoint-resource-groups[use the API]
with
link:/api/doc/cloud-controlplane/resource/create-resource[use the API]
(slug:create-resource)Proposed diff:
--- a/modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc +++ b/modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc @@ -142,5 +142,5 @@ -* To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/topic/authentication[Cloud API authentication guide]. You can link:/api/doc/cloud-controlplane/group/endpoint-resource-groups[use the API] to create a new resource group or use an existing one. +* To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/reference/authentication[Cloud API authentication guide]. You can link:/api/doc/cloud-controlplane/resource/create-resource[use the API] to create a new resource group or use an existing one. ====Verify that both
/reference/authenticationand/resource/create-resourcematch your live Control Plane docs.modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc (3)
58-87: LGTM: cluster creation link updated to operation docEndpoint reference and example look consistent with the Control Plane API patterns.
110-126: LGTM: update-cluster reference for enabling PSCThe switch to the operation doc anchor is correct and matches the enablement payload.
144-159: LGTM: disable PSC via update-cluster operationEndpoint and payload are consistent.
modules/networking/pages/gcp-private-service-connect.adoc (5)
58-86: LGTM: network creation now points to operation docsThe example and placeholders align with BYOVPC (env-byoc) and include customer-managed resources, which is appropriate.
105-151: LGTM: cluster creation with PSC enabled and BYOVPC resourcesThe operation link and payload structure match the BYOVPC flow. Including
gcp_private_service_connectandcustomer_managed_resources.gcpis correct.
226-244: LGTM: patch to add PSC NAT subnet for BYOVPCThe update-cluster operation and body to set
psc_nat_subnet_namelook correct. The subsequent guidance about using the fully-qualified subnet name clarifies usage.
251-267: LGTM: patch to enable PSCOperation and payload are consistent, and the wait/monitoring guidance below is useful.
284-299: LGTM: patch to disable PSCEndpoint and payload are correct; matches the enable flow.
| TIP: To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/topic/authentication[authentication guide]. | ||
|
|
There was a problem hiding this comment.
Fix authentication doc link path
Elsewhere (for example, modules/security/pages/cloud-authentication.adoc Lines 701-703) we link to link:/api/doc/cloud-controlplane/authentication[]. Here it points to link:/api/doc/cloud-controlplane/topic/authentication, which is likely incorrect.
-TIP: To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/topic/authentication[authentication guide].
+TIP: To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/authentication[authentication guide].📝 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.
| TIP: To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/topic/authentication[authentication guide]. | |
| TIP: To get the Redpanda authentication credentials, follow the link:/api/doc/cloud-controlplane/authentication[authentication guide]. |
🤖 Prompt for AI Agents
In modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc around
lines 318 to 319, the authentication guide link uses
link:/api/doc/cloud-controlplane/topic/authentication which is inconsistent with
other docs; update the path to match the canonical
link:/api/doc/cloud-controlplane/authentication (remove the extraneous /topic)
so the TIP points to the correct authentication guide.
| The Cloud API is now generally available. It includes endpoints for xref:manage:api/cloud-serverless-controlplane-api.adoc[managing Serverless clusters], configuring RBAC in xref:manage:api/cloud-byoc-controlplane-api.adoc#manage-rbac[BYOC], xref:manage:api/cloud-serverless-controlplane-api.adoc#manage-rbac[Serverless], and xref:manage:api/cloud-dedicated-controlplane-api.adoc#manage-rbac[Dedicated] clusters, and xref:manage:api/cloud-dataplane-api.adoc#use-redpanda-connect[using Redpanda Connect]. | ||
|
|
||
| To get started, try the xref:manage:api/cloud-api-quickstart.adoc[Cloud API Quickstart], or see the full xref:api:ROOT:cloud-controlplane-api.adoc[Control Plane API] and xref:api:ROOT:cloud-dataplane-api.adoc[Data Plane API] reference documentation. | ||
| To get started, see the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview.adoc[Redpanda Cloud API overview] or try the link:/api/doc/cloud-controlplane/topic/topic-quickstart.adoc[Cloud API Quickstart]. For full reference documentation, see link:/api/doc/cloud-controlplane/[Control Plane API] and link:/api/doc/cloud-dataplane/[Data Plane API]. |
There was a problem hiding this comment.
Replace remaining xrefs and fix .adoc extensions in links
This section still uses xref macros and includes “.adoc” in link targets. The PR objective is to use link:/api/doc/... without file extensions.
-The Cloud API is now generally available. It includes endpoints for xref:manage:api/cloud-serverless-controlplane-api.adoc[managing Serverless clusters], configuring RBAC in xref:manage:api/cloud-byoc-controlplane-api.adoc#manage-rbac[BYOC], xref:manage:api/cloud-serverless-controlplane-api.adoc#manage-rbac[Serverless], and xref:manage:api/cloud-dedicated-controlplane-api.adoc#manage-rbac[Dedicated] clusters, and xref:manage:api/cloud-dataplane-api.adoc#use-redpanda-connect[using Redpanda Connect].
-
-To get started, see the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview.adoc[Redpanda Cloud API overview] or try the link:/api/doc/cloud-controlplane/topic/topic-quickstart.adoc[Cloud API Quickstart]. For full reference documentation, see link:/api/doc/cloud-controlplane/[Control Plane API] and link:/api/doc/cloud-dataplane/[Data Plane API].
+The Cloud API is now generally available. It includes endpoints for managing Serverless clusters, configuring RBAC in BYOC, Serverless, and Dedicated clusters, and using Redpanda Connect.
+
+To get started, see the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Redpanda Cloud API overview] or try the link:/api/doc/cloud-controlplane/topic/topic-quickstart[Cloud API Quickstart]. For full reference documentation, see link:/api/doc/cloud-controlplane/[Control Plane API] and link:/api/doc/cloud-dataplane/[Data Plane API].🤖 Prompt for AI Agents
In modules/get-started/pages/whats-new-cloud.adoc around lines 194 to 196,
replace the remaining xref: macros and any link targets that include “.adoc”
with link:/api/doc/... style targets (remove the .adoc extension) and convert
xref fragments (including anchor references like #manage-rbac) to equivalent
link:/api/doc/... URLs so all links use link:/api/doc/... without file
extensions while preserving anchor fragments and link text.
| * Create a cluster by making a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /v1/clusters`] request. Edit `cluster_configuration` in the request body with a key-value pair for `custom_properties`. | ||
| * Update a cluster by making a xref:api:ROOT:cloud-controlplane-api.adoc#patch-/v1/clusters/-cluster.id-[`PATCH /v1/clusters/{cluster.id}`] request, passing the cluster ID as a parameter. Include the properties to update in the request body. | ||
| * Update a cluster by making a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request, passing the cluster ID as a parameter. Include the properties to update in the request body. |
There was a problem hiding this comment.
Escape {} in link text to avoid AsciiDoc attribute substitution
In AsciiDoc, {cluster.id} in link text may be interpreted as an attribute reference and render blank/misleading depending on build settings. Escape the braces.
Apply this diff:
-* Update a cluster by making a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request, passing the cluster ID as a parameter. Include the properties to update in the request body.
+* Update a cluster by making a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/\{cluster.id}`] request, passing the cluster ID as a parameter. Include the properties to update in the request body.🤖 Prompt for AI Agents
In modules/manage/pages/cluster-maintenance/config-cluster.adoc around line 62,
the link text contains `{cluster.id}` which AsciiDoc may treat as an attribute
reference; escape the braces in the link text so they render literally by
replacing `{cluster.id}` with \{cluster.id\} (keep the URL path
/v1/clusters/{cluster.id} unchanged if it appears outside the link text).
| ---- | ||
| 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. 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 /clusters/{cluster.id}`] request returns the ID of a long-running operation. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /operations/\{id}`] endpoint. |
There was a problem hiding this comment.
Fix endpoint labels: add /v1 and escape {} consistently
The displayed endpoint for PATCH is missing /v1, and {cluster.id} should be escaped to prevent attribute substitution. Also add /v1 to the operations GET label for consistency with examples.
Apply this diff:
-The link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /clusters/{cluster.id}`] request returns the ID of a long-running operation. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`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. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`] endpoint.📝 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.
| The link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /clusters/{cluster.id}`] request returns the ID of a long-running operation. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`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. You can check the status of the operation by polling the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`] endpoint. |
🤖 Prompt for AI Agents
In modules/manage/pages/cluster-maintenance/config-cluster.adoc around line 86,
the two API link labels lack the /v1 version and the PATCH label uses unescaped
{cluster.id} which can trigger Asciidoctor attribute substitution; update the
PATCH label to
link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH
/v1/clusters/\{cluster.id\}`] and update the operations GET label to
link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET
/v1/operations/\{id\}`] so both include /v1 and all braces are escaped
consistently.
| Use the Cloud API to get the current configuration property values for a cluster. | ||
| Make a xref:api:ROOT:cloud-controlplane-api.adoc#get-/v1/clusters/-id-[`GET /clusters/{cluster.id}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]: | ||
| Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster[`GET /clusters/{cluster.id}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]: |
There was a problem hiding this comment.
Align GET endpoint label with examples and escape {}
The label should include /v1 (as used in the curl example below), and {cluster.id} should be escaped.
Apply this diff:
-Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster[`GET /clusters/{cluster.id}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]:
+Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster[`GET /v1/clusters/\{cluster.id}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]:📝 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.
| Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster[`GET /clusters/{cluster.id}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]: | |
| Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster[`GET /v1/clusters/\{cluster.id\}`] request, passing the cluster ID as a parameter. The response body contains the current `computed_properties` values. For example, to get the current value of xref:reference:properties/cluster-properties.adoc#audit_enabled[`audit_enabled`]: |
🤖 Prompt for AI Agents
In modules/manage/pages/cluster-maintenance/config-cluster.adoc around line 134,
the inline link label currently reads GET /clusters/{cluster.id} but must match
the example which uses the v1 path and must escape the braces; update the link
label to include /v1 and escape the curly braces (e.g. GET
/v1/clusters/\{cluster.id\}) so it matches the curl example and prevents
AsciiDoc attribute interpolation.
| == Long-running operations | ||
|
|
||
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of xref:api:ROOT:cloud-controlplane-api.adoc#post-/v1/clusters[`POST /clusters`]: | ||
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /clusters`]: |
There was a problem hiding this comment.
Fix missing “/v1” in displayed endpoint path
The operation label shows POST /clusters but should include the version prefix.
Apply this diff to correct the path:
-Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /clusters`]:
+Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /v1/clusters`]:📝 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.
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /clusters`]: | |
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /v1/clusters`]: |
🤖 Prompt for AI Agents
In modules/manage/partials/controlplane-api.adoc around line 40, the example
operation response shows the endpoint as "POST /clusters" but is missing the API
version prefix; update the displayed path to include the /v1 prefix so it reads
"POST /v1/clusters" (apply the provided diff to replace the incorrect path with
the corrected one).
| To delete a cluster, make a request to the link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_getserverlesscluster[`DELETE /v1/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>. | ||
|
|
||
| ```bash | ||
| curl -H "Authorization: Bearer <token>" -X DELETE https://api.redpanda.com/v1/serverless/clusters/<cluster-id> | ||
| ``` |
There was a problem hiding this comment.
Wrong operation doc anchor for Serverless delete
The link target is “getserverlesscluster” while the text/verb is DELETE. Swap to the delete operation anchor.
Apply this diff:
-To delete a cluster, make a request to the link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_getserverlesscluster[`DELETE /v1/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>.
+To delete a cluster, make a request to the link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_deleteserverlesscluster[`DELETE /v1/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>.📝 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.
| To delete a cluster, make a request to the link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_getserverlesscluster[`DELETE /v1/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>. | |
| ```bash | |
| curl -H "Authorization: Bearer <token>" -X DELETE https://api.redpanda.com/v1/serverless/clusters/<cluster-id> | |
| ``` | |
| To delete a cluster, make a request to the link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_deleteserverlesscluster[`DELETE /v1/serverless/clusters/\{id\}`] endpoint, passing the cluster ID as a parameter. This is a <<lro-serverless,long-running operation>>. | |
🤖 Prompt for AI Agents
In modules/manage/partials/controlplane-api.adoc around lines 412 to 416, the
link anchor currently points to
operation/operation-serverlessclusterservice_getserverlesscluster but the text
and example perform a DELETE; update the link target to the corresponding delete
operation anchor
(operation/operation-serverlessclusterservice_deleteserverlesscluster) so the
link matches the DELETE verb, replacing the existing getserverlesscluster anchor
with deleteserverlesscluster in that link.
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_createserverlesscluster[`POST /serverless/clusters`]: | ||
|
|
There was a problem hiding this comment.
Fix missing “/v1” in displayed serverless create path
The displayed endpoint path is missing the version prefix.
Apply:
-Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_createserverlesscluster[`POST /serverless/clusters`]:
+Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_createserverlesscluster[`POST /v1/serverless/clusters`]:📝 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.
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_createserverlesscluster[`POST /serverless/clusters`]: | |
| Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of link:/api/doc/cloud-controlplane/operation/operation-serverlessclusterservice_createserverlesscluster[`POST /v1/serverless/clusters`]: |
🤖 Prompt for AI Agents
In modules/manage/partials/controlplane-api.adoc around lines 423 to 424, the
example response text for the serverless create endpoint is missing the API
version prefix; update the displayed path from "/serverless/clusters" to include
the version prefix (e.g., "/v1/serverless/clusters") wherever it appears in that
example block so the documentation matches the actual API path.
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from Update Cluster call. When the state is `STATE_READY`, proceed to the next step. | ||
|
|
There was a problem hiding this comment.
Operation state should be STATE_COMPLETED, not STATE_READY
Use STATE_COMPLETED to gate post-update steps.
Apply:
-. Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from Update Cluster call. When the state is `STATE_READY`, proceed to the next step.
+. Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from Update Cluster call. When the state is `STATE_COMPLETED`, proceed to the next step.📝 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.
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from Update Cluster call. When the state is `STATE_READY`, proceed to the next step. | |
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from Update Cluster call. When the state is `STATE_COMPLETED`, proceed to the next step. |
🤖 Prompt for AI Agents
In modules/networking/pages/aws-privatelink.adoc around lines 174-175, the gate
condition references STATE_READY but should use STATE_COMPLETED; update the
sentence to check the Update Cluster operation state via GET /v1/operations/{id}
and require the state to be `STATE_COMPLETED` before proceeding, and search the
surrounding paragraph for any other mentions of `STATE_READY` and replace them
with `STATE_COMPLETED` for consistency.
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from the Update Cluster call. When the state is `STATE_READY`, continue to <<configure-azure-private-link-connection-to-redpanda-cloud,configure the Private Link connection to Redpanda>>. | ||
|
|
There was a problem hiding this comment.
Operation state should be STATE_COMPLETED, not STATE_READY
Operations use STATE_IN_PROGRESS/STATE_COMPLETED/STATE_FAILED. STATE_READY is a resource state, not an operation state.
Apply:
-. Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from the Update Cluster call. When the state is `STATE_READY`, continue to <<configure-azure-private-link-connection-to-redpanda-cloud,configure the Private Link connection to Redpanda>>.
+. Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from the Update Cluster call. When the state is `STATE_COMPLETED`, continue to <<configure-azure-private-link-connection-to-redpanda-cloud,configure the Private Link connection to Redpanda>>.📝 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.
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from the Update Cluster call. When the state is `STATE_READY`, continue to <<configure-azure-private-link-connection-to-redpanda-cloud,configure the Private Link connection to Redpanda>>. | |
| . Before proceeding, check the state of the Update Cluster operation by calling link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/\{id}`], and passing the operation ID returned from the Update Cluster call. When the state is `STATE_COMPLETED`, continue to <<configure-azure-private-link-connection-to-redpanda-cloud,configure the Private Link connection to Redpanda>>. |
🤖 Prompt for AI Agents
In modules/networking/pages/azure-private-link.adoc around lines 188 to 189, the
guidance incorrectly references the operation state STATE_READY; update the text
to check for the operation state STATE_COMPLETED instead (operations use
STATE_IN_PROGRESS/STATE_COMPLETED/STATE_FAILED), so replace `STATE_READY` with
`STATE_COMPLETED` in the sentence and ensure surrounding wording remains
consistent with operation-state terminology.
Description
This pull request updates documentation to replace legacy AsciiDoc
xref:references to Cloud API and Data Plane API docs with new directlink:URLs pointing to the latest API documentation site. This affects navigation menus and in-page references throughout the docs, ensuring users are directed to the most current and authoritative API documentation. The changes also update example commands and tips to use the new links.The most important changes are:
Navigation and Reference Updates:
modules/ROOT/nav.adocto replace allxref:API references withlink:URLs to the new API documentation site for Cloud Control Plane, Data Plane, HTTP Proxy, and Schema Registry APIs. [1] [2]In-Page API Reference Updates:
link:URLs to the new API docs, including for authentication, cluster operations, error codes, and deprecation policy. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20]Consistency and Clarity Improvements:
These updates help ensure the documentation is accurate, up-to-date, and easier for users to navigate when working with the Redpanda Cloud APIs.
Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline:
Page previews
Checks