Skip to main content
In this lesson we’ll show how to define and create a Kubernetes Pod using a YAML manifest. Kubernetes accepts YAML (and JSON) manifests to declare objects such as Pods, ReplicaSets, Deployments, and Services. These manifests follow a consistent structure: at a minimum they generally include apiVersion, kind, and metadata; resource types that require a configuration include a spec section (for example Pods and Deployments).

​
Top-level fields (overview)

Below is a concise summary of the common top-level fields you will see in most Kubernetes manifests.
Always use the API version and fields appropriate for the object you are creating. Consult the Kubernetes API reference for the exact schema for each resource.

​
Minimal Pod YAML example

This is a minimal but complete Pod manifest that runs a single nginx container. Note the four top-level fields and correct indentation.
Key points about the example:
  • apiVersion: v1 — Pods are in the core API group (v1).
  • kind: Pod — Declares the resource type.
  • metadata.name — Unique name for the Pod within a namespace.
  • metadata.labels — Key/value pairs for selection and grouping (example: app: myapp).
  • spec.containers — A list of container definitions. Each item is a mapping with name, image, and optional settings (ports, env, resources, etc.).
  • image — The image name (from Docker Hub or another registry); include a tag if you need a specific version (for example nginx:1.21).

​
Common YAML / indentation pitfalls

  • YAML is whitespace-sensitive. Child properties must be indented more than their parent; sibling keys must align at the same indentation level.
  • Ensure that name and labels are siblings under metadata (same indentation), and that keys like app are children of labels (more indented).
  • Only include valid fields supported by the API for the given section. Unknown keys may be ignored or cause the API to reject the manifest.
Incorrect indentation, invalid field names, or the wrong apiVersion are common causes of manifest errors. Always validate YAML formatting and the resource schema before applying.

​
Create and inspect the Pod

  1. Save the YAML to a file, for example pod-definition.yaml.
  2. Create the Pod:
  1. Useful commands to inspect and debug:
Examples:
The describe output shows events (image pull errors, container start failures), labels, IP addresses, and other runtime details helpful for debugging.

​
Best practices & checklist

  • Use explicit apiVersion values that match your cluster version. For Pods, use v1.
  • Add labels so you can select and manage objects later (Deployments, Services, NetworkPolicies).
  • Specify container resources (requests/limits) in production to help scheduler decisions.
  • Lock container images to a specific tag in production (nginx:1.21), and scan images for vulnerabilities.
  • Validate manifests with kubectl apply --dry-run=client -f pod-definition.yaml or a linter like kube-score or kubeval.

​
Summary

  • Kubernetes manifests typically include apiVersion, kind, metadata, and, where applicable, spec.
  • Use spec.containers (a list) to declare one or more containers in a Pod.
  • Labels are important for selection and grouping of objects later.
  • Pay close attention to YAML indentation and use the correct apiVersion and schema for the resource you define.

Watch Video