Writing a Pod Manifest

A manifest is a YAML file that declares the desired state of a Kubernetes object such as a Pod.

SyntaxapiVersion: v1 kind: Pod metadata: name: <name> spec: containers: - name: <name> image: <image>

The proper way to create objects is with a manifest — a YAML file you hand to kubectl apply. Every manifest has four top-level fields.

The four required fields

  • apiVersion — which API group/version the object belongs to (Pods use v1).
  • kind — the type of object, e.g. Pod.
  • metadata — a name and optional labels.
  • spec — the desired state (which containers, images, ports).

Indentation matters in YAML — always use spaces, never tabs.

Example

Example · yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80

When to use it

  • A team stores all pod manifests in Git so every change is reviewed and the cluster state is fully reproducible from source control.
  • A developer adds resource requests and limits directly in the pod manifest so the scheduler places it on the right node from the start.
  • An SRE adds restart-policy annotations in the manifest to ensure one-off jobs do not restart on completion.

More examples

Annotated pod manifest fields

Shows all key manifest fields with inline comments explaining what each section does for new Kubernetes users.

Example · yaml
apiVersion: v1          # Kubernetes API version
kind: Pod               # Resource type
metadata:
  name: web             # Unique name in namespace
  namespace: production
  labels:
    app: web
    version: v2
spec:
  containers:
    - name: web
      image: nginx:1.25
      ports:
        - containerPort: 80

Pod with resource limits

Adds resource requests (scheduling hint) and limits (enforcement cap) to the container spec within the pod manifest.

Example · yaml
apiVersion: v1
kind: Pod
metadata:
  name: cpu-limited
spec:
  containers:
    - name: app
      image: myapp:1.0
      resources:
        requests:
          cpu: "250m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "256Mi"

Generate manifest from imperative command

Uses --dry-run=client -o yaml to generate a starter pod manifest without creating anything, then saves it for editing.

Example · bash
kubectl run nginx --image=nginx:1.25 \
  --port=80 \
  --dry-run=client \
  -o yaml > pod.yaml

cat pod.yaml

Related

k8s pods introk8s multi container pods

Discussion

  • Be the first to comment on this lesson.