Kubernetes Pods with YAMLCreating a Pod from a YAML file

In the previous tutorial, we learned what YAML is and how key-value pairs, lists, dictionaries and indentation work.

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

For example:

kubectl run nginx --image=nginx

But in a real Kubernetes environment, instead of using a separate command to create each resource, we usually use YAML definition files.

A YAML file lets you tell Kubernetes what kind of resource you want to create and what its configuration should be.

In this tutorial, we will see how to write a Kubernetes Pod YAML definition file and create a Pod from it.

1. Two ways to create Kubernetes objects

There are two common approaches to creating objects in Kubernetes.

Method 1: imperative command

Create the object directly with a kubectl command.

Example:

kubectl run nginx --image=nginx

This command creates a Pod named nginx in Kubernetes.

It is useful for quick testing and learning.

Method 2: YAML definition file

The other approach is to write a YAML file that defines the Kubernetes resource's configuration.

Example:

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

You can then create the Pod from the YAML file.

In Kubernetes, many kinds of resources are defined in YAML definition files.

For example:

• Pods
• ReplicaSets
• Deployments
• Services

Through the YAML file, we tell Kubernetes which object to create and what its desired configuration is.

2. The four main fields of Kubernetes YAML

A Kubernetes object definition file usually has four important root-level fields.

apiVersion:
kind:
metadata:
spec:

These are called top-level properties or root-level fields.

These fields are used in the YAML manifests of most Kubernetes workload resources.

Basic structure

Kubernetes YAML
       |
       ├── apiVersion
       |
       ├── kind
       |
       ├── metadata
       |
       └── spec

Once you understand these four fields, reading and writing many Kubernetes YAML files becomes easy.

Note: spec is not required for every Kubernetes resource. But the Pod definition in this tutorial uses all four fields.

3. apiVersion — Which Kubernetes API version should you use?

apiVersion tells Kubernetes which API version to use to process the object.

For a basic Pod:

apiVersion: v1

Different Kubernetes resources can have different API versions.

Example: Pod

apiVersion: v1

Example: Deployment

apiVersion: apps/v1

The important point here is to use the correct API version for the object type.

In this tutorial, we are creating a Pod.

So we will use:

apiVersion: v1

4. kind — Which Kubernetes object should you create?

The kind field tells Kubernetes what kind of object we want to create.

To create a Pod:

kind: Pod

To create a Deployment:

kind: Deployment

To create a ReplicaSet:

kind: ReplicaSet

To create a Service:

kind: Service

Simple example

apiVersion: v1
kind: Pod

Here we are telling Kubernetes:

We want to create a Pod object using the v1 version of the Kubernetes API.

Remember

The value of kind must match a resource type that Kubernetes supports.

When writing a Pod definition, you must use:

kind: Pod

5. metadata — Information about the Kubernetes object

The metadata field defines information about the Kubernetes object.

For example:

• Name
• Labels
• Other supported metadata properties

Example:

metadata:
  name: myapp-pod
  labels:
    app: myapp

Here:

name is the Pod's name.

labels are key-value tags attached to the Pod.

Structure

metadata
   |
   ├── name: myapp-pod
   |
   └── labels
         |
         └── app: myapp

Here, metadata is a dictionary.

Its child properties are name and labels.

And labels is itself a dictionary.

YAML indentation

metadata:
  name: myapp-pod
  labels:
    app: myapp

Here:

• name and labels are at the same indentation level.
• app is a child property of labels.

This parent-child relationship is expressed through YAML indentation.

6. Why do Kubernetes labels matter?

Kubernetes labels let you identify, group and select objects.

Labels are key-value pairs.

Example:

labels:
  app: myapp
  type: frontend

There are two labels here.

app  → myapp
type → frontend

Say many Pods are running in your Kubernetes cluster.

For example:

100 Frontend Pods
100 Backend Pods
 50 Database Pods

If the Pods' labels are configured properly, identifying and filtering the Pods of a particular category becomes easy.

Example labels

labels:
  app: ecommerce
  tier: frontend
  environment: dev

Here:

Labels let you group Kubernetes objects.

An important difference

You cannot use arbitrary field names inside metadata.

You have to use the metadata fields that Kubernetes supports.

For example:

metadata:
  name: myapp-pod
  labels:
    app: myapp

But inside labels, you can define custom key-value pairs, following Kubernetes' label naming rules.

7. spec — The Pod's desired configuration

The spec field defines the Kubernetes object's desired configuration.

For a Pod, spec tells Kubernetes which containers to run inside the Pod.

Example:

spec:
  containers:
    - name: nginx-container
      image: nginx

Here:

• spec is a dictionary.
• containers is a list.
• Each item in the list is a dictionary.
• name is the container's name.
• image is the container image.

Structure

spec
 |
 └── containers (List)
          |
          └── Container (Dictionary)
                   |
                   ├── name: nginx-container
                   |
                   └── image: nginx

This YAML structure tells Kubernetes to run one container inside the Pod.

The container's name will be nginx-container.

And the container image will be nginx.

8. Why is containers a list?

An important question comes up here.

Why is the containers field defined as a list?

Because a Kubernetes Pod can contain more than one container.

Example:

Pod
 |
 ├── Main Application Container
 |
 └── Helper Container

So in the Kubernetes Pod specification, containers is a list.

Single-container example

containers:
  - name: nginx-container
    image: nginx

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

Even though our Pod has a single container, containers still has to be defined as a list.

Multi-container structure

containers:
  - name: main-container
    image: nginx

  - name: helper-container
    image: busybox

There are two container definitions here.

But in this tutorial we will work with a single-container Pod.

9. A complete Kubernetes Pod YAML example

Now let's write a complete Pod definition using all the fields together.

apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
spec:
  containers:
    - name: nginx-container
      image: nginx

What is this YAML file telling Kubernetes?

Step 1: apiVersion: v1

Use version v1 of the Kubernetes API.

Step 2: kind: Pod

Create a Pod object.

Step 3: metadata.name: myapp-pod

The Pod's name will be myapp-pod.

Step 4: metadata.labels.app: myapp

Attach the label app=myapp to the Pod.

Step 5: spec.containers

Run a container inside the Pod.

Step 6: name: nginx-container

The container's name will be nginx-container.

Step 7: image: nginx

Use the NGINX image to run the container.

Complete structure

Kubernetes Pod
      |
      ├── apiVersion: v1
      |
      ├── kind: Pod
      |
      ├── metadata
      |      |
      |      ├── name: myapp-pod
      |      |
      |      └── labels
      |             |
      |             └── app: myapp
      |
      └── spec
             |
             └── containers
                    |
                    └── nginx-container
                           |
                           └── image: nginx

10. Why does YAML indentation matter?

In YAML, indentation defines parent-child relationships.

So with the wrong indentation, Kubernetes may not be able to parse the YAML file correctly.

Correct example

metadata:
  name: myapp-pod
  labels:
    app: myapp

Here:

• name and labels are children of metadata.
• app is a child of labels.

Incorrect example

metadata:
  name: myapp-pod
    labels:
      app: myapp

This is incorrect.

Because labels has been wrongly nested under name.

But name already has a direct value.

name: myapp-pod

So you can't put a nested dictionary under it.

Correct structure

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

Important: wrong YAML indentation can make a Kubernetes resource definition invalid or produce an unexpected structure.

11. Creating a Pod from a YAML file

Now we will create a Pod YAML file and apply it to Kubernetes.

Step 1: create the YAML file

Create a file in the terminal:

nano pod-definition.yaml

Then write the following YAML configuration:

apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
spec:
  containers:
    - name: nginx-container
      image: nginx

Save the file.

File name:

pod-definition.yaml

Step 2: create the Pod

kubectl create -f pod-definition.yaml

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

Expected output:

pod/myapp-pod created

Kubernetes will now create the Pod and try to run the container.

12. kubectl create vs kubectl apply

When working with Kubernetes YAML files, you usually come across two commands.

kubectl create

kubectl create -f pod-definition.yaml

This command creates a new Kubernetes object from the YAML definition.

kubectl apply

kubectl apply -f pod-definition.yaml

This command is used to create or update a Kubernetes resource from declarative configuration.

Difference

In this tutorial, we will use:

kubectl create -f pod-definition.yaml

Because our main goal here is to create a new Pod from a YAML file.

13. Checking the created Pod

After creating the Pod, check:

kubectl get pods

Expected example:

NAME        READY   STATUS    RESTARTS   AGE
myapp-pod   1/1     Running   0          30s

Here, the myapp-pod Pod is running successfully.

Detailed Pod information

kubectl describe pod myapp-pod

This command shows detailed information about the Pod.

For example:

• Pod name
• Labels
• Node assignment
• Container image
• Container status
• Events

To see the Pod IP and node

kubectl get pods -o wide

This command helps you see the Pod's internal IP and its assigned node.

14. Imperative vs declarative style

So far, we have seen two approaches to creating a Kubernetes Pod.

The imperative approach

kubectl run nginx --image=nginx

Here we are giving Kubernetes a direct command.

This approach is useful for quick testing.

The declarative approach

We write a YAML file:

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

Then:

kubectl apply -f pod-definition.yaml

Here we define the desired configuration in a file.

Kubernetes tries to create or update the resource according to that configuration.

Comparison

In real Kubernetes projects, declarative YAML configuration matters more.

Because a configuration file can be saved, reviewed, reused and version-controlled.

15. A simple mental model of Kubernetes YAML

You can think of a Kubernetes YAML file as an order form.

Say you are placing an order with Kubernetes to create a Pod.

Then:

apiVersion = Which API version will be used?
kind       = What kind of object will be created?
metadata   = What will the object's name and labels be?
spec       = What will the object's configuration be?

For a Pod:

kind: Pod

means:

I want to create a Pod.

And:

spec:
  containers:
    - name: nginx-container
      image: nginx

means:

I want to run a container inside this Pod using the NGINX image.

The complete mental model

              Kubernetes YAML
                     |
         +-----------+-----------+
         |           |           |
         ▼           ▼           ▼
    apiVersion      kind       metadata
                                  |
                                  ▼
                             Name & Labels
                     |
                     ▼
                    spec
                     |
                     ▼
                containers
                     |
                     ▼
                 NGINX Image
                     |
                     ▼
                 Running Pod

16. Important kubectl commands

17. Complete hands-on demo — A Pod with YAML

This tutorial's commands together:

Step 1: create the YAML file

File name:

pod-definition.yaml

File content:

apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
spec:
  containers:
    - name: nginx-container
      image: nginx

Step 2: check the Kubernetes cluster

kubectl get nodes

Step 3: create the Pod

kubectl create -f pod-definition.yaml

Step 4: check the Pod status

kubectl get pods

Step 5: check the Pod details

kubectl describe pod myapp-pod

Step 6: check the Pod IP and node

kubectl get pods -o wide

Step 7: delete the Pod

To remove the Pod once testing is done:

kubectl delete pod myapp-pod

This deletes the Pod from the cluster.

The YAML file stays on your local computer.

18. Final takeaway — Kubernetes Pods with YAML

The most important thing in this tutorial is understanding the structure of a Kubernetes YAML definition file.

A basic Pod YAML definition uses four main fields.

apiVersion:
kind:
metadata:
spec:

Here:

apiVersion: defines the Kubernetes API version.

kind: defines which Kubernetes resource will be created.

metadata: stores information such as the resource's name and labels.

spec: defines the resource's desired configuration.

A complete Pod example:

apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
spec:
  containers:
    - name: nginx-container
      image: nginx

To create the Pod:

kubectl create -f pod-definition.yaml

To check the Pod:

kubectl get pods

To see detailed information:

kubectl describe pod myapp-pod

The final memory rule

apiVersion → Kubernetes API Version
kind       → Object Type
metadata   → Name and Labels
spec       → Desired Configuration

Final one-line summary:

In a Kubernetes Pod YAML file, apiVersion, kind, metadata and spec define which object to create, what its name and labels will be, and which container image will run inside the Pod.

Official Documentation

• Kubernetes — Pods
• Kubernetes — Understanding Kubernetes Objects
• Kubernetes — Object Names and IDs
• Kubernetes — Labels and Selectors
• kubectl create
• kubectl apply

Remember: the point of learning Kubernetes YAML is not just memorizing syntax. It is understanding how YAML defines the desired configuration of Kubernetes resources. Because in the next tutorials, ReplicaSets, Deployments and Services all use this same YAML structure.