> ## Documentation Index
> Fetch the complete documentation index at: https://ventstream.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes deployment

> Choose standalone engine workloads or Fleet-managed engines, then follow the matching Kubernetes runbook.

VentStream has two distinct Kubernetes operating modes. Choose the mode before
creating workloads because a standalone engine cannot be attached to Fleet in
place.

| Mode          | Engine process                                               | Configuration owner                                 | Operations                          | Control plane    |
| ------------- | ------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------- | ---------------- |
| Standalone    | `ventstream` is PID 1                                        | ConfigMap and Secret                                | Helm/Kubernetes restart and rollout | None             |
| Cloud-managed | Fleet supervisor is PID 1 and starts `ventstream` as a child | Immutable Cloud revision plus workload-local Secret | Dashboard and `ventstreamctl`       | VentStream Cloud |

## Standalone

Use standalone mode when each workload should be entirely self-contained and
restart-based lifecycle control is sufficient.

* [Deploy a standalone engine](/docs/deploy/kubernetes-standalone)
* [Canonical engine configuration](/docs/reference/engine-env#canonical-engine-config)

The standalone guide provides a current canonical-config StatefulSet for CDC.
Use the `ventstream-gateway` chart for replicated native WebSocket and GraphQL
subscription roles.

## Cloud-managed

Use managed mode when operators need organization-scoped inventory, immutable
configuration, agent health, audit events, and CLI pause, resume, drain,
reconcile, or rebootstrap operations.

1. Create or join a [VentStream Cloud](https://ventstream.dev/signup)
   organization.
2. [Deploy a managed engine](/docs/deploy/kubernetes-managed-engine) into your
   Kubernetes cluster.
3. [Administer it with ventstreamctl](/docs/fleet/cli) or the dashboard.

VentStream Cloud never enters the CDC or realtime data path. Managed engines
connect outbound to the Cloud agent gateway over mTLS; source records, sink
writes, broker events, WebSocket connections, and GraphQL subscriptions remain
inside the workload environment.

## Common production requirements

* Pin container images by digest and promote the same digest between environments.
* Keep connector credentials and private keys in a managed secret provider.
* Persist source cursors, join state, Fleet identity, and applied configuration.
* Give every CDC pipeline its own replication slot or cursor and exactly one
  active engine instance.
* Run `helm lint` and `helm template` against production values in CI.
* Never delete managed-agent PVCs during routine upgrades.