Status & conditions

How to read a resource’s observed state and interpret the standard conditions pattern across Datum Cloud.

A concept page for the whole API reference. Every resource has a spec (the desired state you declare) and a status (the observed state the platform reports back). This page explains how to read status and the shared conditions pattern. To actually read a resource, see Reading resources and Output formats & scripting.

The Datum Cloud API is currently alpha (v1alpha1; the Gateway API resources are served at stable v1). Status fields, condition types, and reason strings may change in backward-incompatible ways between releases.

Spec vs. status

Datum Cloud resources separate what you want from what the platform observes:

Section	Who writes it	What it means
spec	You	The desired state you declare. This is the part you edit and apply.
status	The platform	The observed state, reported back as the platform works toward your spec. Read-only.

You never set status yourself. When you apply a manifest, the platform stores your spec, then a controller works to make reality match it and records progress in status. Reading status is how you answer “did what I asked for actually happen, and is it healthy?”

Because status is populated asynchronously, a freshly created resource may have an empty or partial status for a short time while the platform reconciles it. Re-read the resource to see it converge.

What lives in status

The exact status fields differ per resource, but they fall into two broad kinds:

• Observed values — concrete data the platform discovered or assigned. For example, a DNSZone reports status.nameservers (the active authoritative nameservers) and status.recordCount. These are useful outputs you often need downstream.
• status.conditions — a standardized list describing the resource’s health and readiness. This is the same shape on every resource that has it, so once you can read conditions on one resource you can read them on all of them.

The rest of this page focuses on conditions, since it is the common pattern.

The conditions pattern

status.conditions is a list of objects. Each entry describes one aspect of the resource’s current state — for example, whether it was accepted, whether it was programmed into the underlying system, or whether it is fully ready. A resource surfaces several conditions at once, and you read them together to understand its overall state.

Every condition has the same fields:

Field	Type	Description
type	string	The aspect of state this condition describes, in CamelCase (e.g. Accepted, Programmed, Ready).
status	string	One of True, False, or Unknown — whether that aspect currently holds.
reason	string	A programmatic, CamelCase identifier for why the condition is in its current state. Stable enough to branch on in scripts.
message	string	A human-readable explanation of the transition. May be empty.
lastTransitionTime	string	RFC 3339 timestamp of when status last changed to its current value.
observedGeneration	integer	The metadata.generation the condition was evaluated against.

Interpreting the status value

The meaning of True and False depends on the condition type — read them relative to what the type asserts (e.g. “is this Ready?”), not as generic pass/fail:

• True — the aspect named by type holds. For a positive readiness type like Ready or Accepted, True is the healthy, desired outcome.
• False — the aspect does not hold. Check reason and message to find out why. For a readiness type, False usually means something needs your attention or is still failing.
• Unknown — the platform cannot currently determine the state (for example, it hasn’t observed the resource yet, or a dependency is itself unknown). Often a transient state right after a change.

Read reason and message together. reason is a stable machine-readable code you can match on in automation; message is the human explanation of what happened and, often, what to do next.

Checking observedGeneration first

metadata.generation increments each time you change a resource’s spec. A condition’s observedGeneration tells you which generation the platform had processed when it set that condition.

If status.conditions[*].observedGeneration is less than the current metadata.generation, the condition is stale — it reflects an earlier version of your spec, not your latest change. Wait for the platform to catch up before trusting a condition’s status. A Ready: True that describes an old generation does not mean your newest edit succeeded.

Common readiness condition types

Condition types are defined per resource, so always confirm the exact set for a given resource (see inspecting the schema). That said, several types recur across the API, especially on networking and DNS resources:

Type	Roughly means
Accepted	The platform validated your spec and accepted the request.
Programmed	The accepted configuration was applied to the underlying system (e.g. the DNS zone or route is live).
Ready	The resource is fully provisioned and usable.

For example, a DNSZone’s status.conditions “tracks state such as Accepted and Programmed readiness,” and the Gateway API resources such as HTTPRoute use Accepted and Programmed in the same way. A healthy resource typically shows these as status: True with a reason that echoes the type (for example Accepted / Programmed).

There is no universal, fixed list of condition types. Treat the table above as common conventions, not a guarantee — the authoritative set for any resource comes from its schema and its own reference page.

Inspecting status with the CLI

Conditions and other status fields are easiest to read with datumctl.

datumctl describe renders conditions in a readable block, which is the fastest way to eyeball readiness and reasons:

datumctl describe dnszone example-com --project my-project

datumctl get -o yaml prints the full object — use it to see the raw status, every condition field, and observedGeneration:

datumctl get dnszone example-com -o yaml --project my-project

For scripting, extract a specific condition or field with an output template instead of parsing text. See Output formats & scripting for JSONPath and Go-template patterns, and Contexts & scoping for selecting the Project or Platform scope you’re reading from.

When a change doesn’t seem to take effect, compare metadata.generation against each condition’s observedGeneration in the -o yaml output. If they differ, the platform is still reconciling your latest spec.

Discovering a resource’s status schema

Because status fields and condition types vary by resource, inspect the live schema rather than guessing:

datumctl explain dnszone.status --recursive

This lists the exact status fields and the conditions structure for that resource, straight from the live API. See Discovering resources & schemas for more on exploring the API this way, and Safe changes & declarative config for previewing edits before you apply them.

Related

• API conventions — the spec/status model this page builds on.
• Resource references — status often reports resolved relationships (for example a ResolvedRefs condition), and this page explains how to follow them.
• Object metadata — metadata.generation, which conditions compare against via observedGeneration.
• Reading resources — get and describe to see status and conditions.
• Output formats & scripting — extract a specific condition or field for automation.
• Contexts & scoping — select the Project or Platform scope you read status from.