Cloud API supplemental/how-to docs (control and data plane, overview) #411

kbatuigas · 2024-04-10T03:52:08Z

Add new Cloud API docs to the RP Cloud docs: https://docs.redpanda.com/current/deploy/deployment-option/cloud/. These are "supplemental" docs to the API reference (PR here) and aim to provide more detailed steps and explanations on using the Cloud API.

Review deadline: 16 May 2024

NOTE: Adding the cloud API reference (i.e. the specs) is done in #283 since that has to be merged in the api branch where our API reference pages live. This PR is against the main branch, where our regular docs live and where we add non-reference (e.g. conceptual topics, or task-oriented docs) content.

Cloud API subsection under Deploy > Cloud: index page
Cloud API overview
Cloud API Authentication
Control Plane API
Data Plane APIs

netlify · 2024-04-10T03:52:25Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`b196634`
🔍 Latest deploy log	https://app.netlify.com/sites/redpanda-docs-preview/deploys/6647dacfb5d8bd00085c9213
😎 Deploy Preview	https://deploy-preview-411--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

modules/ROOT/nav.adoc

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

towfiqa · 2024-05-03T01:50:54Z

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

+
+The Redpanda Admin API is a REST API to manage aspects of a Redpanda cluster. You can use the Admin API to perform operations that are specific to the Redpanda platform and cannot be done using the standard Kafka API.
+
+Redpanda Cloud uses a control plane and data plane architecture. The *control plane* is where most cluster management, operations, and maintenance takes place. The control plane enforces rules in the data plane. The *data plane* is where your cloud cluster lives. The term _data plane_ is used interchangeably with _cluster_. 


I would remove the section header and start the paragraph here. And everything above should be in the "Please Note:" block

@towfiqa want to add a note here to say we could do this, but also wanted to show another option. I'll push up some commits shortly so that we get an updated preview and then you can let us know which one you prefer!

@towfiqa I changed the section header to "Cloud API architecture", removed the info about the other APIs and moved them over to the API and SDK reference index page. What do you think of this flow? Anything you prefer to see?

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

kbatuigas · 2024-05-03T21:03:50Z

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

@towfiqa Right now, the reference overview (preview) is sharing the same content as on this page.

I have a more condensed overview that I drafted here, plus instructions on making requests from the reference page here, and a tiny quickstart here. Do you prefer these to be displayed on the reference page, instead of the content we have in the cloud-api-overview.adoc and cloud-api-authentication.adoc files?

@towfiqa I actually went ahead and replaced it with the "condensed" content. Let me know what you think.

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

kbatuigas · 2024-05-08T03:46:10Z

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc

@@ -0,0 +1,138 @@
+= Manage Cluster Resources Using the Cloud API


Also need confirmation on whether this page title is okay, or if it should be reworded (is "cluster resources" accurate?)

birdayz · 2024-05-14T20:33:53Z

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

+To be able to use the Cloud API:
+
+* You must be a customer with an existing organization in Redpanda Cloud.
+* You can only use one organization for authentication. See xref:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Cloud API Authentication] for steps to authenticate API requests.


Maybe rephrase this a bit, e.g. to explain that a token is always for a specific organization. if they want to switch to a different organization, they must acquire a new token (with a service account from the other org)

@birdayz Added in this commit; please let me know if the change doesn't address this!

micheleRP · 2024-05-17T20:30:50Z

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

+}' -X POST https://api.redpanda.com/v1beta2/clusters
+----
+
+The Create Cluster endpoint returns a <<long_running_operations,long-running operation>>. When the operation is completed, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`], passing the cluster ID as a parameter.


In our regular docs, we use property instead of parameter.

@micheleRP Ah, I think both property and parameter can be used in the API context, but parameter is the more common term for the "specific value you use in the API URL path" https://swagger.io/resources/articles/best-practices-in-api-design/

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

micheleRP · 2024-05-17T20:35:57Z

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

+
+Create a network by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`].
+
+Choose a CIDR range that does not overlap with your existing VPCs or your Redpanda network.


You could consider adding a link for more info: https://deploy-preview-411--redpanda-docs-preview.netlify.app/current/deploy/deployment-option/cloud/cidr-ranges/

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

micheleRP · 2024-05-17T20:45:43Z

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc

@@ -0,0 +1,139 @@
+= Manage Cluster Resources Using the Cloud API


Suggested change

= Manage Cluster Resources Using the Cloud API

= Use the Data Plane APIs

micheleRP · 2024-05-17T20:48:53Z

@kbatuigas I have doubts about the page titles and descriptions:
Manage Clusters using the Cloud API
Use the Control Plane API to manage your clusters and organization-level resources in Redpanda Cloud.

Manage Cluster Resources Using the Cloud API
Use the Data Plane APIs to manage resources within your Redpanda Cloud clusters.

Suggest the following titles and descriptions instead:
= Use the Control Plane API
:description: Use the Control Plane API to manage resources in your Redpanda Cloud organization.
= Use the Data Plane APIs
:description: Use the Data Plane APIs to manage your Redpanda Cloud clusters.

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc

Co-authored-by: Michele Cyran <michele@redpanda.com>

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc

modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc

micheleRP · 2024-05-17T22:08:40Z

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

+- xref:deploy:deployment-option/cloud/dedicated/dedicated-tiers.adoc[Dedicated tiers and regions]
+- xref:deploy:deployment-option/cloud/byoc-tiers.adoc[BYOC tiers and regions]


should these now link to your tiers table in the API docs instead?

@micheleRP good call, I'll make that change. Currently I am only able to link to an "api-description" anchor in the API reference (and we have kept it to the original GCP vs AWS tables), maybe that can be tweaked later.

…oud-api-docs-combined

micheleRP · 2024-05-17T22:10:22Z

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc

+
+Create a network by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`].
+
+Choose a xref:deploy/deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.


Suggested change

Choose a xref:deploy/deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.

Choose a xref:deploy:deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.

micheleRP

pls fix the cidr link and review my other suggestions, then lgtm!

Co-authored-by: Michele Cyran <michele@redpanda.com>

…#411) Co-authored-by: JakeSCahill <jake@redpanda.com> Co-authored-by: Michele Cyran <michele@redpanda.com>

This was referenced Apr 17, 2024

[do not review] preview API doc (how-to/task doc) #307

Closed

[do not review] preview API doc (how-to for Phase 3) #354

Closed

kbatuigas changed the title ~~[DRAFT] cloud API how-to docs (control and data plane, overview)~~ [DRAFT] cloud API supplemental docs (control and data plane, overview) Apr 23, 2024

kbatuigas force-pushed the cloud-api-docs-combined branch from 3bf0b50 to 4ba2f7e Compare May 1, 2024 05:12

micheleRP reviewed May 1, 2024

View reviewed changes

modules/ROOT/nav.adoc Outdated Show resolved Hide resolved

towfiqa self-requested a review May 1, 2024 18:58

towfiqa reviewed May 3, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

towfiqa reviewed May 3, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

towfiqa reviewed May 3, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

towfiqa reviewed May 3, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

JakeSCahill reviewed May 3, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

kbatuigas commented May 3, 2024

View reviewed changes

kbatuigas marked this pull request as ready for review May 4, 2024 01:01

kbatuigas requested a review from a team as a code owner May 4, 2024 01:01

kbatuigas mentioned this pull request May 7, 2024

Add cloud API specs #283

Merged

2 tasks

kbatuigas changed the title ~~[DRAFT] cloud API supplemental docs (control and data plane, overview)~~ Cloud API supplemental docs (control and data plane, overview) May 7, 2024

kbatuigas requested review from sago2k8, birdayz, weeco and yougotashovel May 7, 2024 04:04

towfiqa reviewed May 7, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Show resolved Hide resolved

towfiqa reviewed May 7, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc Outdated Show resolved Hide resolved

towfiqa reviewed May 7, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc Show resolved Hide resolved

kbatuigas commented May 8, 2024

View reviewed changes

kbatuigas requested a review from bojand May 8, 2024 14:49

kbatuigas force-pushed the cloud-api-docs-combined branch from e826e35 to b9c2e8b Compare May 8, 2024 16:52

bojand approved these changes May 8, 2024

View reviewed changes

birdayz reviewed May 14, 2024

View reviewed changes

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-controlplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc Outdated Show resolved Hide resolved

kbatuigas and others added 3 commits May 17, 2024 17:40

Implement suggestions from feedback

8d66d8c

Streamline requirement for auth

808db36

Apply suggestions from code review

a5dadf6

Co-authored-by: Michele Cyran <michele@redpanda.com>

kbatuigas requested a review from micheleRP May 17, 2024 21:51

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-overview.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc Outdated Show resolved Hide resolved

micheleRP reviewed May 17, 2024

View reviewed changes

kbatuigas added 2 commits May 17, 2024 18:09

Fix xref

0a38a6b

Merge remote-tracking branch 'origin/cloud-api-docs-combined' into cl…

1002351

…oud-api-docs-combined

micheleRP reviewed May 17, 2024

View reviewed changes

micheleRP approved these changes May 17, 2024

View reviewed changes

kbatuigas and others added 3 commits May 17, 2024 18:20

Link out to tiers section in reference

8d5be27

Apply suggestions from code review

d1c7763

Co-authored-by: Michele Cyran <michele@redpanda.com>

Change content source back to api branch

b196634

kbatuigas merged commit 51370a8 into main May 17, 2024
5 checks passed

Deflaimun pushed a commit that referenced this pull request Jun 5, 2024

Cloud API supplemental/how-to docs (control and data plane, overview) (…

e79ef19

…#411) Co-authored-by: JakeSCahill <jake@redpanda.com> Co-authored-by: Michele Cyran <michele@redpanda.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cloud API supplemental/how-to docs (control and data plane, overview) #411

Cloud API supplemental/how-to docs (control and data plane, overview) #411

kbatuigas commented Apr 10, 2024 •

edited

netlify bot commented Apr 10, 2024 •

edited

towfiqa May 3, 2024

kbatuigas May 3, 2024

kbatuigas May 3, 2024

kbatuigas May 3, 2024 •

edited

kbatuigas May 4, 2024

kbatuigas May 8, 2024

birdayz May 14, 2024

kbatuigas May 15, 2024

micheleRP May 17, 2024

kbatuigas May 17, 2024

micheleRP May 17, 2024

micheleRP May 17, 2024

micheleRP commented May 17, 2024

micheleRP May 17, 2024

kbatuigas May 17, 2024

micheleRP May 17, 2024

micheleRP left a comment •

edited


		The Redpanda Admin API is a REST API to manage aspects of a Redpanda cluster. You can use the Admin API to perform operations that are specific to the Redpanda platform and cannot be done using the standard Kafka API.

		Redpanda Cloud uses a control plane and data plane architecture. The control plane is where most cluster management, operations, and maintenance takes place. The control plane enforces rules in the data plane. The data plane is where your cloud cluster lives. The term _data plane_ is used interchangeably with _cluster_.

		@@ -0,0 +1,138 @@
		= Manage Cluster Resources Using the Cloud API


		Create a network by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`].

		Choose a CIDR range that does not overlap with your existing VPCs or your Redpanda network.

		@@ -0,0 +1,139 @@
		= Manage Cluster Resources Using the Cloud API

	= Manage Cluster Resources Using the Cloud API
	= Use the Data Plane APIs

		- xref:deploy:deployment-option/cloud/dedicated/dedicated-tiers.adoc[Dedicated tiers and regions]
		- xref:deploy:deployment-option/cloud/byoc-tiers.adoc[BYOC tiers and regions]


		Create a network by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`].

		Choose a xref:deploy/deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.

	Choose a xref:deploy/deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.
	Choose a xref:deploy:deployment-option/cloud/cidr-ranges.adoc[CIDR range] that does not overlap with your existing VPCs or your Redpanda network.

Cloud API supplemental/how-to docs (control and data plane, overview) #411

Cloud API supplemental/how-to docs (control and data plane, overview) #411

Conversation

kbatuigas commented Apr 10, 2024 • edited

netlify bot commented Apr 10, 2024 • edited

✅ Deploy Preview for redpanda-docs-preview ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbatuigas May 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

micheleRP commented May 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

micheleRP left a comment • edited

Choose a reason for hiding this comment

kbatuigas commented Apr 10, 2024 •

edited

netlify bot commented Apr 10, 2024 •

edited

kbatuigas May 3, 2024 •

edited

micheleRP left a comment •

edited