Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 78 ยท Getting Started

YAML and the Shape of a Manifest

Learn the apiVersion, kind, metadata, spec and status layout of Kubernetes manifests, labels, multi-document files and the YAML traps that bite beginners.

Almost everything you do in Kubernetes is described in a text file called a manifest, written in YAML. A manifest is a description of one object you want to exist. Once you know its four-part shape you can read any manifest, even for resources you have never met, and you will recognise a broken one at a glance.

This lesson covers that shape, labels and annotations, files that hold several objects, and the YAML traps that cause the most confusing errors. A Python stand-in validates manifests the way a very small API server would.

Every manifest has four parts

apiVersion Which API group and version.
kind What type of object.
metadata Name, namespace, labels.
spec The state you want.

The cluster adds a fifth part, status, itself.

1 / 2

The four top-level fields

Here is a complete, minimal manifest for a pod:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: hello
  namespace: default
  labels:
    app: hello
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - containerPort: 80
  • apiVersion says which part of the API defines the object and at which version. Core objects such as Pods and Services use v1; Deployments use apps/v1; Jobs use batch/v1. The next lesson explains the scheme.
  • kind is the type of object: Pod, Service, Deployment, and so on.
  • metadata identifies the object. name is required (and must be unique per kind in a namespace). namespace, labels and annotations are optional.
  • spec is the desired state, and its fields depend on the kind. A Pod's spec lists containers; a Deployment's spec lists replicas and a pod template.

When you read the object back from the cluster, a fifth field, status, appears. It holds the observed state, written by controllers and the kubelet (for example phase: Running and the pod's IP). You never write status yourself. This spec versus status split is the desired and actual state from What Is Kubernetes? made concrete.

Besides the name you give, the API server adds fields to metadata: a unique uid, a creationTimestamp and the resourceVersion discussed in Cluster Architecture.

Labels and annotations

Both are key-value maps in metadata, but they serve different purposes.

Labels identify and group objects. Other objects select by them: a Service picks pods with a label, a Deployment owns pods with a label. Keys and values are short strings with strict character rules.

Annotations attach arbitrary information that tools may read but that is never used for selection: a build URL, a contact, a configuration hint for an ingress controller. Values can be long.

YAML
metadata:
  name: hello
  labels:
    app.kubernetes.io/name: hello
    environment: staging
  annotations:
    owner: "[email protected]"
    build-url: "https://ci.example.com/builds/1873"

The next chapter, Labels, Selectors and Annotations, goes deeper.

Several objects in one file

A single YAML file may contain many documents separated by a line with three dashes. kubectl apply -f creates them in order, which lets you keep an app's Deployment and Service together:

YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-config
data:
  GREETING: "hello"
---
apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  selector:
    app: hello
  ports:
    - port: 80

You can also point kubectl apply -f at a directory to apply every file inside it.

YAML pitfalls

YAML is friendly to read and unforgiving to write. These problems cause many beginner errors.

Indentation is structure. Use spaces, never tabs; two per level is the convention. A list item (- name: web) opens a new map, and its sibling keys must align with name, not with the dash.

Strings and numbers. A value that looks like a number becomes a number. Environment variable values, annotations and many other fields must be strings, so quote them. Writing value: 8080 where a string is required is rejected, while value: "8080" is accepted. The same applies to the words true, false, yes, no, on, off, and to null or ~.

The Norway problem. In YAML 1.1, the version many parsers still implement, the unquoted value NO means boolean false. A country-code list [SE, NO, DK] becomes ["SE", false, "DK"]. Kubernetes parses YAML with a 1.1-compatible library, so quote anything that might be read as a boolean or number: "NO", "1.10", "0755".

Multi-line strings. | keeps newlines (good for scripts and config files), > folds them into spaces.

YAML
data:
  start.sh: |
    #!/bin/sh
    echo starting
    exec nginx -g 'daemon off;'

Seeing the traps in action

The stand-in below uses PyYAML, which also implements the 1.1 rules, to show what the parser really produces. This is the same trap Kubernetes users meet.

Python YAML types you did not expect

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output shows version: 1.10 turning into the float 1.1, 0755 into the integer 493 (an octal number), NO and yes into booleans. Always quote values whose type matters.

A small manifest validator

Real API servers validate against detailed schemas. This stand-in checks the four structural rules every object must pass, plus a rule from the label syntax, and then reports every problem rather than just the first one.

Python Validate manifests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second document trips three rules at once, and the last one is missing most of its structure. Real validation (kubectl apply --dry-run=server) is far more detailed, but the idea is the same: the shape comes first, the details second.

Use an editor with a Kubernetes or YAML schema plugin and run kubectl apply --dry-run=server -f file.yaml in your pipeline. Both catch typos long before a deployment does.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which top-level field of a manifest holds the desired state?

    spec is what you want; status is what the cluster observes and is written by the system, not by you.
  2. 2. What is the difference between a label and an annotation?

    Selectors only work on labels. Annotations hold arbitrary, often long, metadata for tools and humans.
  3. 3. In a YAML 1.1 parser, what does the unquoted value NO in a list of country codes become?

    This is the Norway problem. Quote the value as "NO" to keep it a string.
  4. 4. How do you put a Deployment and its Service in one file?

    A YAML stream can hold several documents separated by ---, and kubectl apply -f processes each in order.

Summary

  • Every manifest has apiVersion, kind, metadata and spec; the cluster adds status.
  • Labels select and group objects; annotations carry free-form information.
  • One file can hold many objects separated by ---.
  • Use spaces, and quote values whose type matters: numbers, versions, yes/no/on/off, and codes such as NO.
  • The validator above is a stand-in; use --dry-run=server and schema-aware editors for real checks.

Next, see where apiVersion and kind come from: The Kubernetes API, Resources and Versions.