Kubernetes Manifest Spec

Kubernetes Manifest Spec is the portion of a manifest, nested under the top-level spec key, that carries the actual type-specific desired-state configuration a manifest exists to declare — the container images and replica counts of a Deployment, the selector and ports of a Service, the access mode and size of a PersistentVolumeClaim — and it is this section, more than any other part of the manifest, that varies entirely by Kind and demands the author's closest attention, since every other section (TypeMeta, ObjectMeta) follows a largely uniform pattern across resource types.

Spec as the Type-Specific Core

No Universal Spec Shape

Unlike metadata, whose structure is essentially identical across every Kind, spec has no shared shape at all beyond the general convention that it holds desired state; a Pod's spec describes containers and volumes, a Service's spec describes selectors and ports, and a PersistentVolumeClaim's spec describes storage requirements, each governed entirely by that Kind's own schema.

Why This Variation Is Intentional

This lack of a shared spec shape is a deliberate consequence of the object model's design: forcing every resource type into a common spec structure would either bloat simple types with irrelevant fields or force complex types to encode their configuration awkwardly into a shape that doesn't naturally fit, so each type's spec is instead purpose-built around what that type actually needs to express.

Required Versus Optional Spec Fields

Schema-Enforced Requirements

A given Kind's schema marks certain spec fields as required — a Deployment's spec requires a Pod template and selector, for instance — and a manifest omitting a required field is rejected by structural validation before it ever reaches type-specific semantic checks, meaning manifest authors get relatively fast, clear feedback when a mandatory field is missing.

Defaulted Optional Fields

Optional fields left unset in a manifest are not simply absent in the resulting object; as covered under the API defaulting model, the API server fills many of them in with sensible defaults, meaning a concise manifest and an explicitly verbose one specifying every default value can produce functionally identical stored objects, differing only in how much the manifest itself states outright.

Nested Spec Structures

Templates Within Spec

Many controller types embed an entire nested object's spec within their own — a Deployment's spec.template contains a full Pod spec, which itself contains a spec.containers list, each with its own resource requirements and volume mounts — meaning a manifest author working with these types is effectively authoring multiple layers of spec simultaneously, with the outer layer governing the controller's own behavior and the inner layer governing the Pods it produces.

Lists Within Spec and Merge Key Awareness

List-valued spec fields, such as a Pod's containers or a NetworkPolicy's ingress rules, often carry specific merge semantics (as governed by the object schema model's list-type declarations) that matter most when a manifest is later patched rather than replaced wholesale, making it useful for authors to know which list fields merge by key and which are always replaced entirely when planning how a manifest will be updated over its lifetime.

Spec Immutability Considerations

Fields That Cannot Be Changed After Creation

Certain spec fields become immutable once an object is created — a Pod's node assignment, a PersistentVolumeClaim's storage class in many configurations, a Service's clusterIP — and a manifest author attempting to change such a field on an existing object through a subsequent apply will encounter a validation rejection, since the API server enforces these immutability rules regardless of how the change was submitted.

Designing Manifests Around Immutability

Understanding which fields are immutable shapes how manifests are structured for iterative change: fields expected to change frequently, such as a container image tag, are kept mutable by design, while fields that anchor an object's fundamental identity or allocation, such as storage class, are deliberately fixed to avoid the ambiguity of trying to reconcile a live, already-provisioned resource against a fundamentally different declared configuration.