Configure Access to Multiple Clusters (snctl)

This page shows how to configure access to multiple Pulsar clusters by using configuration files. After your clusters, authentication information, and contexts are defined in one or more configuration files, you can quickly switch between clusters by using the pulsarctl context use command.

Note

A file that is used to configure access to a cluster is sometimes called a pulsarconfig file. This is a generic way of referring to configuration files. It does not mean that there is a file named pulsarconfig.

Warning

Only use pulsarconfig files from trusted sources. Using a specially-crafted pulsarconfig file could result in malicious code execution or file exposure. If you must use an untrusted pulsarconfig file, inspect it carefully first, much as you would a shell script.

Before you begin

You need to have a Pulsar cluster, and the pulsarctl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one fully-managed Pulsar cluster on StreamNative Cloud, spin a self-managed StreamNative Private Cloud cluster, or run a standalone Pulsar cluster locally.

To check that pulsarctl is installed, run pulsarctl --version.

Define contexts and authentication info

Suppose you have two clusters, one for development work and one for production work. The development cluster is self-managed in your own datacenter, using Token authentication, while the production cluster is fully-managed on StreamNative Cloud, using OAuth2 authentication.

Now, you can use pulsarctl context set to define your clusters and the corresponding authentication information.

First, you can create a development context to access your development cluster running at https://1.2.3.4 using token stored in file /path/to/token.

pulsarctl context set development \
  --admin-service-url https://1.2.3.4 \
  --token-file /path/to/token

Secondly, you can create a production context to access your production cluster running at https://5.6.7.8 on StreamNative Cloud using the OAuth2 private key file /path/to/credentials.json.

Note

Instead of manually configuring a context to access a StreamNative Cloud cluster, you can also use snctl x update-pulsar-config to add the cluster to the pulsarconfig file.

Please note that x in snctl x is a sub command for a group of experimental commands.

pulsarctl context set production \
  --admin-service-url https://5.6.7.8 \
  --issuer-endpoint https://auth.streamnative.cloud \
  --key-file /path/to/credentials.json \
  --audience urn:sn:pulsar:myorg:production

Then you can use pulsarctl context get to retrieve the list of available contexts configured for pulsarctl. You should be able to see similar output as below.

+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+
| CURRENT |    NAME     |                                BROKER SERVICE URL                                 |  BOOKIE SERVICE URL   |
+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+
| *       | production  | https://5.6.7.8                                                                   | http://localhost:8080 |
|         | development | https://1.2.3.4                                                                   | http://localhost:8080 |
+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+

You are able to find the pulsarconfig file located at ${HOME}/.config/pulsar/config. Run the following command to check the context of pulsarconfig file.

cat ${HOME}/.config/pulsar/config

You should be able to see similar content as below:

auth-info:
  development:
    locationoforigin: /Users/john.doe/.config/pulsar/config
    tls_trust_certs_file_path: ""
    tls_allow_insecure_connection: false
    token: ""
    tokenFile: /path/to/token
    issuer_endpoint: ""
    client_id: ""
    audience: ""
    scope: ""
    key_file: ""
  production:
    locationoforigin: /Users/john.doe/.config/pulsar/config
    tls_trust_certs_file_path: ""
    tls_allow_insecure_connection: false
    token: ""
    tokenFile: ""
    issuer_endpoint: https://auth.streamnative.cloud
    client_id: ""
    audience: urn:sn:pulsar:myorg:production
    scope: ""
    key_file: /path/to/credentials.json
contexts:
  development:
    admin-service-url: https://1.2.3.4
    bookie-service-url: http://localhost:8080
  production:
    admin-service-url: https://5.6.7.8
    bookie-service-url: http://localhost:8080
current-context: production

Set the current context

When you define the context in ${HOME}/.config/pulsar/config, you can quickly switch between clusters by using the following command (suppose you want to use the development cluster):

pulsarctl context use development

Now, you are using the context of development cluster. And you can validate the current context by using pulsarctl context current command.

If you don't know the current available list of contexts, you can use the following command:

pulsarctl context get

You will see a similar output as follows:

+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+
| CURRENT |    NAME     |                                BROKER SERVICE URL                                 |  BOOKIE SERVICE URL   |
+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+
| *       | production  | https://5.6.7.8                                                                   | http://localhost:8080 |
|         | development | https://1.2.3.4                                                                   | http://localhost:8080 |
+---------+-------------+-----------------------------------------------------------------------------------+-----------------------+

Rename the context

You can modify the context name by using the following command:

pulsarctl context rename <old_name> <new_name>

Delete the context

If the cluster information is invalid or is not used anymore, you want to delete it. You can use the following command to delete a context:

pulsarctl context delete development