Skip to main content
This guide walks you through preparing an environment that can deploy Orca Agents on StreamNative Cloud. You will create a dedicated service account, assign the minimum required permissions, and configure tooling for both the CLI and the StreamNative Cloud Console.

​
Prerequisites

​
Create a service account for agents

  1. In StreamNative Cloud Console, open the left navigation and choose Service Accounts.
  2. Click Create Service Account.
  3. Provide a name and optional description, then click Confirm.
Leave Super Admin unchecked so the account only receives the scoped permissions you grant later.

​
Authorize the service account

To make the service account work, you need to make the service account granted with proper permissions (functions, packages, produce, and consume). To grant the service account permissions on the namespace level, follow these steps:
  • Cloud Console
  1. Navigate to the Namespace Dashboard page by switching to the namespace workspace.
  2. On the Namespace Dashboard page, click Configuration on the left navigation pane.
  3. On the Namespace configuration page, click ADD ROLE, and select the service account that you want to authorize.
  4. On the drop-down menu below the service account, select the proper permissions to assign to the service account. There are six permissions in total:
  • consume: allow the service account to consume messages.
  • produce: allow the service account to publish messages.
  • functions: allow the service account to submit and manage functions.
  • sinks: allow the service account to create and manage sink connectors.
  • sources: allow the service account to create and manage source connectors.
  • packages: allow the service account to upload and manage pulsar packages. If you want to submit a customized function/connector, then you will need to upload the function/connector’s JAR/NAR/Python file first, which requires the packages permission. Authorize Service Account

​
Grant access to the service account

To grant the underlying infrastructure with access to the newly created service account’s OAuth2 key file, you need to create a service account binding via UI. Go to the Service Accounts tab and choose the service account you want to use for running the connector. Clicking on the right button and there willbe a Edit service account bindings option. Binding Service Account step-1 Click the Edit service account bindings, choose the desired pool member and confirm. Binding Service Account step-2 Now your connector is ready to use the service account in StreamNative environments.

​
(Optional) Create a separate IAM role for the service account

StreamNative’s I/O components (Pulsar Functions, Pulsar Connectors, and Kafka Connectors) run as cloud-native workloads on AWS, GCP, and Azure infrastructures. You can use the cloud providers’ native IAM (Identity and Access Management) services to control access to infrastructure resources such as S3, GCS, and Azure Blob Storage. This removes the need for password-based authentication for the service accounts that run connectors in StreamNative Cloud. By default, StreamNative uses a single service account per PulsarCluster for all I/O components (Pulsar Functions, Pulsar Connectors, and Kafka Connectors) to access underlying infrastructure resources. This means all I/O Components in the same cluster share one service account and the same permissions.
Using a single service account for all I/O components means all functions and connectors share the same permissions. If one component is compromised, it could access resources intended for other components.So it’s better to leave the default service account with no permissions and use it for running IO components that do not require access to external resources.And create separate service accounts with the minimum required permissions for each IO component that need to access external resources.
To enhance security and improve isolation, you can create a separate IAM role for each service account used to run connectors. This lets you grant only the permissions each service account needs. Create a separate IAM role for your service account:
This feature is available in snctl v1.3.0 or later.Support in Console will be added soon.
  1. Get the PoolMember name and namespace from the PulsarCluster 
    snctl get pulsarcluster <cluster-id> -o yaml
    In the output, find the poolMemberRef block, which looks like: 
    poolMemberRef:
  name: <pool-member-name>
  namespace: <namespace>
    Multiple clusters may be located in the same PoolMember. You do not need to create separate IAM roles for each cluster within the same PoolMember.
  2. Create a new ServiceAccountBinding that binds the service account to the PoolMember 
    snctl create serviceaccountbinding <binding-name> \
  --pool-member <pool-member-namespace>/<pool-member-name> \
  --enable-iam-account-creation \
  --service-account-name <service-account-name>
    AWS only: You can specify one or more AWS IAM role ARNs that can be assumed by the IAM role created for the service account (repeat the flag for each ARN): 
    snctl create serviceaccountbinding <binding-name> \
  --pool-member <pool-member-namespace>/<pool-member-name> \
  --enable-iam-account-creation \
  --service-account-name <service-account-name> \
  --aws-assume-role-arns <arn1> \
  --aws-assume-role-arns <arn2>
    The IAM role created by StreamNative will include permissions to call sts:AssumeRole on arn1 and arn2. You must still add a trust policy on arn1 and arn2 to allow the newly created role to assume them.
  3. (Optional) Update an existing ServiceAccountBinding to create the IAM role 
    snctl update serviceaccountbinding <binding-name> \
  --enable-iam-account-creation \
  --service-account-name <service-account-name> \
  --pool-member <pool-member-namespace>/<pool-member-name> \
  --aws-assume-role-arns <arn1> \
  --aws-assume-role-arns <arn2>
  4. Verify the IAM role was created successfully 
    snctl get serviceaccountbinding <binding-name> -o yaml
    Expected output (example): 
    apiVersion: cloud.streamnative.io/v1alpha1
kind: ServiceAccountBinding
metadata:
  creationTimestamp: "2025-06-25T08:45:35Z"
  finalizers:
  - serviceaccountbinding.finalizers.cloud.streamnative.io
  generation: 1
  name: test-admin
  namespace: o-lftqu
  ownerReferences:
  - apiVersion: cloud.streamnative.io/v1alpha1
    kind: ServiceAccount
    name: admin
    uid: 4ef639aa-6278-4863-9a23-f1da50cea448
  resourceVersion: "54707713"
  uid: 918d40ad-551d-416b-a2ae-d41548d6608e
spec:
  enableIamRoleCreation: true
  poolMemberRef:
    name: azure-eastus-zephyr
    namespace: streamnative
  serviceAccountName: admin
status:
  conditions:
  - lastTransitionTime: "2025-06-25T08:45:35Z"
    status: "True"
    type: IAMAccountReady
  - lastTransitionTime: "2025-06-25T08:45:35Z"
    status: "True"
    type: ServiceAccountReady
  - lastTransitionTime: "2025-07-16T13:56:17Z"
    status: "True"
    type: ResourceExists
  - lastTransitionTime: "2025-07-16T13:56:17Z"
    status: "True"
    type: PoolMemberReady
  - lastTransitionTime: "2025-07-16T13:56:17Z"
    reason: AllConditionStatusTrue
    status: "True"
    type: Ready
    In the output, the status.conditions array should include a condition with type: IAMAccountReady and status: "True", indicating the IAM role was created successfully.
    In Azure, a Managed Identity sab-[binding-name]-[org-id] is created;In AWS, an IAM role role/StreamNative/sncloud-role/authorization.streamnative.io/iamaccounts/IamAccount-[org-id]-sab-[binding-name] is created;In GCP, a service account with display name: IamAccount/[org-id]/sab-[binding-name] is created.
  5. Use the service account when creating I/O components

    You can now select this service account in Console (or use its API key with the CLI) when creating I/O components (Pulsar Functions, Pulsar Connectors, and Kafka Connectors). The components will inherit the permissions granted to the IAM role created in the previous step.

​
Set up client tools

​
Use snctl to manage agents

StreamNative CLI (snctl) provides agent-aware commands that are surfaced under snctl agents.
  1. Set your organization: snctl config set --organization <org-name>.
  2. Select a cluster context: snctl context use and choose the target cluster.
  3. Work with agents by using the following commands (pass --tenant and --namespace as needed):
    • snctl agents list – list agents in the current namespace.
    • snctl agents create – deploy a new agent from a declarative spec and package.
    • snctl agents update – roll out spec or code changes.
    • snctl agents status – view runtime status.
    • snctl agents start|stop|restart – control the running agent.
    • snctl agents delete – remove an agent.
    • snctl agents get – show the stored agent spec.
    • snctl agents trigger – deliver an ad-hoc test event when supported by the agent implementation.

​
Use StreamNative Cloud Console

The StreamNative Cloud Console offers a guided experience for connecting client applications and reviewing agent activity. Navigate to Agents from the left panel to review existing deployments, logs, and status.

​
What’s next?

  • Review the Orca Agents overview to understand runtime architecture and capabilities.
  • Package your first agent and deploy it with snctl or the Cloud Console.