|
| 1 | += Manage Redpanda using the Admin API |
| 2 | +:page-categories: Management, High Availability, Upgrades |
| 3 | +: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. |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +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). |
| 10 | + |
| 11 | +== Prerequisites |
| 12 | + |
| 13 | +* A running Redpanda Self-Managed cluster. |
| 14 | +* 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.) |
| 15 | +* A tool to make HTTP requests, such as `curl`, or client libraries for your programming language of choice. |
| 16 | +** 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. |
| 17 | + |
| 18 | +== Use the Admin API |
| 19 | + |
| 20 | +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. |
| 21 | + |
| 22 | +Both new and legacy (RESTful) endpoints are accessible on the same port (default: 9644), but they use different URL paths. |
| 23 | + |
| 24 | +NOTE: Legacy Admin API endpoints remain available and fully supported. Use them for operations not yet available as ConnectRPC services. |
| 25 | + |
| 26 | +=== Authentication |
| 27 | + |
| 28 | +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: |
| 29 | + |
| 30 | +[,bash] |
| 31 | +---- |
| 32 | +curl -u <user>:<password> -X GET "http://localhost:9644/v1/cluster_config" |
| 33 | +---- |
| 34 | + |
| 35 | +=== Use legacy (RESTful) endpoints |
| 36 | + |
| 37 | +The base URL for all requests to the legacy endpoints is: |
| 38 | + |
| 39 | +``` |
| 40 | +http://<broker-address>:<admin-api-port>/v1/ |
| 41 | +``` |
| 42 | + |
| 43 | +// TODO: Update link if necessary when v2 URLs are finalized |
| 44 | +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. |
| 45 | + |
| 46 | +==== Example request |
| 47 | + |
| 48 | +To use the Admin API to xref:manage:cluster-maintenance/decommission-brokers.adoc[decommission a broker]: |
| 49 | + |
| 50 | +[tabs] |
| 51 | +==== |
| 52 | +curl:: |
| 53 | ++ |
| 54 | +-- |
| 55 | +Send a PUT request to the link:/api/doc/admin/operation/operation-decommission[`/v1/brokers/\{broker_id}/decommission`] endpoint: |
| 56 | +
|
| 57 | +[,bash] |
| 58 | +---- |
| 59 | +curl \ |
| 60 | + -u <user>:<password> \ |
| 61 | + --request PUT 'http://<broker-address>:<port>/v1/brokers/<broker-id>/decommission' |
| 62 | +---- |
| 63 | +-- |
| 64 | +
|
| 65 | +rpk:: |
| 66 | ++ |
| 67 | +-- |
| 68 | +For Linux deployments only, run xref:reference:rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission.adoc[`rpk redpanda admin brokers decommission`]: |
| 69 | +
|
| 70 | +[,bash] |
| 71 | +---- |
| 72 | +rpk redpanda admin brokers decommission <broker-id> |
| 73 | +---- |
| 74 | +-- |
| 75 | +==== |
| 76 | + |
| 77 | +=== Use ConnectRPC endpoints |
| 78 | + |
| 79 | +The new endpoints differ from the legacy endpoints in the following ways: |
| 80 | + |
| 81 | +* 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. |
| 82 | +* URL paths use the fully-qualified names of the ConnectRPC services. |
| 83 | +* ConnectRPC endpoints accept only POST requests. |
| 84 | + |
| 85 | +Use ConnectRPC endpoints with features introduced in v25.3 such as: |
| 86 | + |
| 87 | +// TODO: Add links to docs when they are merged |
| 88 | +* Shadowing |
| 89 | +* Connected client monitoring |
| 90 | + |
| 91 | +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. |
| 92 | + |
| 93 | +==== Example request |
| 94 | + |
| 95 | +To fail over a specific shadow topic from an existing shadow link: |
| 96 | + |
| 97 | +[tabs] |
| 98 | +==== |
| 99 | +curl:: |
| 100 | ++ |
| 101 | +-- |
| 102 | +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: |
| 103 | +
|
| 104 | +[,bash] |
| 105 | +---- |
| 106 | +curl \ |
| 107 | + -u <user>:<password> \ |
| 108 | + --request POST 'http://<broker-address>:<admin-api-port>/redpanda.core.admin.v2.ShadowLinkService/FailOver' \ |
| 109 | + --header "Content-Type: application/json" \ |
| 110 | + --data '{ |
| 111 | + "name": "<shadow-link-name>", |
| 112 | + "shadowTopicName": "<shadow-topic-name>" |
| 113 | +}' |
| 114 | +---- |
| 115 | +
|
| 116 | +- Request headers `Connect-Protocol-Version` and `Connect-Timeout-Ms` are optional. |
| 117 | +- v2 endpoints also accept binary-encoded Protobuf request bodies. Use the `Content-Type: application/proto` header. |
| 118 | +-- |
| 119 | +
|
| 120 | +rpk:: |
| 121 | ++ |
| 122 | +-- |
| 123 | +Run `rpk shadow failover`: |
| 124 | +
|
| 125 | +[,bash] |
| 126 | +---- |
| 127 | +rpk shadow failover <shadow-link-name> --topic <shadow-topic-name> |
| 128 | +---- |
| 129 | +-- |
| 130 | +==== |
0 commit comments