This is a resource-agnostic concept page. Every Datum Cloud resource — a DNSZone, an HTTPRoute, a Project, and so on — carries the same metadata block, so individual resource pages omit it and link here instead. The Datum Cloud API is currently alpha (v1alpha1; the Gateway API resources are served at stable v1). Fields and behavior may change in backward-incompatible ways between releases.
Overview
Every resource you create or read has three top-level sections: metadata, spec, and status. The spec and status sections are specific to each resource kind, but metadata is shared and looks the same everywhere:
apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSZone
metadata:
name: example-com
labels:
team: platform
env: production
annotations:
datum.net/change-ticket: "OPS-1421"
spec:
# ...resource-specific fields
metadata holds the resource’s identity (its name), the labels and annotations you use to organize and describe it, and a set of system-managed fields the platform maintains for you.
Fields you set
These are the metadata fields you provide when creating or changing a resource.
| Field | Type | Description |
|---|
metadata.name | string | The resource’s name. Required at creation (unless the resource supports server-generated names). Must be unique within its scope and cannot be changed after creation. |
metadata.labels | map[string]string | Key/value pairs used to organize, group, and select resources. Ideal for querying and filtering. |
metadata.annotations | map[string]string | Key/value pairs for arbitrary, non-identifying metadata — often set by tools or automation. Not used for selection or filtering. |
Name
name identifies the resource within its scope. A Project-scoped resource’s name must be unique among resources of the same kind in that Project; a Platform-scoped resource’s name must be unique across the platform. Names are set once, at creation, and cannot be updated afterward — to “rename” a resource you delete it and create a new one.
Names follow the standard DNS-compatible naming rules (RFC 1123): lowercase alphanumeric characters and -, starting and ending with an alphanumeric character (for example, example-com).
Some resources let the server generate a unique name for you instead of requiring one. When supported, you supply a name prefix and the platform appends a unique suffix. Check a resource’s schema with datumctl explain <resource>.metadata — see Discovering resources & schemas. Labels
Labels are key/value pairs meant to be queried and selected on. Use them to attach identifying dimensions — team ownership, environment, application, tier — that you’ll later want to filter by:
metadata:
labels:
team: platform
env: production
app: checkout
Annotations
Annotations are also key/value pairs, but they are for arbitrary metadata that is not queried — longer descriptions, tool state, change-ticket references, contact info, or data that automation reads and writes. They are not used for selection or filtering, so there’s no penalty for larger or more free-form values.
metadata:
annotations:
datum.net/managed-by: "terraform"
datum.net/change-ticket: "OPS-1421"
Labels vs. annotations: if you want to find or group resources by a value, use a label. If you just want to attach information to a resource, use an annotation.
datumctl get -o yaml), and are useful for inspection and automation.
| Field | Type | Description |
|---|
metadata.uid | string | A globally unique identifier assigned at creation. Unlike name, it never changes and is never reused, so it unambiguously identifies one specific instance of a resource over time. |
metadata.creationTimestamp | string | RFC 3339 / UTC timestamp of when the resource was created. |
metadata.generation | integer | A counter that increments each time the resource’s spec (desired state) changes. Controllers compare it against a resource’s observed generation to tell whether the platform has caught up to your latest change. |
metadata.resourceVersion | string | An opaque version token that changes on every update. Used internally for change detection and safe concurrent updates. Treat it as opaque — never edit it. |
metadata.deletionTimestamp | string | Set by the platform when a resource is being deleted. Once set, the resource is scheduled for removal after any outstanding cleanup completes. |
metadata.finalizers | []string | A list of cleanup tasks that must finish before the resource is fully removed. While the list is non-empty, deletion is held so dependent cleanup (releasing addresses, tearing down backing infrastructure) can run. Managed by the platform. |
Don’t copy these fields into a manifest you’re applying. If you save a resource with datumctl get -o yaml and re-apply it, strip the system-managed metadata (and the entire status block) first — leaving resourceVersion in, for example, can cause an apply to be rejected. See Safe changes & declarative config. The namespace field
You may notice a metadata.namespace field when you inspect a resource. In Datum Cloud you don’t manage namespaces directly — the user-facing scoping concept is the Project (or the Platform, for shared resources). Your active context determines where a resource lives, and the CLI sets scope with the --project flag rather than a namespace field you fill in by hand. See Contexts & scoping.
- Read it:
datumctl get <resource> <name> -o yaml shows the full metadata block, including the system-managed fields. See Reading resources.
- Change it: set
name, labels, and annotations in your manifest and apply with datumctl apply -f. See Changing resources.
- Explore it:
datumctl explain <resource>.metadata prints the live schema for the metadata block. See Discovering resources & schemas.
Run datumctl explain <resource>.metadata --recursive to see the full, live metadata field tree for any resource.
