Using kubectl for Pod Operations

Managing Kubernetes Pods involves defining them in YAML manifests and subsequently submitting them to the Kubernetes API server to control their lifecycle. The primary tool for this interaction is kubectl, the official Kubernetes command-line interface. It allows you to perform every cluster operation, from deploying applications to inspecting their runtime state. Here are the essential kubectl commands for creating, inspecting, debugging, and deleting Pods.

Creating Pods from a Manifest

The most common way to create a Pod is by applying a YAML manifest file. The kubectl apply command instructs Kubernetes to create or update a resource to match the state defined in the file. This declarative approach is central to Kubernetes management, as it allows the system to figure out the necessary actions to achieve the desired state.

Let's assume you have the following Pod manifest saved as simple-pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: web-server
  labels:
    app: nginx
spec:
  containers:
  - name: nginx-container
    image: nginx:1.23
    ports:
    - containerPort: 80

To create this Pod, you run the apply command from your terminal in the same directory as the file:

kubectl apply -f simple-pod.yaml

If successful, the API server will acknowledge the request with a simple confirmation:

pod/web-server created

At this point, Kubernetes has accepted the manifest and will begin the process of scheduling and starting the Pod.

This diagram shows the high-level workflow of creating a Pod. The user's intent, captured in a YAML manifest, is passed to the API Server via kubectl. The control plane components then work together to schedule and run the Pod on a suitable worker node.

Inspecting Pod State

Once a Pod has been created, you will need to check its status, find its IP address, and examine its configuration.

Listing Pods

The kubectl get pods command provides a quick summary of one or more Pods in the current namespace.

kubectl get pods

The output is a table with essential information about each Pod:

NAME         READY   STATUS    RESTARTS   AGE
web-server   1/1     Running   0          2m15s

• NAME: The name of the Pod as defined in its metadata.
• READY: Shows how many containers in the Pod are in a "ready" state out of the total number of containers. 1/1 indicates the single container is running and has passed its readiness probe (if configured).
• STATUS: The current phase of the Pod in its lifecycle, such as Pending, Running, Succeeded, or Failed.
• RESTARTS: The number of times containers in the Pod have been restarted. A high number here can indicate a problem.
• AGE: The amount of time that has passed since the Pod was created.

To see more information, such as the Pod's IP address and the node it is scheduled on, use the -o wide flag.

kubectl get pods -o wide

NAME         READY   STATUS    RESTARTS   AGE     IP          NODE       NOMINATED NODE   READINESS GATES
web-server   1/1     Running   0          3m30s   10.244.1.4   minikube   <none>           <none>

Describing a Pod

For a comprehensive view of a Pod's configuration and runtime state, use kubectl describe pod. This command provides a detailed, human-readable output that is invaluable for troubleshooting.

kubectl describe pod web-server

The output is verbose but structured. The most important sections include:

• Labels and Annotations: All metadata attached to the Pod.
• Status: The current lifecycle phase.
• IP: The IP address assigned to the Pod.
• Containers: Detailed information for each container, including the image ID, ports, and resource limits.
• Events: A chronological log of events related to the Pod, such as being scheduled, pulling the image, and starting the container. This is often the first place to look when a Pod is not running correctly.

Here is a snippet of the Events section for a healthy Pod:

Events:
  Type    Reason     Age    From               Message
  ----    ------     ----   ----               -------
  Normal  Scheduled  5m10s  default-scheduler  Successfully assigned default/web-server to minikube
  Normal  Pulling    5m9s   kubelet            Pulling image "nginx:1.23"
  Normal  Pulled     5m5s   kubelet            Successfully pulled image "nginx:1.23" in 4.1s
  Normal  Created    5m5s   kubelet            Created container nginx-container
  Normal  Started    5m5s   kubelet            Started container nginx-container

Accessing Pod Logs

To troubleshoot application behavior, you need access to the logs produced by its containers. The kubectl logs command streams the standard output and standard error from a container.

To view the current logs of our web-server Pod:

kubectl logs web-server

If the Pod contains multiple containers, you must specify which container's logs you want to see using the -c or --container flag:

kubectl logs my-multi-container-pod -c sidecar-container

To follow the log stream in real-time, similar to tail -f in Linux, use the -f flag:

kubectl logs -f web-server

Executing Commands Inside a Pod

Sometimes, viewing logs is not enough. For deeper debugging, you might need to run commands directly inside a running container. kubectl exec provides this capability.

To get an interactive shell session inside the web-server container, use the -it flags (-i for stdin, -t for a tty):

kubectl exec -it web-server -- /bin/bash

The -- separates the kubectl command and its arguments from the command you want to run inside the container. Once inside, you can check network connectivity, inspect the filesystem, or examine running processes.

You can also run non-interactive commands. For example, to list the files in the Nginx web root:

kubectl exec web-server -- ls -l /usr/share/nginx/html

Deleting Pods

Finally, to remove a Pod from the cluster, you use kubectl delete. You can delete a Pod by its name or by reapplying the file it was created from.

To delete the web-server Pod by name:

kubectl delete pod web-server

Alternatively, using the manifest file is also a common practice:

kubectl delete -f simple-pod.yaml

Both commands will terminate the Pod. Kubernetes will signal the container to shut down gracefully before forcibly killing it if it does not comply within a specific grace period.

These commands form the foundation for interacting with Pods. As you progress, you will find that similar command structures are used for managing other Kubernetes resources like Deployments and Services.