Skip to content

Comprehensive Guide to Using Podman with Kubernetes

Published: at 11:00 AM

Table of Contents

Open Table of Contents

Overview

Podman is a daemonless container engine that provides a Docker-compatible command line experience while offering unique features like rootless containers and native Kubernetes integration. This guide explores how to effectively use Podman with Kubernetes for both development and production workflows.

Podman to Kubernetes Architecture

graph TB
    subgraph "Development Environment"
        A[Podman CLI] --> B[Container/Pod]
        B --> C[podman generate kube]
    end

    subgraph "Kubernetes Manifest"
        C --> D[Generated YAML]
        D --> E[Manual Adjustments]
    end

    subgraph "Kubernetes Cluster"
        E --> F[kubectl apply]
        F --> G[Kubernetes Resources]
    end

    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style D fill:#ffd43b,stroke:#fab005,stroke-width:2px
    style G fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Basic Podman to Kubernetes Workflow

1. Generate Kubernetes YAML from Containers

# Generate Kubernetes YAML from a Podman container
podman generate kube container_name > pod.yaml

# Create Kubernetes resources from Podman-generated YAML
podman play kube pod.yaml

# Generate YAML for multiple containers in a pod
podman generate kube pod_name > multipod.yaml

2. Simple Container Example

# Run a container using Podman
podman run -d --name webserver nginx

# Generate Kubernetes manifest
podman generate kube webserver > nginx-pod.yaml

The generated YAML structure:

apiVersion: v1
kind: Pod
metadata:
  name: webserver
  labels:
    app: webserver
spec:
  containers:
    - name: webserver
      image: docker.io/library/nginx:latest
      ports:
        - containerPort: 80
          protocol: TCP

Common Integration Patterns

Image Management Workflow

sequenceDiagram
    participant Dev as Developer
    participant P as Podman
    participant R as Registry
    participant K as Kubernetes

    Dev->>P: podman build
    P->>P: Create image
    Dev->>P: podman push
    P->>R: Upload image
    Dev->>K: kubectl apply
    K->>R: Pull image
    K->>K: Deploy container

Building and Pushing Images

# Build an image
podman build -t myapp:latest .

# Push to a registry
podman push myapp:latest registry.example.com/myapp:latest

# Convert from Docker Compose to Kubernetes
podman-compose -f docker-compose.yml kube > k8s-deployment.yaml

Using Podman with Kind

Kind (Kubernetes in Docker) can work with Podman images:

# Save Podman image to tar
podman save -o myapp.tar myapp:latest

# Load image into Kind cluster
kind load image-archive myapp.tar

Multi-Container Pod Workflows

Creating Complex Pods

# Create pod with multiple containers
podman pod create --name mypod
podman run -dt --pod mypod --name web nginx
podman run -dt --pod mypod --name redis redis

# Generate Kubernetes manifest for the pod
podman generate kube mypod > multipod.yaml

Pod Architecture

graph LR
    subgraph "Podman Pod"
        A[Pod: mypod]
        A --> B[Container: web<br/>nginx]
        A --> C[Container: redis<br/>redis:latest]
        A --> D[Shared Network]
        A --> E[Shared PID namespace]
    end

    style A fill:#e9ecef,stroke:#495057,stroke-width:2px
    style B fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style C fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px

Advanced Features

1. Security Context Generation

# Run rootless containers
podman run --user 1000:1000 nginx

# Generate YAML with security contexts
podman generate kube --security-opt=no-new-privileges container_name

2. Volume Management

graph TD
    A[Podman Volumes] --> B{Volume Types}
    B --> C[Named Volumes]
    B --> D[Bind Mounts]
    B --> E[tmpfs]

    C --> F[Persistent across restarts]
    D --> G[Host filesystem access]
    E --> H[Temporary in-memory]

    style A fill:#74c0fc,stroke:#1971c2,stroke-width:2px
    style B fill:#ffd43b,stroke:#fab005,stroke-width:2px

Development Workflow

Local Development to Production Pipeline

graph LR
    A[Local Development] --> B[Podman Compose]
    B --> C[Test Locally]
    C --> D[Generate K8s Manifests]
    D --> E[Modify for Production]
    E --> F[Deploy to K8s]

    style A fill:#d0f0c0,stroke:#5cb85c,stroke-width:2px
    style F fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Example Development Process

# 1. Create development environment
podman-compose up -d

# 2. Test and develop locally

# 3. Generate Kubernetes manifests
podman generate kube devenv > k8s-dev.yaml

# 4. Apply to Kubernetes
kubectl apply -f k8s-dev.yaml

Best Practices

1. Image Management

2. Manifest Customization

Generated manifests often need modifications for production:

# Add resource limits
resources:
  limits:
    memory: "512Mi"
    cpu: "500m"
  requests:
    memory: "256Mi"
    cpu: "250m"

# Add health checks
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

Troubleshooting Guide

Common Issues and Solutions

1. Version and Info Check

# Check Podman version and info
podman version
podman info

2. Container Status Verification

# Verify container status
podman ps -a

# Check container logs
podman logs container_name

# Inspect container details
podman inspect container_name

3. Network Troubleshooting

graph TD
    A[Network Issue] --> B{Diagnosis}
    B --> C[Check DNS]
    B --> D[Verify Ports]
    B --> E[Inspect Network]

    C --> F[podman network ls]
    D --> G[podman port container]
    E --> H[podman network inspect]

    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
    style B fill:#ffd43b,stroke:#fab005,stroke-width:2px

Kubernetes Manifest Modifications

Production-Ready Adjustments

When moving from Podman-generated manifests to production, consider:

  1. Resource Management

    spec:
      containers:
        - name: app
          resources:
            limits:
              memory: "1Gi"
              cpu: "1000m"
            requests:
              memory: "512Mi"
              cpu: "500m"
    
  2. Service Accounts and RBAC

    spec:
      serviceAccountName: myapp-sa
    
  3. Network Policies

    apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: myapp-netpol
    spec:
      podSelector:
        matchLabels:
          app: myapp
    
  4. Persistent Storage

    volumes:
      - name: data
        persistentVolumeClaim:
          claimName: myapp-pvc
    

Rootless Container Benefits

graph TD
    A[Rootless Containers] --> B[Security Benefits]
    A --> C[User Namespace Isolation]
    A --> D[No Root Privileges]

    B --> E[Reduced Attack Surface]
    B --> F[Compliance Benefits]

    C --> G[UID/GID Mapping]
    C --> H[Process Isolation]

    D --> I[Safer Development]
    D --> J[Production Ready]

    style A fill:#d0f0c0,stroke:#5cb85c,stroke-width:2px
    style B fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Common Pitfalls to Avoid

  1. Not Setting Proper Image Tags

    # Bad
    podman build -t myapp .
    
    # Good
    podman build -t myapp:v1.0.0 .
    
  2. Forgetting Registry Access

    # Ensure Kubernetes can access your registry
    kubectl create secret docker-registry regcred \
      --docker-server=registry.example.com \
      --docker-username=user \
      --docker-password=pass
    
  3. Ignoring Security Contexts

    securityContext:
      runAsNonRoot: true
      runAsUser: 1000
      fsGroup: 2000
    

Integration with CI/CD

GitLab CI Example

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - podman build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - podman push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

deploy:
  stage: deploy
  script:
    - podman generate kube myapp > k8s-manifest.yaml
    - kubectl apply -f k8s-manifest.yaml

Performance Considerations

graph LR
    A[Podman Performance] --> B[No Daemon Overhead]
    A --> C[Direct Kernel Access]
    A --> D[Efficient Resource Usage]

    B --> E[Faster Startup]
    C --> F[Better I/O Performance]
    D --> G[Lower Memory Footprint]

    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px

Conclusion

Podman provides a powerful, secure, and Kubernetes-friendly alternative to Docker. Its ability to generate Kubernetes manifests, support for rootless containers, and OCI compliance make it an excellent choice for modern container workflows.

Key takeaways:

Whether you’re developing locally or deploying to production, Podman’s Kubernetes integration features streamline the container lifecycle while maintaining security and compatibility.