Creating Pods with kubectl in Kubernetes - Step-by-Step CLI Walkthrough

Introduction

Sometimes you want to run a small app or service in Kubernetes. Pods are the smallest units that hold your app containers. Creating a Pod lets you start your app inside the cluster.

When you want to run a simple app or script inside Kubernetes without extra setup.

When testing a container image quickly before making a full deployment.

When you need to run a single container with specific settings for debugging.

When learning Kubernetes basics by creating and managing Pods directly.

When running a temporary task or job that doesn't need scaling or updates.

Config File - pod.yaml

pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: example-container
    image: nginx:1.23
    ports:
    - containerPort: 80

This file defines a Pod named example-pod running one container.

The container uses the nginx:1.23 image and listens on port 80.

The apiVersion and kind tell Kubernetes this is a Pod resource.

Commands

This command creates the Pod in Kubernetes using the configuration file. It tells Kubernetes to start the Pod with the settings defined.

Terminal

kubectl apply -f pod.yaml

Expected Output

pod/example-pod created

This command lists all Pods in the current namespace so you can check if your Pod is running.

Terminal

kubectl get pods

Expected Output

NAME          READY   STATUS    RESTARTS   AGE

example-pod   1/1     Running   0          10s

This command shows detailed information about the Pod, including events and container status, useful for troubleshooting.

Terminal

kubectl describe pod example-pod

Expected Output

Name:         example-pod

Namespace:    default

Priority:     0

Node:         <node-name>/192.168.1.10

Start Time:   Thu, 01 Jun 2023 12:00:00 +0000

Labels:       <none>

Annotations:  <none>

Status:       Running

IP:           10.244.1.5

Containers:

  example-container:

    Container ID:   docker://abcdef123456

    Image:          nginx:1.23

    Image ID:       docker-pullable://nginx@sha256:...

    Port:           80/TCP

    State:          Running

      Started:      Thu, 01 Jun 2023 12:00:05 +0000

    Ready:          True

    Restart Count:  0

Conditions:

  Type           Status

  Initialized    True 

  Ready          True 

  ContainersReady True 

  PodScheduled   True 

Events:

  Type    Reason     Age   From               Message

  ----    ------     ----  ----               -------

  Normal  Scheduled  20s   default-scheduler  Successfully assigned default/example-pod to <node-name>

  Normal  Pulled     19s   kubelet            Container image "nginx:1.23" already present on machine

  Normal  Created    19s   kubelet            Created container example-container

  Normal  Started    19s   kubelet            Started container example-container

This command deletes the Pod when you no longer need it, cleaning up resources.

Terminal

kubectl delete pod example-pod

Expected Output

pod "example-pod" deleted

Key Concept

If you remember nothing else from this pattern, remember: a Pod is the smallest unit you create in Kubernetes to run your containerized app.

Common Mistakes

Trying to create a Pod without a valid YAML file or with syntax errors.

Kubernetes will reject the file and not create the Pod, showing an error.

Always validate your YAML syntax and ensure required fields like apiVersion, kind, metadata, and spec are present.

Not checking Pod status after creation.

The Pod might fail to start or crash, and you won't know unless you check.

Use 'kubectl get pods' and 'kubectl describe pod' to verify the Pod is running and healthy.

Deleting the Pod without confirming the Pod name.

You might delete the wrong Pod or get an error if the name is wrong.

List Pods first with 'kubectl get pods' and copy the exact Pod name before deleting.

Summary

Create a Pod by writing a YAML file that defines the container and its settings.

Use 'kubectl apply -f pod.yaml' to create the Pod in Kubernetes.

Check the Pod status with 'kubectl get pods' and 'kubectl describe pod example-pod'.

Delete the Pod with 'kubectl delete pod example-pod' when done.