Skip to main content
Kubernetes Introduction
CHAPTER 05 Intermediate

Kubernetes YAML Configuration Files

Updated: May 15, 2026
25 min read

# CHAPTER 5

Kubernetes YAML Configuration Files

1. Introduction

In Docker, we learned to move away from messy docker run commands and utilize docker-compose.yml files. Kubernetes demands the exact same evolution, but at an enterprise scale. Kubernetes is a heavily declarative system. Instead of giving the API server a list of commands to execute, you provide it with a Manifest File (written in YAML) describing the exact architecture you desire. In this chapter, we will dissect the anatomy of Kubernetes YAML manifests, mastering the apiVersion, kind, metadata, and spec blocks.

2. Learning Objectives

By the end of this chapter, you will be able to:
  • Understand the paradigm of Declarative Infrastructure.
  • Deconstruct the 4 mandatory root fields of a Kubernetes YAML file.
  • Author a valid Pod manifest from scratch.
  • Apply and delete manifests using kubectl apply -f.
  • Understand the critical importance of Labels and Selectors.

3. Beginner-Friendly Explanation

Imagine ordering a custom house from an architect.
  • Imperative (The Old Way): You stand in an empty field and yell commands at construction workers. "Put a brick here! Put a window there! Wait, move the window left!" It is exhausting and hard to replicate.
  • Declarative (The Kubernetes Way): You hand the construction workers a highly detailed, stamped Blueprint (The YAML file). You walk away. The workers look at the blueprint and do whatever is mathematically necessary to build exactly what the blueprint says. If a tornado destroys a wall, the workers look at the blueprint and rebuild the wall automatically.

4. The 4 Mandatory Root Fields

Every single Kubernetes YAML file, whether it is for a tiny Pod or a massive Load Balancer, MUST contain these 4 root-level fields:
  1. 1. apiVersion: Which version of the Kubernetes API are you talking to? (e.g., v1, apps/v1).
  1. 2. kind: What type of object are you trying to create? (e.g., Pod, Service, Deployment).
  1. 3. metadata: Data that helps identify the object. This must include a name, and optionally labels.
  1. 4. spec: The most important part. The SPECification. This defines the "Desired State" of the object (e.g., which Docker image to use, which ports to open).

5. Breaking Down a Pod YAML

Let's look at a complete Pod manifest:
yaml
12345678910111213 
apiVersion: v1
kind: Pod
metadata:
  name: my-nginx-pod
  labels:
    app: frontend
    tier: web
spec:
  containers:
    - name: nginx-container
      image: nginx:alpine
      ports:
        - containerPort: 80

*Notice the indentation! YAML relies on strict spaces (usually 2 spaces per indentation level) to define nested relationships. A misplaced space will break the file.*

6. Labels and Selectors (The Glue)

In the metadata block above, we added labels: app: frontend. Labels are incredibly important. Kubernetes relies on a system of tags to group objects. If you have 500 Pods running, how do you know which ones belong to the billing department and which belong to the frontend? You use Labels. Later, we will use Selectors to tell a Load Balancer: "Please route traffic ONLY to Pods that have the label app: frontend." Labels are the glue that connects disparate Kubernetes objects together.

7. Mini Project: Author and Apply a YAML File

Let's stop typing terminal commands and build real Infrastructure as Code.

Step-by-Step Tutorial:

  1. 1. On your laptop, create a folder named k8s-basics.
  1. 2. Inside, create a file named pod.yaml.
  1. 3. Type (do not copy/paste, practice the syntax!) the YAML code from Section 5 above into the file and save it.
  1. 4. Open your terminal in that folder. Send the blueprint to Kubernetes:

bash
1 
kubectl apply -f pod.yaml

*(The -f flag stands for filename).*

  1. 5. Verify the API server accepted your blueprint:

bash
1 
kubectl get pods
  1. 6. Now, let's test Declarative State. Open pod.yaml and change the label tier: web to tier: production. Save it.
  1. 7. Run kubectl apply -f pod.yaml again. Kubernetes will reply: pod/my-nginx-pod configured. It smartly detected the change and updated the live Pod without destroying it!
  1. 8. Clean up by deleting the infrastructure using the file:
bash
1 
kubectl delete -f pod.yaml

8. Real-World Scenarios

A DevOps team manages a cluster with 1,000 running Pods. Because they use YAML manifests stored in a GitHub repository (GitOps), if a rogue administrator accidentally deletes 500 Pods, the team doesn't panic. They simply run kubectl apply -f ./production-folder, and Kubernetes instantly reads the YAMLs and recreates all 500 missing Pods to restore the desired state.

9. Best Practices

  • Version Control Everything: You should never deploy infrastructure to a Kubernetes cluster unless the YAML file has been committed to a Git repository. Your Git repository should act as the absolute, single source of truth for the physical state of your cluster.

10. Common Mistakes

  • Mixing up API Versions: Beginners often copy code from a 2018 tutorial that uses apiVersion: extensions/v1beta1 for a Deployment. If you run this on a modern cluster, it will throw a massive error. The API evolves. Always check the official Kubernetes documentation for the correct, current apiVersion.

11. Exercises

  1. 1. What kubectl command replaces the imperative kubectl run command when adopting a declarative infrastructure workflow?
  1. 2. Explain the structural hierarchy of the spec block in a Pod manifest. Why is containers formatted as a list (using hyphens)?

12. FAQs

Q: I hate YAML. Can I write Kubernetes configurations in JSON? A: Yes! Kubernetes actually converts your YAML into JSON before sending it to the API server anyway. However, YAML supports comments (#) and is generally considered more human-readable, which is why 99% of the industry uses it.

13. Interview Questions

  • Q: Explain the philosophical difference between Imperative and Declarative infrastructure management. Why is Kubernetes inherently designed for Declarative workflows?
  • Q: Describe the functional purpose of Labels and Selectors within Kubernetes architecture. Provide a scenario demonstrating how a loose or missing Label strategy could cause a production outage.

14. Summary

In Chapter 5, we abandoned manual terminal commands and embraced the enterprise standard: Infrastructure as Code via YAML manifests. We dissected the four mandatory pillars of a Kubernetes configuration—apiVersion, kind, metadata, and spec. We learned how to apply these blueprints to the API server, demonstrating how Kubernetes reads our Desired State and automatically manipulates the cluster to match our written declarations.

15. Next Chapter Recommendation

We know how to write a YAML file for a single Pod. But what if we want 5 Pods? What if we want them to automatically restart if they crash? We need a manager. Proceed to Chapter 6: Deployments and ReplicaSets.

Finish this Chapter

Save your progress on your learning path and prepare for coding interview challenges.

Previous Chapter Understanding Pods in Kubernetes
Next Chapter Deployments and ReplicaSets

Discussion

Join the discussion

Log in or create a free account to participate.

Sort: ·

Explore More

📖 Related Tutorials 5

❓ Related Quizzes 6