Contexts for Key/Value Usage
Metadata keys in native.cloud are designed to be applied across several distinct operational contexts in cloud native infrastructure. Each context serves different operational roles, has specific syntax and size constraints, and integrates with different control plane components.
Context Overview
Section titled “Context Overview”The ontology supports five primary metadata contexts across Kubernetes and container ecosystems:
Kubernetes annotation
Items suitable to go into the .metadata.annotations field of a Kubernetes object.
Kubernetes label
Items suitable to go into the .metadata.labels field of a Kubernetes object.
Labels are constrained; as well as being strings, you also have to use values that match the syntax of a DNS label name. For example, whitespace is not allowed.
Kubernetes taint
Items suitable to be used as taints on a Kubernetes node.
Taints are a way to mark nodes so that Pods (sets of related containers) do not run there, with one exception: Kubernetes Pods can tolerate a taint, allowing them to run where other normal Pods cannot.
Kubernetes ResourceClaim parameter
Items suitable to go into the .spec.parameters field of a Dynamic Resource Allocation (DRA) ResourceClaim.
ResourceClaims are used to request special hardware or other resources through the Dynamic Resource Allocation mechanism of Kubernetes.
OCI annotation
Annotations suitable for use on OCI container images and other OCI artifacts.
OCI annotations use reverse domain name notation with dots as separators, unlike Kubernetes labels which use a slash between the prefix and name.
Comparison Matrix
Section titled “Comparison Matrix”| Context | Target Scope | Value Limit | Syntax Constraints | Primary Use Case |
|---|---|---|---|---|
| Annotation | All Kubernetes Objects | Unlimited (etcd object limits) | UTF-8 string, structured JSON/YAML | Tooling config, audit metadata, non-identifying info |
| Label | All Kubernetes Objects | 63 characters max | Alphanumeric, -, _, ., DNS format |
Selectors, grouping, scheduling, routing |
| Taint | Kubernetes Nodes | 63 characters (value) | Key/value with effect (NoSchedule, etc.) |
Node isolation, dedicated workloads |
| Resource Claim | Dynamic Resource Allocation | Driver-dependent | Structured claim parameters | GPU/FPGA allocation, specialized hardware |
| OCI Annotation | OCI Images & Artifacts | Registry-dependent | Reverse domain notation keys | Build provenance, source repo, image descriptions |
Choosing the Right Context
Section titled “Choosing the Right Context”When choosing where to apply an ontology key, consider how downstream tooling interacts with the metadata:
- Use Labels when controllers, ingress routers, Prometheus scrapers, or operators need to filter, select, or query resources (
kubectl get pods -l ...). - Use Annotations when recording timestamps, Git commit hashes, issue tracker URLs, policy references, or complex structured data that controllers read directly without querying by selector.
- Use Taints when nodes must repel workloads by default, reserving compute for specific pods that declare matching tolerations.
- Use Resource Claims when workloads require declarative, lifecycle-managed access to heterogeneous physical devices.
- Use OCI Annotations when metadata needs to travel alongside container images through registries, build pipelines, and artifact scanners.