Connect to cluster through pulsarctl

pulsarctl is a CLI tool, developed in Go language and based on Pulsar REST API, to control and manage Pulsar clusters, tenants, namespaces, topics, schemas, sources, sinks, functions, and so on.

This document assumes that you have created a Pulsar cluster and a service account, and have granted the service account produce and consume permissions to the namespace for the target topic.

Prerequisites

pulsarctl 2.9.0 or higher version

Connect to cluster through OAuth2 authentication plugin

pulsarctl supports to connect to Pulsar cluster through the OAuth2 authentication plugin in two ways:

CLI tool
Go Admin API

Use CLI tool

If it is the first time you install and use pulsarctl, you must use the pulsarctl context set command to set a context (cluster) in advance.

Add a cluster to the Pulsar client configuration file (context of the pulsarctl tool).
In a multi-cluster environment, context helps you cache information about multiple clusters and switch between them.
This example adds a neo-1 cluster to the Pulsar client configuration file.
Input
```
snctl x update-pulsar-config --cluster-name <neo-1>
```
Output
```
Updated Pulsar client configuration for context 'neo-1'.
```
Verify that the current context has been changed.
Input
```
pulsarctl context current
```
Output
```
neo-1
```

Connect to the target cluster.

Input

pulsarctl oauth2 login

Output

We've launched your web browser to complete the login process.
Verification code: CTSM-XLHB


Waiting for login to complete...
Logged in as google-oauth2|111222985617062794188.
Welcome to Pulsar!

Use the pulsarctl CLI tool to get Pulsar resources.

This example lists tenants for the cluster neo-1.

Input

pulsarctl tenants list

OutPut

+-------------+
| TENANT NAME |
+-------------+
| public      |
| pulsar      |
| sn          |
+-------------+

Use Go Admin API

pulsarctl provides the function of the Go Admin API. You can use the interface of the Go Admin API to establish a connection with a Pulsar cluster.

Get the Pulsar Web service URL. For details, see get a service URL.
Get the OAuth2 credential file of your service account. For details, see get an OAuth2 credential file.
Connect to a Pulsar cluster through the OAuth2 authentication plugin.
```
func main() {
  flag.Parse()

  if help {
    flag.Usage()
  }

  pulsarCtlConfig := &common.Config{
    WebServiceURL:              webServiceURL,
    TLSAllowInsecureConnection: true,
  }
  issuer := oauth2.Issuer{
    IssuerEndpoint: issuerUrl,
    ClientID:       clientId,
    Audience:       audience,
  }
  oauth, err := auth.NewAuthenticationOAuth2WithDefaultFlow(issuer, privateKey)
  if err != nil {
    log.Fatal(err)
  }
  admin := pulsar.NewWithAuthProvider(pulsarCtlConfig, oauth)
  ns, err := admin.Namespaces().GetNamespaces("public")
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("the namespace is: %s\n", ns)
}
```
- WebServiceURL: the broker service URL of your Pulsar cluster.
- IssuerEndpoint: the URL of your OAuth2 authentication provider. You can get the value from your downloaded OAuth2 credential file.
- client_id: the client ID of your application. You can get the value from your downloaded OAuth2 credential file.
- credentialsUrl: the path to your downloaded OAuth2 credential file. The privateKey parameter supports the following three pattern formats:
  - file:///path/to/file
  - file:/path/to/file
  - data:application/json;base64,<base64-encoded value>
- audience: the audience parameter is the Uniform Resource Name (URN), which is a combination of the urn:sn:pulsar, the organization name, and the Pulsar instance name, in this format urn:sn:pulsar:<org_name>:<instance_name>.

Connect to cluster through Token authentication plugin

To connect a cluster through the Token authentication plugin, follow these steps.

Get the service URL of your Pulsar cluster. For details, see get a service URL.
Get the token of your service account. For details, see get a token.
Connect to a Pulsar cluster through the Token authentication plugin.
```
pulsarctl \
  --admin-service-url WEB_SERVICE_URL \
  --token AUTH_PARAMS \
  tenants list
```
- admin-service-url: the HTTP service URL of your Pulsar cluster.
- token: the token of your service account.