Creating Deployments with YAML in Kubernetes - Mechanics & Internals

Overview - Creating Deployments with YAML

What is it?

Creating Deployments with YAML means writing a simple text file that tells Kubernetes how to run and manage your application. This file describes what your app looks like, how many copies to run, and how to update it safely. Kubernetes reads this file and makes sure your app runs exactly as you described. It helps automate running apps in a consistent and reliable way.

Why it matters

Without YAML Deployments, managing apps on Kubernetes would be manual and error-prone. You would have to start, stop, and update each app copy by hand, which is slow and risky. YAML files let you declare your app setup once, and Kubernetes keeps it running smoothly. This saves time, reduces mistakes, and helps apps stay available even during updates or failures.

Where it fits

Before learning this, you should understand basic Kubernetes concepts like Pods and Containers. After this, you can learn about advanced Deployment features like rolling updates, scaling, and strategies for zero downtime. This topic is a key step in mastering Kubernetes app management.

Mental Model

Core Idea

A Deployment YAML file is a clear instruction sheet that tells Kubernetes how many app copies to run, what app to run, and how to keep it running smoothly.

Think of it like...

It's like giving a recipe to a kitchen robot: you specify the dish, how many servings, and the robot keeps cooking more if some servings run out or need replacing.

┌───────────────────────────────┐
│        Deployment YAML         │
├─────────────┬─────────────────┤
│ replicas    │ Number of copies│
│ template    │ Pod description │
│   ├── spec  │ Container info  │
│   └── metadata│ Labels         │
│ selector    │ Which Pods to manage│
└─────────────┴─────────────────┘
        ↓
┌───────────────────────────────┐
│      Kubernetes Deployment     │
│  Creates and manages Pods      │
│  Ensures desired replicas run  │
│  Handles updates and rollbacks │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Kubernetes Pods

Concept: Pods are the smallest units in Kubernetes that run your app containers.

A Pod is like a small box that holds one or more containers running your app. It has its own IP address and storage. Pods are temporary and can be replaced if they fail.

Result

You know that Pods run your app containers and are the building blocks for Deployments.

Understanding Pods is essential because Deployments manage these Pods to keep your app running.

2

Foundation

What is a Deployment in Kubernetes

Concept: A Deployment manages multiple copies of Pods and handles updates automatically.

Instead of running Pods manually, a Deployment lets you say how many copies you want. It watches the Pods and replaces any that fail. It also updates Pods one by one when you change the app version.

Result

You see that Deployments automate running and updating your app copies.

Knowing Deployments exist helps you avoid manual, error-prone app management.

3

Intermediate

Basic Structure of Deployment YAML

🤔Before reading on: do you think a Deployment YAML only needs the app name and replicas, or does it also need container details? Commit to your answer.

Concept: A Deployment YAML includes metadata, replicas count, selector, and a Pod template with container specs.

A typical Deployment YAML has: - apiVersion and kind to identify it - metadata with name - spec with replicas (how many Pods) - selector to match Pods - template describing the Pods, including containers and images Example snippet: apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 3 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp-container image: myapp:1.0

Result

You can write a Deployment YAML that tells Kubernetes what app to run and how many copies.

Knowing the YAML structure lets you customize your app deployment precisely.

4

Intermediate

Applying Deployment YAML with kubectl

🤔Before reading on: do you think 'kubectl apply' creates or updates a Deployment, or only creates it? Commit to your answer.

Concept: The kubectl command applies your YAML to create or update Deployments in the cluster.

Use the command: kubectl apply -f deployment.yaml This tells Kubernetes to create the Deployment if it doesn't exist or update it if it does. You can check status with: kubectl get deployments kubectl describe deployment myapp

Result

Your app runs in Kubernetes as described in your YAML, and you can update it by changing the YAML and reapplying.

Understanding kubectl apply lets you manage app lifecycles declaratively.

5

Intermediate

Labels and Selectors in Deployments

🤔Before reading on: do you think selectors match Pods by name or by labels? Commit to your answer.

Concept: Selectors use labels to identify which Pods belong to the Deployment.

Labels are key-value pairs attached to Pods. The Deployment's selector matches these labels to manage the right Pods. For example, if Pods have label app: myapp, the selector matches Pods with that label. This ensures the Deployment controls only its own Pods.

Result

You understand how Deployments find and manage the correct Pods.

Knowing labels and selectors prevents mistakes where Deployments manage wrong or no Pods.

6

Advanced

Rolling Updates with Deployment YAML

🤔Before reading on: do you think Kubernetes replaces all Pods at once during update or one by one? Commit to your answer.

Concept: Deployments update Pods gradually to avoid downtime using rolling updates.

When you change the container image version in the YAML and apply it, Kubernetes creates new Pods with the new version and deletes old Pods slowly. This keeps the app available during updates. You can control update speed with parameters like maxUnavailable and maxSurge.

Result

Your app updates smoothly without downtime.

Understanding rolling updates helps you deploy changes safely in production.

7

Expert

Advanced Deployment Strategies and Pitfalls

🤔Before reading on: do you think setting replicas to zero deletes the Deployment or just stops Pods? Commit to your answer.

Concept: Deployments support advanced update strategies and have subtle behaviors that can cause issues if misunderstood.

Besides rolling updates, you can use strategies like Recreate (stop all old Pods before starting new ones). Setting replicas to zero stops all Pods but keeps the Deployment object. Also, mismatched selectors and labels can cause Deployments to fail managing Pods. YAML indentation or syntax errors can silently break deployments. Experts use tools like kubectl diff and dry-run to catch mistakes before applying.

Result

You can design complex update flows and avoid common deployment errors.

Knowing these advanced details prevents costly downtime and debugging headaches in real systems.

Under the Hood

Kubernetes Deployment controller continuously watches the Deployment YAML and the cluster state. It compares desired replicas and Pod specs with actual running Pods. If there are fewer Pods than desired, it creates new Pods using the Pod template. If there are extra or outdated Pods, it deletes them. During updates, it creates new Pods with the updated spec and removes old Pods gradually, ensuring availability. Labels and selectors link Pods to Deployments, enabling precise control.

Why designed this way?

This design allows declarative management: users declare desired state, and Kubernetes handles the complex steps to reach it. It separates the 'what' from the 'how,' making app management reliable and scalable. Alternatives like manual Pod management were error-prone and did not support smooth updates or self-healing.

┌───────────────┐
│ Deployment YAML│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Deployment    │
│ Controller    │
└──────┬────────┘
       │ Watches desired state
       ▼
┌───────────────┐
│ Pod Template  │
└──────┬────────┘
       │ Creates Pods
       ▼
┌───────────────┐
│ Running Pods  │
│ (with labels) │
└──────┬────────┘
       │ Reports status
       └─────────────┐
                     ▼
             ┌───────────────┐
             │ Deployment    │
             │ Controller    │
             └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does changing the Deployment YAML always immediately update running Pods? Commit yes or no.

Common Belief: Changing the Deployment YAML instantly changes all running Pods to the new version.

Reality: Kubernetes performs rolling updates gradually; Pods are replaced one by one to avoid downtime.

Why it matters: Assuming instant updates can lead to confusion when old Pods still run, causing unexpected app behavior.

Quick: Do you think a Deployment manages Pods without matching labels? Commit yes or no.

Common Belief: Deployments manage any Pods with the same name, regardless of labels.

Reality: Deployments only manage Pods whose labels match the Deployment's selector exactly.

Why it matters: Incorrect labels cause Deployments to lose control of Pods, leading to orphaned or unmanaged Pods.

Quick: Does setting replicas to zero delete the Deployment object? Commit yes or no.

Common Belief: Setting replicas to zero deletes the Deployment entirely.

Reality: It only stops all Pods but keeps the Deployment object intact for future scaling.

Why it matters: Misunderstanding this can cause accidental deletion or confusion about app state.

Quick: Can you use kubectl apply with any YAML file to update a Deployment? Commit yes or no.

Common Belief: Any YAML file with a Deployment name can update the Deployment, even if incomplete.

Reality: The YAML must be complete and valid; missing fields or syntax errors can cause failed or partial updates.

Why it matters: Applying incomplete YAML can break your Deployment silently, causing downtime or misconfiguration.

Expert Zone

1

Deployments rely heavily on label selectors; even a small mismatch can cause Pods to be unmanaged, which is a common silent failure in production.

2

The rolling update strategy parameters (maxUnavailable and maxSurge) allow fine control over update speed and availability, but misconfiguration can cause downtime or resource spikes.

3

kubectl apply uses a client-side cache and a three-way merge patch; understanding this helps debug why some YAML changes do not apply as expected.

When NOT to use

Deployments are not ideal for stateful applications that require stable network IDs or storage; StatefulSets are better suited there. Also, for simple one-off jobs, Jobs or CronJobs are more appropriate than Deployments.

Production Patterns

In production, teams use Deployment YAMLs stored in Git repositories for version control and use CI/CD pipelines to apply changes automatically. They often combine Deployments with Horizontal Pod Autoscalers to scale apps based on load and use readiness probes to ensure traffic only goes to healthy Pods.

Connections

Infrastructure as Code (IaC)

Both use declarative files to define desired system state.

Understanding Deployment YAML helps grasp how IaC tools like Terraform or Ansible declare infrastructure, enabling consistent and repeatable setups.

Load Balancing

Deployments create multiple Pods that a load balancer distributes traffic to.

Knowing how Deployments manage replicas clarifies how load balancers achieve high availability and distribute user requests evenly.

Factory Production Lines

Deployments automate creating and replacing Pods like a factory line producing and swapping products.

Seeing Deployments as automated production lines helps understand their role in maintaining consistent app availability and quality.

Common Pitfalls

#1 Using mismatched labels and selectors causing Pods not to be managed.

Wrong approach:

spec:
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp-v2

Correct approach:

spec:
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp

Root cause:

The selector and Pod template labels must match exactly for the Deployment to manage Pods.

#2 Applying incomplete or invalid YAML causing Deployment failure.

Wrong approach:

apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 3
template:
spec:
containers:
- name: myapp-container
image: myapp:1.0

Correct approach:

apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 3
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp-container
image: myapp:1.0

Root cause:

Missing selector and labels cause Kubernetes to reject or mismanage the Deployment.

#3 Expecting immediate Pod replacement on Deployment update.

Wrong approach:

Change image tag in YAML and assume all Pods update instantly without checking rollout status.

Correct approach:

After applying YAML changes, run 'kubectl rollout status deployment/myapp' to monitor gradual Pod updates.

Root cause:

Not understanding rolling update behavior leads to confusion about app version running.

Key Takeaways

Deployment YAML files declare how many copies of your app Kubernetes should run and how to run them.

Labels and selectors link Deployments to the Pods they manage; mismatches cause management failures.

kubectl apply lets you create or update Deployments declaratively, enabling smooth app lifecycle management.

Rolling updates replace Pods gradually to keep apps available during changes.

Advanced Deployment features and careful YAML syntax are crucial to avoid downtime and errors in production.