The desired state for this engine VM (db-agent).
curl --request GET \ --url https://stratum.example.com/v1/db-agent/desired \ --header 'Authorization: Bearer <token>'Read by db-agent every 5 s with the VM’s instance-profile
credentials. The control plane resolves which database instance the
calling VM belongs to from the VM itself (the stratum.dev/asg tag of
the group that launched it); a caller that is not an engine VM, or asks
for anything but its own instance, is refused with 403 NOT_OWN_INSTANCE. The document carries everything the agent converges
toward — the engine role and version, the data volume, the rendered
parameters and their generation, the master credential and any pending
operation. It is served only over this own-instance path and never
logged. Cedar-gated on db:AgentDesired.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”The desired document.
What the engine VM should converge toward. Served only to the VM it describes.
object
The calling VM’s compute instance id.
Bumps on every change to this document; the agent echoes the generation it applied.
The data volume attached as the second disk; the agent finds it by its serial (the volume id), formats it once and mounts it at /var/lib/db/data.
The rendered parameter group — name → value.
object
The secret version the master role must hold: the secret’s CURRENT, or the PENDING a rotation staged (then apply_master_password is pending). The agent reads it from the customer’s Secrets Manager with its own credentials under the resource policy the service keeps on the secret; the value never rides this document. Null until the secret has a value.
object
Client networks pg_hba.conf accepts with SCRAM — the customer VPC once the endpoint port is attached, and the backend network.
The endpoint certificate — a leaf from the cluster CA with the endpoint name and VIP as SANs, and the CA bundle. The agent applies it when its on-disk certificate is absent, signed by another CA, missing a SAN, or expiring; a fresh leaf is issued per document, so the agent must not reload on every fetch.
object
The guest’s second interface — the endpoint port in the customer’s subnet (as amended). The agent brings it up without a default route. Null until the port is attached.
object
Continuous archiving: the agent renders archive_mode=on with an archive_command that spools every segment on the data volume; the agent daemon ships the spool to this bucket through presigned URLs from POST /v1/db-agent/wal/presign. Null = archive off.
object
Archive_timeout — a segment ships at least this often.
The snapshot whose backup the engine must hold: phase start = run pg_backup_start and keep the session open, report started; phase stop = run pg_backup_stop in that session, put the backup label and the start..stop WAL range under snapshots/stopped. Null = no backup wanted.
object
On a restored instance: replay before serving — the snapshot whose own WAL range comes first, the SOURCE’s bucket the continuous archive is read from, and the target (absent = the snapshot’s consistent point). Null once the engine promoted.
object
On a Multi-AZ member, its side of the stream. A standby clones the peer with pg_basebackup and streams from it; a primary admits the peer for replication and, while synchronous is set, waits for it on every commit (remote_apply). The replication role’s password travels by reference like the master credential — the agent fetches it with its own credentials.
object
The secret version the replication role holds — service-owned, in the system project; fetched by the agent, never in the document.
object
The other member — the primary to stream from on a standby, the standby admitted on a primary.
The standby’s application_name, what synchronous_standby_names points at.
On a member of a blue/green deployment, its side of the logical stream. The publisher (blue’s primary) checks the preconditions, creates the publication and one logical slot per database, advances them to advanceToLsn (the base snapshot’s consistent point), and at fence admits no client network, defaults to read-only transactions and terminates every client session, reporting the fence LSN; retired is the former blue after the switchover (readable, read-only, its slots and publication dropped). The subscriber (green’s primary) subscribes from the pre-created slots (no initial copy — the data came with the snapshot), and at finalize copies the sequence values from the publisher and drops its subscriptions. The replication role’s password travels by reference.
object
The slot of a database is <slotPrefix>_<digest of the database name>, derived the same way on both sides.
object
Publisher — the addresses pg_hba admits for the replication role.
Publisher — every slot behind this position is advanced to it.
The curated extensions the engine must hold and where each belongs. The agent creates them as the engine’s own superuser — the master role is not one — and drops the ones the list no longer names, unless something depends on them.
object
The databases it belongs in; empty = every connectable database and template1, so a new database inherits it.
Operations the agent performs once, then reports through completedOperation. shutdown = clean stop and stay stopped (delete or terminate in progress); apply_master_password = fetch masterCredential and ALTER ROLE to it, confirmed through masterPasswordVersionId (or refused through failedOperation); promote = end recovery on a standby, confirmed once replication.inRecovery is false; rebuild = discard the standby’s data directory and clone the peer again.
Example
{ "role": "primary", "dataMountPath": "/var/lib/db/data", "port": 5432, "backup": { "phase": "start" }, "blueGreen": { "role": "publisher", "phase": "publish" }, "pendingOperations": [ "shutdown" ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}