Writing a Pod Manifest in YAML

To create a Pod in Kubernetes, you define its desired state in a YAML file known as a manifest. This file acts as a blueprint, telling the Kubernetes control plane exactly what you want to run. While you can create Pods imperatively using command-line arguments, the declarative approach using manifests is the standard for production environments because it allows for version control, repeatability, and easier management of complex configurations.

A Pod manifest is structured with several required top-level fields. Let's examine the essential components you will use to define any Pod.

The Anatomy of a Pod Manifest

Every Kubernetes object manifest, including a Pod's, contains four primary fields: apiVersion, kind, metadata, and spec.

The hierarchical structure of a Kubernetes Pod manifest, showing the required fields and nested configuration for defining a container.

1. apiVersion: This field specifies which version of the Kubernetes API you are using to create this object. For core objects like Pods, Services, and ConfigMaps, the version is v1. For other objects like Deployments or ReplicaSets, you will use different API versions, such as apps/v1. The API version determines the valid structure and fields for the object.

2. kind: This field specifies the type of Kubernetes object you want to create. To create a Pod, you set this value to Pod. This tells Kubernetes what kind of resource the manifest describes.

3. metadata: This is an object that contains data to help uniquely identify the resource. The two most common fields within metadata are:

   • name: A unique name for the Pod within its namespace. For example, webapp-pod-xyz.
   • labels: A map of key-value pairs that are attached to the object. Labels are used for organization and to allow other resources, like Services, to select and operate on groups of Pods. For instance, you might label all your web server Pods with app: frontend.

4. spec (Specification): This field is where you define the desired state of the object. The content of the spec varies significantly between different kinds of Kubernetes objects. For a Pod, the spec primarily describes the containers that should run within it. The most important field inside the spec is containers.

Defining the Containers

The spec.containers field is a list, meaning a Pod can contain one or more containers. Each item in this list is a container object with its own set of attributes. At a minimum, you must provide:

• name: A name for the container within the Pod. This is useful for logging and identification, especially in multi-container Pods.
• image: The container image to run, specified in the same format as you would for Docker, such as nginx:1.21.6 or your-repo/your-app:v2. Kubernetes will pull this image from a container registry.
• ports: A list of network ports to expose from the container. The containerPort specifies the port number that the application inside the container is listening on. Note that this does not expose the port outside the Pod; it is purely informational for other Kubernetes components. Exposing the application to the network requires a Service, which we will cover in a later chapter.

Example: A Single-Container Pod Manifest

Let's put these pieces together into a complete manifest file. This example defines a simple Pod named nginx-pod that runs a single container using the official Nginx image.

Create a file named nginx-pod.yaml and add the following content:

# nginx-pod.yaml

# Specifies the API version. 'v1' is the core API group.
apiVersion: v1

# Specifies the object type. In this case, it's a Pod.
kind: Pod

# Contains metadata for the Pod, like its name and labels.
metadata:
  # The unique name for this Pod within the namespace.
  name: nginx-pod
  # Labels are key-value pairs for organization and selection.
  labels:
    app: webserver

# Defines the desired state of the Pod.
spec:
  # A list of containers to run inside the Pod.
  containers:
    # Each item in the list is a container definition.
  - name: nginx-container
    # The Docker image to use for this container.
    image: nginx:1.21.6
    # A list of ports to expose from the container.
    ports:
    - containerPort: 80

This manifest is a declarative instruction. It does not say how to create the Pod, but rather what the final state of the Pod should be. When you apply this manifest to a cluster, the Kubernetes control plane reads it and works to match the cluster's actual state to this desired state. If a Pod named nginx-pod does not exist, it will be created.

To apply this manifest, you would use the kubectl command-line tool, which we will explore in detail later in this chapter:

kubectl apply -f nginx-pod.yaml

This command sends the manifest to the Kubernetes API server, which then schedules the Pod to run on a worker node. With this foundational understanding of the manifest structure, you are now prepared to define both simple and more complex Pod configurations.