6.6 Kubernetes Manifest Spec

Kubernetes Manifest Spec is the portion of a manifest that carries the actual configuration content an author is trying to express, nested under the spec key, containing every field specific to the object's kind that determines its behavior, and representing the part of the manifest that varies most dramatically from one resource type to another compared to the comparatively uniform apiVersion, kind, and metadata sections surrounding it.

The Spec as Kind-Specific Content

No Universal Spec Shape

Unlike metadata, which follows a nearly identical structure across every resource type, a manifest's spec is entirely defined by the schema of its specific kind: a Deployment's spec describes replica counts and a pod template, while a Service's spec describes ports and a selector, meaning understanding a manifest's spec requires understanding that particular kind's documentation or schema rather than any general-purpose knowledge.

Nested Specs Within Specs

Many workload manifests embed an entire PodTemplateSpec within their own spec, such as a Deployment's spec.template, itself containing a further metadata and spec describing the Pods that will ultimately be created, a layered pattern that lets higher-level controllers reuse Pod-level configuration structure rather than reinventing it.

Required Versus Optional Spec Fields

Fields That Must Be Present

Every kind's schema designates certain spec fields as required, such as a container's image field, without which the manifest is rejected as invalid; authors constructing a manifest from scratch need to know, or look up, which fields are mandatory for the specific kind they are working with.

Optional Fields and Defaulting Interaction

Fields left out of the spec are subject to the defaulting model, meaning an author's decision to omit an optional field is not the same as explicitly disabling whatever that field controls, since the API server will typically substitute a default value, and the true, fully resolved spec only becomes apparent by inspecting the created object rather than the originally authored manifest alone.

Common Spec Patterns Across Kinds

Selector and Template Pairing

A recurring pattern across workload controllers is a spec.selector paired with a spec.template, where the selector determines which Pods the controller considers its own and the template describes what new Pods matching that selector should look like, a pairing that appears, with kind-specific variations, across Deployment, ReplicaSet, StatefulSet, and DaemonSet.

Replica and Scaling Fields

Workload kinds that support horizontal scaling include a replicas field within their spec, representing the desired count of running instances, which is also the field exposed generically through the scale subresource for tools like the Horizontal Pod Autoscaler to adjust without needing to understand the rest of the spec.

Resource Requests and Limits

Container specifications nested within a Pod template commonly include a resources block specifying requests and limits for CPU and memory, a pattern so consistent across container-based workloads that it functions almost as a sub-convention within the broader diversity of spec shapes.

Authoring Considerations for Spec Content

Balancing Explicitness and Brevity

Manifest authors face a tradeoff between explicitly specifying every relevant field, for clarity and to avoid depending on defaults that could change in future versions, and relying on sensible defaults to keep the manifest concise and focused on what actually differs from the common case for that kind.

Spec Immutability Constraints

Certain spec fields are immutable after object creation, such as a Deployment's selector or a PersistentVolumeClaim's storageClassName in most configurations, meaning an author revising a manifest for an already-existing object needs to be aware of which fields can be freely changed on reapplication and which would instead require deleting and recreating the object entirely.

Spec as the Primary Target of Automated Tooling

Templating and Overlay Targets

Because spec content is what varies most between environments, templating tools like Helm and overlay tools like Kustomize concentrate the bulk of their parameterization logic on spec fields, such as image tags, replica counts, or resource limits, while metadata and the overall manifest envelope typically require far less environment-specific variation.