Skip to content

Operate

Bring your own cloud (BYOC) cells

Tested with:zb CLI · API 1.0.0 (cells, enrolment tokens) · Enterprise

A BYOC cell is a Kubernetes cluster in your own cloud account that runs your organization’s databases. A dedicated cell is the same thing in an account Databasezy operates for you alone. Both are Enterprise placements (byoc, dedicated-cell): instances created with them are scheduled only onto your organization’s own cells, and only onto cells in the residency you pin.

The cell agent connects out to the control plane over mutual TLS and pulls signed desired state. Nothing connects in: Databasezy never holds a kubeconfig, a cloud credential or the cell’s private key, and the agent refuses anything outside its boundary (platform workloads, cluster-wide RBAC, credentials that look like a control-plane or cloud key).

ActionNeeds
Mint an enrolment tokenEnterprise plan, org:manage (owner or admin, or an API key with org:manage), and a second factor completed in the last 15 minutes
Revoke an enrolment tokenorg:manage
List the organization’s cellsAny member (org:read)

A Team or lower plan gets 402 plan_limit; a member without org:manage gets 403 forbidden; a stale or missing second factor gets 403 mfa_required (sign in again with MFA, then retry).

  1. Mint a one-time enrolment token for the residency the cell will declare (a lower-case region or jurisdiction code such as eu-de). Instances placed on this cell are pinned to that residency.

    Terminal window
    zb cell enrolment-token create --placement byoc --residency eu-de

    The token is written to a new file, <cell id>.token, created with mode 0600 (choose the path with --out; an existing file is never overwritten). The command prints the token id (cet_...), when it expires, and the exact zb cell bootstrap command to run next. Options: --engines postgres,valkey limits the engines the cell will run; --ttl 4h sets the validity (1 minute to 24 hours, default 1 hour).

    The token is shown once. Databasezy stores only its hash; audit entries and security events carry the token id and a short fingerprint (zbe_... plus four hex characters), never the value. If you lose it, revoke it and mint a new one.

  2. Move the token to the account that owns the cluster (or run the next step on the same machine). To avoid a file altogether, pipe it:

    Terminal window
    zb cell enrolment-token create --residency eu-de --stdout \
    | zb cell bootstrap --enrol-url <enrol url> --residency eu-de --token-stdin
  3. Bootstrap the cluster with kubectl and helm pointed at it:

    Terminal window
    zb cell bootstrap --enrol-url <enrol url> --residency eu-de --token-file <cell id>.token

    A key pair is generated on this machine and never leaves your account. The token and a certificate signing request are exchanged, over one outbound HTTPS call, for the cell’s client certificate; the certificate is written to the cluster as the Secret the zb-cell-agent chart mounts, and the agent is installed with Helm. Use --output <dir> to write the manifests for review instead of applying them, or --no-helm to print the Helm command.

  4. Delete the token file. The token is single-use: once the cell is enrolled it cannot enrol another cluster.

  5. Check the cell once the agent reports in:

    Terminal window
    zb cell list

    Each cell shows its placement, residency, enrolment time, whether the agent is connected and when it was last seen, and how many instances it runs. Credentials, kubeconfigs and certificates are never part of this list.

A token that was never used stays valid until it expires. Revoke it as soon as you know it will not be used:

Terminal window
zb cell enrolment-token revoke cet_01J...

Revoking is idempotent: revoking a token twice, or one that was already used, succeeds and changes nothing. A token id that is not your organization’s is 404.

RouteWhat it does
POST /v1/orgs/{org_id}/cells/enrolment-tokensBody {"placement": "byoc", "residency": "eu-de", "engines": ["postgres"], "ttl_seconds": 3600}. 201 with id, token (only here, only once), token_fingerprint, cell_id, expires_at, enrol_url and bootstrap_command. Do not send Idempotency-Key: it is refused (400) because a replayed response could not carry the token again.
DELETE /v1/orgs/{org_id}/cells/enrolment-tokens/{token_id}Revoke; 204, also when already revoked or used.
GET /v1/orgs/{org_id}/cellsYour organization’s cells: placement, residency, region, engines, enrolled_at, agent_connected, agent_last_seen_at, cordoned, instance_count.

Every mint and revoke is in the organization’s audit log (cell.enrolment_token.create, cell.enrolment_token.revoke) and emits a security event (cell.enrolment_token_issued, cell.enrolment_token_revoked) that your SIEM export receives.

Create an instance with placement: byoc (or dedicated-cell). It is scheduled only onto your own cells of that placement and pinned to their residency; it is never moved to the shared fleet. Branches, copies, restores into a new instance and cell migrations keep the same residency, and an instance that cannot be placed in it fails with residency-unavailable rather than being placed elsewhere. If every one of your cells is cordoned or full, the request waits for capacity on them.

  • Choosing the residency per instance: the create request has no residency field yet, so an organization with cells in several residencies sees the instance fail with residency-unavailable naming them. Until it lands, keep one residency per placement or ask your account team.
  • Backups of BYOC instances go to the Databasezy backup store; a backup store in your own account is planned.
  • Renewing an enrolled cell’s certificate takes a new token bound to that cell, which your account team issues (a token minted here always enrols a new cell). There is deliberately no automatic renewal the control plane could use without you.