Resource references

How one Datum Cloud resource points at another through a reference object, and how to follow those links.

Resources in Datum Cloud rarely stand alone. A route attaches to a gateway, a zone belongs to a domain, an access policy binds a role — and each of those relationships is expressed the same way: with a reference object. This page explains that common pattern so you can recognize it on any resource page, regardless of the service.

This is a resource-agnostic concept page. For the resources cited as examples, see DNSZone, HTTPRoute, and SecurityPolicy. For how to read and change resources with the CLI, see Reading resources and Changing resources.

The pattern

A reference is a small object embedded in one resource that identifies another resource. By convention its field name ends in Ref (a single reference) or Refs (a list of references). Instead of copying the target’s data inline, the referencing resource just names the target and lets the platform resolve the link.

A reference object typically carries some subset of these keys:

Key	Meaning
name	The name of the target resource. Almost always present, and usually required.
kind	The target’s resource type (e.g. Gateway, Role). Present when a field can point at more than one type.
group (or apiGroup)	The API group the target’s kind belongs to. Distinguishes types that share a name across services.
namespace	The scope the target lives in, when it may differ from the referencing resource’s own scope.

Simpler references carry only a name because the target’s type is fixed by the field itself. Broader references — ones that can point at several kinds of resource — add kind and group so the target is unambiguous.

A reference’s namespace key is the raw metadata field on the target. In Datum Cloud terms, resources are scoped to a Project or to the Platform; a reference within a Project usually omits namespace and resolves to that same Project unless it explicitly points elsewhere.

Where references appear

References show up in both halves of a resource:

• In spec, a reference is part of the desired state you declare — you are telling the platform which other resource to relate to.
• In status, a reference is populated by the platform to report a relationship it discovered or established on your behalf. Status references are read-only.

Real examples

The examples below are all confirmed on their resource pages.

A fixed-type reference: DNSZone.status.domainRef

A DNSZone reports the Domain it belongs to through status.domainRef. This is a platform-populated (read-only) reference: you create the zone with a domain name, and the platform links it to the managing Domain and records that link in status. Because the target is always a Domain, the reference needs little more than a name.

A multi-target list of references: HTTPRoute.spec.parentRefs

An HTTPRoute attaches to the gateways that serve it through spec.parentRefs, a list of reference objects you declare:

spec:
  parentRefs:
    - name: example-gateway   # required
      # kind, group, namespace, sectionName, port are optional

Each entry requires name and accepts optional group, kind, namespace, sectionName, and port. The extra keys exist because a parent is usually — but not always — a Gateway; supplying kind and group disambiguates when it isn’t, and sectionName narrows the attachment to a specific listener within the parent. The referenced parent must also allow the attachment, so a reference expresses intent, not a guarantee.

A policy target reference: SecurityPolicy.spec.targetRefs

A SecurityPolicy is not embedded in the gateway it protects — it attaches to one through spec.targetRefs:

spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: my-gateway

Here group, kind, and name are all required. This is the typical shape for policy attachment: a standalone policy resource points at the resource it governs, so you can add, change, or remove the policy without editing the target. (A PolicyBinding uses the same idea for access control, binding a Role to subjects through a roleRef.)

Following a reference

A reference is a lookup key, not the target’s data. To inspect what a reference points at, read the target resource by the name (and, where present, kind and scope) the reference gives you.

For example, once you have a route’s parentRefs, you can look up the gateway it names:

# See the references on the route
datumctl get httproute example-route -o yaml --project my-project

# Follow one: read the parent it names
datumctl get gateway example-gateway --project my-project

The same approach works in reverse: from a DNSZone you can follow status.domainRef to the Domain, and from there see the domain’s own status.

datumctl describe often surfaces related resources and the conditions that report whether a reference resolved successfully — a good first stop when a relationship isn’t behaving as expected.

When a reference doesn’t resolve

Because a reference only names a target, the target may be missing, may not permit the relationship, or may live in a scope the referencing resource can’t reach. Resources that resolve references generally report the outcome in status.conditions — for instance, an HTTPRoute records a ResolvedRefs condition per parent describing whether its backend and parent references resolved.

Creating a reference does not create the target. If you point at a resource that doesn’t exist yet, the reference stays unresolved until the target appears. Check the referencing resource’s conditions to confirm the link was established.

Related

• Status & conditions — how resources report whether a reference resolved (for example a ResolvedRefs condition).
• API conventions — the shared spec/status model these reference fields live in.
• Field formats & types — how Ref/Refs object fields are described in the field tables.
• Reading resources — fetch a resource and the targets its references name.
• Discovering resources & schemas — find which fields on a resource are references, and their types.
• Changing resources and Safe changes & declarative config — declare and update references safely.
• Output formats & scripting — extract reference fields for automation.
• Contexts & scoping — how Project and Platform scope affect where a reference resolves.

On any resource page, scan the field tables for names ending in Ref or Refs to see what that resource relates to. You can also explore them live with datumctl explain <resource> --recursive.