Skip to main content

Pods

Podman's unique pod management capabilities for grouping containers, Kubernetes-style orchestration, and multi-container application deployment.

Pod Basics​

Understanding Pods​

Pods in Podman are groups of containers that share network and storage namespaces, similar to Kubernetes pods. Containers in a pod can communicate using localhost and share volumes.

Creating Pods​

# Create empty pod
podman pod create --name mypod

# Create pod with port mapping
podman pod create --name webapp -p 8080:80

# Create pod with shared volumes
podman pod create --name datastack -v shared-data:/data

# Create pod with custom network
podman pod create --name netpod --network custom-net

# Create pod with labels
podman pod create --name labeled-pod --label app=myapp --label env=prod

Pod Information​

# List pods
podman pod ps
podman pod ps -a               # Include stopped pods
podman pod ps --format table  # Formatted output

# Pod details
podman pod inspect mypod
podman pod top mypod          # Processes in all containers
podman pod stats mypod        # Resource usage

Running Containers in Pods​

Adding Containers to Pods​

# Run container in existing pod
podman run -d --pod mypod nginx
podman run -d --pod mypod --name web nginx
podman run -it --pod mypod alpine sh

# Multiple containers in same pod
podman pod create --name webapp -p 8080:80
podman run -d --pod webapp --name web nginx
podman run -d --pod webapp --name cache redis
podman run -d --pod webapp --name db postgres

Pod with Shared Storage​

# Create pod with shared volume
podman pod create --name shared-storage -v app-data:/shared

# Containers sharing the volume
podman run -d --pod shared-storage --name producer \
  -v app-data:/output \
  alpine sh -c 'while true; do date > /output/timestamp; sleep 5; done'

podman run -d --pod shared-storage --name consumer \
  -v app-data:/input \
  alpine sh -c 'while true; do cat /input/timestamp; sleep 1; done'

Pod Lifecycle Management​

Starting and Stopping Pods​

# Start pod (starts all containers)
podman pod start mypod

# Stop pod (stops all containers)
podman pod stop mypod

# Restart pod
podman pod restart mypod

# Pause/unpause entire pod
podman pod pause mypod
podman pod unpause mypod

# Kill pod (force stop)
podman pod kill mypod

Pod Removal​

# Remove stopped pod
podman pod rm mypod

# Force remove running pod
podman pod rm -f mypod

# Remove all stopped pods
podman pod prune

# Remove pod and all containers
podman pod rm -f --all mypod

Pod Status and Monitoring​

# Check pod status
podman pod ps
podman pod ps --filter status=running
podman pod ps --filter label=app=myapp

# Monitor pod resources
podman pod stats
podman pod stats mypod --no-stream

# Pod logs (all containers)
podman pod logs mypod
podman pod logs -f mypod      # Follow logs

Advanced Pod Configuration​

Pod with Custom Network​

# Create custom network
podman network create --subnet=192.168.100.0/24 podnet

# Create pod with custom network
podman pod create --name netpod --network podnet

# Add containers to networked pod
podman run -d --pod netpod --name web nginx
podman run -d --pod netpod --name api node:alpine

Pod with Resource Limits​

# Create pod with resource constraints
podman pod create --name limited-pod \
  --memory=1g \
  --cpus=2.0 \
  --memory-swap=2g

# Containers inherit pod limits
podman run -d --pod limited-pod nginx
podman run -d --pod limited-pod redis

Pod Security Configuration​

# Create pod with security options
podman pod create --name secure-pod \
  --security-opt label=level:s0:c123,c456 \
  --userns keep-id

# Add containers with additional security
podman run -d --pod secure-pod \
  --cap-drop ALL \
  --cap-add NET_BIND_SERVICE \
  nginx

Multi-Container Applications​

Web Application Stack​

# Create web application pod
podman pod create --name webapp-stack -p 80:80 -p 443:443

# Add web server
podman run -d --pod webapp-stack --name nginx \
  nginx

# Add application server
podman run -d --pod webapp-stack --name app \
  -e DATABASE_URL=postgresql://localhost/myapp \
  myapp:latest

# Add database
podman run -d --pod webapp-stack --name postgres \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_PASSWORD=secret \
  postgres:13

# Add cache
podman run -d --pod webapp-stack --name redis \
  redis:alpine

Monitoring Stack​

# Create monitoring pod
podman pod create --name monitoring \
  -p 3000:3000 \
  -p 9090:9090 \
  -v monitoring-data:/data

# Add Prometheus
podman run -d --pod monitoring --name prometheus \
  -v monitoring-data:/prometheus \
  prom/prometheus

# Add Grafana
podman run -d --pod monitoring --name grafana \
  -v monitoring-data:/var/lib/grafana \
  grafana/grafana

# Add Node Exporter
podman run -d --pod monitoring --name node-exporter \
  prom/node-exporter

Development Environment​

# Create development pod
podman pod create --name devenv \
  -p 3000:3000 \
  -p 5432:5432 \
  -v $(pwd):/workspace

# Add development container
podman run -it --pod devenv --name dev \
  -v $(pwd):/workspace \
  -w /workspace \
  node:18-alpine \
  sh

# Add database for development
podman run -d --pod devenv --name dev-db \
  -e POSTGRES_PASSWORD=dev \
  postgres:13

Pod Networking​

Internal Communication​

# Containers in same pod communicate via localhost
podman pod create --name comm-test -p 8080:80

# Web server container
podman run -d --pod comm-test --name web nginx

# API container (accessible via localhost from web container)
podman run -d --pod comm-test --name api \
  -e PORT=3000 \
  node:alpine sh -c 'node -e "require(\"http\").createServer((req,res)=>res.end(\"API\")).listen(3000)"'

# Test communication
podman exec web curl localhost:3000

Pod Network Modes​

# Host networking
podman pod create --name hostpod --network host

# No networking
podman pod create --name isolated --network none

# Custom bridge network
podman network create mybridgenet
podman pod create --name bridgepod --network mybridgenet

Kubernetes Integration​

Generating Kubernetes YAML​

# Generate Kubernetes YAML from pod
podman generate kube mypod > mypod.yaml

# Generate with service
podman generate kube --service mypod > mypod-with-service.yaml

# Include volumes in YAML
podman generate kube --volume mypod > mypod-complete.yaml

Example Generated YAML​

# Example output of podman generate kube
apiVersion: v1
kind: Pod
metadata:
  name: webapp-stack
spec:
  containers:
    - name: nginx
      image: nginx
      ports:
        - containerPort: 80
          hostPort: 80
    - name: app
      image: myapp:latest
      env:
        - name: DATABASE_URL
          value: postgresql://localhost/myapp
    - name: postgres
      image: postgres:13
      env:
        - name: POSTGRES_DB
          value: myapp
        - name: POSTGRES_PASSWORD
          value: secret

Running Kubernetes YAML​

# Create pod from Kubernetes YAML
podman play kube mypod.yaml

# Update existing pod from YAML
podman play kube --replace mypod.yaml

# Remove pod created from YAML
podman play kube --down mypod.yaml

Pod Templates and Automation​

Pod Template Script​

#!/bin/bash
# create-webapp-pod.sh

POD_NAME=${1:-webapp}
WEB_IMAGE=${2:-nginx}
APP_IMAGE=${3:-myapp:latest}

echo "Creating pod: $POD_NAME"
podman pod create --name $POD_NAME -p 80:80

echo "Adding web server"
podman run -d --pod $POD_NAME --name web $WEB_IMAGE

echo "Adding application"
podman run -d --pod $POD_NAME --name app $APP_IMAGE

echo "Pod $POD_NAME created successfully"
podman pod ps --filter name=$POD_NAME

Pod Compose Alternative​

# pod-stack.sh - Docker Compose-like script
#!/bin/bash

case $1 in
  up)
    podman pod create --name mystack -p 80:80 -p 5432:5432
    podman run -d --pod mystack --name web nginx
    podman run -d --pod mystack --name db postgres:13
    podman run -d --pod mystack --name cache redis
    ;;
  down)
    podman pod stop mystack
    podman pod rm mystack
    ;;
  logs)
    podman pod logs -f mystack
    ;;
  *)
    echo "Usage: $0 {up|down|logs}"
    ;;
esac

Pod Troubleshooting​

Debugging Pod Issues​

# Check pod status
podman pod ps
podman pod inspect mypod

# Check individual containers in pod
podman ps --filter pod=mypod

# Container logs within pod
podman logs -f container_name

# Execute commands in pod containers
podman exec -it container_name sh

# Network connectivity test
podman exec container_name ping localhost
podman exec container_name netstat -tulpn

Pod Resource Issues​

# Check resource usage
podman pod stats mypod

# Check individual container resources
podman stats container_name

# Inspect resource limits
podman pod inspect mypod | grep -A 10 Resources

Pod Networking Issues​

# Check pod network configuration
podman pod inspect mypod | grep -A 20 NetworkSettings

# Test internal connectivity
podman exec web-container curl localhost:3000
podman exec web-container nslookup localhost

# Check port mappings
podman port mypod

Production Pod Patterns​

High Availability Setup​

# Create multiple pod instances
for i in {1..3}; do
  podman pod create --name webapp-$i -p $((8080+i)):80
  podman run -d --pod webapp-$i --name web-$i nginx
  podman run -d --pod webapp-$i --name app-$i myapp:latest
done

Pod Health Monitoring​

# Pod with health checks
podman pod create --name monitored-pod -p 80:80

podman run -d --pod monitored-pod --name web \
  --health-cmd="curl -f http://localhost || exit 1" \
  --health-interval=30s \
  nginx

# Check pod health
podman pod ps --format "table {{.Name}}\t{{.Status}}\t{{.InfraID}}"

Pod Backup and Migration​

# Export pod configuration
podman generate kube mypod > mypod-backup.yaml

# Export pod data
podman run --rm -v pod-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/pod-data-$(date +%Y%m%d).tar.gz /data

# Restore pod
podman play kube mypod-backup.yaml

Quick Reference​

Essential Pod Commands​

# Pod lifecycle
podman pod create --name mypod
podman pod start mypod
podman pod stop mypod
podman pod rm mypod

# Add containers to pod
podman run -d --pod mypod nginx
podman run -it --pod mypod alpine sh

# Pod information
podman pod ps
podman pod inspect mypod
podman pod logs mypod

# Kubernetes integration
podman generate kube mypod > mypod.yaml
podman play kube mypod.yaml

Common Pod Patterns​

# Web application pod
podman pod create --name webapp -p 80:80
podman run -d --pod webapp nginx
podman run -d --pod webapp myapp:latest

# Shared storage pod
podman pod create --name shared -v data:/shared
podman run -d --pod shared --name writer alpine
podman run -d --pod shared --name reader alpine

# Networked services pod
podman pod create --name services
podman run -d --pod services nginx    # Accessible via localhost
podman run -d --pod services redis    # from other containers