Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Systemd and Operations

Podman and Kubernetes YAML

Use Kubernetes YAML with Podman: podman kube generate to export pods, podman kube play to run Pod, Deployment, PersistentVolumeClaim and ConfigMap files, and podman kube down.

Kubernetes describes workloads in YAML. Podman can read a useful subset of that YAML and run it on a single machine, and it can produce YAML from containers and pods you already have. This gives you a smooth path in both directions: develop locally with Podman, then hand the same description to a Kubernetes cluster, or take a Kubernetes manifest and try it on your laptop without a cluster.

This lesson covers podman kube generate, podman kube play, the supported object kinds, and how to run the result under systemd. Real Podman is not available in the browser, so commands are read-only; stand-ins build and inspect pod manifests.

Why this exists

Podman's own concept of a pod (containers sharing a network namespace) matches a Kubernetes Pod closely. That is why a Kubernetes Pod manifest maps almost directly onto podman pod create plus podman run --pod. It is not a Kubernetes replacement: there is no scheduler, no multi-node cluster and no Services load balancing. It is a convenient single-host runner for the same YAML.

Generating YAML

Create a pod with two containers, then export it:

Terminal
podman pod create --name shop -p 8080:80
podman run -d --pod shop --name web docker.io/library/nginx:stable
podman run -d --pod shop --name cache docker.io/library/redis:7

podman kube generate shop > shop.yaml

You can also generate from one container, a volume or add a Service object:

Terminal
podman kube generate web
podman kube generate -s shop            # also writes a Service
podman kube generate --type deployment shop

The file begins with a comment saying which Podman version created it. It contains a Pod (or Deployment) with containers, ports, environment variables, volume mounts and security settings that Podman could read from the running objects.

A minimal manifest looks like this:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: shop
spec:
  containers:
    - name: web
      image: docker.io/library/nginx:stable
      ports:
        - containerPort: 80
          hostPort: 8080
    - name: cache
      image: docker.io/library/redis:7

Running YAML

Terminal
podman kube play shop.yaml
podman pod ps
podman ps --pod
podman kube down shop.yaml
  • kube play creates the pod and its containers, pulling images as needed.
  • kube down stops and removes everything the file created (add --force to remove named volumes too).
  • --replace recreates objects that already exist, handy while editing: podman kube play --replace shop.yaml.
  • --start=false creates without starting.
  • --build builds images from a Containerfile found in a directory named after the image.
  • --network NAME attaches the pod to a Podman network; --publish 8081:80 publishes extra ports.

Kinds Podman understands

Kind What Podman does
Pod Creates a pod with its containers
Deployment Creates a pod from the template (replicas become pod copies)
DaemonSet, Job Runs as a pod (with limitations)
PersistentVolumeClaim Creates a named Podman volume
ConfigMap Provides environment variables or mounted files
Secret Provides environment variables or mounted files (from the file or Podman secrets)
Service Used for port information, not load balancing

You can put several documents in one file, separated by ---, for example a PersistentVolumeClaim, a ConfigMap and a Pod.

Python Build a Pod manifest (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

(JSON is valid YAML, so the printed document is a legal manifest.)

Mapping a manifest back to commands

Understanding what kube play does makes failures easier to debug. This stand-in reads a manifest and prints the equivalent Podman commands.

Python What would kube play run? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Container names created by kube play are <pod>-<container> (for example shop-web), which the stand-in mirrors.

Persistent data and configuration

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: dbdata
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: db
spec:
  containers:
    - name: postgres
      image: docker.io/library/postgres:17
      env:
        - name: POSTGRES_PASSWORD
          value: example
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: dbdata

The claim becomes a Podman volume named dbdata. Host paths work too (hostPath volumes), which is often what developers want locally.

Running under systemd

A .kube Quadlet file starts the YAML at boot and supervises it:

INI
# shop.kube
[Kube]
Yaml=shop.yaml

[Install]
WantedBy=default.target

This is the easiest way to migrate a Kubernetes-style definition into a service on a single server (see Quadlet for Pods, Volumes and Networks).

kube play supports a subset of Kubernetes. Features that need a cluster (Ingress, RBAC, HPA, NetworkPolicy, multi-node scheduling) are ignored or unsupported. Test the YAML you plan to deploy on a real cluster, not only with Podman.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does podman kube generate shop produce?

    kube generate exports existing Podman objects as Kubernetes YAML.
  2. 2. How do you remove everything a YAML file created?

    podman kube down stops and removes the pods and containers created from the file.
  3. 3. What does a PersistentVolumeClaim become under podman kube play?

    The claim name becomes a named volume that containers can mount.
  4. 4. Which is true about Services in Podman's kube support?

    Podman runs on one host and has no Kubernetes Services layer.

Summary

  • podman kube generate exports containers and pods as Kubernetes YAML; podman kube play runs YAML; podman kube down removes it.
  • Pods, Deployments, PVCs, ConfigMaps and Secrets are supported; cluster-only features are not.
  • Container names follow <pod>-<container>; PVCs become named volumes.
  • A .kube Quadlet unit runs the YAML under systemd at boot.
  • Treat Podman as a single-host runner for the same files, not a replacement for a cluster.

Next: Storage Maintenance and Cleanup