Defining a Deployment Manifest

A Deployment provides a method for managing your application's desired state within Kubernetes. A Deployment manifest is a YAML file that describes this desired state. Instead of telling Kubernetes what to do step-by-step, you tell it what you want the end result to be. The Deployment controller then works to make the cluster's current state match your declared state.

This approach is more reliable and predictable. The manifest serves as version-controlled documentation for your application's deployment, defining everything from the container image to the number of running replicas and the strategy for updates.

The Anatomy of a Deployment Manifest

A Deployment manifest builds upon the structure of a Pod manifest by adding fields to manage replication and updates. Let's examine a typical manifest for an Nginx web server.

# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21.6
        ports:
        - containerPort: 80

This manifest has four required top-level fields: apiVersion, kind, metadata, and spec.

• apiVersion: apps/v1: This specifies the Kubernetes API version being used to create this object. Deployments are part of the apps API group, and v1 is the stable version.
• kind: Deployment: This identifies the type of object being created.
• metadata: This contains data that helps uniquely identify the object, such as its name and descriptive labels. While labels on the Deployment object itself are for organizational purposes, the labels inside the spec have a functional role.
• spec: This is where you define the desired state for the Deployment. This section is the most important and contains the logic for how the application will run.

The Deployment Specification (spec)

The spec field is the heart of the Deployment, detailing the controller's instructions. It consists of three primary fields: replicas, selector, and template.

replicas

This field is straightforward. It specifies the desired number of Pods you want to run. In our example, replicas: 3 tells Kubernetes to ensure that three Pods matching this application's template are running at all times. If a Pod fails, the controller will automatically create a new one to maintain the count of three.

selector

The selector field tells the Deployment controller which Pods to manage. It does this by matching the labels defined in matchLabels. In our example, the selector is { "matchLabels": { "app": "nginx" } }. This means the Deployment will look for and manage any Pods that have the label app: nginx.

This link between the controller's selector and the Pods' labels is fundamental. The selector must match the labels assigned to the Pods in the template section. If they do not match, the Deployment will create Pods but will not be able to find them, leading to an endless loop of Pod creation.

template

The template field (spec.template) is a blueprint for the Pods that the Deployment will create. Its contents are nearly identical to a standalone Pod manifest, containing its own metadata and spec.

• template.metadata.labels: These are the labels applied to each Pod created by the Deployment. It is essential that these labels match the spec.selector.matchLabels of the Deployment. In our example, app: nginx in the template matches the selector, correctly linking the Pods to the Deployment.
• template.spec: This defines the specification for the containers that will run inside each Pod, just like a standard Pod manifest. You specify the container name, the container image to use, and any ports the container will expose.

The diagram below illustrates how these components are connected. The Deployment doesn't directly manage Pods. Instead, it manages a ReplicaSet, which in turn ensures the correct number of Pods are running. The selector is the mechanism that links all three objects together.

The Deployment creates and manages a ReplicaSet. The selector defined in the Deployment spec is used by the ReplicaSet to identify and manage the Pods, which are created based on the Pod template.

When you apply this manifest using a command like kubectl apply -f nginx-deployment.yaml, the Kubernetes control plane reads it and creates a Deployment object. The Deployment controller then creates a corresponding ReplicaSet, and the ReplicaSet controller creates the three Pods. From that point on, the controllers work continuously to ensure the cluster state matches this definition.