WorkspaceSpec reference

Field reference for the StreamNative Cloud Workspace custom resource that hosts Orca Agent Engine and publishes its registry endpoint.

A Workspace is the StreamNative Cloud resource bound to a registry Workspace in Orca Agent Engine. The Workspace custom resource lives in the compute.streamnative.io/v1alpha1 API group. Its annotations select product surfaces; its spec records placement and Functions Worker configuration; its status includes client endpoints and conditions.

Spec fields

The spec block describes the desired state of the Workspace. Fields marked Required must be present at create time; optional fields can be omitted and accept the controller defaults.

Field	Type	Required	Description
`instanceName`	`string`	No (required for Instance-based Workspaces)	References a sibling `Instance` resource in the same namespace. Leave empty only for legacy Flink-only Workspaces.
`clusterRefs`	`[]ClusterRef`	No	Lists the clusters this Workspace can access. Each entry has `name`, `type` (`pulsar` or `kafka`), and optional `instanceName`. Reference names must be unique within the Workspace, even across types. Replaces the deprecated `pulsarClusterNames`.
`pulsarClusterNames`	`[]string`	No (deprecated)	Legacy list of Pulsar cluster names. Use `clusterRefs` with `type=pulsar` for new Workspaces.
`poolRef`	`PoolRef`	Yes (Flink Workspaces)	References the pool that hosts the Workspace. For Instance-based Workspaces, the controller infers this from the parent `Instance` at admission time.
`poolMemberRef`	`PoolMemberReference`	No	Targets the PoolMember where the Functions Worker and Connection CRs are deployed.
`agentPoolMemberRef`	`PoolMemberReference`	No	Targets the managed-agents PoolMember used for Orca Registry onboarding. Admission can select it when the `agents` surface is enabled at creation. Updates do not backfill it.
`location`	`string`	No	Deployment region or zone. When set, the admission controller uses this value as a scheduling constraint when it picks a `PoolMember`.
`description`	`string`	No	Free-form description of the Workspace for humans.
`image`	`string`	No	Container image override for the functions worker. Leave empty to use the platform default.
`runnerImages`	`RunnerImages`	No	Function runner images for the functions worker (Java, Python, Go). Overrides the platform default runner set.
`customWorkerConfig`	`string`	No	Raw YAML/JSON string merged into the functions worker configuration. Use only for advanced overrides; settings here are not validated by the admission controller.
`enableAgent`	`*bool`	No	Enables generic agent support on the functions worker. Default `false`.
`enableKafkaConnect`	`*bool`	No	Enables Kafka Connect support on the functions worker. Default `false`.
`enablePackages`	`*bool`	No	Enables Pulsar Package Management on the functions worker. Default `false`.
`enableState`	`*bool`	No	Enables shared state storage for Workspace components, including Agent Functions and Pulsar Functions. Default `false`.
`enableUnifiedRBAC`	`*bool`	No	Enables unified RBAC state storage for the Workspace. Default `false`.
`flink`	`FlinkWorkspaceConfig`	No	Flink-specific settings. Contains `useExternalAccess` and `blobStorage`. Replaces the top-level `flinkBlobStorage` and `useExternalAccess` fields.
`flinkBlobStorage`	`FlinkBlobStorage`	No (deprecated)	Legacy Flink blob storage configuration. Use `flink.blobStorage` instead.
`useExternalAccess`	`*bool`	No (deprecated)	Legacy external-access flag. Use `flink.useExternalAccess` instead.

ClusterRef

ClusterRef declares a cluster the Workspace can reach. Each Workspace can list any number of pulsar and kafka clusters in its clusterRefs.

Field	Type	Required	Description
`name`	`string`	Yes	Cluster name. Must be unique within the Workspace, even across types.
`type`	`string`	Yes	`pulsar` or `kafka`.
`instanceName`	`string`	No	Name of the `Instance` that owns the cluster. Defaults to `WorkspaceSpec.instanceName`.

RunnerImages

RunnerImages overrides the function runner images. Set only the runtimes you need; unset runtimes inherit the platform default.

Field	Type	Description
`java`	`string`	Override for the Java function runner image.
`python`	`string`	Override for the Python function runner image.
`go`	`string`	Override for the Go function runner image.

FlinkWorkspaceConfig

Field	Type	Description
`useExternalAccess`	`*bool`	Exposes Flink endpoints to the public internet when `true`.
`blobStorage`	`FlinkBlobStorage`	Blob storage configuration for Flink checkpoints and savepoints.

Product surfaces

The cloud.streamnative.io/workspace-surfaces annotation selects compute, agents, or compute,agents. If absent, the API retains legacy behavior and enables both surfaces. The agents surface requires the agent-engine feature gate.

Status fields

The status block reflects the observed state maintained by the Workspace controller. Clients read status to discover whether the Workspace is ready and where to send Orca Registry API calls.

Field	Type	Description
`conditions`	`[]Condition`	Current observed conditions. Inspect the `Ready` condition's `status` and `reason` to confirm provisioning completed.
`observedGeneration`	`int64`	The `metadata.generation` value the controller last reconciled. When `observedGeneration` lags `metadata.generation`, the controller is still applying recent spec changes.
`serviceEndpoints`	`[]ServiceEndpoint`	Functions Worker client endpoints copied into Workspace status. See Service endpoints.

Condition

Condition follows the standard StreamNative Cloud condition shape: type, status (True / False / Unknown), reason, message, and lastTransitionTime. The controller publishes a Ready condition you can poll to wait for provisioning.

Service endpoints

status.serviceEndpoints[] is how the Cloud CLI discovers a Workspace client host. The Workspace controller copies these endpoints from Functions Worker status and can publish an external hostname from the worker spec before data-plane status is available.

ServiceEndpoint defines a Workspace client endpoint.

Each entry has the following shape:

Field	Type	Description
`type`	`string`	`internal` or `external`. Use the external endpoint from outside the Kubernetes cluster.
`dnsName`	`string`	DNS name or `host:port`. The internal endpoint may use a different scheme; Cloud CLI normalizes its selected host.

Example status block

status:
  observedGeneration: 3
  conditions:
    - type: Ready
      status: "True"
      reason: Provisioned
      lastTransitionTime: "2026-05-10T12:34:56Z"
  serviceEndpoints:
    - type: internal
      dnsName: workspace-internal.svc.cluster.local:6750
    - type: external
      dnsName: workspace.example.streamnative.cloud

Read the registry endpoint from the status

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.