Understanding Pods and kubectl

When we start studying Kubernetes, one of the first questions that arises is:

After all, what is a Pod?

Many people answer that a Pod is a container, but that answer is not correct.

In reality, the Pod is the smallest unit that Kubernetes manages. Whenever we create an application within a cluster, Kubernetes creates a Pod, and inside it, there will be one or more containers.

This concept is extremely important, as practically all Kubernetes resources work on top of Pods.

In this article, we will understand Pods, learn how kubectl works, and create our first resource using YAML manifests.

What is a Pod?

A Pod is the smallest execution unit in Kubernetes.

It functions as a kind of “home” for one or more containers.

Instead of Kubernetes managing containers individually, it manages Pods.

We can represent this as follows:

Kubernetes
      │
      ▼
+------------------------+
|          Pod           |
|                        |
|  +------------------+  |
|  |    Container     |  |
|  +------------------+  |
+------------------------+

In most cases, there is only one container inside the Pod.

However, this is not a rule.

It is also possible to run several containers within the same Pod.

Containers within the same Pod

When there are two or more containers in the same Pod, they all share several resources.

Among them:

the same IP address;
the same network interface;
the same ports;
storage volumes;
the same lifecycle.

This means that two containers belonging to the same Pod can communicate using only localhost.

Imagine the following scenario:

+--------------------------------+
|              Pod               |
|                                |
|  +-----------+  +-----------+  |
|  |  Nginx    |  | BusyBox   |  |
|  | Porta 80  |  | curl      |  |
|  +-----------+  +-----------+  |
+--------------------------------+

The BusyBox container can access Nginx using:

curl localhost:80

This happens because both share the same network stack.

Sidecar Containers

Although it’s common to find only one container per Pod, there are several scenarios where it makes sense to run multiple containers.

This pattern is known as the Sidecar Pattern.

Imagine a main application and a container solely responsible for sending logs to an observability platform.

Pod
│
├── Application
│
└── Log Agent

The two containers work together.

If the Pod is removed, both will be terminated at the same time.

That’s why we say they share the same lifecycle.

Kubernetes manages Pods, not Containers

This detail often causes a lot of confusion.

When we run a command like:

kubectl run corinthians --image=nginx

It seems like we are only creating one container.

In practice, Kubernetes creates a Pod named corinthians, and inside it, there is a container using the Nginx image.

This difference becomes clearer when we observe the YAML manifest generated by Kubernetes.

We will see this later.

Understanding kubectl

kubectl is the official Kubernetes client.

It is through kubectl that we send commands to the cluster.

Whenever we execute a command, kubectl communicates with the Kubernetes API Server.

The flow happens as follows.

            kubectl
               │
               ▼
         Kubernetes API
               │
               ▼
         Control Plane
               │
               ▼
          Worker Nodes
               │
               ▼
              Pods

In other words, kubectl never communicates directly with a Worker Node.

All communication happens through the Kubernetes API.

Creating our first Pod

One of the quickest ways to create a Pod is by using the kubectl run command.

kubectl run corinthians --image=nginx

Let’s understand this command.

kubectl is the Kubernetes client.
run requests the creation of a Pod.
corinthians will be the name of the Pod.
--image=nginx specifies which image will be used by the container.

After a few seconds, we can verify if the resource has been created.

kubectl get pods

Expected result:

NAME          READY   STATUS    RESTARTS   AGE
corinthians   1/1     Running   0          5s

The kubectl get command provides a quick overview of the existing resources in the cluster.

Each column has a meaning.

Column	Description
NAME	Pod name
READY	Number of ready containers
STATUS	Current state of the Pod
RESTARTS	Number of restarts
AGE	Time since creation

This is usually the first command used during problem analysis in a Kubernetes cluster.

Getting more details

While kubectl get only provides a summary, the describe command displays all resource information.

kubectl describe pod corinthians

Among the information displayed are:

name;
namespace;
labels;
IP address;
image used;
ports;
events;
conditions;
volumes;
node where the Pod is running.

In practice, whenever something is not working correctly, the combination below will be one of the first tools used.

kubectl get pods

kubectl describe pod corinthians

These two commands already provide enough information to identify most of the problems encountered during Pod management.

In the next article in the series, we will learn how to generate YAML manifests using kubectl run --dry-run=client, understand the structure of a YAML file, and discover why virtually all production environments use declarative resources instead of imperative commands.

References

Kubernetes — Pods — documents the main object discussed in this article.
Kubernetes — kubectl Reference — documents cluster management and inspection commands.
Kubernetes — kubectl run — official reference for imperative Pod creation.
LINUXtips — Kubernetes Essentials — course used as the basis for my studies and this series of notes.