StreamNative Cloud provides a command line tool for communicating with StreamNative Cloud’s control plane, using the StreamNative Cloud API. This tool is named snctl
. This overview includes how to install and configure snctl
, covers snctl
syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the snctl reference documentation.
To resolve ambiguity with Apache Pulsar’s concept of namespaces, particularly when using snctl pulsar
subcommands, the flags --namespace
(-n
) were updated to --organization
(-O
) beginning in snctl v1.0.0.
Before moving on to the subsequent steps, ensure you review the following requirements.
The StreamNative CLI is compatible with the following operating systems and architectures only:
When the StreamNative CLI interacts with StreamNative Cloud, it requires network access to the following domains:
api.streamnative.cloud
auth.streamnative.cloud
log.streamnative.cloud
This section describes how to install snctl on Linux, MAC, and Windows Operating System (OS).
You can use the curl
command or use Homebrew to install snctl on Linux.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
You can use the curl
command or use Homebrew to install snctl on Linux.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
You can use the curl command or use Homebrew to install snctl on a Mac.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
Add the repository.
Install snctl.
Download the latest release package.
Extract the snctl .zip
package using Windows Explorer. For details, see the instructions.
(Optional) Copy the snctl.exe
binary to a directory on your PATH
.
Check whether snctl is installed successfully.
When upgrading from snctl
v0.x.x
to v1.x.x
, please run snctl config init
again to ensure all newly introduced configuration settings are applied to your local configuration file.
This section describes how to configure snctl
.
Before logging in to snctl
, you need to configure snctl
. You can either use the snctl config init
command to initialize snctl with default configurations or you can use the snctl config set
command to update the .snctl/config
snctl configuration file.
The .snctl/config
file contains configurations about snctl, including OAuth2 configurations, service URL for the StreamNative Cloud API, and so on. You can use the snctl config set
command to set snctl configurations.
This example sets a target organization as the default organization. Consequently, in this organization, you can perform other operations on StreamNative Cloud resources without specifying the organization name every time.
With the organization
option, you need to use the organization id, not the descriptive organization name. To find the organization id, see Cloud Organization ID.
You need to sign in to an organization before executing any snctl
commands. You can sign in either as a specific user or as a service account.
This example shows how to sign in as a user account. In this way, snctl
is given a token to impersonate the user.
Output
This example shows how to sign in as a user account. In this way, snctl
is given a token to impersonate the user.
Output
This example shows how to sign in as a service account.
Download the credentials file of the service account.
Sign in as a service account.
Output
Notes:
Replace <service_account_name>
with the service account name you use.
Replace /path/to/service_account_credentials.json
with the right file path to save the credentials of the service account. Please make sure the credentials are saved in a safe location.
If your organization already has a valid subscription, you can skip this section.
Before you provision a cluster using snctl
, you need to set up a subscription to StreamNative Cloud. If you have a legacy cluster, submit a ticket to get assistance with moving your cluster to the updated subscription plan.
snctl create subscription
command is available for snctl
version 0.14.1
and above.snctl
does not support setting up a payment method. You can add a payment method for your organization through StreamNative Cloud Console. For details, see manage billing using StreamNative Cloud Console.You can use the snctl create subscription
command to create a subscription.
Notes:
--offer-type
: the offer type. Two options are available:
private
: the private offer that is made to a specific customer. It is a commitment to a minimum amount of spend over a specified time period.public
: the public offer that anyone may subscribe to through StreamNative or Marketplace channels. It is a Pay-As-You-Go subscription with usage-based pricing.--offer
: the offer name.
SN2_OD_HOSTED_CLOUD
) that snctl
uses by default.Output
You should see the following output if you create a public offer subscription:
You should see the following output if you create a private offer subscription:
This section describes how to provision Pulsar clusters through snctl.
In this section, the target organization name is already set in the .snctl/config
file. Therefore, you do not need to use the --organization <organization_name>
flag to specify the target organization every time when executing snctl
commands. For details about how to set snctl configurations, see set snctl configuration.
This section describes how to create a Dedicated cluster through snctl.
Create a Pulsar instance named neo
.
This example shows how to create the neo
instance on the AWS cloud platform. To create a Pulsar instance on Google Cloud, set the infrastructure pool name to streamnative/shared
. To create a BYOC instance/cluster, the StreamNative team needs to provision an infrastructure pool in your cloud account before you can use it.
Output
Find the available locations of a given infrastructure pool to deploy a Pulsar cluster.
This example shows how to find the available locations for the infrastructure pool streamnative/shared-aws
.
You can find the locations shown up in the spec.locations
section of the output.
Create a Pulsar cluster named neo-1
, consisting of 2 brokers, each using 0.5 CU, and 3 bookies, each using 0.5 SU, to be deployed in us-east-1
.
The following command is available for snctl
version 0.15.0
and above.
Output
You can use the snctl describe pulsarcluster <cluster_name>
command to get details of a Pulsar cluster.
This example gets details of the neo-1
cluster.
Output
From the outputs, you can see that the status
and type
parameters for items under Conditions
are set to true
and ready
respectively. This means that the neo-1
cluster is created successfully.
Starting from version v1.0.0
, snctl
introduces the concept of a Service Context. This feature aims to make snctl
a unified tool not only for managing StreamNative Cloud resources (like creating and managing clusters) but also for directly interacting with the data plane of your Pulsar clusters using both the native Pulsar protocol and the Kafka protocol (via KSN or Ursa Engine).
A Service Context is essentially a named configuration profile stored within your snctl
configuration (~/.snctl/config
). It bundles the necessary connection details —- primarily the service URL and authentication information —- required to connect to a specific Pulsar cluster managed by StreamNative Cloud.
Automatic Context Discovery
Typically, you don’t need to manually create contexts for your StreamNative Cloud Pulsar clusters. After successfully logging in using snctl auth login
, snctl
can often automatically detect the Pulsar clusters you have access to within your organization. It makes these clusters available as selectable contexts, usually using the instance name and cluster name as the context.
(Note: For managing contexts related to external, non-StreamNative Cloud clusters, see commands like snctl context add-external-context
, snctl context list-external-context
, etc.)
Switching and Using Contexts
To interact with a specific cluster using snctl pulsar
or snctl kafka
commands, you first need to activate its corresponding context.
Set the Active Context: Use the snctl context use
command, will likely prompt you to choose from a list of all available Pulsar Instances and Pulsar Clusters, select the target cluster by keyboard, and additional authentication may required if no valid token cached.
Non-interactive
Verify the Current Context: You can check which context is currently active using:
Output (Example)
Interacting with Pulsar and Kafka Protocols
Once a service context is active, all subsequent snctl pulsar client ...
, snctl pulsar admin ...
, snctl kafka client ...
, and snctl kafka admin ...
commands will automatically use the connection details (service URL, authentication) defined in that active context. You no longer need to specify connection flags repeatedly for these commands.
Running commands by using specific Service Account
While the active context usually derives its authentication from your user login (snctl auth login
), you can override this for individual command executions to run as a specific service account. This is useful for automation or when specific permissions granted to a service account are needed. Another use case is to submit Pulsar Functions, Pulsar IO Connectors, and Kafka Connect connectors in StreamNative Cloud, this will makes the submitted instances running under given permission by the service account.
Crucially, snctl
will verify if your currently logged-in user account has the necessary permissions to impersonate the chosen service account before executing the command.
Specify Service Account by Name: Use the --as-service-account
flag followed by the service account name. snctl
will use the credentials associated with this service account for the command.
Interactively Select Service Account: Use the --use-service-account
flag without specifying a name. snctl
will likely prompt you to choose from a list of available service accounts you have access to. This will shows you the details of each Service Account, as well as the status of each Service Account Binding, which is useful on manage Pulsar Functions, Pulsar IO Connectors, and Kafka Connect connectors.
Example Workflow:
Note on pulsarctl
Configuration:
This Service Context mechanism is internal to snctl
for unifying its own commands. It is distinct from the snctl x update-pulsar-config
command (described later). The update-pulsar-config
command is specifically designed to configure the separate pulsarctl
tool, allowing it to connect to your StreamNative Cloud cluster. The snctl context
commands enable snctl
itself to perform data plane operations directly via its pulsar
and kafka
subcommands.
This section describes how to add a cluster to the Pulsar client configuration file. After adding a cluster to the Pulsar client configuration file, you can manage the cluster using the pulsarctl
CLI tool. To get details about the access and managing Apache Pulsar resources through pulsarctl
, see pulsarctl
command reference.
It is recommended to use the pulsarctl context get
command to set the context (cluster) in advance.
Add a cluster to the Pulsar client configuration file.
This example adds a neo-1
cluster to the Pulsar client configuration file.
Input
Output
Verify that the current context has been changed.
Input
Output
After verifying that the change was made, you can use the pulsarctl
CLI tool to interact with the target cluster. For details, see the pulsarctl reference docs. To work with tenants, namespaces, and topics, you can use the StreamNative Cloud Console. snctl does not currently support working with these features.
StreamNative Cloud provides a command line tool for communicating with StreamNative Cloud’s control plane, using the StreamNative Cloud API. This tool is named snctl
. This overview includes how to install and configure snctl
, covers snctl
syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the snctl reference documentation.
To resolve ambiguity with Apache Pulsar’s concept of namespaces, particularly when using snctl pulsar
subcommands, the flags --namespace
(-n
) were updated to --organization
(-O
) beginning in snctl v1.0.0.
Before moving on to the subsequent steps, ensure you review the following requirements.
The StreamNative CLI is compatible with the following operating systems and architectures only:
When the StreamNative CLI interacts with StreamNative Cloud, it requires network access to the following domains:
api.streamnative.cloud
auth.streamnative.cloud
log.streamnative.cloud
This section describes how to install snctl on Linux, MAC, and Windows Operating System (OS).
You can use the curl
command or use Homebrew to install snctl on Linux.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
You can use the curl
command or use Homebrew to install snctl on Linux.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
You can use the curl command or use Homebrew to install snctl on a Mac.
Execute the following command to download and install the latest snctl.
If you want to download a specific version, use the flag -v
or --version
to specify the version. For example, you can use the following command to download snctl v1.0.0
.
Check whether snctl is installed successfully.
Add the repository.
Install snctl.
Download the latest release package.
Extract the snctl .zip
package using Windows Explorer. For details, see the instructions.
(Optional) Copy the snctl.exe
binary to a directory on your PATH
.
Check whether snctl is installed successfully.
When upgrading from snctl
v0.x.x
to v1.x.x
, please run snctl config init
again to ensure all newly introduced configuration settings are applied to your local configuration file.
This section describes how to configure snctl
.
Before logging in to snctl
, you need to configure snctl
. You can either use the snctl config init
command to initialize snctl with default configurations or you can use the snctl config set
command to update the .snctl/config
snctl configuration file.
The .snctl/config
file contains configurations about snctl, including OAuth2 configurations, service URL for the StreamNative Cloud API, and so on. You can use the snctl config set
command to set snctl configurations.
This example sets a target organization as the default organization. Consequently, in this organization, you can perform other operations on StreamNative Cloud resources without specifying the organization name every time.
With the organization
option, you need to use the organization id, not the descriptive organization name. To find the organization id, see Cloud Organization ID.
You need to sign in to an organization before executing any snctl
commands. You can sign in either as a specific user or as a service account.
This example shows how to sign in as a user account. In this way, snctl
is given a token to impersonate the user.
Output
This example shows how to sign in as a user account. In this way, snctl
is given a token to impersonate the user.
Output
This example shows how to sign in as a service account.
Download the credentials file of the service account.
Sign in as a service account.
Output
Notes:
Replace <service_account_name>
with the service account name you use.
Replace /path/to/service_account_credentials.json
with the right file path to save the credentials of the service account. Please make sure the credentials are saved in a safe location.
If your organization already has a valid subscription, you can skip this section.
Before you provision a cluster using snctl
, you need to set up a subscription to StreamNative Cloud. If you have a legacy cluster, submit a ticket to get assistance with moving your cluster to the updated subscription plan.
snctl create subscription
command is available for snctl
version 0.14.1
and above.snctl
does not support setting up a payment method. You can add a payment method for your organization through StreamNative Cloud Console. For details, see manage billing using StreamNative Cloud Console.You can use the snctl create subscription
command to create a subscription.
Notes:
--offer-type
: the offer type. Two options are available:
private
: the private offer that is made to a specific customer. It is a commitment to a minimum amount of spend over a specified time period.public
: the public offer that anyone may subscribe to through StreamNative or Marketplace channels. It is a Pay-As-You-Go subscription with usage-based pricing.--offer
: the offer name.
SN2_OD_HOSTED_CLOUD
) that snctl
uses by default.Output
You should see the following output if you create a public offer subscription:
You should see the following output if you create a private offer subscription:
This section describes how to provision Pulsar clusters through snctl.
In this section, the target organization name is already set in the .snctl/config
file. Therefore, you do not need to use the --organization <organization_name>
flag to specify the target organization every time when executing snctl
commands. For details about how to set snctl configurations, see set snctl configuration.
This section describes how to create a Dedicated cluster through snctl.
Create a Pulsar instance named neo
.
This example shows how to create the neo
instance on the AWS cloud platform. To create a Pulsar instance on Google Cloud, set the infrastructure pool name to streamnative/shared
. To create a BYOC instance/cluster, the StreamNative team needs to provision an infrastructure pool in your cloud account before you can use it.
Output
Find the available locations of a given infrastructure pool to deploy a Pulsar cluster.
This example shows how to find the available locations for the infrastructure pool streamnative/shared-aws
.
You can find the locations shown up in the spec.locations
section of the output.
Create a Pulsar cluster named neo-1
, consisting of 2 brokers, each using 0.5 CU, and 3 bookies, each using 0.5 SU, to be deployed in us-east-1
.
The following command is available for snctl
version 0.15.0
and above.
Output
You can use the snctl describe pulsarcluster <cluster_name>
command to get details of a Pulsar cluster.
This example gets details of the neo-1
cluster.
Output
From the outputs, you can see that the status
and type
parameters for items under Conditions
are set to true
and ready
respectively. This means that the neo-1
cluster is created successfully.
Starting from version v1.0.0
, snctl
introduces the concept of a Service Context. This feature aims to make snctl
a unified tool not only for managing StreamNative Cloud resources (like creating and managing clusters) but also for directly interacting with the data plane of your Pulsar clusters using both the native Pulsar protocol and the Kafka protocol (via KSN or Ursa Engine).
A Service Context is essentially a named configuration profile stored within your snctl
configuration (~/.snctl/config
). It bundles the necessary connection details —- primarily the service URL and authentication information —- required to connect to a specific Pulsar cluster managed by StreamNative Cloud.
Automatic Context Discovery
Typically, you don’t need to manually create contexts for your StreamNative Cloud Pulsar clusters. After successfully logging in using snctl auth login
, snctl
can often automatically detect the Pulsar clusters you have access to within your organization. It makes these clusters available as selectable contexts, usually using the instance name and cluster name as the context.
(Note: For managing contexts related to external, non-StreamNative Cloud clusters, see commands like snctl context add-external-context
, snctl context list-external-context
, etc.)
Switching and Using Contexts
To interact with a specific cluster using snctl pulsar
or snctl kafka
commands, you first need to activate its corresponding context.
Set the Active Context: Use the snctl context use
command, will likely prompt you to choose from a list of all available Pulsar Instances and Pulsar Clusters, select the target cluster by keyboard, and additional authentication may required if no valid token cached.
Non-interactive
Verify the Current Context: You can check which context is currently active using:
Output (Example)
Interacting with Pulsar and Kafka Protocols
Once a service context is active, all subsequent snctl pulsar client ...
, snctl pulsar admin ...
, snctl kafka client ...
, and snctl kafka admin ...
commands will automatically use the connection details (service URL, authentication) defined in that active context. You no longer need to specify connection flags repeatedly for these commands.
Running commands by using specific Service Account
While the active context usually derives its authentication from your user login (snctl auth login
), you can override this for individual command executions to run as a specific service account. This is useful for automation or when specific permissions granted to a service account are needed. Another use case is to submit Pulsar Functions, Pulsar IO Connectors, and Kafka Connect connectors in StreamNative Cloud, this will makes the submitted instances running under given permission by the service account.
Crucially, snctl
will verify if your currently logged-in user account has the necessary permissions to impersonate the chosen service account before executing the command.
Specify Service Account by Name: Use the --as-service-account
flag followed by the service account name. snctl
will use the credentials associated with this service account for the command.
Interactively Select Service Account: Use the --use-service-account
flag without specifying a name. snctl
will likely prompt you to choose from a list of available service accounts you have access to. This will shows you the details of each Service Account, as well as the status of each Service Account Binding, which is useful on manage Pulsar Functions, Pulsar IO Connectors, and Kafka Connect connectors.
Example Workflow:
Note on pulsarctl
Configuration:
This Service Context mechanism is internal to snctl
for unifying its own commands. It is distinct from the snctl x update-pulsar-config
command (described later). The update-pulsar-config
command is specifically designed to configure the separate pulsarctl
tool, allowing it to connect to your StreamNative Cloud cluster. The snctl context
commands enable snctl
itself to perform data plane operations directly via its pulsar
and kafka
subcommands.
This section describes how to add a cluster to the Pulsar client configuration file. After adding a cluster to the Pulsar client configuration file, you can manage the cluster using the pulsarctl
CLI tool. To get details about the access and managing Apache Pulsar resources through pulsarctl
, see pulsarctl
command reference.
It is recommended to use the pulsarctl context get
command to set the context (cluster) in advance.
Add a cluster to the Pulsar client configuration file.
This example adds a neo-1
cluster to the Pulsar client configuration file.
Input
Output
Verify that the current context has been changed.
Input
Output
After verifying that the change was made, you can use the pulsarctl
CLI tool to interact with the target cluster. For details, see the pulsarctl reference docs. To work with tenants, namespaces, and topics, you can use the StreamNative Cloud Console. snctl does not currently support working with these features.