Bringing Kubernetes to Your Local Machine: 5 Game-Changing Innovations from Podman

+-------------------------------------------------------------+
|                    Docker Architecture (Client-Server)       |
|                                                              |
|  +----------+     REST API      +------------------------+  |
|  | docker   | ----------------->|       dockerd          |  |
|  | CLI      |     /var/run/     |   (Docker Daemon)      |  |
|  +----------+    docker.sock    |   +------------------+  |  |
|                                 |   |   containerd     |  |  |
|  +----------+     REST API      |   |  +------------+  |  |  |
|  | docker   | ----------------->|   |  |   runc     |  |  |  |
|  | CLI      |     /var/run/     |   |  +------------+  |  |  |
|  +----------+    docker.sock    |   +------------------+  |  |
|                                 |                        |  |
|  +----------+     REST API      |   +-----+ +-----+     |  |
|  | docker   | ----------------->|   | C1  | | C2  | ... |  |
|  | CLI      |                   |   +-----+ +-----+     |  |
|  +----------+                   +------------------------+  |
|                                          ^                  |
|                                          |                  |
|                              * Single Point of Failure *    |
|                              If dockerd dies,               |
|                              all container management lost  |
+-------------------------------------------------------------+

+-------------------------------------------------------------+
|                  Podman Architecture (Daemonless Fork-Exec)  |
|                                                              |
|  +----------+   fork/exec    +-------+    +--------------+  |
|  | podman   | -------------->| conmon |--->| Container 1  |  |
|  | CLI      |                +-------+    +--------------+  |
|  +----------+                                                |
|       |                                                      |
|       |          fork/exec    +-------+    +--------------+  |
|       +--------------------->| conmon |--->| Container 2  |  |
|       |                      +-------+    +--------------+  |
|       |                                                      |
|       |          fork/exec    +-------+    +--------------+  |
|       +--------------------->| conmon |--->| Container 3  |  |
|                              +-------+    +--------------+  |
|                                                              |
|  * No daemon: each container is an independent process       |
|  * Exiting Podman CLI does not affect containers             |
|  * conmon: lightweight container monitor (logs, exit codes)  |
|  * Direct OCI runtime (crun/runc) invocation                 |
+-------------------------------------------------------------+

# /etc/containers/systemd/webapp.container (Quadlet format)
[Unit]
Description=Production Web Application
After=network-online.target
Wants=network-online.target

[Container]
Image=registry.example.com/webapp:v2.1.0
PublishPort=8080:8080
Environment=NODE_ENV=production
Environment=DB_HOST=db.internal
Volume=/data/webapp:/app/data:Z
Network=webapp.network
AutoUpdate=registry
HealthCmd=/bin/curl -f http://localhost:8080/health || exit 1
HealthInterval=30s
HealthRetries=3
HealthStartPeriod=10s

[Service]
Restart=always
RestartSec=5
TimeoutStartSec=120
WatchdogSec=60

[Install]
WantedBy=multi-user.target default.target

# ~/.config/containers/systemd/app-network.network
[Network]
Subnet=10.89.1.0/24
Gateway=10.89.1.1

# ~/.config/containers/systemd/postgres.container
[Unit]
Description=PostgreSQL Database

[Container]
Image=docker.io/library/postgres:16-alpine
Volume=pgdata.volume:/var/lib/postgresql/data:Z
Network=app-network.network
Environment=POSTGRES_DB=appdb
Environment=POSTGRES_USER=appuser
Secret=pg-password,type=env,target=POSTGRES_PASSWORD
HealthCmd=pg_isready -U appuser
HealthInterval=10s

[Service]
Restart=always

[Install]
WantedBy=multi-user.target default.target

# ~/.config/containers/systemd/pgdata.volume
[Volume]

# Apply Quadlet
systemctl --user daemon-reload

# Start service
systemctl --user start postgres.service

# Check status
systemctl --user status postgres.service

# View logs
journalctl --user -u postgres.service -f

+-------------------------------------------------------------+
|               User Namespace UID Mapping Diagram             |
|                                                              |
|  +---------------------+      +---------------------------+ |
|  |   Inside Container  |      |        Host System        | |
|  |   (User Namespace)  |      |                           | |
|  |                     |      |                           | |
|  |   UID 0 (root) ----+------+--> UID 1000 (youruser)    | |
|  |   UID 1        ----+------+--> UID 100000             | |
|  |   UID 2        ----+------+--> UID 100001             | |
|  |   UID 3        ----+------+--> UID 100002             | |
|  |   ...               |      |    ...                    | |
|  |   UID 65535    ----+------+--> UID 165535             | |
|  |                     |      |                           | |
|  +---------------------+      +---------------------------+ |
|                                                              |
|  * Even if container root escapes, it's UID 1000 on host    |
|  * Unprivileged user -> no access to system files            |
|  * Kernel exploit scope drastically reduced                  |
+-------------------------------------------------------------+

# /etc/subuid - subordinate UID range per user
youruser:100000:65536

# /etc/subgid - subordinate GID range per user
youruser:100000:65536

# Meaning: youruser can use 65536 UIDs starting from UID 100000

# Run a container in rootless mode
podman run -d --name test-rootless alpine sleep 3600

# Check UID inside the container
podman exec test-rootless id
# uid=0(root) gid=0(root)  <- Appears as root inside container

# Check actual UID on the host
podman top test-rootless huser
# HUSER
# 1000     <- Regular user (UID 1000) on the host

# keep-id mode: Maintain host UID inside the container
# -> Solves bind-mounted file ownership issues
podman run --userns=keep-id -v $HOME/project:/workspace:Z \
  -it node:20-alpine sh

# nomap mode: Does not map host user UID at all
# -> Container cannot access host user-owned files (except world permissions)
podman run --userns=nomap alpine cat /proc/self/uid_map

# Check Podman default Capabilities
podman run --rm alpine grep Cap /proc/1/status
# CapBnd: 00000000a80425fb

# Check Docker default Capabilities
docker run --rm alpine grep Cap /proc/1/status
# CapBnd: 00000000a80435fb
# -> Docker grants more Capabilities (includes NET_RAW, etc.)

+-------------------------------------------------------------+
|              Dev/Ops Language Duality Problem                 |
|                                                              |
|  Developer Laptop                     Production Cluster     |
|  +-------------------+            +--------------------+    |
|  | docker-compose.yml|            |  deployment.yaml   |    |
|  |                   |  ------->  |  service.yaml      |    |
|  | version: "3.8"    | Translation|  configmap.yaml    |    |
|  | services:         |  Required  |  ingress.yaml      |    |
|  |   web:            |            |                    |    |
|  |     image: app    |            |  apiVersion: apps/v1|   |
|  |     ports:        |            |  kind: Deployment  |    |
|  |       - "8080:80" |            |  spec:             |    |
|  +-------------------+            |    replicas: 3     |    |
|                                   +--------------------+    |
|                                                              |
|  * Two syntaxes, two tools, double the learning cost         |
|  * Deployment failures due to subtle conversion differences  |
|  * A new variant of "It worked on my laptop..."              |
+-------------------------------------------------------------+

# microservices-stack.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_HOST: 'postgres'
  DATABASE_PORT: '5432'
  DATABASE_NAME: 'appdb'
  APP_LOG_LEVEL: 'info'
---
apiVersion: v1
kind: Pod
metadata:
  name: microservices
  labels:
    app: microservices-stack
    environment: development
spec:
  # Init container: database migration
  initContainers:
    - name: db-migration
      image: docker.io/library/flyway/flyway:10
      command: ['flyway', 'migrate']
      env:
        - name: FLYWAY_URL
          value: 'jdbc:postgresql://localhost:5432/appdb'
        - name: FLYWAY_USER
          value: 'appuser'
        - name: FLYWAY_PASSWORD
          value: 'secret123'
      volumeMounts:
        - name: migration-scripts
          mountPath: /flyway/sql
  containers:
    # Database
    - name: postgres
      image: docker.io/library/postgres:16-alpine
      ports:
        - containerPort: 5432
      env:
        - name: POSTGRES_DB
          value: 'appdb'
        - name: POSTGRES_USER
          value: 'appuser'
        - name: POSTGRES_PASSWORD
          value: 'secret123'
      volumeMounts:
        - name: pgdata
          mountPath: /var/lib/postgresql/data
    # API Server
    - name: api-server
      image: docker.io/library/node:20-alpine
      ports:
        - containerPort: 3000
          hostPort: 3000
      env:
        - name: DATABASE_HOST
          value: 'localhost'
        - name: DATABASE_PORT
          value: '5432'
      command: ['node', 'server.js']
      volumeMounts:
        - name: app-source
          mountPath: /app
    # Redis Cache
    - name: redis
      image: docker.io/library/redis:7-alpine
      ports:
        - containerPort: 6379
      command: ['redis-server', '--maxmemory', '256mb']
  volumes:
    - name: pgdata
      persistentVolumeClaim:
        claimName: pgdata-pvc
    - name: migration-scripts
      hostPath:
        path: ./migrations
    - name: app-source
      hostPath:
        path: ./src

# Create the entire stack from the YAML file
podman kube play microservices-stack.yaml

# Check running status
podman pod ps
# POD ID        NAME            STATUS   CREATED        INFRA ID      # OF CONTAINERS
# a1b2c3d4e5f6  microservices   Running  10 seconds ago 9f8e7d6c5b4a  4

# Check individual containers
podman ps --pod
# CONTAINER ID  IMAGE                            STATUS         POD ID        NAMES
# ...           docker.io/library/postgres:16    Up 10 seconds  a1b2c3d4e5f6  microservices-postgres
# ...           docker.io/library/node:20        Up 8 seconds   a1b2c3d4e5f6  microservices-api-server
# ...           docker.io/library/redis:7        Up 8 seconds   a1b2c3d4e5f6  microservices-redis

# Check API server logs
podman logs microservices-api-server

# Tear down and clean up the entire stack with the --down flag
podman kube play --down microservices-stack.yaml

# Verify
podman pod ps
# (empty - all resources cleaned up)

Project directory structure:
+-- my-stack.yaml          <- references image: my-api
+-- my-api/                <- auto-build target
|   +-- Containerfile
|   +-- src/
|       +-- server.js
+-- my-frontend/           <- references image: my-frontend
    +-- Containerfile
    +-- dist/
        +-- index.html

# Auto-build images + run with --build flag
podman kube play --build my-stack.yaml

# Replace already-built images (force build)
podman kube play --replace --build my-stack.yaml

# Specifying Init container type (Podman annotation)
metadata:
  annotations:
    io.podman.annotations.init.container.type/wait-for-db: 'always'
spec:
  initContainers:
    - name: wait-for-db
      image: docker.io/library/busybox:latest
      command:
        ['sh', '-c', 'until nc -z localhost 5432; do echo "Waiting for DB..."; sleep 2; done']

+-------------------------------------------------------------+
|                      Podman Pod Architecture                 |
|                                                              |
|  +--- Pod ------------------------------------------------+ |
|  |                                                        | |
|  |  +----------+                                          | |
|  |  |  Infra   |  <- pause container                      | |
|  |  |Container |  <- network namespace owner              | |
|  |  | (pause)  |  <- Pod lifecycle anchor                 | |
|  |  +----------+                                          | |
|  |       |                                                | |
|  |       |-- Shared: Network Namespace                    | |
|  |       |-- Shared: IPC Namespace                        | |
|  |       |-- Shared: UTS Namespace (hostname)             | |
|  |       |                                                | |
|  |  +----------+  +----------+  +----------+             | |
|  |  |   App    |  |  Sidecar |  |  Logging |             | |
|  |  |Container |  | (envoy)  |  | (fluentd)|             | |
|  |  |          |  |          |  |          |             | |
|  |  | :8080    |  | :15001   |  | :24224   |             | |
|  |  +----------+  +----------+  +----------+             | |
|  |                                                        | |
|  |  * All containers communicate via localhost             | |
|  |  * Same network model as Kubernetes Pods                | |
|  +--------------------------------------------------------+ |
|                                                              |
+-------------------------------------------------------------+

# 1. Create Pod (port mapping is set at the Pod level)
podman pod create --name my-app \
  --publish 8080:8080 \
  --publish 9090:9090

# 2. Main application container
podman run -d --pod my-app \
  --name app-main \
  my-registry.io/my-app:v1.0

# 3. Sidecar: Envoy proxy
podman run -d --pod my-app \
  --name app-envoy \
  docker.io/envoyproxy/envoy:v1.31

# 4. Sidecar: Log collector
podman run -d --pod my-app \
  --name app-logger \
  docker.io/fluent/fluentd:v1.17

# 5. Sidecar: Metrics collector
podman run -d --pod my-app \
  --name app-metrics \
  docker.io/prom/node-exporter:v1.8

# Check Pod status
podman pod inspect my-app

# Step 1: Configure Pod locally
podman pod create --name webapp --publish 8080:80

podman run -d --pod webapp \
  --name webapp-nginx \
  -v ./html:/usr/share/nginx/html:Z \
  docker.io/library/nginx:alpine

podman run -d --pod webapp \
  --name webapp-redis \
  docker.io/library/redis:7-alpine

# Step 2: Generate Kubernetes YAML
podman kube generate webapp -f webapp-k8s.yaml

# Step 3: Inspect generated YAML
cat webapp-k8s.yaml

# webapp-k8s.yaml (auto-generated by podman kube generate)
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: '2026-03-01T09:00:00Z'
  labels:
    app: webapp
  name: webapp
spec:
  containers:
    - name: webapp-nginx
      image: docker.io/library/nginx:alpine
      ports:
        - containerPort: 80
          hostPort: 8080
          protocol: TCP
      volumeMounts:
        - mountPath: /usr/share/nginx/html
          name: html-host
    - name: webapp-redis
      image: docker.io/library/redis:7-alpine
  volumes:
    - name: html-host
      hostPath:
        path: /home/user/project/html
        type: Directory

# Step 4: Apply generated YAML to Kubernetes cluster
kubectl apply -f webapp-k8s.yaml

# Or run the same YAML on another Podman host
podman kube play webapp-k8s.yaml

# Generate Service object as well
podman kube generate -s webapp -f webapp-with-service.yaml

# Generate as Deployment type (specify replicas)
podman kube generate --type deployment --replicas 3 webapp

# Can also generate as DaemonSet or Job type
podman kube generate --type job webapp

+-----------------------------------------------------------+
|            Podman <-> Kubernetes Bidirectional Workflow    |
|                                                           |
|   Local Development                  Kubernetes Cluster   |
|   +---------+                       +-------------+      |
|   | podman  |   podman kube generate| kubectl     |      |
|   | pod     | --------------------->| apply -f    |      |
|   | create  |                       |             |      |
|   | + run   |   podman kube play    | Deployment  |      |
|   |         | <---------------------| export      |      |
|   +---------+                       +-------------+      |
|                                                           |
|   * Same YAML, same semantics                             |
|   * No translation needed between environments            |
+-----------------------------------------------------------+

Container -> TAP device -> slirp4netns (user-space NAT) -> Host network

+-------------------------------------------------------------+
|            slirp4netns vs Pasta Architecture Comparison       |
|                                                              |
|  +- slirp4netns (Legacy) ----------------------------------+|
|  |                                                          ||
|  |  Container          User Space             Host          ||
|  |  +-------+    +------------------+    +----------+       ||
|  |  | eth0  |--->|  slirp4netns     |--->| Host     |       ||
|  |  | (TAP) |    |  +------------+  |    | Network  |       ||
|  |  +-------+    |  | User-space |  |    +----------+       ||
|  |               |  | TCP/IP     |  |                       ||
|  |               |  | + NAT      |  |  <- All packets NAT'd||
|  |               |  +------------+  |  <- High CPU overhead ||
|  |               +------------------+                       ||
|  +----------------------------------------------------------+|
|                                                              |
|  +- Pasta (Podman 5.0+ default) ---------------------------+|
|  |                                                          ||
|  |  Container          Kernel Space           Host          ||
|  |  +-------+    +------------------+    +----------+       ||
|  |  | eth0  |--->| L2->L4 socket    |--->| Host     |       ||
|  |  | (TAP) |    |  mapping         |    | Network  |       ||
|  |  +-------+    |  +------------+  |    | cfg copy |       ||
|  |               |  | splice(2)  |  |    +----------+       ||
|  |               |  | sendmmsg() |  |                       ||
|  |               |  | recvmmsg() |  |                       ||
|  |               |  +------------+  |  <- No NAT            ||
|  |               +------------------+  <- Direct socket fwd ||
|  +----------------------------------------------------------+|
|                                                              |
+-------------------------------------------------------------+

# Pasta is the default in Podman 5.0+
# To explicitly specify:
podman run --network=pasta -d nginx

# To fall back to slirp4netns:
podman run --network=slirp4netns -d nginx

# Pasta port forwarding (expose specific ports only)
podman run --network=pasta:-T,8080,-U,5353 -d my-app

# Check Pasta networking status
podman inspect --format '{{.HostConfig.NetworkMode}}' <container>

# macOS
brew install podman
podman machine init --cpus 4 --memory 8192 --disk-size 60
podman machine start

# RHEL/CentOS/Fedora
sudo dnf install -y podman

# Ubuntu/Debian
sudo apt-get install -y podman

# Windows
winget install RedHat.Podman

# ~/.bashrc or ~/.zshrc
alias docker=podman

# Docker Socket compatibility (for tools that use the Docker API)
# macOS:
podman machine stop
podman machine set --rootful
podman machine start

# Linux (rootless):
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

# Method 1: podman compose (Podman 5.x built-in support)
podman compose up -d

# Method 2: podman-compose (Python-based standalone tool)
pip install podman-compose
podman-compose up -d

# Method 3: Convert to Kubernetes YAML (recommended)
# After converting docker-compose.yml to Kubernetes YAML
podman kube play my-stack.yaml

# GitHub Actions example
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Podman
        run: |
          sudo apt-get update
          sudo apt-get install -y podman

      - name: Build Image
        run: podman build -t my-app:${{ github.sha }} .

      - name: Push to Registry
        run: |
          podman login -u ${{ secrets.REGISTRY_USER }} \
                       -p ${{ secrets.REGISTRY_PASS }} \
                       registry.example.com
          podman push my-app:${{ github.sha }} \
                      registry.example.com/my-app:${{ github.sha }}

+-------------------------------------------------------------+
|                   Podman's 5 Innovations Summary             |
|                                                              |
|  +-------------+   Removed the daemon  -> Stability         |
|  | Innovation 1|   Eliminated SPOF     -> Container autonomy|
|  | Daemonless  |   systemd integration -> OS-native mgmt   |
|  +-------------+                                            |
|                                                              |
|  +-------------+   Removed root        -> Minimized attack surface |
|  | Innovation 2|   User Namespace      -> UID isolation     |
|  | Rootless    |   Minimal Capabilities-> Compliance        |
|  +-------------+                                            |
|                                                              |
|  +-------------+   Removed translation -> Dev/Ops language unity |
|  | Innovation 3|   Direct K8s YAML exec-> Cross-env consistency |
|  | play kube   |   Convention builds   -> Workflow simplification |
|  +-------------+                                            |
|                                                              |
|  +-------------+   Removed abstraction -> Same unit as K8s  |
|  | Innovation 4|   Native Pods         -> Local sidecar patterns |
|  | Pod mgmt    |   generate kube       -> Bidirectional workflow |
|  +-------------+                                            |
|                                                              |
|  +-------------+   Removed NAT         -> Reduced latency   |
|  | Innovation 5|   L2-L4 socket mapping-> Increased throughput |
|  | Pasta       |   splice(2)           -> Zero-copy transfer |
|  +-------------+                                            |
|                                                              |
|  * Common philosophy: Maximize essential value by removing   |
|    the unnecessary                                           |
+-------------------------------------------------------------+