Object metadata

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

Because labels are indexed for selection, keep the set small and stable, and use them for values you actually filter on. See Reading resources and Output formats & scripting for filtering and label-selector usage.

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.

Fields the platform manages

The platform populates and maintains the following fields automatically. They are read-only — do not set them in your manifests. They appear when you read a resource (for example with 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.

Working with metadata

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.

API conventions — where metadata sits in the apiVersion/kind/spec/status model.
Scopes — why a name must be unique within its Project or across the Platform.
Status & conditions — how metadata.generation is compared against a condition’s observedGeneration.
Field formats & types — the RFC 1123 rules for name and the map types used by labels and annotations.
Reading resources and Changing resources — read and set metadata with the CLI.
Contexts & scoping — how the CLI resolves the namespace field from your active context.

Overview

Concepts

Resource Manager

IAM

Compute

Networking

DNS

IPAM

Quota

Billing

Telemetry

Notification

Platform resources

Overview

Fields you set

Name

Labels

Annotations

Fields the platform manages

The namespace field

Working with metadata

​Overview

​Fields you set

​Name

​Labels

​Annotations

​Fields the platform manages

​The namespace field

​Working with metadata

​Related

Overview

Fields you set

Name

Labels

Annotations

Fields the platform manages

The namespace field

Working with metadata

Related