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..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 @@ -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 @@ -31,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-api-quickstart.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-api-quickstart.adoc index 68c6060fe6..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 @@ -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,31 @@ rpk cloud byoc aws apply --redpanda-id= Serverless:: + -- -. xref:ROOT:deploy:deployment-option/cloud/api/cloud-api-authentication.adoc[Authenticate to the API]. -. Create a cluster by making a `POST /v1beta2/serverless/clusters` request. +. 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 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 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' +---- +. 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 " \ +-d '{ + "name": , + "resource_group_id": , + "serverless_region": "pro-us-east-1" +}' -X POST https://api.redpanda.com/v1beta2/serverless/clusters +---- -- ====== @@ -65,7 +88,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/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc b/modules/deploy/pages/deployment-option/cloud/api/cloud-dataplane-api.adoc index 5e70254342..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 @@ -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 xref:api:ROOT:cloud-api.adoc#get-/v1beta2/serverless/clusters/-id-[`GET /v1beta2/serverless/clusters/\{id}`]. +-- +====== The response includes a `dataplane_api.url` value: @@ -35,12 +48,14 @@ 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"}' ---- +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] @@ -60,7 +75,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"}' ---- @@ -79,7 +95,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"}' ---- @@ -93,8 +110,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"}' ---- @@ -128,6 +146,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 db452a3a71..48524586d7 100644 --- a/modules/deploy/partials/cloud/controlplane-api.adoc +++ b/modules/deploy/partials/cloud/controlplane-api.adoc @@ -22,14 +22,13 @@ 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 +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`): @@ -58,12 +57,12 @@ 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`. +TIP: When using a shell substitution variable for the token, use double quotes to wrap the header value. -ifndef::env-serverless[] +The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. == Cluster tiers @@ -83,7 +82,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 @@ -107,10 +106,10 @@ 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 <>. +This endpoint returns a <>. === Create a new cluster @@ -133,10 +132,10 @@ 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. +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 @@ -169,14 +168,22 @@ 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 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 +``` + +==== 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. [,bash] ---- curl -H 'Content-Type: application/json' \ --H 'Authorization: Bearer ' \ +-H "Authorization: Bearer " \ -d '{ "name": "" }' -X POST https://api.redpanda.com/v1beta2/resource-groups @@ -186,14 +193,15 @@ 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/ +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] ---- { @@ -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": "" @@ -224,23 +234,20 @@ 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] ---- 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 ---- -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 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::[] @@ -248,10 +255,10 @@ 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/ +curl -H "Authorization: Bearer " -X DELETE https://api.redpanda.com/v1beta2/clusters/ ``` ifdef::env-byoc[] @@ -286,15 +293,48 @@ 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 -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. +[[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 xref:api:ROOT:cloud-api.adoc#post-/v1beta2/serverless/clusters[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 -H "Authorization: Bearer " https://api.redpanda.com/v1beta2/operations/ +``` + +The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. + endif::[] == Next steps