Creating Deployments with YAML in Kubernetes - Step-by-Step CLI Walkthrough

Introduction

When you want to run and manage multiple copies of your app in Kubernetes, you use a Deployment. It helps keep your app running smoothly by automatically restarting or updating it. Writing a Deployment in YAML lets you tell Kubernetes exactly how to do this.

When you want to run several copies of a web app to handle more users.

When you need to update your app without downtime by rolling out changes gradually.

When you want Kubernetes to restart your app automatically if it crashes.

When you want to manage app versions and roll back if something goes wrong.

When you want to define your app setup in a file to share or reuse later.

Config File - deployment.yaml

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  labels:
    app: example-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-app
  template:
    metadata:
      labels:
        app: example-app
    spec:
      containers:
      - name: example-container
        image: nginx:1.23.3
        ports:
        - containerPort: 80

apiVersion: Specifies the Kubernetes API version to use for Deployment.

kind: Defines this resource as a Deployment.

metadata: Names and labels the Deployment for identification.

spec: Describes the desired state, including number of replicas and pod template.

replicas: Number of pod copies to run.

selector: Matches pods with the label app: example-app.

template: Defines the pod's metadata and spec, including container image and port.

Commands

This command creates the Deployment in Kubernetes using the YAML file. It tells Kubernetes to start 3 pods running the nginx container.

Terminal

kubectl apply -f deployment.yaml

Expected Output

deployment.apps/example-deployment created

This command lists all Deployments in the current namespace to verify the Deployment was created.

Terminal

kubectl get deployments

Expected Output

NAME                READY   UP-TO-DATE   AVAILABLE   AGE

example-deployment   3/3     3            3           10s

This command lists all pods with the label app=example-app to check that the pods are running as expected.

Terminal

kubectl get pods -l app=example-app

Expected Output

NAME                                  READY   STATUS    RESTARTS   AGE

example-deployment-6d4b75f7d7-abc12  1/1     Running   0          10s

example-deployment-6d4b75f7d7-def34  1/1     Running   0          10s

example-deployment-6d4b75f7d7-ghi56  1/1     Running   0          10s

→

-l - Filter pods by label

This command shows detailed information about the Deployment, including events and pod status.

Terminal

kubectl describe deployment example-deployment

Expected Output

Name:                   example-deployment

Namespace:              default

CreationTimestamp:      Thu, 01 Jun 2023 12:00:00 +0000

Labels:                 app=example-app

Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable

StrategyType:           RollingUpdate

Pods Status:            3 Running / 0 Waiting / 0 Succeeded / 0 Failed

Events:

  Type    Reason             Age   From                   Message

  ----    ------             ----  ----                   -------

  Normal  ScalingReplicaSet  1m    deployment-controller  Scaled up replica set example-deployment-6d4b75f7d7 to 3

Key Concept

If you remember nothing else from this pattern, remember: a Deployment manages multiple copies of your app and keeps them running as you defined in the YAML file.

Common Mistakes

Not matching the selector labels with the pod template labels

Kubernetes won't know which pods belong to the Deployment, so it won't manage them properly.

Ensure the selector.matchLabels exactly matches the labels in template.metadata.labels.

Forgetting to specify the container image in the pod template

Pods won't start because Kubernetes doesn't know what container to run.

Always include the container image under spec.template.spec.containers.

Applying the YAML file without saving changes

Kubernetes applies the old configuration, so your updates don't take effect.

Save the YAML file after editing before running kubectl apply.

Summary

Write a Deployment YAML file to define how many app copies to run and what container to use.

Use 'kubectl apply -f deployment.yaml' to create or update the Deployment in Kubernetes.

Check the Deployment and pods with 'kubectl get deployments' and 'kubectl get pods -l app=example-app' to confirm they are running.