snctl
) for both cloud infrastructure and Pulsar resource management/interaction. We will also show alternative methods using the traditional pulsarctl
and pulsar-client
tools.
This tutorial covers:
snctl
).snctl
).snctl
).snctl
).snctl
):
snctl
Service Context.snctl pulsar admin
.snctl pulsar admin
.snctl pulsar client
.pulsarctl
context using the API Key.pulsarctl
.pulsarctl
.pulsar-client
configured with the API Key.pulsar-client
alternative method.snctl-super-admin
. After creating the service account, download and save its OAuth2 credentials file (e.g., snctl-super-admin-credentials.json
).
Activate this service account for snctl
. This identity will be used for provisioning cloud resources (instances, clusters, other service accounts). Make sure to replace /path/to/snctl-super-admin-credentials.json
with the actual path.
snctl
to avoid specifying -n
or -O
repeatedly. Replace <your-org-id>
with your actual organization ID.
001-instance.yaml
with the following content:
<your-instance-name>
: The name of the Serverless Instance.<your-org-id>
: The organization ID.True
, the instance is ready.
002-cluster.yaml
with the following content:
us-central1
region. Replace the following placeholders with your actual values:
<your-instance-name>
: The name of the Serverless Instance.<your-org-id>
: The organization ID.<your-cluster-name>
in the output message because the cluster name of a Serverless Cluster is generated by StreamNative Cloud. You will need this cluster name in the future steps.True
, then the cluster is ready. A Serverless Cluster is usually ready within 1~2 minutes.
003-sa.yaml
with the following content:
<your-service-account-name>
. Replace the following placeholders with your actual values:
<your-service-account-name>
: The name of the Service Account.<your-org-id>
: The organization ID.Ready
condition is True
, then the service account is ready.
snctl
typically uses OAuth2 via auth activate-service-account
or context impersonation (--as-service-account
), you might need an API Key for external clients or tools that only support token authentication. This API key will be used in the alternative pulsarctl
and pulsar-client
method later.
Edit a file named 004-api-key.yaml
:
<your-service-account-name>
. Replace the following placeholders with your actual values:
<your-api-key-name>
: The name of the API Key.<your-service-account-name>
: The name of the Service Account.<your-instance-name>
: The name of the Serverless Instance.<your-org-id>
: The organization ID.Issued
condition is True
, then the API Key is issued and ready to use. You can obtain the token from the token
field in the status block.
You can use the following command to obtain the token and export it as an environment variable API_KEY_TOKEN
:
snctl
snctl
for configuring access, managing Pulsar resources, and interacting with the data plane.
snctl
Service Context for Pulsar Interactionsnctl
uses Service Contexts to manage connections to Pulsar/Kafka clusters. After creating a cluster, snctl
usually discovers it automatically. Let’s explicitly set the context for the cluster we created to ensure subsequent commands target it correctly.
Set the active context to your newly created cluster. Replace <your-instance-name>
and <your-cluster-name>
with the actual name from step 2.
snctl-super-admin
service account (in step 0), snctl
commands will run as that identity by default.
snctl
can communicate with the Pulsar cluster’s admin endpoint using the super-admin credentials via the active context.
snctl
sl-app
using snctl pulsar admin
commands. These commands will use the active context (<your-cluster-name>
) and run as the activated super-admin user (snctl-super-admin
).
First, create a tenant named sl-app-tenant
.
sl-app-ns
under the tenant sl-app-tenant
.
sl-app-topic
with 4 partitions under the namespace sl-app-tenant/sl-app-ns
.
<your-service-account-name>
(created in step 3) the permission to produce and consume messages within the sl-app-tenant/sl-app-ns
namespace. We are still running as snctl-super-admin
to grant these permissions. Replace <your-service-account-name>
with the name from step 3.
snctl pulsar client
snctl pulsar client
commands to produce and consume messages. Crucially, these actions should be performed as the application service account (<your-service-account-name>
) because we granted it the produce/consume permissions, not the super-admin. We use the --as-service-account
flag for this, leveraging snctl
’s ability to impersonate the specified service account (assuming the logged-in super-admin has permission to do so, which is typical).
Produce 10 messages to the topic, acting as the application service account. Replace <your-service-account-name>
with the name from step 3.
<your-service-account-name>
with the name from step 3.
snctl
for the entire lifecycle using the unified approach.
pulsarctl
and pulsar-client
(Alternative)pulsarctl
tool for admin tasks and the pulsar-client
tool for producing/consuming. This method often relies on API Key authentication for simplicity when interacting with StreamNative Cloud clusters via these tools.
pulsarctl
Context (Using API Key)ADMIN_SERVICE_URL
, you can use the following command to configure pulsarctl
to access the cluster we created in the previous steps:
<your-cluster-name>-admin
and update the pulsarctl
configuration to use the oauth2 credentials of snctl-super-admin
to authenticate to the cluster.
You should see the following message:
pulsarctl
has been configured properly by running the following command:
pulsarctl tenants list
to verify if you configured the pulsarctl
properly.
pulsarctl
sl-app
that produces messages to a topic persistent://sl-app-tenant/sl-app-ns/sl-app-topic
and consumes messages from the same topic.
First, create a tenant named sl-app-tenant
.
sl-app-ns
under the tenant sl-app-tenant
.
sl-app-topic
with 4 partitions under the namespace sl-app-tenant/sl-app-ns
.
<your-service-account-name>
the permission to produce and consume messages from the namespace sl-app-tenant/sl-app-ns
.
pulsar-client
/path/to/pulsar-dist
.
conf/client.conf
file:
webServiceUrl
to the ADMIN_SERVICE_URL
you obtained in the previous steps.brokerServiceUrl
to the BROKER_SERVICE_URL
you obtained in the previous steps.authPlugin
to org.apache.pulsar.client.impl.auth.AuthenticationToken
.authParams
to be token:<your-api-key>
. <your-api-key>
is the API Key you obtained in the previous steps.snctl delete -f 002-cluster.yaml
to delete the cluster because the cluster name is generated by StreamNative Cloud. So you need to delete the cluster using the snctl delete PulsarCluster <your-cluster-name>
command.