Demo — Kubernetes Pods with YAML: A Step-by-Step Hands-on Guide

In the previous tutorials, we learned what a Kubernetes Pod is, how YAML works, and what the structure of a Kubernetes Pod definition file looks like.

We also saw how to create a Pod with the kubectl run command.

For example:

kubectl run nginx --image=nginx

But in real Kubernetes projects, resources are usually created and managed with YAML definition files.

Because YAML files can be saved, reused, edited and version-controlled in a Git repository.

In this demo, we will write a YAML definition file called pod.yaml and use it to create an NGINX Pod inside a Minikube Kubernetes cluster.

1. The goal of this demo

The goal of this demo is to create a Kubernetes Pod definition file.

File name:

pod.yaml

In this file, we will define:

Which Kubernetes object we want to create
What the object's name will be
What the object's labels will be
Which container image will run inside the Pod

Then we will create the Pod in Kubernetes:

kubectl create -f pod.yaml

Or:

kubectl apply -f pod.yaml

Complete workflow

Create pod.yaml
      |
      ▼
Define Kubernetes Pod
      |
      ▼
Save YAML File
      |
      ▼
kubectl create -f pod.yaml
      |
      ▼
Kubernetes API Server
      |
      ▼
Pod Created
      |
      ▼
NGINX Container Running

2. Why use a YAML file?

In an earlier tutorial, we created an NGINX Pod.

kubectl run nginx --image=nginx

This command is useful for quick testing.

But it doesn't save the application's configuration as a reusable YAML file.

With YAML, we can:

Save the configuration.
Reuse the same configuration again and again.
Edit the configuration later.
Store it in a Git repository.
Share it with team members.
Use it in real Kubernetes deployments.

Imperative vs YAML approach

Imperative Approach
        |
        ▼
kubectl run nginx --image=nginx
        |
        ▼
Pod Created

YAML Approach
        |
        ▼
     pod.yaml
        |
        ▼
kubectl create/apply
        |
        ▼
     Pod Created

For real Kubernetes projects, YAML-based declarative configuration is usually the better fit.

3. Creating the YAML file

This demo uses a Linux environment to create the YAML file.

In a Linux terminal, you can use the vim editor.

Command:

vim pod.yaml

This opens a file called pod.yaml.

If the file doesn't exist yet, Vim will create it.

Which editor can you use on Windows?

On Windows, you can use:

Notepad
Notepad++
Visual Studio Code (VS Code)

It is better to use an editor with YAML support, because it makes indentation mistakes easier to spot.

Editing the file in Vim

vim pod.yaml

Once Vim is open, press i to enter insert mode.

Now you can write the YAML configuration.

4. The four root-level fields of Kubernetes YAML

When writing a Kubernetes Pod definition file, four main root-level fields are used.

apiVersion:
kind:
metadata:
spec:

These are called root-level properties.

For a Pod definition:

apiVersion: v1
kind: Pod
metadata:
spec:

Here:

Field	Meaning
`apiVersion`	Kubernetes API version
`kind`	Kubernetes object type
`metadata`	The object's name and labels
`spec`	The object's desired configuration

The kind field is case-sensitive

Capitalization matters when writing a Kubernetes resource type.

Correct:

kind: Pod

Incorrect:

kind: pod

The P in Pod has to be a capital letter.

5. Defining metadata

The metadata field defines information about the Pod.

Example:

metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend

Here:

`name: nginx`

The Pod's name will be nginx.

`app: nginx`

One of the Pod's labels will be app=nginx.

`tier: frontend`

Another label will be tier=frontend.

Structure

metadata
    |
    ├── name: nginx
    |
    └── labels
          |
          ├── app: nginx
          |
          └── tier: frontend

Why do labels matter?

Labels let you group and select Kubernetes objects.

Say your application has two layers.

E-Commerce Application
         |
    +----+----+
    |         |
    ▼         ▼
Frontend    Backend
  Pods       Pods

For the frontend Pods:

labels:
  tier: frontend

For the backend Pods:

labels:
  tier: backend

This way, you can define labels according to each Pod's responsibility.

These labels will become important later, when we use Kubernetes Services and selectors.

6. Understanding YAML indentation

One of the most important rules in YAML is indentation.

Indentation defines parent-child relationships.

Correct example

metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend

Here:

name and labels are children of metadata.
app and tier are children of labels.

Indentation structure

metadata
   |
   ├── name
   |
   └── labels
          |
          ├── app
          |
          └── tier

Important rules

YAML indentation must use spaces, not tabs.

The common practice is to use 2 spaces per indentation level.

Incorrect example

metadata:
  name: nginx
    labels:
      app: nginx

Here, labels has been wrongly nested under name.

But name already has a direct value:

name: nginx

So you can't put nested properties under it.

7. Defining the container inside spec

The spec field defines the Pod's desired configuration.

In our demo, we will run one NGINX container inside the Pod.

Example:

spec:
  containers:
    - name: nginx
      image: nginx

Here:

Field	Meaning
`spec`	Pod specification
`containers`	The list of containers
`-`	One item in the list
`name`	Container name
`image`	Container image

Structure

spec
 |
 └── containers
         |
         └── Container 1
                |
                ├── name: nginx
                |
                └── image: nginx

Why is containers a list?

Because a Pod can contain multiple containers.

So the containers field is a list.

containers:
  - name: nginx
    image: nginx

Here, the dash (-) marks one item in the list.

Even though our Pod has a single container, Kubernetes still expects containers to be a list.

8. The complete Kubernetes Pod YAML file

Now let's write our complete pod.yaml file.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
    - name: nginx
      image: nginx

This YAML configuration tells Kubernetes:

Create a Pod named nginx. Its labels will be app=nginx and tier=frontend. Run a container inside the Pod using the nginx image.

Complete structure

Kubernetes Pod YAML
         |
         ├── apiVersion: v1
         |
         ├── kind: Pod
         |
         ├── metadata
         |      |
         |      ├── name: nginx
         |      |
         |      └── labels
         |             |
         |             ├── app: nginx
         |             |
         |             └── tier: frontend
         |
         └── spec
                |
                └── containers
                       |
                       └── Container
                              |
                              ├── name: nginx
                              |
                              └── image: nginx

9. What if the container image is in another registry?

In our example, the container image is:

image: nginx

This usually uses the official NGINX image from Docker Hub.

But if the image is stored in another registry, you need to use the full registry path.

Private company registry example

image: myregistry.example.com/myteam/myapp:v1

GitHub Container Registry example

image: ghcr.io/myuser/myapp:v1

Docker Hub official image

image: nginx

Important: with a private registry, you may need to configure image pull credentials in Kubernetes.

10. Can a Pod hold multiple containers?

Yes.

The reason containers is a list is exactly so that multiple containers can be defined in one Pod.

Example:

spec:
  containers:
    - name: nginx
      image: nginx

    - name: busybox
      image: busybox

There are two container definitions here.

Pod
 |
 ├── NGINX Container
 |
 └── BusyBox Container

But in this demo we will only use one container.

Because a single-container Pod is easier to understand at the beginner level.

Note: this multi-container example only illustrates the YAML structure. In practice, you may need to configure a suitable command or process to keep the busybox container running.

11. Saving and checking the YAML file

Once you have written the YAML configuration, save the file.

This demo uses the Vim editor.

Save and exit in Vim

First, press:

Esc

Then type:

:wq

and press Enter.

Here:

w → write, or save
q → quit

Checking the file content

In the terminal:

cat pod.yaml

Expected output:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
    - name: nginx
      image: nginx

This command confirms that the YAML file's content was saved correctly.

12. Creating the Pod from the YAML file

Our YAML file is now ready.

File name:

pod.yaml

To create the Pod in Kubernetes:

kubectl create -f pod.yaml

Expected output:

pod/nginx created

This command reads the YAML file and sends a request to the Kubernetes API server to create the Pod.

Using kubectl apply

As an alternative, you can use:

kubectl apply -f pod.yaml

For a new object, both commands can create the resource.

kubectl create vs kubectl apply

Command	Basic Meaning
`kubectl create -f pod.yaml`	Create a new object from the YAML file
`kubectl apply -f pod.yaml`	Create or update the object according to the YAML configuration

kubectl apply is commonly used in real Kubernetes projects.

Because after editing the YAML file, you can apply the configuration again.

Not every field of a Pod can be updated, though. Some changes require recreating the Pod.

The main command in this demo is:

kubectl create -f pod.yaml

13. Checking the Pod status

After creating the Pod from the YAML file, check:

kubectl get pods

Right after the Pod is created, the output may look like this:

NAME    READY   STATUS              RESTARTS   AGE
nginx   0/1     ContainerCreating   0          5s

Here, Kubernetes is preparing to start the container.

After a while:

NAME    READY   STATUS    RESTARTS   AGE
nginx   1/1     Running   0          20s

Here:

NAME → Pod name
READY → ready containers / total containers
STATUS → current Pod status
RESTARTS → container restart count
AGE → time since the Pod was created

ContainerCreating

When this status shows, Kubernetes may be:

Pulling the container image.
Creating the container.
Setting up networking.
Mounting volumes.

Running

The Running status means the Pod is in the Running phase.

And READY 1/1 means the NGINX container is ready.

14. Inspecting the Pod with kubectl describe

To see detailed information about the Pod:

kubectl describe pod nginx

This command shows a lot of information about the Pod.

For example:

Pod name
Labels
Node assignment
Container details
Container image
Container status
Pod events
Errors, if any

Example information

Name:         nginx
Namespace:    default
Labels:       app=nginx
              tier=frontend
Node:         minikube/192.168.49.2
Status:       Running

Containers:
  nginx:
    Image:    nginx
    State:    Running

The actual output can contain many more details.

The Events section

The Events section of kubectl describe shows the Pod's lifecycle-related events.

Example:

Pod Scheduled
      |
      ▼
Image Pulled
      |
      ▼
Container Created
      |
      ▼
Container Started

If the Pod isn't running, the Events section is useful for troubleshooting.

15. The important commands in this demo

Command	Purpose
`vim pod.yaml`	Create or edit the YAML file
`cat pod.yaml`	Show the YAML file's content
`kubectl create -f pod.yaml`	Create the Pod from the YAML file
`kubectl apply -f pod.yaml`	Create or update from the YAML configuration
`kubectl get pods`	Check the Pod status
`kubectl describe pod nginx`	See detailed Pod information

16. Complete hands-on demo — All commands

This tutorial's commands together:

# 1. Check Kubernetes Cluster
kubectl get nodes

# 2. Create YAML File
vim pod.yaml

# 3. Check YAML File
cat pod.yaml

# 4. Create Pod from YAML
kubectl create -f pod.yaml

# 5. Check Pod Status
kubectl get pods

# 6. Inspect Pod Details
kubectl describe pod nginx

pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
    - name: nginx
      image: nginx

With these commands and this YAML file, you can create and inspect a basic Kubernetes NGINX Pod.

17. A simple mental model — How does a YAML file work?

You can think of a Kubernetes YAML file as an instruction, or configuration document.

Developer
    |
    ▼
  pod.yaml
    |
    ▼
kubectl create -f pod.yaml
    |
    ▼
Kubernetes API Server
    |
    ▼
  Pod Created
    |
    ▼
NGINX Container
    |
    ▼
    Running

Here, the YAML file tells Kubernetes what to create.

The four main fields

apiVersion
    |
    └── Which Kubernetes API Version?

kind
    |
    └── Which Object Type?

metadata
    |
    └── Name and Labels?

spec
    |
    └── Which Container Image Should Run?

For a Pod:

kind: Pod

means we want to create a Pod.

And:

spec:
  containers:
    - name: nginx
      image: nginx

means we want to run an NGINX container inside that Pod.

18. Final takeaway — Kubernetes Pods with YAML

In this demo, we learned how to create a Kubernetes Pod from a YAML definition file.

First, create a file called pod.yaml.

Define the four main fields in it:

apiVersion:
kind:
metadata:
spec:

Then define the Pod name and labels inside metadata.

Define the container name and image inside spec.containers.

Complete example:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
    - name: nginx
      image: nginx

Then, to create the Pod:

kubectl create -f pod.yaml

Or:

kubectl apply -f pod.yaml

To check whether the Pod is running:

kubectl get pods

And to see detailed information:

kubectl describe pod nginx

The final memory rule

Write YAML File
       |
       ▼
Define Pod Configuration
       |
       ▼
Save pod.yaml
       |
       ▼
kubectl create -f pod.yaml
       |
       ▼
kubectl get pods
       |
       ▼
kubectl describe pod nginx

Final one-line summary:

To create a Pod from a YAML file in Kubernetes, you define apiVersion, kind, metadata and spec. Then you configure the container image inside spec.containers and create the Pod with kubectl create -f pod.yaml or kubectl apply -f pod.yaml.

Official Documentation

The key point: a YAML file lets you save the configuration of Kubernetes resources, and then reuse, edit, share and version-control that configuration. That is why YAML-based resource management is an important practice in real Kubernetes projects.