Appearance

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.

Ownership viewStep 1 of 3
Choose the resource schemaapiVersion apps/v1 and kind Deployment select a specific resource schema. YAML is one serialization of that object.. YAML document, active. apps/v1 Deployment, ready. API schema, readyYAML document
YAML documentIn focus
apps/v1 Deployment
apps/v1 DeploymentReady
API schema
API schemaReady
YAML documentIn focus
apps/v1 DeploymentReady
API schemaReady
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: valid YAML, wrong schema
Choose the resource schema

apiVersion apps/v1 and kind Deployment select a specific resource schema. YAML is one serialization of that object.

Read the complete visual sequence
  1. Choose the resource schema

    apiVersion apps/v1 and kind Deployment select a specific resource schema. YAML is one serialization of that object.

  2. Separate object and Pod metadata

    Deployment metadata identifies the parent. template.metadata describes labels of child Pods, not the parent’s existing metadata.

  3. 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

  1. 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.

  2. 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.

  3. 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.

Flow viewStep 1 of 3
Preview the changeThe local file requests two replicas. Diff compares intended configuration with the live object before a write.. File: replicas 2, active. Live spec: replicas 1, ready. kubectl diff, activeFile: replicas 2
File: replicas 2In focus
Live spec: replicas 1
Live spec: replicas 1Ready
kubectl diff
kubectl diffIn focus
File: replicas 2In focus
Live spec: replicas 1Ready
kubectl diffIn focus
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: competing desired-state writers
Preview the change

The local file requests two replicas. Diff compares intended configuration with the live object before a write.

Read the complete visual sequence
  1. Preview the change

    The local file requests two replicas. Diff compares intended configuration with the live object before a write.

  2. Persist the desired change

    Apply updates the addressed Deployment. The spec is two while the status can still show one available replica.

  3. 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

  1. Manual scaling changes the live spec

    An operator scales to four replicas, but the saved manifest still requests two.

  2. Reapply restores the file’s target

    Reapplying the authoritative-looking file requests two again. The controllers follow the latest accepted desired state.

  3. 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

Search the book

Search loads when you open it.