Skip to main content
A managed engine is the same public binary or image everyone runs. What makes it managed is an agent key: a deployment-scoped secret with the vsa1. prefix that the engine presents on first connect. The gateway converts that first connect into a deployment-bound X.509 workload identity; later connects use the bound mTLS identity, and the engine renews certificates before expiry. An engine started without an agent key makes provably zero platform connections.

​
Mint a key

Mint one key per deployment, from the dashboard’s deployment guide or the CLI:
The key is shown once, is revocable, and is reusable across restarts of the same deployment. Minting a new key revokes the previous one, so rotation is a single key create. The dashboard shows key metadata (never the secret again) in the deployment’s Agent keys panel.
Do not place the key in a configuration revision, shell history, log, image, or GitOps file. Pipe it directly into your secret store, for example ventstreamctl agents key create ... | kubectl create secret generic <name> --from-file=key=/dev/stdin.

​
Give the key to the engine

Provide the key through the VS_AGENT_KEY environment variable, or through a managed: block in ventstream.yaml:
A managed engine takes its source, sink, and spec configuration from the pipeline’s selected configuration revision. An agent key alongside local source, sink, or specs sections is a hard startup error — an engine is either managed or standalone, never both.

​
What the handshake does

  1. On first connect the engine generates a keypair locally. The private key never leaves the workload environment.
  2. The engine presents the agent key to the enrollment endpoint over verified server TLS. Cloud gateways use public WebPKI trust by default.
  3. The gateway binds the new public key to the key’s deployment and issues a deployment-bound X.509 identity.
  4. The engine persists identity and management state in its managed state directory and opens the outbound mTLS control stream.
Restarts skip the handshake: the engine reconnects with its persisted identity. If the state volume is lost, the same key simply re-binds a fresh identity on the next start; the rotation is recorded as an audited identity event in the dashboard.

​
Failure semantics

  • Key revoked, or gateway unreachable at startup: the engine exits nonzero. It never falls back to local configuration.
  • First boot fails closed: without a trusted desired-state snapshot the engine does not start CDC.
  • Transient control-plane outage: an engine that already holds trusted running state keeps processing; management downtime does not interrupt the data path.
  • Identity revoked (ventstreamctl agents identity revoke): reconnects with the old identity are rejected. The next start re-binds through the deployment’s agent key — revoke the key as well to keep the deployment offline.
CDC deployments remain singleton: one active identity per deployment, fenced by the gateway. Replicated realtime instances each need their own deployment and key.

​
Legacy: enrollment tokens

Before agent keys, bootstrap used a one-time enrollment grant (vse1. prefix) created with ventstreamctl agents enroll-token create, delivered via VS_FLEET_ENROLLMENT_TOKEN_PATH, and redeemed by a dedicated enroll init container in the chart, with rendered values from ventstreamctl agents manifest. Grants expire after ten minutes and are invalidated on redemption. Token-enrolled deployments keep working through the deprecation window, and their persisted identities remain valid. To migrate, mint an agent key for the deployment, replace the enrollment Secret with the key Secret, and switch the release to the public image in one upgrade — see Migrating from enrollment tokens.