Comprehensive Guide to Using Podman with Kubernetes

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#

1
graph TB
2
    subgraph "Development Environment"
3
        A[Podman CLI] --> B[Container/Pod]
4
        B --> C[podman generate kube]
5
    end
6

7
    subgraph "Kubernetes Manifest"
8
        C --> D[Generated YAML]
9
        D --> E[Manual Adjustments]
10
    end
11

12
    subgraph "Kubernetes Cluster"
13
        E --> F[kubectl apply]
14
        F --> G[Kubernetes Resources]
15
    end
16

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

Basic Podman to Kubernetes Workflow#

1. Generate Kubernetes YAML from Containers#

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

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

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

2. Simple Container Example#

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

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

The generated YAML structure:

1
apiVersion: v1
2
kind: Pod
3
metadata:
4
  name: webserver
5
  labels:
6
    app: webserver
7
spec:
8
  containers:
9
    - name: webserver
10
      image: docker.io/library/nginx:latest
11
      ports:
12
        - containerPort: 80
13
          protocol: TCP

Common Integration Patterns#

Image Management Workflow#

1
sequenceDiagram
2
    participant Dev as Developer
3
    participant P as Podman
4
    participant R as Registry
5
    participant K as Kubernetes
6

7
    Dev->>P: podman build
8
    P->>P: Create image
9
    Dev->>P: podman push
10
    P->>R: Upload image
11
    Dev->>K: kubectl apply
12
    K->>R: Pull image
13
    K->>K: Deploy container

Building and Pushing Images#

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

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

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

Using Podman with Kind#

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

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

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

Multi-Container Pod Workflows#

Creating Complex Pods#

1
# Create pod with multiple containers
2
podman pod create --name mypod
3
podman run -dt --pod mypod --name web nginx
4
podman run -dt --pod mypod --name redis redis
5

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

Pod Architecture#

1
graph LR
2
    subgraph "Podman Pod"
3
        A[Pod: mypod]
4
        A --> B[Container: web<br/>nginx]
5
        A --> C[Container: redis<br/>redis:latest]
6
        A --> D[Shared Network]
7
        A --> E[Shared PID namespace]
8
    end
9

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

Advanced Features#

1. Security Context Generation#

1
# Run rootless containers
2
podman run --user 1000:1000 nginx
3

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

2. Volume Management#

1
graph TD
2
    A[Podman Volumes] --> B{Volume Types}
3
    B --> C[Named Volumes]
4
    B --> D[Bind Mounts]
5
    B --> E[tmpfs]
6

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

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

Development Workflow#

Local Development to Production Pipeline#

1
graph LR
2
    A[Local Development] --> B[Podman Compose]
3
    B --> C[Test Locally]
4
    C --> D[Generate K8s Manifests]
5
    D --> E[Modify for Production]
6
    E --> F[Deploy to K8s]
7

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

Example Development Process#

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

4
# 2. Test and develop locally
5

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

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

Best Practices#

1. Image Management#

Always tag images properly
Use multi-stage builds
Leverage Podman’s rootless containers
Maintain consistency between environments

2. Manifest Customization#

Generated manifests often need modifications for production:

1
# Add resource limits
2
resources:
3
  limits:
4
    memory: "512Mi"
5
    cpu: "500m"
6
  requests:
7
    memory: "256Mi"
8
    cpu: "250m"
9

10
# Add health checks
11
livenessProbe:
12
  httpGet:
13
    path: /health
14
    port: 8080
15
  initialDelaySeconds: 30
16
  periodSeconds: 10

Troubleshooting Guide#

Common Issues and Solutions#

1. Version and Info Check#

1
# Check Podman version and info
2
podman version
3
podman info

2. Container Status Verification#

1
# Verify container status
2
podman ps -a
3

4
# Check container logs
5
podman logs container_name
6

7
# Inspect container details
8
podman inspect container_name

3. Network Troubleshooting#

1
graph TD
2
    A[Network Issue] --> B{Diagnosis}
3
    B --> C[Check DNS]
4
    B --> D[Verify Ports]
5
    B --> E[Inspect Network]
6

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

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

Kubernetes Manifest Modifications#

Production-Ready Adjustments#

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

Resource Management

1
spec:
2
  containers:
3
    - name: app
4
      resources:
5
        limits:
6
          memory: "1Gi"
7
          cpu: "1000m"
8
        requests:
9
          memory: "512Mi"
10
          cpu: "500m"

Service Accounts and RBAC
```
1
spec:
2
  serviceAccountName: myapp-sa
```

Network Policies

1
apiVersion: networking.k8s.io/v1
2
kind: NetworkPolicy
3
metadata:
4
  name: myapp-netpol
5
spec:
6
  podSelector:
7
    matchLabels:
8
      app: myapp

Persistent Storage

1
volumes:
2
  - name: data
3
    persistentVolumeClaim:
4
      claimName: myapp-pvc

Rootless Container Benefits#

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

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

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

12
    D --> I[Safer Development]
13
    D --> J[Production Ready]
14

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

Common Pitfalls to Avoid#

Not Setting Proper Image Tags

1
# Bad
2
podman build -t myapp .
3

4
# Good
5
podman build -t myapp:v1.0.0 .

Forgetting Registry Access

1
# Ensure Kubernetes can access your registry
2
kubectl create secret docker-registry regcred \
3
  --docker-server=registry.example.com \
4
  --docker-username=user \
5
  --docker-password=pass

Ignoring Security Contexts

1
securityContext:
2
  runAsNonRoot: true
3
  runAsUser: 1000
4
  fsGroup: 2000

Integration with CI/CD#

GitLab CI Example#

1
stages:
2
  - build
3
  - deploy
4

5
build:
6
  stage: build
7
  script:
8
    - podman build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
9
    - podman push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
10

11
deploy:
12
  stage: deploy
13
  script:
14
    - podman generate kube myapp > k8s-manifest.yaml
15
    - kubectl apply -f k8s-manifest.yaml

Performance Considerations#

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

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

10
    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:

Podman seamlessly integrates with Kubernetes workflows
podman generate kube bridges local development and Kubernetes deployment
Rootless containers provide enhanced security
Generated manifests often need production-specific modifications
Podman can replace Docker in most Kubernetes workflows

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