admin-api-overview.md

id	title	sidebar_label
admin-api-overview	The Pulsar admin interface	Overview

The Pulsar admin interface enables you to manage all of the important entities in a Pulsar instance, such as tenants, topics, and namespaces.

You can currently interact with the admin interface via:

• Making HTTP calls against the admin {@inject: rest:REST:/} API provided by Pulsar brokers. For some restful apis, they might be redirected to topic owner brokers for serving with 307 Temporary Redirect, hence the HTTP callers should handle 307 Temporary Redirect. If you are using curl, you should specify -L to handle redirections.
• The pulsar-admin CLI tool, which is available in the bin folder of your Pulsar installation:

$ bin/pulsar-admin

Full documentation for this tool can be found in the Pulsar command-line tools doc.

• A Java client interface.

The REST API is the admin interface

Under the hood, both the pulsar-admin CLI tool and the Java client both use the REST API. If you’d like to implement your own admin interface client, you should use the REST API as well. Full documentation can be found here.

In this document, examples from each of the three available interfaces will be shown.

Admin setup

Each of Pulsar's three admin interfaces---the pulsar-admin CLI tool, the Java admin API, and the {@inject: rest:REST:/} API ---requires some special setup if you have authentication enabled in your Pulsar instance.

pulsar-admin

If you have authentication enabled, you will need to provide an auth configuration to use the pulsar-admin tool. By default, the configuration for the pulsar-admin tool is found in the conf/client.conf file. Here are the available parameters:

Name	Description	Default
webServiceUrl	The web URL for the cluster.	http://localhost:8080/
brokerServiceUrl	The Pulsar protocol URL for the cluster.	pulsar://localhost:6650/
authPlugin	The authentication plugin.
authParams	The authentication parameters for the cluster, as a comma-separated string.
useTls	Whether or not TLS authentication will be enforced in the cluster.	false
tlsAllowInsecureConnection	Accept untrusted TLS certificate from client.	false
tlsTrustCertsFilePath	Path for the trusted TLS certificate file.

REST API

You can find documentation for the REST API exposed by Pulsar brokers in this reference {@inject: rest:document:/}.

Java admin client

To use the Java admin API, instantiate a {@inject: javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object, specifying a URL for a Pulsar broker and a {@inject: javadoc:PulsarAdminBuilder:/admin/org/apache/pulsar/client/admin/PulsarAdminBuilder}. Here's a minimal example using localhost:

String url = "http://localhost:8080";
// Pass auth-plugin class fully-qualified name if Pulsar-security enabled
String authPluginClassName = "com.org.MyAuthPluginClass";
// Pass auth-param if auth-plugin class requires it
String authParams = "param1=value1";
boolean useTls = false;
boolean tlsAllowInsecureConnection = false;
String tlsTrustCertsFilePath = null;
PulsarAdmin admin = PulsarAdmin.builder()
.authentication(authPluginClassName,authParams)
.serviceHttpUrl(url)
.tlsTrustCertsFilePath(tlsTrustCertsFilePath)
.allowTlsInsecureConnection(tlsAllowInsecureConnection)
.build();

If you have multiple brokers to use, you can use multi-host like Pulsar service. For example,

String url = "http://localhost:8080,localhost:8081,localhost:8082";
// Pass auth-plugin class fully-qualified name if Pulsar-security enabled
String authPluginClassName = "com.org.MyAuthPluginClass";
// Pass auth-param if auth-plugin class requires it
String authParams = "param1=value1";
boolean useTls = false;
boolean tlsAllowInsecureConnection = false;
String tlsTrustCertsFilePath = null;
PulsarAdmin admin = PulsarAdmin.builder()
.authentication(authPluginClassName,authParams)
.serviceHttpUrl(url)
.tlsTrustCertsFilePath(tlsTrustCertsFilePath)
.allowTlsInsecureConnection(tlsAllowInsecureConnection)
.build();