Kubernetes Manifest Authoring Practice

Kubernetes Manifest Authoring Practice is the body of accumulated conventions experienced practitioners follow when writing manifests, addressing concerns that go beyond mere syntactic or schema correctness — pinning images precisely, setting meaningful resource and probe configuration, avoiding secrets in plain manifest content, and keeping label usage consistent — practices that distinguish a manifest that merely works from one that behaves predictably and safely over the long run of a workload's operational life.

Image Reference Precision

Avoiding Mutable Tags in Production Manifests

Referencing an image by a mutable tag such as latest, or even a semantically versioned tag that a build pipeline might overwrite, creates ambiguity about exactly what code is running at any given moment; production manifests generally pin to an immutable image digest, or at minimum a tag a pipeline never reuses, so that the manifest itself unambiguously identifies the exact content deployed.

imagePullPolicy Alignment With Tag Strategy

Using a mutable tag together with imagePullPolicy: IfNotPresent compounds the ambiguity problem, since a node may continue running a stale cached image even after the tag has been updated elsewhere; authors relying on mutable tags for legitimate reasons generally pair them with Always pull policy to at least ensure freshness, while digest-pinned images can safely use the more efficient default.

Resource Requests and Limits

Requests as a Scheduling and Fairness Commitment

Authoring a manifest without resource requests leaves a container as BestEffort, subject to eviction ahead of any container with requests set, and contributes no meaningful signal to the scheduler about how much capacity the workload actually needs; setting requests based on observed real usage, rather than an arbitrary guess, is a foundational authoring practice for any workload expected to run reliably alongside others.

Avoiding Overly Tight Limits

Setting a memory limit too close to a container's actual working set risks frequent OOM kills under normal load variation, while an absent or excessively generous limit risks one workload starving its neighbors during a spike; authoring practice generally favors deriving limits from measured peak usage with a deliberate margin, rather than either omitting limits entirely or copying values from an unrelated workload's manifest.

Probe Configuration

Distinguishing Liveness From Readiness Intent

A common authoring mistake is configuring a liveness probe that checks the same condition a readiness probe should check, causing a temporarily overloaded but otherwise healthy container to be killed and restarted rather than simply marked not-ready and given time to recover; disciplined authoring treats liveness probes as asking "is this process fundamentally stuck" and readiness probes as asking "can this container currently serve traffic," which are frequently different questions.

Setting Realistic Timing Parameters

Probe timing parameters — initial delay, period, timeout, and failure threshold — should reflect the actual startup and response characteristics of the specific application rather than defaults copied from an unrelated example manifest, since probe misconfiguration is a frequent, avoidable cause of unnecessary restarts or slow failure detection.

Secrets and Sensitive Data

Never Embedding Secret Values Directly

Sensitive values — credentials, tokens, keys — are never authored directly into a manifest's plain fields, since manifests are typically committed to version control and widely readable; the established practice is referencing a Secret object by name (itself populated through a separate, more tightly controlled mechanism such as an external secrets integration) rather than embedding the value inline.

Avoiding Secrets in ConfigMaps by Habit

Because ConfigMaps and Secrets share a similar structural shape, it is a recognized authoring mistake to place sensitive values in a ConfigMap out of convenience; disciplined practice keeps this distinction strict regardless of how similar the two objects look structurally, since ConfigMap content typically receives less restrictive access controls than Secret content.

Label and Annotation Consistency

Adopting a Consistent Labeling Scheme From the Start

Establishing consistent label keys (commonly aligned with the recommended app.kubernetes.io/* conventions) across every manifest in a project from the outset avoids the far more disruptive task of retrofitting labels onto selectors, Services, and NetworkPolicies later, once many objects already depend on an inconsistent or incomplete labeling scheme.

Reserving Annotations for Genuinely Non-Selecting Metadata

Disciplined authoring resists the temptation to use annotations as a catch-all configuration mechanism when a proper typed field exists, reserving annotation-based configuration for cases genuinely outside the type's own schema, keeping the object's structural validation as meaningful as possible.