Managing Clusters

tip

This page only shows some frequently used operations. For the latest and complete information, see the reference docs below.

Category	Method	If you want to manage clusters...
Pulsar CLI	pulsar-admin, which lists all commands, flags, descriptions, and more.	See the clusters command
Pulsar admin APIs	REST API, which lists all parameters, responses, samples, and more.	See the /admin/v2/clusters endpoint
Pulsar admin APIs	Java admin API, which lists all classes, methods, descriptions, and more.	See the clusters method of the PulsarAdmin object

You can perform the following operations on clusters.

Provision cluster

You can provision new clusters using the admin interface.

note

• This operation requires superuser privileges.

• When provisioning a new cluster, you need to initialize cluster metadata. Cluster metadata can be initialized through the pulsar-admin CLI only. It cannot be performed via Pulsar admin APIs (REST API and Java admin API).

pulsar-admin

You can provision a new cluster using the create subcommand. Here's an example:

pulsar-admin clusters create cluster-1 \
    --url http://my-cluster.org.com:8080 \
    --broker-url pulsar://my-cluster.org.com:6650

REST API

PUT /admin/v2/clusters/{cluster}

Java

ClusterData clusterData = new ClusterData(
        serviceUrl,
        serviceUrlTls,
        brokerServiceUrl,
        brokerServiceUrlTls
);
admin.clusters().createCluster(clusterName, clusterData);

Get cluster configuration

You can fetch the configuration for an existing cluster at any time.

pulsar-admin

Use the get subcommand and specify the name of the cluster. Here's an example:

pulsar-admin clusters get cluster-1

Output:

{
    "serviceUrl": "http://my-cluster.org.com:8080/",
    "serviceUrlTls": null,
    "brokerServiceUrl": "pulsar://my-cluster.org.com:6650/",
    "brokerServiceUrlTls": null
    "peerClusterNames": null
}

REST API

GET /admin/v2/clusters/{cluster}

Java

admin.clusters().getCluster(clusterName);

Update cluster

Update cluster configuration

You can update the configuration for an existing cluster at any time.

pulsar-admin

Use the update subcommand and specify new configuration values using flags.

pulsar-admin clusters update cluster-1 \
    --url http://my-cluster.org.com:4081 \
    --broker-url pulsar://my-cluster.org.com:3350

REST API

POST /admin/v2/clusters/{cluster}

Java

ClusterData clusterData = new ClusterData(
        serviceUrl,
        serviceUrlTls,
        brokerServiceUrl,
        brokerServiceUrlTls
);
admin.clusters().updateCluster(clusterName, clusterData);

Update peer-cluster data

Peer clusters can be configured for a given cluster in a Pulsar instance.

pulsar-admin

Use the update-peer-clusters subcommand and specify the list of peer-cluster names.

pulsar-admin update-peer-clusters cluster-1 --peer-clusters cluster-2

REST API

POST /admin/v2/clusters/{cluster}/peers

Java

admin.clusters().updatePeerClusterNames(clusterName, peerClusterList);

List cluster

You can fetch a list of all clusters in a Pulsar instance.

pulsar-admin

Use the list subcommand.

pulsar-admin clusters list

Output:

cluster-1
cluster-2

REST API

GET /admin/v2/clusters

Java

admin.clusters().getClusters();

Delete cluster

Clusters can be deleted from a Pulsar instance.

pulsar-admin

Use the delete subcommand and specify the name of the cluster.

pulsar-admin clusters delete cluster-1

REST API

DELETE /admin/v2/clusters/{cluster}

Java

admin.clusters().deleteCluster(clusterName);