Objects, YAML, and apply
Read Kubernetes object structure and make declarative changes you can inspect.
What you will understand
- Identify object identity, metadata, spec, and status
- Read YAML mappings, sequences, and string values
- Preview and apply a deliberate object change
Builds on: From kubectl to a running Pod
Mental model: an API record, not a script
A Kubernetes object is a persistent API record representing intent, observations, or configuration. A manifest is a serialized description sent to the API. Writing YAML does not execute each line from top to bottom. The API interprets a document using its apiVersion and kind, validates its fields, supplies defaults where appropriate, and stores an object. Other components then act asynchronously.
An object’s name identifies it within its resource type and scope. Namespaced resources also need a namespace. The server assigns a UID that distinguishes this particular instance from another object later created with the same name. Deleting and recreating web can preserve the name while changing its UID. This matters for ownership, logs, and references to a specific lifetime.
metadata contains identifying and organizing information, including name, namespace, labels, annotations, UID, and resource version. Some fields are authored by you and others by the server. A typical workload spec contains desired configuration. status contains reported observations supplied by cluster components. ConfigMaps and Secrets illustrate why “every object has a spec” is wrong: their primary configuration fields include data rather than a workload-style spec.
Read the object tree
Distinguish API identity, metadata, desired configuration, and observed status.
apiVersion apps/v1 and kind Deployment select a specific resource schema. YAML is one serialization of that object.
- YAML document to apps/v1 Deploymentdeclares type
- API schema to apps/v1 Deploymentvalidates shape
Read the complete visual sequence
- Choose the resource schema
apiVersion apps/v1 and kind Deployment select a specific resource schema. YAML is one serialization of that object.
- Separate object and Pod metadata
Deployment metadata identifies the parent. template.metadata describes labels of child Pods, not the parent’s existing metadata.
- Server adds identity and observations
The API supplies a UID and metadata. Controllers report status; the authored spec remains the desired input.
Failure: valid YAML, wrong schema
Failure: valid YAML, wrong schema
- Indentation changes the tree
A field under metadata is not the same as a field under spec. The parser can accept YAML that the API schema rejects.
- The API rejects the request
With kubectl's default strict validation, unknown or wrongly typed fields reject this request. Other field-validation modes can warn about or ignore unknown fields. No controller can repair a change that was not accepted.
- Inspect the actual schema
Use explain and server dry-run to repair nesting and types, then reapply the corrected input.
About this model
A Deployment is shown; not every Kubernetes kind has both spec and status.
Walkthrough: read structure before values
YAML mappings associate keys and values. Sequences use a dash for each item. Indentation defines nesting, so containers belongs under spec, while name under one container identifies that container rather than the Pod. Use spaces consistently. Quote values that must be strings when YAML could interpret them as numbers or booleans. A Kubernetes schema determines the expected field type; visually plausible YAML can still violate that schema.
Save this as object-demo.yaml in your disposable lab namespace:
apiVersion: apps/v1 # API group and version for Deployments.
kind: Deployment
metadata:
name: object-demo
labels:
app: object-demo # Label on the Deployment object itself.
spec:
replicas: 1 # Integer, not the string "1".
selector:
matchLabels:
app: object-demo
template:
metadata:
labels:
app: object-demo # Separate labels for created Pods.
spec:
containers: # A sequence; here it has one container item.
- name: web
image: nginx:1.27.5
The Deployment’s labels do not automatically become Pod labels. The nested template is a separate recipe for Pods; its metadata is where you label those Pods. This repeated structure is intentional, not redundant formatting.
# Discover field structure from the API schema.
kubectl explain deployment.spec.template.spec.containers
# Ask the server to validate/admit without persisting the result.
kubectl apply --dry-run=server -f object-demo.yaml
# A diff returns a nonzero status when differences exist; read the output.
kubectl diff -f object-demo.yaml
kubectl apply -f object-demo.yaml
kubectl get deployment object-demo -o yaml
The retrieved object includes server fields and observed status beyond your original file. Keep your source manifest focused on intentional input; do not copy a live object wholesale into a release repository with transient status, UID, or managed field records attached.
Apply changes intent before status
Preview an object update and observe independent reconciliation.
The local file requests two replicas. Diff compares intended configuration with the live object before a write.
- File: replicas 2 to kubectl diffdesired input
- Live spec: replicas 1 to kubectl diffcurrent API state
Read the complete visual sequence
- Preview the change
The local file requests two replicas. Diff compares intended configuration with the live object before a write.
- Persist the desired change
Apply updates the addressed Deployment. The spec is two while the status can still show one available replica.
- Observe convergence
Controllers create and start the missing replica through their normal chain. Status eventually reports the new availability.
Failure: competing desired-state writers
Failure: competing desired-state writers
- Manual scaling changes the live spec
An operator scales to four replicas, but the saved manifest still requests two.
- Reapply restores the file’s target
Reapplying the authoritative-looking file requests two again. The controllers follow the latest accepted desired state.
- Coordinate field writers
Choose how replicas are managed and update the source deliberately. Reconciliation cannot decide which human intention was preferred.
About this model
Default client-side apply is used; advanced managedFields conflict resolution is deferred.
Practice: change intent and inspect convergence
Change replicas from one to two, run the diff, then apply the file again. Expect the desired count to change immediately after the accepted write, while observed readiness can lag. Applying the same intended file repeatedly should not create a fresh Deployment each time. The resource name and scope address the existing object.
Apply is a declarative management operation, not a guarantee that your file is the only writer. The default client-side apply uses a last-applied configuration annotation to calculate changes. Server-side apply records field managers and detects some conflicting ownership; its deeper rules appear later. In either mode, mixing imperative edits, multiple pipelines, and competing manifest copies needs deliberate coordination. An earlier kubectl scale can be overwritten when you reapply a file that still declares the old replica count.
Pitfalls
A dry run validates what the API can check at request time. It does not prove image availability, enough node capacity, valid application credentials, or healthy HTTP behavior. Likewise, a syntactically valid file can put a valid field at the wrong level, changing its meaning. Read the nesting and use kubectl explain instead of guessing field locations.
Some object fields are immutable after creation. An apply error about an immutable field is not a request to force-delete the workload immediately. Understand the field and plan the replacement or a differently named object, especially when storage or stable identity is involved.
Check your understanding
You changed the manifest’s replicas to two, but status still reports one available replica. Which value is wrong?
Neither must be wrong. The spec records the accepted target, while status reports observed progress. Inspect whether the controller has processed the update and whether the new Pod can schedule, start, and become ready. Treat a persistent mismatch as evidence to investigate, not as a reason to manually edit status.
Next, use labels to select related objects without confusing selection with identity. Practice schema discovery, diff, and apply in the module lab.
Primary documentation
Go to the source
Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise