Run Your First Pod with Python

Let’s face it: you’ve built a Python app, wrapped it in a Docker image, and pushed it to a registry — but now what? The moment you try to run that image in Kubernetes, you hit a wall of YAML, networking, and pod lifecycle concepts that feel alien to a Python developer. This lesson cuts through the noise and shows you exactly how to run your first pod with a Python image — no fluff, no 40-minute videos. You’ll go from a container image to a running pod, understand what’s happening under the hood, and learn to debug it when things go sideways. By the end, you'll have a working pod and the foundation to tackle Deployments, Services, and everything else in the track.

The Problem This Lesson Solves

You have a Python app — maybe a Flask API, maybe a background worker — and you’ve containerized it with Docker. But Kubernetes is a different beast. A pod is the smallest unit you can run, and getting your Python image into a pod is the first real hurdle on your journey to orchestrating services.

The pain is real: you copy-paste a kubectl run command from a blog, and you get an ErrImagePull or a pod that crashes instantly. You see CrashLoopBackOff and have no idea if it’s your code, your image, or your Kubernetes config. The docs assume you know what a pod is, how image pull policies work, and why a container needs a command. This lesson solves that exact problem — it gives you a clear mental model and a hands-on path to your first running pod.

By the end of this lesson, you won’t just have a pod running; you’ll understand why it works, what to do when it doesn’t, and how this fits into the bigger Kubernetes picture.

Core Concept / Mental Model

Think of a pod as a single “container box” on a Kubernetes cluster. It’s the smallest deployable unit — like a single process on your laptop, but scheduled across a cluster. A pod can contain one or more containers that share networking and storage, but for most Python apps, a pod with a single container is the norm.

Here’s a diagram-in-words: you have a Kubernetes cluster (a group of machines), a node (one machine), and pods (the containers running on that node). Your Python image is the blueprint; the pod is the running instance of that blueprint.

A pod has a lifecycle: it’s Pending (waiting to be scheduled), Running (actively executing), Succeeded (finished), Failed (error), or Unknown (lost). When you create a pod, the Kubernetes scheduler places it on a node, the kubelet on that node pulls the image, and the container runtime starts your Python process.

Key terms you’ll see everywhere: - Image: The Docker image (e.g., python:3.12-slim or your own image). - Container: The running instance of that image. - Pod: The wrapper that gives the container a shared network namespace and optional volumes. - kubectl: The command-line tool to talk to your cluster. - Restart policy: What happens when the container exits (e.g., Always, OnFailure, Never).

Pro tip: A pod is not a long-running process by default. If your Python script exits, the pod exits too — unless you use a restart policy or a long-running web server.

How It Works Step by Step

The process of running your first pod with a Python image follows a predictable flow:

1. Ensure your cluster is ready – You need a running Kubernetes cluster (local like Minikube, or a managed service like EKS, AKS, GKE) and kubectl configured.
2. Create a pod manifest – A YAML file that declares what image to run, the container name, and any commands.
3. Apply the manifest – Use kubectl apply -f pod.yaml to send the manifest to the API server.
4. Check the pod status – Use kubectl get pods to see the phase, and kubectl describe pod for details.
5. View logs – If the pod is running, use kubectl logs to see your Python output.
6. Clean up – Delete the pod when you’re done.

Each step is independent, but they build on each other. The cause is the manifest you write; the effect is the pod running on a node with your Python image.

Hands-On Walkthrough

Let’s get our hands dirty. We’ll use two approaches: a quick one-liner for testing, and a proper YAML manifest for real projects.

Prerequisites

• A running Kubernetes cluster (e.g., Minikube, kind, Docker Desktop with Kubernetes, or a cloud cluster).
• kubectl installed and configured.
• A Python image — either your own or a public one like python:3.12-slim.

Approach 1: Quick start with kubectl run

For a fast sanity check, you can run a pod directly:

kubectl run my-python-pod --image=python:3.12-slim --restart=Never -- python -c "print('Hello from Python in a pod!')"

This creates a pod that runs a one-off Python command. Check its status:

kubectl get pods

You should see my-python-pod in Running, then Completed (since the script exits). To see the output:

kubectl logs my-python-pod

Expected output:

Hello from Python in a pod!

Pro tip: The --restart=Never flag is crucial for a one-off pod. Without it, Kubernetes treats it as a Job and may restart it, which is fine but different from a simple pod.

Approach 2: The proper YAML way

For anything beyond a quick test, you’ll want a manifest file. Create python-pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: python-web-pod
  labels:
    app: python-web
spec:
  containers:
  - name: python-web
    image: python:3.12-slim
    command: ["python", "-m", "http.server", "8080"]
    ports:
    - containerPort: 8080

Apply it:

kubectl apply -f python-pod.yaml

Check the status:

kubectl get pods

You should see python-web-pod in Running. To verify it’s actually serving, you can port-forward:

kubectl port-forward pod/python-web-pod 8080:8080

Then open http://localhost:8080 in your browser — you’ll see the directory listing from the Python HTTP server.

Expected output: After kubectl get pods, something like:

NAME            READY   STATUS    RESTARTS   AGE
python-web-pod  1/1     Running   0          10s

Clean up

Delete the pod when you’re done:

kubectl delete pod python-web-pod

Or with the manifest:

kubectl delete -f python-pod.yaml

Compare Options / When to Choose What

There are several ways to run a pod, each suited to different situations. Here’s a comparison to help you choose:

When to choose what: For learning and quick experiments, kubectl run is perfect. For any real application or anything you’ll share, use a YAML manifest. If your Python app is a web server that must stay up, you’ll eventually want a Deployment — but that’s the next lesson.

Troubleshooting & Edge Cases

Even with a simple pod, things go wrong. Here are the most common issues and how to fix them:

Pod stays Pending or ContainerCreating

• Issue: Image pull failure. Check with kubectl describe pod <name>.
• Fix: Ensure the image name is correct and you have access (for private images, add imagePullSecrets).

kubectl describe pod my-python-pod

Look for Events — you’ll often see Failed to pull image .... If you’re using a private registry, you need a Secret.

Pod enters CrashLoopBackOff

• Issue: Your container exits immediately with a non-zero code.
• Fix: Check the logs with kubectl logs. It might be a missing dependency or a bad command.

kubectl logs my-python-pod

For example, if you run a Python script that needs a module that isn’t installed, it will fail.

Python script finishes instantly

• If you run a short script, the pod will go to Completed. That’s expected. If you want it to stay running, run a server like http.server or add a while true loop.

Image pull policy surprises

• By default, Kubernetes uses IfNotPresent on most clusters, but sometimes it’s Always. If you update your image tag locally, you might need to set imagePullPolicy: IfNotPresent to use the local image (with Minikube) or Always to force a fresh pull.

Port not accessible

• Remember that a pod isn’t exposed to the outside world by default. You need a Service or port-forward to reach it.

What You Learned & What's Next

You’ve now run your first pod with a Python image — and not by black magic, but by understanding the pieces. You can:

• Explain what a pod is and how it wraps your container.
• Use kubectl run for quick tests and YAML manifests for real work.
• Check pod status, view logs, and troubleshoot common issues like ImagePullBackOff and CrashLoopBackOff.
• Compare when to use a raw pod versus a Deployment or a Job.

You’ve strengthened your Kubernetes mental model, and you can now confidently create a pod from any Python image — whether it’s a simple script or a web server. This is the foundation for everything that follows.

Next up: In the next lesson, you’ll learn how to create a Deployment — the way to run and manage multiple replicas of your pod, with self-healing and rollback capabilities. That’s where Kubernetes really starts to shine for Python services.

Keep your python-web-pod.yaml handy — you’ll be extending it into a Deployment next.