snctl CLI reference
snctl is a Command Line Interface (CLI) tool for StreamNative Cloud. This topic includes a list of available releases, as well as how to install, configure, and log in to snctl.
Available releases
The following table lists the available releases of snctl.
Version | Reference |
---|---|
latest | Command reference |
0.14.1 | Command reference |
0.13.1 | Command reference |
0.12.1 | Command reference |
0.11.1 | Command reference |
0.10.1 | Command reference |
0.9.0 | Command reference |
0.8.0 | Command reference |
0.6.0 | Command reference |
0.5.0 | Command reference |
Install snctl
This section describes how to install snctl on Linux, MAC, and Windows Operating System (OS).
Install snctl on Linux OS
You can use the curl command or use Homebrew to install snctl on Linux.
Install snctl with curl command
Execute the following command to download and install the latest snctl.
bash -c "$(curl -fsSL https://storage.googleapis.com/downloads.streamnative.cloud/snctl/install.sh)"
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 snctlv0.5.0
.bash -c "$(curl -fsSL https://storage.googleapis.com/downloads.streamnative.cloud/snctl/install.sh) -v v0.5.0"
Check whether snctl is installed successfully.
snctl version --client
Install snctl with Homebrew
Add the repository.
brew tap streamnative/streamnative
Install snctl.
brew install snctl
Install snctl on Mac OS
You can use the curl command or use Homebrew to install snctl on a Mac.
Install snctl with curl command
Execute the following command to download and install the latest snctl.
bash -c "$(curl -fsSL https://storage.googleapis.com/downloads.streamnative.cloud/snctl/install.sh)"
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 snctlv0.5.0
.bash -c "$(curl -fsSL https://storage.googleapis.com/downloads.streamnative.cloud/snctl/install.sh) -v v0.5.0"
Check whether snctl is installed successfully.
snctl version --client
Install snctl with Homebrew
Add the repository.
brew tap streamnative/streamnative
Install snctl.
brew install snctl
Install snctl on Windows OS
Download the latest release package.
curl https://storage.googleapis.com/downloads.streamnative.cloud/snctl/v0.12.1/snctl_0.12.1_windows_amd64.zip -o-output <your_file_name>
Extract the snctl
.zip
package using Windows Explorer. For details, see the instructions.(Optional) Copy the
snctl.exe
binary to a directory on yourPATH
.Check whether snctl is installed successfully.
snctl version --client
Configure snctl
This section describes how to configure snctl.
Initialize snctl configuration
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.
Set snctl configuration
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.
Note
With the namespace
option, you need to use the random string for the organization name, not the descriptive name. You can find the random string on the Dashboard, next to the organization's descriptive name. For an example, see organizations.
snctl config set --namespace <organization_name>
Log in to snctl as a specific user or service account
You can log in to snctl as a specific user or as a service account (admin). Compared with the user, the service account has the admin role and can grant permissions to Pulsar resources.
Log in to snctl as a user
This example shows how to log in to snctl as a user. In this way, snctl is given a token to impersonate the user.
snctl auth login
Output
Logged in as [email protected].
Welcome to StreamNative Cloud!
Log in to snctl as a service account
This example shows how to log in to snctl as a service account.
Download the credentials file of the service account.
snctl auth export-service-account <service_account_name> --key-file <service_account_name>.json
Log in to snctl as a service account.
snctl auth activate-service-account <service_account_name> --key-file <service_account_name>.json
Output
Logged in as [email protected]. Welcome to StreamNative Cloud!
Subscribe to StreamNative Cloud
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.
Note
- The
snctl create subscription
command is available forsnctl
version 0.14.1 and above. - Ensure to add a payment method if you have not done so already.
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.
snctl create subscription <subscription_name> -n <organization_name> --offer-type <type_of_offer> --offer <offer_name>
--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.- For a public offer, there is a well-known name (
SN2_OD_HOSTED_CLOUD
) thatsnctl
uses by default. - For a private offer, you will get the offer name from StreamNative sales.
- For a public offer, there is a well-known name (
Output
You should see the following output if you create a public offer subscription:
Preparing the subscription, please wait... Subscription has been activated.
You should see the following output if you create a private offer subscription:
Preparing the subscription, please wait... To activate your subscription, please pay the initial invoice. Open the following URL: https://stripe.com/... Subscription has been activated.
Use snctl to provision a Pulsar cluster
This section describes how to provision Pulsar clusters through snctl.
Note
In this section, the target organization name is already set in the .snctl/config
file. Therefore, you do not need to use the --namespace <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.
Create a Pulsar cluster
This section describes how to create a Pulsar 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 tostreamnative/shared
.snctl create pulsarinstance neo --pool streamnative/shared-aws
Output
pulsarinstance.cloud.streamnative.io/neo created
Create a Pulsar cluster named
neo-1
, which usestiny-1
node type and is deployed inus-east-1
.snctl create pulsarcluster neo-1 --instance-name neo --node-type tiny-1 --location us-east-1
Output
pulsarcluster.cloud.streamnative.io/neo-1 created
Get the details of a Pulsar cluster
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.
snctl describe pulsarcluster neo-1
Output
Cluster neo-1
Name: neo-1
Namespace: matrix
Labels: <none>
Annotations: <none>
API Version: cloud.streamnative.io/v1alpha1
Kind: PulsarCluster
Metadata:
Creation Timestamp: 2021-01-25T14:48:27Z
Finalizers:
pulsarcluster.finalizers.cloud.streamnative.io
Generation: 2
Managed Fields:
API Version: cloud.streamnative.io/v1alpha1
Fields Type: FieldsV1
fieldsV1:
f:spec:
f:bookkeeper:
.:
f:replicas:
f:resourceSpec:
f:broker:
f:resourceSpec:
.:
f:nodeType:
f:instanceName:
f:location:
Manager: snctl
Operation: Update
Time: 2021-01-25T14:48:27Z
API Version: cloud.streamnative.io/v1alpha1
Fields Type: FieldsV1
fieldsV1:
f:spec:
f:broker:
f:replicas:
Manager: kubectl
Operation: Update
Time: 2021-01-29T09:51:58Z
API Version: cloud.streamnative.io/v1alpha1
Fields Type: FieldsV1
fieldsV1:
f:metadata:
f:finalizers:
.:
v:"pulsarcluster.finalizers.cloud.streamnative.io":
f:status:
f:conditions:
.:
k:{"type":"BookKeeperReady"}:
.:
f:lastTransitionTime:
f:status:
f:type:
k:{"type":"PulsarBrokerReady"}:
.:
f:lastTransitionTime:
f:reason:
f:status:
f:type:
k:{"type":"PulsarProxyReady"}:
.:
f:lastTransitionTime:
f:reason:
f:status:
f:type:
k:{"type":"Ready"}:
.:
f:lastTransitionTime:
f:reason:
f:status:
f:type:
k:{"type":"ZookeeperReady"}:
.:
f:lastTransitionTime:
f:status:
f:type:
Manager: controller-manager
Operation: Update
Time: 2021-02-05T03:16:49Z
Resource Version: 18740114
Self Link: /apis/cloud.streamnative.io/v1alpha1/namespaces/matrix/pulsarclusters/neo-1
UID: 774c4774-47c7-4913-b9b7-58c47c2f5e43
Spec:
Book Keeper Set Ref:
Name: shared-aws-us-east-1
Namespace: streamnative
Broker:
Image: 598203581484.dkr.ecr.us-east-2.amazonaws.com/streamnative/pulsar-cloud:2.7.0.4
Replicas: 1
Resource Spec:
Node Type: tiny-1
Instance Name: neo
Location: us-east-1
Pool Member Ref:
Name: aws-us-east-1
Namespace: streamnative
Service Endpoints:
Dns Name: neo-1.matrix.aws-us-east-1.streamnative.aws.snio.cloud
Zoo Keeper Set Ref:
Name: shared-aws-us-east-1
Namespace: streamnative
Status:
Conditions:
Last Transition Time: 2021-02-05T03:16:49Z
Status: True
Type: ZookeeperReady
Last Transition Time: 2021-02-05T03:00:11Z
Status: True
Type: BookKeeperReady
Last Transition Time: 2021-02-05T02:33:29Z
Reason: Deploy
Status: True
Type: PulsarBrokerReady
Last Transition Time: 2021-01-25T14:54:28Z
Reason: Deploy
Status: True
Type: PulsarProxyReady
Last Transition Time: 2021-02-05T03:16:49Z
Reason: AllConditionStatusTrue
Status: True
Type: Ready
Events: <none>
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.
Add clusters to the Pulsar configuration file
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. For details about how to manage Pulsar resources through pulsarctl
, see pulsarctl
command reference.
Note
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
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
After verifying that the change was made, you can use the pulsarctl
CLI tool to interact with the target cluster. For details, see Connect to cluster through pulsarctl. To work with tenants, namespaces, and topics, you can use the StreamNative Cloud Console. snctl does not currently support working with these features.