YAML BasicsKubernetes configuration files, simply

An important topic when learning Kubernetes is YAML.

In the previous tutorials, we saw how to create Pods and Deployments using kubectl commands.

For example:

kubectl run nginx --image=nginx

But in a real Kubernetes environment, we don't always create resources by typing commands in the terminal.

Instead, we define the configuration of Kubernetes resources in YAML files.

For example:

• Pods
• Deployments
• Services
• ConfigMaps
• Secrets
• Volumes

YAML is a human-readable data serialization format for writing structured configuration data.

In this tutorial, we will learn YAML's basic syntax: key-value pairs, lists, dictionaries, indentation and nested structures.

Then we will see how Kubernetes uses YAML files to create resources.

1. What is YAML?

YAML is a data representation, or serialization, format.

With YAML, structured data is easy to write and read.

YAML stands for:

YAML Ain't Markup Language

YAML works much like JSON and XML.

But YAML is usually easier for humans to read and write.

Example YAML

fruit: apple
vegetable: carrot
liquid: water
meat: chicken

Here we have defined four key-value pairs.

Structure

Key          Value
 |             |
 ▼             ▼
fruit:       apple
vegetable:   carrot
liquid:      water
meat:        chicken

This structure is called a key-value mapping.

The most basic concept in YAML is the key and the value.

2. What are key-value pairs?

The simplest structure in YAML is a key-value pair.

Example:

fruit: apple

Here:

• fruit is the key.
• apple is the value.

The general syntax:

key: value

Another example:

fruit: apple
vegetable: carrot
liquid: water
meat: chicken

Here, each line is a key-value pair.

Why does the space after the colon matter?

In YAML, you usually need a space after the colon (:) to separate the key from the value.

Correct:

fruit: apple

Incorrect mapping syntax:

fruit:apple

A YAML parser may read the second example as a plain string instead of a mapping.

So always put a space after the colon when writing a key-value mapping.

3. YAML lists / arrays

Say you have a fruit category.

You want to keep several fruits in that category.

For example:

• Apple
• Banana
• Orange

In this case, you can use a YAML list.

Example

fruits:
  - apple
  - banana
  - orange

Here, fruits is the key.

And its value is a list.

Structure

fruits
   |
   ▼
  List
   |
   ├── apple
   ├── banana
   └── orange

In YAML, list items are written with a dash (-).

Another example

vegetables:
  - carrot
  - broccoli
  - spinach

Here, vegetables holds three values.

Simple rule: use a list when you want to keep several values in one category.

4. YAML dictionaries / maps

Now say you want to store information about a banana.

A banana has some properties:

• Calories
• Fat
• Carbs

In this case, you use a dictionary, or map.

Example

banana:
  calories: 105
  fat: 0.4
  carbs: 27

Here, banana is an object-like mapping.

It has three properties.

Structure

banana
   |
   ├── calories: 105
   |
   ├── fat: 0.4
   |
   └── carbs: 27

Here:

Simple rule: use a dictionary, or map, when you want to describe several properties of one object.

5. Why does YAML indentation matter?

One of the most important rules in YAML is indentation.

YAML uses spaces to express structure.

As in Python, indentation in YAML determines what the structure means.

Correct example

banana:
  calories: 105
  fat: 0.4
  carbs: 27

Here, calories, fat and carbs are at the same indentation level.

So all three properties belong to the banana dictionary.

Incorrect example

banana:
  calories: 105
    fat: 0.4
    carbs: 27

Here, fat and carbs are indented incorrectly.

That is because calories already has a direct value:

calories: 105

You can't put nested properties under that scalar value.

To make it easy to see

Correct:

banana
   |
   ├── calories
   ├── fat
   └── carbs

Incorrect:

banana
   |
   └── calories: 105
          |
          ├── fat
          └── carbs

Here, calories is a number, not a nested dictionary.

Important: changing the indentation in YAML can change the meaning of the data structure or cause a syntax error.

6. YAML uses spaces, not tabs

YAML uses spaces for indentation.

You should not indent with tabs.

Correct example

car:
  color: blue
  model: mustang

Here, each nested property has two spaces in front of it.

YAML files usually use 2 spaces per indentation level.

But YAML does not require exactly 2 spaces.

What matters is that the indentation is consistent.

Example

car:
  color: blue
  model: mustang
  transmission: automatic

Here, all the properties are at the same level.

Kubernetes best practice

When writing Kubernetes YAML files, 2-space indentation is common.

It makes nested resources easier to read.

7. A dictionary inside a dictionary

In YAML, you can put one dictionary inside another.

This is called a nested dictionary.

Say we want to store information about a car.

The car's properties:

• Color
• Model
• Transmission
• Price

But the model itself also has a name and a year.

Example

car:
  color: blue
  model:
    name: mustang
    year: 2020
  transmission: automatic
  price: 25000

Here:

• car is the main dictionary.
• model is another dictionary inside the car dictionary.
• name and year are properties of the model dictionary.

Structure

car
 |
 ├── color: blue
 |
 ├── model
 |     |
 |     ├── name: mustang
 |     |
 |     └── year: 2020
 |
 ├── transmission: automatic
 |
 └── price: 25000

This way, you can keep more detailed information about one of an object's properties.

This nested structure is very common in Kubernetes YAML files.

8. A list of strings

Say you only want to store the names of a few cars.

In this case, a list of strings is enough.

Example

cars:
  - blue mustang
  - red corvette
  - black tesla

Here, cars is a list.

Each item is a string.

Structure

cars
 |
 ├── blue mustang
 |
 ├── red corvette
 |
 └── black tesla

There are no additional properties for each car here.

Only string values.

A list of strings is used when each item is a simple value.

9. A list of dictionaries

Now say we want to store several cars.

But each car has its own properties.

For example:

• Color
• Model
• Transmission
• Price

In this case, you use a list of dictionaries.

Example

cars:
  - color: blue
    model: mustang
    transmission: automatic
    price: 25000

  - color: red
    model: corvette
    transmission: manual
    price: 55000

Here, cars is a list.

But each item in the list is a dictionary.

Structure

cars
 |
 ├── Car 1
 |     |
 |     ├── color: blue
 |     ├── model: mustang
 |     ├── transmission: automatic
 |     └── price: 25000
 |
 └── Car 2
       |
       ├── color: red
       ├── model: corvette
       ├── transmission: manual
       └── price: 55000

This structure is very common in Kubernetes.

That is because Kubernetes YAML often has to define multiple containers, ports or volumes.

10. List → dictionary → nested dictionary → list

YAML can represent even more complex data structures.

Say we have several fruits.

For each fruit, we need to store:

• Name
• Nutrition information
• A list of vitamins

Example

fruits:
  - name: banana
    nutrition:
      calories: 105
      fat: 0.4
      carbs: 27
    vitamins:
      - vitamin B6
      - vitamin C

  - name: grape
    nutrition:
      calories: 62
      fat: 0.3
      carbs: 16
    vitamins:
      - vitamin C
      - vitamin K

This YAML structure uses several data types.

Step-by-step breakdown

Step 1: fruits is a list.

Step 2: each item in the list is a dictionary.

Step 3: each dictionary contains a nested dictionary called nutrition.

Step 4: each dictionary contains a list called vitamins.

Complete structure

fruits (List)
    |
    ├── Fruit 1 (Dictionary)
    |      |
    |      ├── name: banana
    |      |
    |      ├── nutrition (Dictionary)
    |      |      |
    |      |      ├── calories: 105
    |      |      ├── fat: 0.4
    |      |      └── carbs: 27
    |      |
    |      └── vitamins (List)
    |             |
    |             ├── vitamin B6
    |             └── vitamin C
    |
    └── Fruit 2 (Dictionary)
           |
           ├── name: grape
           |
           ├── nutrition (Dictionary)
           |      |
           |      ├── calories: 62
           |      ├── fat: 0.3
           |      └── carbs: 16
           |
           └── vitamins (List)
                  |
                  ├── vitamin C
                  └── vitamin K

Nested structures like this are used in Kubernetes manifests.

That is because the configuration of Kubernetes resources is often complex and hierarchical.

11. When to use a dictionary and when to use a list

This is the most important conceptual part of YAML.

Use a dictionary to describe one object

Example:

car:
  color: blue
  model: mustang
  price: 25000

Here, several properties of one car are being described.

So a dictionary is used.

Use a list to store multiple items

Example:

cars:
  - mustang
  - corvette
  - tesla

Here, the names of several cars are stored.

So a list is used.

Multiple objects with properties: a list of dictionaries

Example:

cars:
  - color: blue
    model: mustang
    price: 25000

  - color: red
    model: corvette
    price: 55000

Here there are several cars, and each car has its own properties.

So a list of dictionaries is used.

Quick comparison

12. Dictionary order vs list order

There is an important difference between dictionaries and lists in YAML.

Dictionary order usually doesn't matter

Example 1:

banana:
  calories: 105
  fat: 0.4
  carbs: 27

Example 2:

banana:
  carbs: 27
  calories: 105
  fat: 0.4

The logical data in these two examples is the same.

That is because in a dictionary, or mapping, properties are usually identified by their key, not their position.

In other words:

calories → 105
fat      → 0.4
carbs    → 27

Even if the order of the properties changes, the meaning of the mapping stays the same.

List order matters

Example 1:

fruits:
  - apple
  - banana

Example 2:

fruits:
  - banana
  - apple

These two lists have the same items, but in a different order.

The first list:

1. apple
2. banana

The second list:

1. banana
2. apple

A list is an ordered collection.

So the order of a list's items can matter.

Whether the order of a specific list matters operationally in Kubernetes depends on the semantics of that Kubernetes field.

13. YAML comments

In YAML, comments are written with the hash symbol (#).

Example:

# This is a comment
fruit: apple

The YAML parser does not process comments as configuration data.

Comments are used to explain part of the configuration.

Example

# Application Configuration
app:
  name: my-app

  # Application Port
  port: 8080

  # Environment
  environment: production

Here, comments explain the purpose of the configuration.

In Kubernetes YAML files, comments can improve documentation and readability.

14. Why does YAML matter in Kubernetes?

Kubernetes can use YAML files to define the desired state of resources.

Say you want to create an NGINX Pod in Kubernetes.

In the previous tutorial, we used a command:

kubectl run nginx --image=nginx

But the same Pod can also be created with a YAML manifest.

Kubernetes Pod YAML example

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx

Here, the YAML file is telling Kubernetes:

Create a Pod named nginx, and run a container inside it using the nginx container image.

YAML structure breakdown

Structure visualization

Kubernetes YAML
       |
       ├── apiVersion: v1
       |
       ├── kind: Pod
       |
       ├── metadata
       |      |
       |      └── name: nginx
       |
       └── spec
              |
              └── containers (List)
                       |
                       └── Container (Dictionary)
                                |
                                ├── name: nginx
                                |
                                └── image: nginx

Here, containers is a list.

The list contains one container dictionary.

This is why it is important to understand YAML lists and dictionaries before learning Kubernetes.

Creating a Pod from a YAML file

Save the configuration above as pod.yaml.

Then:

kubectl apply -f pod.yaml

To check the Pod:

kubectl get pods

Detailed information:

kubectl describe pod nginx

That is how you create a Pod from a Kubernetes YAML manifest.

15. Common YAML mistakes

There are some common mistakes when writing YAML.

Mistake 1: missing space

Incorrect:

fruit:apple

Correct:

fruit: apple

Mistake 2: wrong indentation

Incorrect:

banana:
  calories: 105
    fat: 0.4

Correct:

banana:
  calories: 105
  fat: 0.4

Mistake 3: using tabs

Use spaces for YAML indentation.

Correct:

car:
  color: blue
  model: mustang

Mistake 4: writing a list structure incorrectly

Incorrect:

cars:
  - blue
    - red

If the goal is a list of two strings, the correct structure is:

cars:
  - blue
  - red

Mistake 5: putting properties under a scalar value

Incorrect:

car:
  price: 25000
    currency: USD

If you want the price to hold both an amount and a currency, you need a nested dictionary.

Correct:

car:
  price:
    amount: 25000
    currency: USD

16. The complete mental model of YAML

To understand YAML, remembering three fundamental structures makes it much easier.

1. Key-value pair

fruit: apple

2. Dictionary

banana:
  calories: 105
  fat: 0.4
  carbs: 27

3. List

fruits:
  - apple
  - banana
  - orange

Combining these three structures creates more complex YAML configurations.

YAML
 |
 ├── Key-Value Pair
 |
 ├── Dictionary / Map
 |       |
 |       └── Nested Dictionary
 |
 └── List / Array
         |
         └── Dictionary
                |
                ├── Nested Dictionary
                |
                └── Nested List

Most of the structure in Kubernetes YAML files rests on these basic concepts.

17. YAML vs JSON vs XML

YAML, JSON and XML can all represent structured data.

Let's look at a simple application configuration.

YAML example

app:
  name: my-app
  port: 8080

JSON example

{
  "app": {
    "name": "my-app",
    "port": 8080
  }
}

XML example

<app>
  <name>my-app</name>
  <port>8080</port>
</app>

All three formats aim to represent the same kind of structured information.

But the syntax differs.

YAML is very common in Kubernetes configuration files, because it can represent nested structures comparatively simply.

18. A complete Kubernetes YAML example

Now let's look at a slightly bigger Kubernetes YAML.

Say we want to create an NGINX Deployment.

This Deployment will maintain three NGINX Pods.

deployment.yaml

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

Here we can see all the YAML concepts from before.

Key-value pairs

kind: Deployment

Dictionary

metadata:
  name: nginx-deployment

Nested dictionary

selector:
  matchLabels:
    app: nginx

List of dictionaries

containers:
  - name: nginx
    image: nginx:latest

Nested list of dictionaries

ports:
  - containerPort: 80

Complete structure

Deployment
    |
    ├── apiVersion
    |
    ├── kind
    |
    ├── metadata
    |      |
    |      └── name
    |
    └── spec
           |
           ├── replicas
           |
           ├── selector
           |      |
           |      └── matchLabels
           |
           └── template
                  |
                  ├── metadata
                  |
                  └── spec
                         |
                         └── containers
                                  |
                                  ├── name
                                  |
                                  ├── image
                                  |
                                  └── ports

This example shows how YAML lists, dictionaries and nested structures are used together in Kubernetes manifests.

Applying it to Kubernetes

Save the file as deployment.yaml.

Then:

kubectl apply -f deployment.yaml

Check the Deployment:

kubectl get deployments

Check the Pods:

kubectl get pods

This is how you create and manage Kubernetes resources with YAML files.

19. Important YAML rules — Quick reference

20. Final takeaway — YAML basics

The main goal of this tutorial was to understand YAML's basic data structures.

The most important concepts for learning YAML:

Key-value pairs: associate a value with a key.

Lists: store multiple values.

Dictionaries: describe an object's properties.

Indentation: determines which parent structure a piece of data belongs to.

Nested structures: combine lists and dictionaries to represent complex data.

Kubernetes YAML files are built on these fundamental concepts.

The final mental model

YAML
 |
 ├── Key-Value Pairs
 |
 ├── Lists
 |
 ├── Dictionaries
 |
 ├── Nested Structures
 |
 └── Kubernetes Manifests
          |
          ├── Pods
          ├── Deployments
          ├── Services
          ├── ConfigMaps
          ├── Secrets
          └── Volumes

Final one-line summary:

YAML is a human-readable configuration format in which structured data is written with key-value pairs, lists, dictionaries and indentation. Kubernetes uses this YAML format to define and manage the desired state of Pods, Deployments, Services and other resources.

Official Documentation

• YAML Official Website
• YAML Specification
• Kubernetes — Understanding Kubernetes Objects
• Kubernetes — Declarative Object Management
• Kubernetes — Pod Concepts
• Kubernetes — Deployment Concepts

Once you understand YAML's basic syntax and structure, reading, writing and troubleshooting Kubernetes configuration files becomes much easier.