Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Pods and Volumes

Kubernetes YAML with podman kube generate and play

Turn pods into Kubernetes YAML with podman kube generate, run YAML with podman kube play, tear down with --down, and learn which Kubernetes fields Podman supports.

Podman can speak a limited, useful part of Kubernetes. It can write a Kubernetes YAML file that describes your pod, and it can read a YAML file and run it on your machine, with no cluster. This gives you two things: a readable, shareable, version-controlled description of a pod, and an easy path from "works on my laptop" toward Kubernetes later.

This lesson shows both directions, a hand-written example, the supported kinds of objects, and the limits to keep in mind. Podman does not replace Kubernetes: it plays back the parts of the manifest that make sense on one host.

Generate YAML from what is running

Start from the pod in the previous lesson:

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

podman kube generate shop > shop.yaml

(You will also see podman generate kube, the older spelling, which still works but kube generate is the current one.) The file looks like this, shortened and with Podman's extra annotations removed:

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

Notes about generated files: they include the container commands and arguments Podman recorded, environment variables, volumes and some annotations that preserve Podman-specific settings. They are a starting point: clean them up before sharing, and never commit secrets that were passed as environment variables. Useful options:

Option Effect
--service also write a Kubernetes Service for the published ports
--filename FILE (-f) write to a file
--type deployment produce a Deployment instead of a Pod
--replicas N set replicas, with --type deployment
--no-trunc keep long command lines

You can also generate from a single container (podman kube generate web) or from volumes.

Run YAML with kube play

Terminal
podman kube play shop.yaml
podman pod ps
podman ps --pod
podman kube down shop.yaml            # stop and remove what the file created

kube play creates the pod, pulls images, creates volumes and starts everything. The reverse command podman kube down FILE (or podman kube play --down FILE) removes them. Because the file is declarative, you can also rerun with --replace to recreate the objects after you changed the file, or --start=false to create but not start.

Write a file by hand

A hand-written file is often better than a generated one. This example runs a small web server with environment variables and a named volume for its data:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: notes
  labels:
    app: notes
spec:
  restartPolicy: Always
  containers:
    - name: web
      image: docker.io/library/nginx:alpine
      ports:
        - containerPort: 80
          hostPort: 8081
      env:
        - name: GREETING
          value: "hello"
      volumeMounts:
        - name: html
          mountPath: /usr/share/nginx/html
          readOnly: true
  volumes:
    - name: html
      persistentVolumeClaim:
        claimName: notes-html

For a persistentVolumeClaim volume, Podman uses (and creates) a Podman named volume called notes-html. Other volume types you can use: hostPath (a bind mount of a host folder), emptyDir (temporary, deleted with the pod) and configMap and secret (see below). Add a securityContext per container for runAsUser, capabilities, readOnlyRootFilesystem and so on.

Supported kinds

podman kube play understands several object kinds. You can put them in one YAML file, separated by ---:

Kind What Podman does
Pod creates a pod and its containers
Deployment creates a pod (and replicas copies); no rolling updates, no controller
DaemonSet, Job creates a pod (Job runs to completion)
PersistentVolumeClaim creates a named volume
ConfigMap provides values for env and as files in volumes
Secret provides values from podman secret-style data in the file or existing secrets
Service accepted, but only published ports matter on one host

Features that need a cluster are ignored or unsupported: node scheduling, Ingress, network policies, horizontal autoscaling, live rolling updates. Always read the warnings Podman prints.

Why this matters

  • Documentation that runs. A YAML file tells a teammate exactly what the pod is. podman kube play runs it, no instructions needed.
  • A bridge. If you later move to Kubernetes, kubectl apply -f accepts the same Pod and Deployment manifests (adjust storage, services and images).
  • systemd integration. A YAML file can be managed by systemd with a Quadlet .kube unit, which you will meet in a later chapter.

Here is a stand-in that checks a tiny subset of a manifest like Podman would: it checks required fields and warns about kinds and fields it would ignore. It reads JSON in the TryIt because there is no YAML parser here, but the structure is identical.

JS Stand-in: pre-flight check of a manifest

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

No output.

Round trip and review

A healthy workflow:

  1. Prototype with podman pod create and podman run --pod.
  2. podman kube generate to capture it.
  3. Edit the YAML: fully qualified images, fixed tags, remove generated noise, move secrets to Secret objects.
  4. podman kube play --down the prototype, then podman kube play the file to prove it works from scratch.
  5. Commit the file.

Another stand-in shows what the "same description, many outputs" idea looks like: it turns a small pod description into the YAML text.

JS Stand-in: render a pod description as YAML

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

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command writes a Kubernetes YAML file from an existing pod named shop?

    kube generate (older spelling: generate kube) prints YAML to standard output.
  2. 2. How do you remove everything that a YAML file created with kube play?

    kube down (or kube play --down) stops and removes the pods and resources defined in the file.
  3. 3. What does a persistentVolumeClaim volume become in podman kube play?

    Podman creates or reuses a named volume with the claim's name.
  4. 4. Which Kubernetes feature does podman kube play not provide?

    Podman runs on one host and does not replace the cluster control plane.
  5. 5. Why edit a generated YAML file before sharing it?

    Generated files capture the current state, including values you may not want to publish.

Summary

  • podman kube generate writes Kubernetes YAML from pods, containers or volumes; podman kube play runs YAML; kube down removes it.
  • Podman supports Pod, Deployment, DaemonSet, Job, PersistentVolumeClaim, ConfigMap, Secret and Service objects in a single-host form.
  • PVC volumes become named volumes; hostPath is a bind mount and emptyDir is temporary.
  • Cluster-only features (scheduling, Ingress, autoscaling) are ignored.
  • Review and clean generated files; they are a starting point for documentation and for Kubernetes later.

Next: Volumes and Bind Mounts