Apply suggestions from SKO session #21
Conversation
|
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 📝 WalkthroughWalkthroughThe PR updates two quickstart docs. In cloud-controlplane/x-topics/quickstart.md, it restructures the resource creation flows (BYOC, Dedicated, Serverless), updates terminology, adds explicit API Explorer links, introduces JSON payload/response examples, clarifies authentication text, and adds BYOC apply commands per provider. It also standardizes instructions (e.g., “Add” vs “+ Add”) and links directly to Get operation docs. In cloud-dataplane/x-topics/quickstart.md, it converts two steps into explicit hyperlinks to the API Explorer and specific Control Plane operations for obtaining the data plane URL. No API or code signatures are changed. Sequence Diagram(s)sequenceDiagram
autonumber
participant User
participant API_Explorer as API Explorer (Docs UI)
participant CP_API as Control Plane API
note over User,API_Explorer: Control Plane quickstart (Resource Group → Network → Cluster)
rect rgb(240,248,255)
User->>API_Explorer: Authenticate and open CP Explorer
User->>CP_API: Create Resource Group (POST)
CP_API-->>User: resource_group { id, name, timestamps }
note right of User: Copy resource_group.id
end
rect rgb(245,255,250)
User->>CP_API: Create Network (POST, resource_group_id)
CP_API-->>User: operation { id, state, metadata{network_id} }
User->>CP_API: Get Operation (GET) until STATE_COMPLETED
end
rect rgb(255,250,240)
User->>CP_API: Create Cluster (POST, network/resource_group)
CP_API-->>User: operation { id, state, metadata{cluster_id} }
User->>CP_API: Get Operation (GET) until STATE_COMPLETED
end
note over User: For BYOC, run rpk cloud byoc apply (AWS/Azure/GCP) with redpanda_id
sequenceDiagram
autonumber
participant User
participant API_Explorer_CP as CP API Explorer
participant CP_API as Control Plane API
participant API_Explorer_DP as DP API Explorer
participant DP_API as Data Plane API
note over User,API_Explorer_CP: Data Plane quickstart (Create Topic)
User->>API_Explorer_CP: Open CP Explorer link
User->>CP_API: Get Cluster (BYOC/Dedicated) or Get Serverless Cluster
CP_API-->>User: ... dataplane_api.url (includes subdomain)
User->>API_Explorer_DP: Open DP Explorer link using data plane URL
rect rgb(250,250,210)
User->>DP_API: Create Topic (POST)
DP_API-->>User: topic creation response
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Comment |
![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
🧹 Nitpick comments (8)
cloud-dataplane/x-topics/quickstart.md (1)
1-1: Link to Data Plane reference, not “Cloud API Overview.”This paragraph is about the Data Plane; the “Cloud API Overview” is Control Plane–focused. Point to the DP reference instead.
-The following steps describe how to authenticate with the Data Plane APIs and create a new topic. For more information on the Data Plane APIs, see the [Cloud API Overview](#topic-cloud-api-overview). +The following steps describe how to authenticate with the Data Plane APIs and create a new topic. For more information on the Data Plane APIs, see the [Data Plane API Reference](/api/doc/cloud-dataplane).cloud-controlplane/x-topics/quickstart.md (7)
1-5: Replace invalid anchor with explicit CP “Cloud API Overview” link.
(#topic-cloud-api-overview)appears to trigger MD051. Use an explicit path.-To view the available endpoints for managing resources within your clusters, such as topics, users, access control lists (ACLs), and connectors, see the [Data Plane API Reference](/api/doc/cloud-dataplane). For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview). +To view the available endpoints for managing resources within your clusters, such as topics, users, access control lists (ACLs), and connectors, see the [Data Plane API Reference](/api/doc/cloud-dataplane). For more information on the Control Plane API, see the [Cloud API Overview](/api/doc/cloud-controlplane/topic/topic-cloud-api-overview).
13-13: Clarify BYOC command: include the apply subcommand.Matches the commands shown later and the issue objective.
-**BYOC only**: BYOC clusters require running the `rpk cloud byoc` command to install and start the Redpanda Cloud agent service. See [Install or Update `rpk`](https://docs.redpanda.com/redpanda-cloud/manage/rpk/rpk-install). +**BYOC only**: BYOC clusters require running the `rpk cloud byoc <provider> apply` command to install and start the Redpanda Cloud agent service. See [Install or Update `rpk`](https://docs.redpanda.com/redpanda-cloud/manage/rpk/rpk-install).
37-49: Use jsonc or plain text for elided JSON.
...is invalid in JSON blocks; switch fence tojsoncand use comments, or totext.-```json +```jsonc { "resource_group": { "id": "d61b4c7f-95da-4d62-a237-9fd9f20a0c19", "name": "test-resource-group", - ... + // ... } }--- `51-51`: **Consistent phrasing: “Choose an operation” vs “operation dropdown.”** Align with earlier wording. ```diff -1. In the operation dropdown, select **Create network**. +1. In the **Choose an operation** dropdown, select **Create network**.
100-112: Same JSON elision nit.-```json +```jsonc // ... -``` +```
116-120: Add link to “Get serverless regions” and verify default region.Include a link to the regions endpoint and keep
us-east-1only as an example.-1. In the request body, use the resource group ID. You can use `us-east-1` for the Serverless region if you don't require a specific region for your cluster. +1. In the request body, use the resource group ID. Choose a Serverless region (for example, `us-east-1`). To list available regions, see the **Get serverless regions** endpoint in the API Explorer.Can you confirm the exact API Explorer path for “Get serverless regions” so I can wire the link to the correct operation?
125-125: Fix backticks around https://.Mismatched backticks break rendering.
-1. From the value of `dataplane_api.url` in the response body, save the subdomain (the part between ``https://` and `.cloud.redpanda.com`). +1. From the value of `dataplane_api.url` in the response body, save the subdomain (the part between `https://` and `.cloud.redpanda.com`).
📜 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 selected for processing (2)
cloud-controlplane/x-topics/quickstart.md(3 hunks)cloud-dataplane/x-topics/quickstart.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
cloud-controlplane/x-topics/quickstart.md
4-4: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (7)
cloud-dataplane/x-topics/quickstart.md (2)
25-25: LGTM: clearer entry to API Explorer.
19-20: Confirm cross‑API token reuse claim or remove.The note says the same token works for both CP and DP. This was questioned in DOC-1661.
Would you like me to remove this sentence until verified, or update it with the current, confirmed behavior?
cloud-controlplane/x-topics/quickstart.md (5)
29-29: LGTM: direct link to CP API Explorer.
57-71: LGTM: long‑running operation guidance and example are clear.
73-73: LGTM: clear handoff to Create cluster with ID reuse.
75-88: Verify provider flags and pre‑reqs for BYOC apply.Confirm the exact flag names and any prerequisite IAM/permissions or agent version constraints that must be called out here.
I can add a short prereqs bullet list if you share the current requirements per provider.
114-114: LGTM: direct link to Create Serverless cluster reduces misclicks.
paulohtb6
left a comment
paulohtb6
left a comment
There was a problem hiding this comment.
approved but probably best to check with others as I wasn't on SKO
kbatuigas
force-pushed
the
DOC-1661-cloud-api-quickstart-fixes
branch
from
1a77e67 to
fbdd1dc
Compare
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
This pull request updates the quickstart guides for both the Control Plane and Data Plane APIs, focusing on improving clarity, accuracy, and usability for users setting up and managing Redpanda Cloud clusters. The changes streamline instructions, add direct links to API Explorer operations, clarify required parameters and steps, and provide example responses for better guidance.
Closes https://redpandadata.atlassian.net/browse/DOC-1661
Control Plane API quickstart improvements:
rpk cloud byoc <cloud-provider> applyand clarified usage of response IDs and flags for different cloud providers.Data Plane API quickstart improvements: