Connections
Configure reusable Pulsar, Kafka, and generic endpoints for Orca Agent Engine on StreamNative Cloud.
A connection is a named endpoint and credential reference that StreamNative Cloud workloads use to reach Pulsar, Kafka, or another external system. Functions, sources, sinks, Kafka Connect connectors, and messaging triggers reference a connection by name.
This resource is a StreamNative Cloud capability served under /apis/cloud.sn.io/v1. A
self-hosted engine does not advertise the cloud.sn.io extension group. The ork CLI and
TypeScript SDK check GET /apis and report that the capability is unavailable before sending the
resource request.
Get your registry endpoint
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Connection configuration fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Workspace-unique name that workloads reference. |
spec.type | enum | Yes | pulsar, kafka, or other. |
spec.pulsar | object | For Pulsar | Broker/admin URLs, authentication references, and TLS settings. |
spec.kafka | object | For Kafka | Bootstrap servers, authentication references, and TLS stores. |
spec.kafka.schemaRegistry | object | No | Schema Registry URL and optional authConfig credential references. Kafka functions inherit this configuration. |
spec.other | object | For other | Endpoint, string properties, and one Secret reference. |
status | object | Read-only | Health phase, message, conditions, and last test time. |
internal | boolean | Read-only | Whether the Workspace manages the connection. |
clusterRef | string | Read-only | Cluster associated with the connection. |
Connection credentials are referenced from Kubernetes Secrets. Do not place passwords, tokens, or keystore contents directly in the connection object.
Create a Kafka connection
This example creates a connection with no authentication. Add the Kafka auth and TLS fields required by your cluster; the CLI reference lists every supported flag.
ork connections create \
--name events-kafka \
--type kafka \
--kafka-bootstrap-servers broker-1:9092,broker-2:9092 \
--kafka-auth-type none \
-o jsonValidate and test connections
Validate checks a configuration without storing it. Test probes a stored connection and returns its current health.
ork connections validate \
--name events-kafka \
--type kafka \
--kafka-bootstrap-servers broker-1:9092,broker-2:9092 \
--kafka-auth-type none
ork connections test events-kafka -o jsonManage connections
| Operation | CLI | TypeScript | REST |
|---|---|---|---|
| List | ork connections list | orca.cloud.connections.list() | GET /apis/cloud.sn.io/v1/connections |
| Retrieve | ork connections get <name> | .retrieve(name) | GET /apis/cloud.sn.io/v1/connections/{name} |
| Update | ork connections update --name <name> | .update(name, params) | PUT /apis/cloud.sn.io/v1/connections/{name} |
| Delete | ork connections delete <name> | .delete(name) | DELETE /apis/cloud.sn.io/v1/connections/{name} |
The raw PUT and SDK update replace the stored connection body. Send the complete configuration
you want to retain. The CLI first reads the connection, applies the flags you changed, and sends the
result back.
Permissions
Treat every credential that can call the Workspace's cloud.sn.io routes as full access to its
connections, and separate access with Workspaces. See
Control registry access.