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).
Who can do this
Section titled “Who can do this”| Action | Needs |
|---|---|
| Mint an enrolment token | Enterprise 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 token | org:manage |
| List the organization’s cells | Any 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).
Enrol a cell
Section titled “Enrol a cell”-
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-deThe token is written to a new file,
<cell id>.token, created with mode0600(choose the path with--out; an existing file is never overwritten). The command prints the token id (cet_...), when it expires, and the exactzb cell bootstrapcommand to run next. Options:--engines postgres,valkeylimits the engines the cell will run;--ttl 4hsets 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. -
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 -
Bootstrap the cluster with
kubectlandhelmpointed at it:Terminal window zb cell bootstrap --enrol-url <enrol url> --residency eu-de --token-file <cell id>.tokenA 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-agentchart mounts, and the agent is installed with Helm. Use--output <dir>to write the manifests for review instead of applying them, or--no-helmto print the Helm command. -
Delete the token file. The token is single-use: once the cell is enrolled it cannot enrol another cluster.
-
Check the cell once the agent reports in:
Terminal window zb cell listEach 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.
Revoke a token you no longer need
Section titled “Revoke a token you no longer need”A token that was never used stays valid until it expires. Revoke it as soon as you know it will not be used:
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.
Using the API directly
Section titled “Using the API directly”| Route | What it does |
|---|---|
POST /v1/orgs/{org_id}/cells/enrolment-tokens | Body {"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}/cells | Your 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.
Placing instances on the cell
Section titled “Placing instances on the cell”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.
What is not built yet
Section titled “What is not built yet”- Choosing the residency per instance: the create request has no
residencyfield yet, so an organization with cells in several residencies sees the instance fail withresidency-unavailablenaming 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.