Every VPC's recursor replica set, placement and health.
curl --request GET \ --url https://stratum.example.com/v1/admin/network/dns/recursors \ --header 'Authorization: Bearer <token>'The operator’s view of the per-VPC DNS recursors: for each VPC,
the replicas (the node each runs on, its address on the VPC’s internal DNS
switch, whether the VPC’s .3 balances to it, and its own measured
health), the placement inputs, the desired and placed replica counts, the
guest-path verdict per subnet, and how the converger left the VPC’s switch
and VIPs. Optionally narrowed by project or VPC. Install-scope; gates on
network:ListDNSRecursors.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Responses
Section titled “Responses”The recursors.
object
The operator’s view of a VPC’s recursor: its replica set (where each replica runs, its address on the VPC’s DNS switch, its own health), the placement inputs, the replica counts, and how the converger left the VPC’s switch and .3 VIPs. The tenant’s view of the same VPC is RecursorStatus.
object
The tenant’s verdict on the same data (see RecursorStatus.healthy).
A subnet’s resolver address with its raw guest-path probe.
object
The node whose probe port on the subnet asked.
The probe’s raw failure detail.
The cluster’s replica setting (GET /v1/admin/network/dns/recursor-settings).
Replicas the recursor sweeps place for this VPC: the setting, fewer on a cluster with fewer ready nodes, more while a 2 to 1 change drains.
What the deterministic placement hashes: the VPC id (fnv32a) over these sorted ready, workload-capable nodes, the first replica on the hashed node and the next in ring order. Every node’s sweep computes the same answer.
object
How many replicas it was asked to place, max(setting, serving).
The placed replicas, by index.
One placed recursor replica.
object
0 (100.66.0.2) or 1 (100.66.0.3).
Its address on the VPC’s internal DNS switch. Every VPC reuses 100.66.0.0/29, so this identifies nothing outside the VPC.
With the prefix its netns carries, as its node reports it:.2/30 (or.2/29 for a replica 0 an older control plane placed),.3/29.
The VPC’s .3 VIPs balance to it, per the converger’s last record.
A replica’s own health, measured: the host-helper on its node sends it a recursive query for a public name from inside its netns every 30 s. Replaces a placement state that read “assigned” whatever was true.
object
Unknown when the node placement puts it on has no verdict newer than two minutes (not probed yet, or the node stopped reporting).
Each upstream DNS server’s answer in the same verdict, asked directly from the replica’s netns. Absent without upstream servers.
One upstream DNS server’s answer to a recursive query sent from inside a recursor replica’s netns.
object
Why not, when not answering.
A VPC’s DNS switch and .3 VIPs as the network-dns-recursor converger last left them. Absent before its first pass covered the VPC.
object
Replica ports on the switch (1 is a /30, 2 a /29).
Replicas the VIPs balance to.
Replicas they should balance to (the setting, or fewer with fewer ready nodes).
Whether each of the cluster’s upstream DNS servers answers this VPC’s replicas, in the list’s order. Empty with no upstream servers.
Whether one upstream DNS server answers the VPC resolvers. The host helper on each node asks it a recursive query directly from inside every recursor’s netns every 30 s; this judges every replica verdict newer than two minutes.
object
The server’s IPv4 address.
Answering: every replica that asked got an answer. not-answering: at least one did not. unknown: no recent verdict asked it yet.
True when state is answering.
Replicas with a recent verdict on this server.
Of those, how many got an answer.
A failing replica’s error, naming its node and VPC.
The newest verdict on this server.
Example
{ "items": [ { "replicas": [ { "health": { "state": "answering" } } ], "upstreams": [ { "state": "answering" } ] } ]}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" } ]}Upstream temporarily unavailable (driver / scheduler / dependency).
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" } ]}