Kubernetes YAML Explained: Deployments, Services, and What Your AI Writes

Quick answer
A Kubernetes manifest is YAML describing one object: what you want, not how to do it.
Four fields carry the meaning: apiVersion and kind say what it is, metadata names it, spec declares the desired state.
A Deployment says which image to run and how many replicas; a Service says how to reach the pods.
The fields that break deployments are selectors, image tags, ports, and resource blocks.
Read a generated manifest by scanning spec first, then labels and selectors, then anything missing.

What is a Kubernetes manifest?

A manifest is a YAML file describing one Kubernetes object and the state you want it in. You apply it with kubectl, and controllers work continuously to make the cluster match. Every manifest has the same outer shape: apiVersion and kind identify the object type, metadata gives it a name and labels, and spec holds the object-specific configuration. Once you can read that shape, unfamiliar objects become readable quickly because the skeleton is always the same.

What does a Deployment look like?

A Deployment declares a pod template and a replica count, then manages pods to match. The two parts that cause the most trouble are the selector, which must match the template’s labels exactly, and the container spec, where the image, ports, and resources live.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api      # must match template labels below
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: ghcr.io/acme/api:1.4.2   # pin the tag
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi

What does a Service look like?

A Service gives a stable DNS name and address to a set of pods, selected by label. It does not run anything; it routes. The selector must match the pod labels from the Deployment, and targetPort must match the port the container actually listens on.

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 3000

Which fields actually matter?

Most of a manifest is boilerplate. The load-bearing fields are: the image tag (pin it), the selector and labels (they must match), containerPort and targetPort (they must line up), the resource requests and limits, health probes, and any env or volume references. If those are correct, the object usually behaves; if one is wrong, the failure mode is often silent. Producing valid YAML is easy — producing YAML that matches the cluster’s expectations is the skill.

How do I review a manifest my AI generated?

Read in this order: does the image have a concrete tag; do the selector labels match the template labels exactly; does targetPort match the port the app listens on; are resource requests and limits present; are readiness and liveness probes defined; does anything reference a ConfigMap or Secret that does not exist. Those six questions catch the overwhelming majority of generated manifests that apply cleanly and then fail.

Where this bites vibecoders
Generated manifests are syntactically perfect and semantically approximate. The assistant knows the schema, so the YAML applies without error, but it does not know your app listens on port 8080 rather than 3000, or that your image is only published for the amd64 architecture, or that your service needs 512 MB before it will pass a health check. The result is a manifest set that reports success and a pod that crash-loops for a reason nowhere in the YAML. Reviewing the six fields above, against what the app actually does, is how you close that gap.

Where AI coding assistants get this wrong

Using the latest tag or omitting the tag entirely.
Mismatching Service selectors and pod template labels.
Setting targetPort to a port the app does not listen on.
Omitting resource requests and limits.
Referencing a ConfigMap, Secret, or volume that does not exist.
Copying apiVersion values from an older Kubernetes version that the cluster rejects.

Checklist

Pin a concrete image tag on every container.
Verify selector labels match the pod template exactly.
Confirm targetPort matches the port the app binds.
Set CPU and memory requests and limits.
Define readiness and liveness probes.
Apply with –dry-run=server to catch schema issues early.

FAQ

What is the difference between a manifest and a Helm chart?

A manifest is a single static object. A Helm chart is a package of templated manifests plus default values, so one chart can deploy the same application with different settings. You can start with plain manifests and adopt Helm later.

Why does kubectl apply succeed but the pod never starts?

Applying only validates that the object is well-formed; it does not check that the image is pullable, that the port matches, or that a referenced Secret exists. Run kubectl describe pod and read the events, which name the actual failure.

Can I keep all my objects in one YAML file?

Yes. Separate documents with a line containing three dashes, and kubectl apply -f processes them in order. Many teams keep one file per object for readability and diffing.