Kubernetes Manifest Quality Guidelines

Kubernetes Manifest Quality Guidelines are the practical conventions for writing individual manifests that are correct, maintainable, and safe to apply repeatedly, covering explicit versioning, avoiding mutable image tags, consistently setting probes and resource requests, automated linting in CI, and preferring declarative management over ad hoc imperative commands.

Explicit API Versioning

Avoiding Deprecated or Beta APIs Without Reason

apiVersion: apps/v1
kind: Deployment

Pinning manifests to stable, non-deprecated apiVersion values, and proactively migrating away from a version once its deprecation is announced rather than waiting until removal forces an emergency fix, avoids the disruption of a manifest suddenly failing to apply after a routine cluster upgrade crosses a version-removal boundary.

kubectl get --raw /openapi/v2 | grep -i deprecated

Avoiding Mutable Image Tags

The :latest Tag Reliability Hazard

image: myapp:latest

image: myapp@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b85

Using :latest, or any other mutable tag that can point to different actual image content over time, means the exact same manifest applied twice can pull entirely different code, breaking the reproducibility every other best practice here depends on; pinning to a specific version tag, and ideally a content digest, guarantees that a given manifest always resolves to the exact same image regardless of when or where it is applied.

Always Setting Probes and Resource Requests

Defaults That Should Never Be Left Implicit

resources:
  requests: { cpu: 250m, memory: 256Mi }
  limits: { memory: 512Mi }
readinessProbe:
  httpGet: { path: /ready, port: 8080 }
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }

Every container manifest should explicitly declare resource requests and both liveness and readiness probes as a baseline expectation, not merely a recommendation applied selectively, since the absence of any one of these silently degrades the reliability mechanisms covered throughout the reliability and availability knowledge area for that specific workload without any error or warning surfaced at apply time.

Automated Linting in CI

Catching Structural and Best-Practice Violations Before Merge

kubeconform -strict manifests/
kube-linter lint manifests/

kubeconform validates manifests against the Kubernetes OpenAPI schema, catching structurally invalid YAML before it reaches a cluster, while kube-linter and similar tools check for common best-practice violations directly, missing resource limits, a :latest tag, a container running as root, surfacing these issues in CI rather than relying on manual review to catch every instance across a growing manifest set.

# CI pipeline step
- run: kube-linter lint ./manifests --fail-on-invalid-resource

Avoiding Hardcoded Secrets

Keeping Sensitive Values Out of Version Control

# anti-pattern
env:
  - name: DB_PASSWORD
    value: "hardcoded-secret"

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: password

Referencing a Secret rather than embedding a literal credential value directly in a manifest is a baseline requirement, not an optional hardening step, since any value committed to version control persists in that history indefinitely even if later removed from the current file state.

Consistent Formatting and Style

Reducing Diff Noise and Review Friction

yamllint manifests/

Applying a consistent YAML formatting style, indentation width, key ordering conventions, line length, across a manifest repository via an automated formatter or linter keeps diffs focused on actual content changes rather than incidental formatting churn, which otherwise makes code review meaningfully harder as unrelated formatting differences obscure the substantive change being reviewed.

Declarative Management Over Imperative Commands

kubectl apply Over Ad Hoc Edits

kubectl edit deployment web

kubectl apply -f deployment.yaml

Editing a live resource directly with kubectl edit or kubectl patch produces a change with no corresponding record in version control, creating drift between what is actually running and what the manifest repository describes; routing every change through an updated manifest applied via kubectl apply (or, more robustly, through a GitOps controller reconciling from Git automatically) keeps the manifest repository an accurate, single source of truth for cluster state.

Relationship to Best Practices Scope and Object Naming, Labeling, and Selector Guidelines

Manifest quality guidelines are the practice that ties together the naming, labeling, and selector conventions already covered into a single, concrete authoring discipline: a well-named, well-labeled, correctly selector-scoped manifest that omits resource requests, pins to a mutable tag, or embeds a hardcoded secret still fails the broader quality bar this best practices area establishes, since manifest quality requires every one of these individually necessary practices applied together, not any single one in isolation.