The mechanism
A Kubernetes object combines a type, identity and desired configuration. apiVersion and kind select the API contract; metadata names the object and carries labels and annotations. Most workload objects have a desired spec and observed status, maintained by different actors.
Labels are queryable identity attributes, not decoration. A Service or controller selector matches them to associate objects. An accidental label change can disconnect traffic or cause a controller to manage the wrong set. Annotations carry non-selection metadata and should not contain secrets.
Server-side apply tracks field ownership and can surface conflicts between managers. It is not permission to overwrite another actor’s fields indiscriminately. Review rendered manifests and ownership before deciding how a conflict should be resolved.
Worked example
This offline ConfigMap example is safe to read and parse; it is not applied by the handbook. The namespace is explicit. The object contains public synthetic configuration only. ConfigMaps are not a secret-storage mechanism.
apiVersion: v1
kind: ConfigMap
metadata:
name: parcelops-config
namespace: handbook-lab
labels:
app.kubernetes.io/name: parcelops
data:
LOG_LEVEL: info
FIXTURE_MODE: "true"Practice: predict, inspect, explain
Offline exercise. Identify identity, selection metadata and configuration fields. Change the label in one copy and explain which selectors would stop matching. Then imagine two managers attempting to own the same data key and describe the review needed before overriding the conflict.
Expected observation: YAML syntax success proves little about API validity, policy acceptance or runtime behavior. Create a checklist with separate local parsing, server validation, admission and observed rollout stages. Keep each stage marked unrun until the corresponding evidence exists.
Troubleshooting and trade-offs
If a manifest parses but the API rejects it, inspect the selected API version, field schema and admission message. If apply conflicts, determine whether the field belongs to another controller or deployment process. Avoid forceful conflict resolution as a default. A clean diff is useful only when it represents the fully rendered object that will reach the API.
Interview practice
Why are spec and status different?
Spec describes desired state; status reports observed state from controllers and node components. Their difference is often the starting point for diagnosis.
What does a field-ownership conflict tell you?
Multiple managers disagree over an owned field. Resolve responsibility and intended value rather than blindly forcing an overwrite.
Completion check
Explain what local parsing, API validation and successful reconciliation each establish.
Sources and version notes
Baseline checked 6 October 2026: the official release page lists Kubernetes 1.37.1. Verify your cluster and distribution prerequisites. All manifests are offline teaching examples; no cluster mutations or cloud resources are executed by this handbook.
- Official documentation: Working with objects
- Official documentation: Server side apply
- Official documentation: Configmap
Make the understanding yours.
Use the completion check above. Mark this chapter when you can explain the mechanism and its limits.
Self-assessed reading progress. This does not certify that a lab ran or a system is secure.