Skip to content
StratumStratum Docs

Set the cluster's upstream DNS servers and the root-server fallback.

PUT
/v1/admin/network/dns/upstream-servers
Code sample: Shell / cURL
curl --request PUT \
  --url https://stratum.example.com/v1/admin/network/dns/upstream-servers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "servers": [ "example" ], "fallback": true }'

Records the list and returns at once (202), with no render and no control-plane restart. The dns-recursor reconciler rewrites every recursor’s . forward zone at once (the change wakes it), and every node’s recursor sweep routes the new servers over its recursors’ management veth within one sweep (30 s), in place: no recursor is restarted. The answer’s status says how far that has got; read it again with GET.

Give servers, fallback, or both; a field left out keeps what the setting has. servers: up to 4 IPv4 addresses, none twice, none a node of this cluster, the same rule node.yaml dns.upstream_servers applies. [] turns forwarding off (the recursors resolve from the root servers, which needs DNS out to the internet). fallback: when every server fails, resolve from the root servers instead of failing the query; changing only it needs the servers to have been set. Example: {"servers": ["172.24.2.3", "172.24.2.4"], "fallback": false}. Install-scope; gates on network:UpdateDNSUpstreamServers.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The cluster’s upstream DNS servers, and the root-server fallback. Give servers, fallback, or both; a field left out keeps what the setting has.

object
>= 1 properties
servers

Up to 4 IPv4 addresses, in the order the recursors try them; none twice and none a node of this cluster. [] turns forwarding off.

Array<string>
<= 4 items
fallback

When every server fails, resolve from the root servers instead of failing the query. Needs the servers to have been set, in this request or before. Default off.

boolean

Example generated

{
  "servers": [
    "example"
  ],
  "fallback": true
}

Responses

Section titled “Responses”

202

Section titled “202”

Recorded; the cluster converges to it.

Media typeapplication/json

The cluster’s upstream DNS servers (where every VPC’s recursor forwards the names the cloud does not serve) and how far the cluster has converged on them.

object
servers
required

What every consumer acts on: the setting, or this control plane’s env while it was never set. Empty means no forwarding.

Array<string>
fallback
required

When every server fails, the recursors resolve from the root servers instead of failing the query. Off by default: the fallback hides a dead server from tenants and sends names only your own resolvers serve out to public resolution. No effect without servers.

boolean
set
required

False while the setting was never set: each control plane then uses its own STRATUM_NETWORK_DEFAULT_DNS_SERVERS, and servers is this one’s.

boolean
source
required

Environment: never set; seed: from a control plane’s env at its first start; operator: set through this API.

string
Allowed values: environment seed operator
generation
required

Moves on every change of servers or fallback; 0 while never set.

integer format: int64
maxServers
required

The most servers the list takes (4).

integer
updatedBy
string
updatedAt
string format: date-time
status
required

How far the cluster has converged on the upstream DNS servers, judged from what the consumers produced: the stored . forward zones the recursors render, and each node’s report of what its host helper applied.

object
phase
required

Converged when every per-VPC recursor forwards to servers (or has no . zone, for an empty list) and every node recursors are placed on has routes to them applied; converging otherwise.

string
Allowed values: converged converging
recursors
required

Per-VPC recursors.

integer
recursorsConverged
required
integer
nodesExpected
required

Ready nodes recursors are placed on.

integer
nodesConverged
required
integer
nodes
required
Array<object>

One node’s part of the upstream DNS status: what its recursor sweep stamped into its recursors’ netns intents, and how many of them its host helper has applied.

object
nodeId
required
string
expected
required

A ready node recursors are placed on. A node that is not is listed when it has reported and does not hold the phase back.

boolean
reported
required

False for an expected node whose sweep has not reported.

boolean
generation
required

The setting generation the sweep read; 0 = never set.

integer format: int64
servers
required

The servers the sweep routed.

Array<string>
recursors
required

Recursors this node runs.

integer
applied
required

Of them, how many carry the routes in the host helper’s applied state.

integer
converged
required

A report under 5 minutes old, the same servers, every recursor applied.

boolean
detail
string
observedAt
string format: date-time
detail

The first thing not at the list, and why.

string
health
required

Whether each server answers the VPC resolvers, over every recursor in the cluster, in the list’s order. Empty with no servers.

Array<object>

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
address
required

The server’s IPv4 address.

string
state
required

Answering: every replica that asked got an answer. not-answering: at least one did not. unknown: no recent verdict asked it yet.

string
Allowed values: answering not-answering unknown
healthy
required

True when state is answering.

boolean
asked
required

Replicas with a recent verdict on this server.

integer
answering
required

Of those, how many got an answer.

integer
lastError

A failing replica’s error, naming its node and VPC.

string
checkedAt

The newest verdict on this server.

string format: date-time

Example 

{
  "source": "environment",
  "status": {
    "phase": "converged"
  },
  "health": [
    {
      "state": "answering"
    }
  ]
}

400

Section titled “400”

Bad request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

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
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

403

Section titled “403”

Authenticated but not authorized.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

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
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

503

Section titled “503”

Upstream temporarily unavailable (driver / scheduler / dependency).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

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
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}