From ea5a4ee617cf562663b159563ad9859382eba1a1 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:43:56 -0400 Subject: [PATCH 1/7] Edits per PM input --- .../cloud/api/cloud-api-authentication.adoc | 1 + .../cloud/api/cloud-api-quickstart.adoc | 29 +++++++- .../cloud/api/cloud-dataplane-api.adoc | 13 ++++ .../partials/cloud/controlplane-api.adoc | 68 +++++++++++++++---- 4 files changed, 97 insertions(+), 14 deletions(-) diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc index 0d6442ec86..d0a3105106 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc @@ -14,6 +14,7 @@ You only need to authenticate once to the Cloud API. That is, after you obtain a == Request an access token Users with administrative privileges in a Redpanda Cloud organization can create a service account. + NOTE: Service accounts have administrative privileges by default. Cloud user roles are not applied for the API. // UI change not applied diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc index 68c6060fe6..4cf5657cf8 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc @@ -13,7 +13,7 @@ The following steps describe how to authenticate with the Cloud API and create a BYOC or Dedicated:: + -- -. xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Authenticate to the API]. +. In the Redpanda Cloud UI, create a https://cloud.redpanda.com/clients[service account (client)] and use the client ID and secret to request an API token. Use the token to xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[authenticate to the API]. . Create a resource group by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/resource-groups[`POST /v1beta2/resource-groups`] request. . Create a network by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/networks[`POST /v1beta2/networks`] request. Note that this operation may be long-running. . Create a cluster by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/clusters[`POST /v1beta2/clusters`] request. @@ -35,8 +35,33 @@ rpk cloud byoc aws apply --redpanda-id= Serverless:: + -- -. xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Authenticate to the API]. +. In the Redpanda Cloud UI, create a https://cloud.redpanda.com/clients[service account (client)] and use the client ID and secret to request an API token. Use the token to xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[authenticate to the API]. +. Make a `GET /v1beta2/resource-groups` request to retrieve the default resource group ID. ++ +[bash] +---- +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups +---- +. Make a `GET /v1beta2/serverless/regions` request to see available regions. ++ +[bash] +---- +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS +---- . Create a cluster by making a `POST /v1beta2/serverless/clusters` request. ++ +[bash] +---- +curl -H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-d '{ + "serverless_cluster": { + "name": , + "resource_group_id": , + "serverless_region": "pro-us-east-1" + } +}' -X POST https://api.redpanda.com/v1beta2/serverless/clusters +---- -- ====== diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc index 5e70254342..2a91c644af 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc @@ -11,7 +11,20 @@ The xref:deploy:deployment-option/cloud/api/cloud-api-overview.adoc#cloud-api-ar == Get Data Plane API URL +[tabs] +====== +BYOC or Dedicated:: ++ +-- To retrieve the Data Plane API URL of a cluster, make a request to xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`]. +-- + +Serverless:: ++ +-- +To retrieve the Data Plane API URL of a cluster, make a request to `GET /v1beta2/serverless/clusters/\{id}`. +-- +====== The response includes a `dataplane_api.url` value: diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index db452a3a71..4965a0ed5e 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -29,7 +29,9 @@ ifdef::env-serverless[] // * pass:a,m[xref:{tag-serverless-regions}[ServerlessRegionService\]] endif::[] - +// For serverless, show this section at the end of the doc +ifndef::env-serverless[] +[[lro]] == 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-api.adoc#post-/v1beta2/clusters[Create Cluster] (`POST /clusters`): @@ -63,8 +65,6 @@ curl https://api.redpanda.com/v1beta2/operations/ The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. -ifndef::env-serverless[] - == Cluster tiers When you create a BYOC or Dedicated cluster, you select a usage tier. Each tier provides tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region and the cluster type. See the full list of regions, zones, and tiers available with each provider in the xref:api:ROOT:cloud-api.adoc#api-description[API reference]. @@ -110,7 +110,7 @@ curl -d \ }' -X POST https://api.redpanda.com/v1beta2/networks ---- -This endpoint returns a <>. +This endpoint returns a <>. === Create a new cluster @@ -136,7 +136,7 @@ curl -d \ }' -X POST https://api.redpanda.com/v1beta2/clusters ---- -The Create Cluster endpoint returns a <>. 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. +The Create Cluster endpoint returns a <>. 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. ifdef::env-byoc[] ==== Additional steps to create a BYOC cluster @@ -169,7 +169,15 @@ To create a new serverless cluster, you can use the default resource group, or c === Create a resource group -NOTE: This step is optional. Serverless includes a default resource group. Skip this step to use the default. +[NOTE] +==== +This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the `/v1beta2/resource-groups` endpoint: + +```bash +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups +``` + +==== Create a resource group by making a POST request to the xref:api:ROOT:cloud-api.adoc#post-/v1beta2/resource-groups[`/v1beta2/resource-groups`] endpoint. Pass a name for your resource group in the request body. @@ -191,7 +199,7 @@ To see the available regions for Redpanda Serverless, make a GET request to the [,bash] ---- -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions/ +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS ---- [,json,role=no-copy] @@ -205,7 +213,8 @@ curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverl "id": "Europe/Berlin", "version": "" }, - "cloud_provider": "CLOUD_PROVIDER_AWS" + "cloud_provider": "CLOUD_PROVIDER_AWS", + "available": true }, { "name": "pro-us-east-1", @@ -214,7 +223,8 @@ curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverl "id": "America/New_York", "version": "" }, - "cloud_provider": "CLOUD_PROVIDER_AWS" + "cloud_provider": "CLOUD_PROVIDER_AWS", + "available": true } ], "next_page_token": "" @@ -240,7 +250,7 @@ curl -H 'Content-Type: application/json' \ }' -X POST https://api.redpanda.com/v1beta2/serverless/clusters ---- -The Create Serverless Cluster endpoint returns a <>. When the operation is completed, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, passing the cluster ID as a parameter. +The Create Serverless Cluster endpoint returns a <>. When the operation is completed, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, passing the cluster ID as a parameter. endif::[] @@ -248,7 +258,7 @@ endif::[] ifndef::env-serverless[] -To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. +To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. ```bash curl -X DELETE https://api.redpanda.com/v1beta2/clusters/ @@ -287,7 +297,7 @@ endif::[] ifdef::env-serverless[] // TODO: Update xref when prod spec contains serverless endpoints -To delete a cluster, make a request to the `DELETE /v1beta2/serverless/clusters/\{id}` endpoint, passing the cluster ID as a parameter. This is a <>. +To delete a cluster, make a request to the `DELETE /v1beta2/serverless/clusters/\{id}` endpoint, passing the cluster ID as a parameter. This is a <>. ```bash curl -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ @@ -295,6 +305,40 @@ curl -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ Optional: When the cluster is deleted, the delete operation’s state changes to `STATE_COMPLETED`. At this point, you may make a DELETE request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/resource-groups/-id-[`/v1beta2/resource-groups/\{id}`] endpoint to delete the resource group. +[[lro-serverless]] +== Long-running operations + +Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of Create Serverless Cluster (`POST /serverless/clusters`): + +[,bash,role=no-copy] +---- +{ + "operation": { + "id": "cqaramrndjr40k3qei50", + "metadata": null, + "state": "STATE_IN_PROGRESS", + "started_at": { + "seconds": "1721087323", + "nanos": 888601218 + }, + "finished_at": null, + "type": "TYPE_CREATE_SERVERLESS_CLUSTER" + } +} +---- + +The response object represents the long-running operation of creating a cluster. Cluster creation is an example of an operation that can take a longer period of time to complete. + +=== Check operation state + +To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter: + +```bash +curl https://api.redpanda.com/v1beta2/operations/ +``` + +The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. + endif::[] == Next steps From 96db235fc7eba519002bd1e0a49fe2a85abc4919 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Wed, 31 Jul 2024 13:47:36 -0400 Subject: [PATCH 2/7] Add auth header to curl commands --- .../cloud/api/cloud-api-quickstart.adoc | 6 +++--- modules/deploy/partials/cloud/controlplane-api.adoc | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc index 4cf5657cf8..c318b6da29 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc @@ -38,19 +38,19 @@ Serverless:: . In the Redpanda Cloud UI, create a https://cloud.redpanda.com/clients[service account (client)] and use the client ID and secret to request an API token. Use the token to xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[authenticate to the API]. . Make a `GET /v1beta2/resource-groups` request to retrieve the default resource group ID. + -[bash] +[,bash] ---- curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups ---- . Make a `GET /v1beta2/serverless/regions` request to see available regions. + -[bash] +[,bash] ---- curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS ---- . Create a cluster by making a `POST /v1beta2/serverless/clusters` request. + -[bash] +[,bash] ---- curl -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index 4965a0ed5e..aca58d4886 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -60,7 +60,7 @@ The response object represents the long-running operation of creating a cluster. To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter: ```bash -curl https://api.redpanda.com/v1beta2/operations/ +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/operations/ ``` The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. @@ -107,7 +107,7 @@ curl -d \ "name": "", "resource_group_id": "", "region": "us-west1" -}' -X POST https://api.redpanda.com/v1beta2/networks +}' -H 'Authorization: Bearer ' -X POST https://api.redpanda.com/v1beta2/networks ---- This endpoint returns a <>. @@ -133,7 +133,7 @@ curl -d \ "us-west1-b", "us-west1-c" ] - }' -X POST https://api.redpanda.com/v1beta2/clusters + }' -H 'Authorization: Bearer ' -X POST https://api.redpanda.com/v1beta2/clusters ---- The Create Cluster endpoint returns a <>. 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. @@ -261,7 +261,7 @@ ifndef::env-serverless[] To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. ```bash -curl -X DELETE https://api.redpanda.com/v1beta2/clusters/ +curl -H 'Authorization: Bearer ' -X DELETE https://api.redpanda.com/v1beta2/clusters/ ``` ifdef::env-byoc[] @@ -300,7 +300,7 @@ ifdef::env-serverless[] To delete a cluster, make a request to the `DELETE /v1beta2/serverless/clusters/\{id}` endpoint, passing the cluster ID as a parameter. This is a <>. ```bash -curl -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ +curl -H 'Authorization: Bearer ' -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ ``` Optional: When the cluster is deleted, the delete operation’s state changes to `STATE_COMPLETED`. At this point, you may make a DELETE request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/resource-groups/-id-[`/v1beta2/resource-groups/\{id}`] endpoint to delete the resource group. @@ -334,7 +334,7 @@ The response object represents the long-running operation of creating a cluster. To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter: ```bash -curl https://api.redpanda.com/v1beta2/operations/ +curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/operations/ ``` The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. From 3c866bfa803a4fc0657906310f0d56c3d9e506e0 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Wed, 31 Jul 2024 21:18:52 -0400 Subject: [PATCH 3/7] API reference links are live --- .../cloud/api/cloud-api-quickstart.adoc | 10 ++++----- .../partials/cloud/controlplane-api.adoc | 22 +++++++------------ 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc index c318b6da29..c5356da2f5 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc @@ -36,19 +36,19 @@ Serverless:: + -- . In the Redpanda Cloud UI, create a https://cloud.redpanda.com/clients[service account (client)] and use the client ID and secret to request an API token. Use the token to xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[authenticate to the API]. -. Make a `GET /v1beta2/resource-groups` request to retrieve the default resource group ID. +. Make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/resource-groups[`GET /v1beta2/resource-groups`] request to retrieve the default resource group ID. + [,bash] ---- curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups ---- -. Make a `GET /v1beta2/serverless/regions` request to see available regions. +. Make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/regions[`GET /v1beta2/serverless/regions`] request to see available regions. + [,bash] ---- -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS +curl -H 'Authorization: Bearer ' 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' ---- -. Create a cluster by making a `POST /v1beta2/serverless/clusters` request. +. Create a cluster by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[`POST /v1beta2/serverless/clusters`] request. + [,bash] ---- @@ -90,7 +90,7 @@ For requests to the Control Plane API endpoints: For requests to the Data Plane API endpoints: -. Make a Get Cluster request for your target cluster. +. Make a Get Cluster (BYOC, Dedicated) or Get Serverless Cluster (Serverless) request for your target cluster. . The Get Cluster response contains the Data Plane API URL. Copy the value of `dataplane_api.url` from the response body. . Click *API Servers* in the sidebar and select “\{dataplane_api_url} - Data Plane API”. . Paste the URL into the `dataplane_api_url` input field. diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index aca58d4886..5d83cd063c 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -22,11 +22,8 @@ endif::[] * pass:a,m[xref:{tag-operations}[OperationService\]] * pass:a,m[xref:{tag-resource-groups}[ResourceGroupService\]] ifdef::env-serverless[] -* ServerlessClusterService -* ServerlessRegionService -// TODO: Update xref when prod spec contains serverless endpoints -// * pass:a,m[xref:{tag-serverless-clusters}[ServerlessClusterService\]] -// * pass:a,m[xref:{tag-serverless-regions}[ServerlessRegionService\]] +* pass:a,m[xref:{tag-serverless-clusters}[ServerlessClusterService\]] +* pass:a,m[xref:{tag-serverless-regions}[ServerlessRegionService\]] endif::[] // For serverless, show this section at the end of the doc @@ -171,7 +168,7 @@ To create a new serverless cluster, you can use the default resource group, or c [NOTE] ==== -This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the `/v1beta2/resource-groups` endpoint: +This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/resource-groups[`/v1beta2/resource-groups`] endpoint: ```bash curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups @@ -194,12 +191,11 @@ A resource group ID is returned. Pass this ID later when you call the Create Ser === Choose a region -// TODO: Update xref when prod spec contains serverless endpoints -To see the available regions for Redpanda Serverless, make a GET request to the `/v1beta2/serverless/regions` endpoint. You can specify a cloud provider in your request. Serverless currently only supports AWS. +To see the available regions for Redpanda Serverless, make a GET request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/regions[`/v1beta2/serverless/regions`] endpoint. You can specify a cloud provider in your request. Serverless currently only supports AWS. [,bash] ---- -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS +curl -H 'Authorization: Bearer ' 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' ---- [,json,role=no-copy] @@ -234,8 +230,7 @@ curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/serverl === Create a new serverless cluster -// TODO: Update xref when prod spec contains serverless endpoints -Create a Serverless cluster by making a request to `POST /v1beta2/serverless/clusters` with the resource group ID and serverless region name in the request body. +Create a Serverless cluster by making a request to xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[`POST /v1beta2/serverless/clusters`] with the resource group ID and serverless region name in the request body. [,bash] ---- @@ -296,8 +291,7 @@ endif::[] ifdef::env-serverless[] -// TODO: Update xref when prod spec contains serverless endpoints -To delete a cluster, make a request to the `DELETE /v1beta2/serverless/clusters/\{id}` endpoint, passing the cluster ID as a parameter. This is a <>. +To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/serverless/clusters/-id-[`DELETE /v1beta2/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. ```bash curl -H 'Authorization: Bearer ' -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ @@ -308,7 +302,7 @@ Optional: When the cluster is deleted, the delete operation’s state changes to [[lro-serverless]] == Long-running operations -Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of Create Serverless Cluster (`POST /serverless/clusters`): +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-api.adoc#post-/v1beta2/serverless/clusters[Create Serverless Cluster] (`POST /serverless/clusters`): [,bash,role=no-copy] ---- From 0592fccaa69d159ba92d0a301bc4c4d61861ba18 Mon Sep 17 00:00:00 2001 From: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> Date: Wed, 31 Jul 2024 22:05:55 -0400 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- modules/deploy/partials/cloud/controlplane-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index 5d83cd063c..fb3e74677e 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -133,7 +133,7 @@ curl -d \ }' -H 'Authorization: Bearer ' -X POST https://api.redpanda.com/v1beta2/clusters ---- -The Create Cluster endpoint returns a <>. 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. +The Create Cluster endpoint returns a <>. When the operation completes, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/clusters/-id-[`GET /v1beta2/clusters/\{id}`], and passing the cluster ID as a parameter. ifdef::env-byoc[] ==== Additional steps to create a BYOC cluster @@ -245,7 +245,7 @@ curl -H 'Content-Type: application/json' \ }' -X POST https://api.redpanda.com/v1beta2/serverless/clusters ---- -The Create Serverless Cluster endpoint returns a <>. When the operation is completed, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, passing the cluster ID as a parameter. +The Create Serverless Cluster endpoint returns a <>. When the operation completes, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, and passing the cluster ID as a parameter. endif::[] From c72ea1fc8102e31fed5272b88db082b4e46d7072 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Thu, 1 Aug 2024 10:53:47 -0400 Subject: [PATCH 5/7] Add double quotes and fix incorrect request body example for code blocks --- .../cloud/api/cloud-api-quickstart.adoc | 14 ++++----- .../cloud/api/cloud-dataplane-api.adoc | 16 ++++++---- .../partials/cloud/controlplane-api.adoc | 30 +++++++++---------- 3 files changed, 30 insertions(+), 30 deletions(-) diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc index c5356da2f5..2ac454dd03 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc @@ -40,26 +40,24 @@ Serverless:: + [,bash] ---- -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups +curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/resource-groups ---- . Make a xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/regions[`GET /v1beta2/serverless/regions`] request to see available regions. + [,bash] ---- -curl -H 'Authorization: Bearer ' 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' +curl -H "Authorization: Bearer " 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' ---- . Create a cluster by making a xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[`POST /v1beta2/serverless/clusters`] request. + [,bash] ---- curl -H 'Content-Type: application/json' \ --H 'Authorization: Bearer ' \ +-H "Authorization: Bearer " \ -d '{ - "serverless_cluster": { - "name": , - "resource_group_id": , - "serverless_region": "pro-us-east-1" - } + "name": , + "resource_group_id": , + "serverless_region": "pro-us-east-1" }' -X POST https://api.redpanda.com/v1beta2/serverless/clusters ---- -- diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc index 2a91c644af..4e13676062 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc @@ -48,8 +48,8 @@ To create a new user in your Redpanda cluster, make a POST request to the xref:a [,bash] ---- curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/users" \ - -H "accept: application/json"\ - + -H "Authorization: Bearer " \ + -H "accept: application/json" \ -H "content-type: application/json" \ -d '{"mechanism":"SASL_MECHANISM_SCRAM_SHA_256","name":"payment-service","password":"secure-password"}' ---- @@ -73,7 +73,8 @@ To create a new ACL in your Redpanda cluster, make a xref:api:ROOT:cloud-api.ado [,bash] ---- curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/acls" \ - -H "accept: application/json"\ + -H "Authorization: Bearer " \ + -H "accept: application/json" \ -H "content-type: application/json" \ -d '{"host":"*","operation":"OPERATION_ALL","permission_type":"PERMISSION_TYPE_ALLOW","principal":"User:payment-service","resource_name":"*","resource_pattern_type":"RESOURCE_PATTERN_TYPE_LITERAL","resource_type":"RESOURCE_TYPE_TOPIC"}' ---- @@ -92,7 +93,8 @@ To create a new Redpanda topic without specifying any further parameters, such a [,bash] ---- curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/topics" \ - -H "accept: application/json"\ + -H "Authorization: Bearer " \ + -H "accept: application/json" \ -H "content-type: application/json" \ -d '{"name":"my-simple-test-topic"}' ---- @@ -106,8 +108,9 @@ To create a managed connector, make a POST request to xref:api:ROOT:cloud-api.ad [,bash] ---- curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/connect/clusters/redpanda/connectors" \ - -H "accept: application/json"\ --H "content-type: application/json" \ + -H "Authorization: Bearer " \ + -H "accept: application/json" \ + -H "content-type: application/json" \ -d '{"config":{"connector.class":"com.redpanda.kafka.connect.s3.S3SinkConnector","topics":"test-topic","aws.secret.access.key":"secret-key","aws.s3.bucket.name":"bucket-name","aws.access.key.id":"access-key","aws.s3.bucket.check":"false","region":"us-east-1"},"name":"my-sample-connector"}' ---- @@ -141,6 +144,7 @@ To restart a connector, make a POST request to the xref:api:ROOT:cloud-api.adoc# [,bash] ---- curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.com/v1alpha1/connect/clusters/redpanda/connectors/my-connector/restart" \ + -H "Authorization: Bearer " \ -H "accept: application/json"\ -H "content-type: application/json" \ -d '{"include_tasks":false,"only_failed":false}' diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index 5d83cd063c..2568e205f1 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -57,7 +57,7 @@ The response object represents the long-running operation of creating a cluster. To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter: ```bash -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/operations/ +curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ ``` The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. @@ -80,7 +80,7 @@ Create a resource group by making a POST request to the xref:api:ROOT:cloud-api. [,bash] ---- curl -H 'Content-Type: application/json' \ --H 'Authorization: Bearer ' \ +-H "Authorization: Bearer " \ -d '{ "name": "" }' -X POST https://api.redpanda.com/v1beta2/resource-groups @@ -104,7 +104,7 @@ curl -d \ "name": "", "resource_group_id": "", "region": "us-west1" -}' -H 'Authorization: Bearer ' -X POST https://api.redpanda.com/v1beta2/networks +}' -H "Authorization: Bearer " -X POST https://api.redpanda.com/v1beta2/networks ---- This endpoint returns a <>. @@ -130,7 +130,7 @@ curl -d \ "us-west1-b", "us-west1-c" ] - }' -H 'Authorization: Bearer ' -X POST https://api.redpanda.com/v1beta2/clusters + }' -H "Authorization: Bearer " -X POST https://api.redpanda.com/v1beta2/clusters ---- The Create Cluster endpoint returns a <>. 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. @@ -171,7 +171,7 @@ To create a new serverless cluster, you can use the default resource group, or c This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/resource-groups[`/v1beta2/resource-groups`] endpoint: ```bash -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/resource-groups +curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/resource-groups ``` ==== @@ -181,7 +181,7 @@ Create a resource group by making a POST request to the xref:api:ROOT:cloud-api. [,bash] ---- curl -H 'Content-Type: application/json' \ --H 'Authorization: Bearer ' \ +-H "Authorization: Bearer " \ -d '{ "name": "" }' -X POST https://api.redpanda.com/v1beta2/resource-groups @@ -195,7 +195,7 @@ To see the available regions for Redpanda Serverless, make a GET request to the [,bash] ---- -curl -H 'Authorization: Bearer ' 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' +curl -H "Authorization: Bearer " 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' ---- [,json,role=no-copy] @@ -235,13 +235,11 @@ Create a Serverless cluster by making a request to xref:api:ROOT:cloud-api.adoc# [,bash] ---- curl -H 'Content-Type: application/json' \ --H 'Authorization: Bearer ' \ +-H "Authorization: Bearer " \ -d '{ - "serverless_cluster": { - "name": , - "resource_group_id": , - "serverless_region": "pro-us-east-1" - } + "name": , + "resource_group_id": , + "serverless_region": "pro-us-east-1" }' -X POST https://api.redpanda.com/v1beta2/serverless/clusters ---- @@ -256,7 +254,7 @@ ifndef::env-serverless[] To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/clusters/-id-[`DELETE /v1beta2/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. ```bash -curl -H 'Authorization: Bearer ' -X DELETE https://api.redpanda.com/v1beta2/clusters/ +curl -H "Authorization: Bearer " -X DELETE https://api.redpanda.com/v1beta2/clusters/ ``` ifdef::env-byoc[] @@ -294,7 +292,7 @@ ifdef::env-serverless[] To delete a cluster, make a request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/serverless/clusters/-id-[`DELETE /v1beta2/serverless/clusters/\{id}`] endpoint, passing the cluster ID as a parameter. This is a <>. ```bash -curl -H 'Authorization: Bearer ' -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ +curl -H "Authorization: Bearer " -X DELETE https://api.redpanda.com/v1beta2/serverless/clusters/ ``` Optional: When the cluster is deleted, the delete operation’s state changes to `STATE_COMPLETED`. At this point, you may make a DELETE request to the xref:api:ROOT:cloud-api.adoc#delete-/v1beta2/resource-groups/-id-[`/v1beta2/resource-groups/\{id}`] endpoint to delete the resource group. @@ -328,7 +326,7 @@ The response object represents the long-running operation of creating a cluster. To check the progress of an operation, make a request to the xref:api:ROOT:cloud-api.adoc#get-/v1beta2/operations/-id-[`GET /operations/\{id}`] endpoint using the operation ID as a parameter: ```bash -curl -H 'Authorization: Bearer ' https://api.redpanda.com/v1beta2/operations/ +curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ ``` The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. From af4f8d64e62f91420275a1be051dd4ecac11daf5 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Thu, 1 Aug 2024 11:05:40 -0400 Subject: [PATCH 6/7] Add double quote tip for shell variables in auth header --- .../cloud/api/cloud-api-authentication.adoc | 4 +++- .../deployment-option/cloud/api/cloud-dataplane-api.adoc | 4 +++- modules/deploy/partials/cloud/controlplane-api.adoc | 6 +++++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc index d0a3105106..85aabef9ca 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-authentication.adoc @@ -32,4 +32,6 @@ You must pass the access token in the authorization header of each API request: ```bash curl -H "Authorization: Bearer $YOUR_TOKEN" -``` \ No newline at end of file +``` + +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. \ No newline at end of file diff --git a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc index 4e13676062..e49cb11b16 100644 --- a/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc +++ b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc @@ -22,7 +22,7 @@ To retrieve the Data Plane API URL of a cluster, make a request to xref:api:ROOT Serverless:: + -- -To retrieve the Data Plane API URL of a cluster, make a request to `GET /v1beta2/serverless/clusters/\{id}`. +To retrieve the Data Plane API URL of a cluster, make a request to xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/clusters/-id-[`GET /v1beta2/serverless/clusters/\{id}`]. -- ====== @@ -54,6 +54,8 @@ curl -X POST "https://api-aeb32d9b.cn20bu40d061nvem7sv0.fmc.prd.cloud.redpanda.c -d '{"mechanism":"SASL_MECHANISM_SCRAM_SHA_256","name":"payment-service","password":"secure-password"}' ---- +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. + The success response returns the newly-created username and SASL mechanism: [.no-copy] diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index 3796d099df..50cf6f6052 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -60,6 +60,8 @@ To check the progress of an operation, make a request to the xref:api:ROOT:cloud curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ ``` +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. + The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. == Cluster tiers @@ -243,7 +245,7 @@ curl -H 'Content-Type: application/json' \ }' -X POST https://api.redpanda.com/v1beta2/serverless/clusters ---- -The Create Serverless Cluster endpoint returns a <>. When the operation completes, you can retrieve cluster details by calling `GET /v1beta2/serverless/clusters/\{id}`, and passing the cluster ID as a parameter. +The Create Serverless Cluster endpoint returns a <>. When the operation completes, you can retrieve cluster details by calling xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/clusters/-id-[`GET /v1beta2/serverless/clusters/\{id}`], and passing the cluster ID as a parameter. endif::[] @@ -329,6 +331,8 @@ To check the progress of an operation, make a request to the xref:api:ROOT:cloud curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ ``` +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. + The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. endif::[] From f7b5c39cc7632f0a2374d5634929a6c8f0fc65c0 Mon Sep 17 00:00:00 2001 From: kbatuigas <36839689+kbatuigas@users.noreply.github.com> Date: Thu, 1 Aug 2024 11:24:39 -0400 Subject: [PATCH 7/7] Move TIP to earlier in the serverless version of control plane doc --- modules/deploy/partials/cloud/controlplane-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/deploy/partials/cloud/controlplane-api.adoc b/modules/deploy/partials/cloud/controlplane-api.adoc index 50cf6f6052..48524586d7 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -200,6 +200,8 @@ To see the available regions for Redpanda Serverless, make a GET request to the curl -H "Authorization: Bearer " 'https://api.redpanda.com/v1beta2/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS' ---- +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. + [,json,role=no-copy] ---- { @@ -331,8 +333,6 @@ To check the progress of an operation, make a request to the xref:api:ROOT:cloud curl -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ ``` -TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. - The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. endif::[]