Skip to main content
Welcome to this comprehensive guide where you’ll learn how to define and manage a Kubernetes Pod using a YAML configuration file. Kubernetes relies on declarative YAML manifests to create and update resources such as Pods, Deployments, and Services. By the end of this tutorial, you’ll understand the required fields, best practices for YAML structure, and how to deploy and inspect your Pod.

​
Table of Contents

  1. Understanding the Top-Level Fields
  2. Pod Definition Skeleton
  3. Detailed Field Breakdown
  4. Deploying Your Pod
  5. Inspecting Your Pod
  6. Summary
  7. Links and References

​
Understanding the Top-Level Fields

Every Kubernetes manifest shares four mandatory top-level fields. These fields tell Kubernetes what to create, how to version it, and any additional identifying metadata or configuration details.
YAML is indentation-sensitive. Always use spaces (not tabs) and ensure child elements are indented correctly under their parent keys.

​
Pod Definition Skeleton

Start with the minimal skeleton for a Pod manifest:
You’ll expand each section to specify your Pod’s name, labels, and container settings.

​
Detailed Field Breakdown

​
apiVersion

Defines the API group and version that Kubernetes will use to process this resource.
For Pods, it’s always:

​
kind

Specifies the type of object to create. For this tutorial:
Other common values include Deployment, Service, and ReplicaSet.

​
metadata

Contains identifying information such as the resource’s name and optional labels for grouping and selection.
  • name: A unique identifier for the Pod within its namespace.
  • labels: Arbitrary key/value pairs for organizational or selection purposes.

​
spec

Defines the desired state. In a Pod, this means listing the containers it should run.
Key points:
  • containers is a YAML list; you can define multiple containers per Pod.
  • Each container requires at least a name and image.
  • You can optionally define ports, environment variables, volume mounts, and more.
Kubernetes object names must:
  • Contain only lowercase alphanumeric characters and -.
  • Start and end with an alphanumeric character.
  • Be unique within a namespace.

​
Deploying Your Pod

  1. Save your manifest to pod-definition.yaml.
  2. Run the following command to create the Pod:
You should see:

​
Inspecting Your Pod

​
List All Pods

Sample output:

​
Describe a Pod

To view detailed status and event logs:
Key sections in the output include Labels, Containers, Conditions, and recent Events.

​
Summary

In this lesson, you learned how to:
  1. Structure a basic Kubernetes Pod manifest with the required top-level fields.
  2. Define metadata and container specifications in YAML.
  3. Deploy your Pod using kubectl create.
  4. Inspect status and logs with kubectl get and kubectl describe.
Up next, we’ll explore Deployments and how they automate pod scaling and updates.

Watch Video