External Services

Begin adding a single new member to a running cluster.

Currently only replica members can be added at runtime. The response is 202 Accepted as soon as the validation passes and the placeholder service_members row is inserted. The actual container provisioning + DNS registration runs in the background; poll GET /external-services/{id}/members/{member_id} to watch provisioning_step advance through the phases.

post/external-services/{id}/members

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/external-services/{id}/members
  • Auth: HTTP bearer

Path parameters

idinteger required

External service ID

Request body

node_idinteger nullable

Target worker node ID. Omit or null to run on the control plane.

rolestring required

Member role. Currently only replica is accepted at runtime — monitor is a singleton, primary is elected by pg_auto_failover.

Example request

{
  "role": "replica"
}

Response

Cluster member provisioning started

compute_ipstring nullable

Container's IP on the temps-overlay multi-host network. Populated by the lifecycle hook (ADR-011 Phase 3); None on single-host clusters where the overlay isn't attached.

container_namestring required
hostnamestring nullable
idinteger required
live_statestring nullable

Live FSM state from the pg_auto_failover monitor (primary, secondary, catchingup, report_lsn, …). None when the monitor is unreachable, the service is not a cluster, or the row is the monitor itself.

The UI must render the role badge from this field, falling back to role only when live_state is null. role is now config-only (monitor or replica); flipping the badge to "primary" when the monitor elects a new one used to require a reconciler that lagged ~5s behind real failovers — and during that window the UI showed two primaries. live_state is read directly from the monitor on every list, so it can never lag.

node_idinteger nullable
ordinalinteger required
portinteger nullable
provisioning_errorstring nullable

Most recent provisioning failure message, when status='failed'. Set by the background task so the UI can show why the new replica didn't come up.

provisioning_stepstring nullable

Last-attempted phase of the async add_cluster_member background task (e.g. validating, provisioning_container, done, failed). None for members not created through that flow — the UI falls back to the status column for those.

rolestring required
statusstring required

Changes

No recorded changes to this operation across all 53 revisions of this API.