Creating Your First Pod Manifest: A Kubernetes YAML Guide

Previously in this course, we explored The Pod: The Smallest Unit of Execution in Kubernetes. Now that you understand why Pods are the fundamental building block of your cluster, it is time to move beyond imperative kubectl run commands and define them using YAML.

Writing a Pod manifest is the bread and butter of daily operations in Kubernetes. A manifest is a YAML (YAML Ain't Markup Language) file that acts as a blueprint. It tells the Kubernetes API exactly what state you want your cluster to maintain.

The Anatomy of a Pod Specification

Every Kubernetes object requires four top-level fields in its specification. These fields tell the cluster who you are, what kind of object you're creating, and the details of the configuration.

1. apiVersion: Which version of the Kubernetes API to use (e.g., v1).
2. kind: The type of resource you are creating (in this case, Pod).
3. metadata: Data that uniquely identifies the object, like its name or labels.
4. spec: The actual desired state, where we define containers, images, and ports.

Writing Your First Manifest

Let's create a manifest for a simple web server using the official Nginx image. Create a file named nginx-pod.yaml and add the following content:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: my-first-pod
  labels:
    app: web-server
spec:
  containers:
  - name: nginx-container
    image: nginx:latest
    ports:
    - containerPort: 80

Breaking Down the Specification

• containers: This is a list (indicated by the - dash). Kubernetes allows multiple containers in a single Pod, though usually, we keep it to one for simple apps.
• image: This points to the container registry. nginx:latest tells the Kubelet to pull the latest version of Nginx from Docker Hub.
• ports: This is documentation for the cluster. By defining containerPort: 80, you are explicitly stating that this container is listening on port 80. While not strictly required for the container to start, it is best practice for service discovery and documentation.

Hands-on Exercise: Define Your Own Pod

Now it's your turn to get hands-on.

1. Create a new file called hello-world.yaml.
2. Define a Pod named hello-pod.
3. Use the busybox image.
4. Set the command to run ["echo", "Hello from Kubernetes!"]. (Hint: You will need to add a command: field under the container spec).
5. Save the file. Don't worry about applying it yet—we will cover the application process in the next lesson.

Common Pitfalls

Even experienced engineers trip over these YAML nuances:

• Indentation Errors: YAML is strictly whitespace-dependent. Never use tabs; always use two spaces for each level of nesting.
• Case Sensitivity: Kubernetes fields are case-sensitive. apiVersion is correct; apiversion will result in a validation error.
• The "List" Dash: Newcomers often forget the - before the container name. If you omit that dash, Kubernetes interprets containers as a single object rather than a list, which will cause the manifest to fail validation.
• Hardcoding Versions: Using :latest in production is a dangerous practice because it makes deployments unpredictable. Always pin your images to a specific version (e.g., nginx:1.25) to ensure your environment stays consistent across different runs.

Frequently Asked Questions

Does the order of fields in YAML matter? Generally, no. As long as the indentation levels are correct, the order within a scope (like metadata or spec) does not affect the outcome.

Can I put multiple containers in one Pod? Yes, but they will share the same network namespace and storage. This is typically used for "sidecar" patterns, which we will cover later in the course.

How do I know what fields are available for a Pod? You can use kubectl explain pod.spec in your terminal. This is a built-in documentation tool that saves you from searching the web for every configuration option.

Recap

We have moved from the concept of a Pod to the practical YAML definition required to create one. By defining the apiVersion, kind, metadata, and spec, you have created a declarative manifest that serves as the foundation for all your future deployments.

Up next: Applying Manifests to the Cluster, where we will take this YAML file and actually spin up the Pod in your local cluster.