Admin API guide #1390
+151
−2
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,130 @@ | ||
| = Manage Redpanda using the Admin API | ||
| :page-categories: Management, High Availability, Upgrades | ||
| :description: Manage components of a Redpanda cluster, such as individual brokers and partition leadership. The Redpanda Admin API also allows you to perform operations that are specific to Redpanda Self-Managed and cannot be done using the standard Kafka API. | ||
|
|
||
| The Redpanda Admin API allows you to manage your cluster and perform operations specific to Redpanda Self-Managed that are not available through the standard Kafka API. You can call the Admin API using any HTTP client. | ||
|
|
||
| Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool that interacts with the Admin API under the hood. | ||
|
|
||
| Redpanda v25.3 introduces new endpoints to the Admin API that are served with https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations available starting in v25.3 are accessible as RPC services through these new endpoints. Existing Admin API operations from versions earlier than 25.3 remain available at their current URLs and you can continue to use them as usual (including with rpk v25.3 and later). | ||
|
|
||
| == Prerequisites | ||
|
|
||
| * A running Redpanda Self-Managed cluster. | ||
| * Superuser privileges, if xref:manage:security/authentication.adoc#enable-authentication[authentication] is enabled on your cluster for the Admin API. For more information, see xref:manage:security/authentication.adoc#create-superusers[Configure Authentication]. (Some endpoints are read-only and do not require superuser access.) | ||
| * A tool to make HTTP requests, such as `curl`, or client libraries for your programming language of choice. | ||
| ** For Admin API operations introduced in v25.3 and later, you can also make requests using a ConnectRPC client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. These RPC services are also available in a Buf module, which you can access through the https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2[Buf Schema Registry]. The https://buf.build/docs/cli/[Buf CLI] provides an easy way to generate client SDKs. | ||
|
|
||
| == Use the Admin API | ||
|
|
||
| Starting in Redpanda v25.3, in addition to RESTful HTTP endpoints, the Admin API serves new endpoints as ConnectRPC services. You can use either autogenerated Protobuf clients or HTTP requests to call ConnectRPC services. | ||
|
|
||
| Both new and legacy (RESTful) endpoints are accessible on the same port (default: 9644), but they use different URL paths. | ||
|
|
||
| NOTE: Legacy Admin API endpoints remain available and fully supported. Use them for operations not yet available as ConnectRPC services. | ||
|
|
||
| === Authentication | ||
|
|
||
| If authentication is enabled on your cluster, you must provide credentials with each request, either using HTTP Basic authentication or by including an `Authorization` header with a bearer token. For example: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| curl -u <user>:<password> -X GET "http://localhost:9644/v1/cluster_config" | ||
| ---- | ||
|
|
||
| === Use legacy (RESTful) endpoints | ||
|
|
||
| The base URL for all requests to the legacy endpoints is: | ||
|
|
||
| ``` | ||
| http://<broker-address>:<admin-api-port>/v1/ | ||
| ``` | ||
|
|
||
| // TODO: Update link if necessary when v2 URLs are finalized | ||
| For a full list of available endpoints, see the link:/api/doc/admin/v1/[Admin API Reference]. Select "v1" in the version selector to view legacy endpoints. | ||
|
|
||
| ==== Example request | ||
|
|
||
| To use the Admin API to xref:manage:cluster-maintenance/decommission-brokers.adoc[decommission a broker]: | ||
|
|
||
| [tabs] | ||
| ==== | ||
| curl:: | ||
| + | ||
| -- | ||
| Send a PUT request to the link:/api/doc/admin/operation/operation-decommission[`/v1/brokers/\{broker_id}/decommission`] endpoint: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| curl \ | ||
| -u <user>:<password> \ | ||
| --request PUT 'http://<broker-address>:<port>/v1/brokers/<broker-id>/decommission' | ||
| ---- | ||
| -- | ||
|
|
||
| rpk:: | ||
| + | ||
| -- | ||
| For Linux deployments only, run xref:reference:rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission.adoc[`rpk redpanda admin brokers decommission`]: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| rpk redpanda admin brokers decommission <broker-id> | ||
| ---- | ||
| -- | ||
| ==== | ||
|
|
||
| === Use ConnectRPC endpoints | ||
|
|
||
| The new endpoints differ from the legacy endpoints in the following ways: | ||
|
|
||
| * You can use a generated ConnectRPC client to call methods directly from your application code, or send `curl` requests with a JSON payload, as with legacy endpoints. | ||
| * URL paths use the fully-qualified names of the ConnectRPC services. | ||
| * ConnectRPC endpoints accept only POST requests. | ||
|
|
||
| Use ConnectRPC endpoints with features introduced in v25.3 such as: | ||
|
|
||
| // TODO: Add links to docs when they are merged | ||
| * Shadowing | ||
| * Connected client monitoring | ||
|
|
||
| For a full list of available endpoints, see the link:/api/doc/admin/v2/[Admin API Reference]. Select "v2" in the version selector to view the ConnectRPC endpoints. | ||
|
There was a problem hiding this comment. @mattschumpert I think users are going to be throwing questions our way--we should be up front/transparent about v1 vs v2. If we are not, this will generate questions and may undermine user confidence in the docs. |
||
|
|
||
| ==== Example request | ||
|
|
||
| To fail over a specific shadow topic from an existing shadow link: | ||
|
|
||
| [tabs] | ||
| ==== | ||
| curl:: | ||
| + | ||
| -- | ||
| Send a POST request to the link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-shadowlinkservice-failover[`redpanda.core.admin.v2.ShadowLinkService/FailOver`] endpoint: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| curl \ | ||
| -u <user>:<password> \ | ||
| --request POST 'http://<broker-address>:<admin-api-port>/redpanda.core.admin.v2.ShadowLinkService/FailOver' \ | ||
| --header "Content-Type: application/json" \ | ||
| --data '{ | ||
| "name": "<shadow-link-name>", | ||
| "shadowTopicName": "<shadow-topic-name>" | ||
| }' | ||
| ---- | ||
|
|
||
| - Request headers `Connect-Protocol-Version` and `Connect-Timeout-Ms` are optional. | ||
| - v2 endpoints also accept binary-encoded Protobuf request bodies. Use the `Content-Type: application/proto` header. | ||
| -- | ||
|
|
||
| rpk:: | ||
| + | ||
| -- | ||
| Run `rpk shadow failover`: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| rpk shadow failover <shadow-link-name> --topic <shadow-topic-name> | ||
| ---- | ||
| -- | ||
| ==== | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So if I want to know if the endpoints I need to use require superuser access, can I view a list somewhere that tells me which endpoints require it and which ones don't?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All v2 endpoints require superuser, but I don't have a definitive list for v1. Will reach out to an SME - if this list can be put together, these details can be added at a later time