Chapter 8: Working with Kubernetes
Introduces Kubernetes as the tool for orchestrating containers across machines and outlines how Podman helps developers work with Kubernetes YAML and run Podman in containers.
After this chapter you will be able to
- Podman and Kubernetes roles. Distinguish Podman’s role in creating local containers and pods from Kubernetes’s role in deploying, scaling, and managing containerized applications across machines. Explain why the chapter recommends CRI-O rather than Podman as a Kubernetes container backend.
- Kubernetes YAML development bridge. Explain the difficulty of moving from Podman command-line options to Kubernetes’s declarative YAML files, and describe the two directions of the chapter’s workflow: generating YAML from local pods and containers, then running Kubernetes YAML locally with podman play kube to test or debug without a cluster.
- Kubernetes YAML purpose. Explain that Kubernetes YAML files describe the desired state of an application and are used to launch pods and containers in Kubernetes.
- YAML authoring barrier. Explain why writing Kubernetes YAML can be a barrier when moving local containers to Kubernetes: developers may copy an existing file and paste in their container command, image, and options, risking unintended consequences and unnecessary work.
- Podman generation motivation. State that Podman developers created `podman generate kube` to help users move from working with containers in Podman toward orchestrating them with Kubernetes.
- Kubernetes YAML generation workflow. Explain how to recreate a local container or pod and use `podman generate kube myapp` to produce Kubernetes YAML from it. Describe the optional output-file and service-object flags.
- Generated pod specification contents. Describe how the generated YAML represents even a single original container as a Kubernetes pod, and identify the application details carried into its container specification.
- Kubernetes handoff and replica limits. Explain that Kubernetes commands can launch the generated YAML in a cluster, while orchestration features such as two replicas must be added to the YAML. Distinguish those Kubernetes-specific fields from what `podman play kube` supports.
- Local playback of Kubernetes YAML. Explain that `podman play kube` reads structured Kubernetes YAML and automatically creates and starts its pods, containers, and volumes locally, without setting up a Kubernetes cluster. Describe why the example starts a pod rather than a standalone container.
- Simple pod shutdown limits. Explain that the simple example can be shut down with `podman pod stop`, while a YAML file that creates multiple distinct pods makes shutdown more complex.
- YAML-based pod teardown. Explain that podman play kube --down stops and removes pods created by an earlier play kube run, while leaving created volumes intact. Describe how to verify removal and then run play kube again to create fresh pods and containers.
- On-demand image building. Explain how podman play kube --build replaces the usual build, push, and pull steps by building an image locally when it launches the pod. Distinguish this Podman feature from Kubernetes, which does not build images from YAML files.
- Matching image build directories. Describe how podman play kube --build finds build inputs: it reads image names from the YAML, looks for matching subdirectories, and runs podman build using each directory as a context containing a Containerfile or Dockerfile.
- Nested Podman setup choices. Describe the section's setup for learning nested Podman: the quay.io/podman/stable image simplifies a configuration-heavy task, Podman can run rootful or rootless, and the upcoming Podman-within-Podman experiment considers the capabilities needed for the inner Podman to run a container.
- Rootful Podman mounting requirements. Explain why running rootful Podman inside a rootless Podman container requires --privileged: the inner Podman must mount filesystems, and mounting as root requires CAP_SYS_ADMIN.
- Rootless Podman capability choices. Describe how --user podman runs rootless Podman inside the container and why it needs CAP_SETUID and CAP_SETGID to set up a user namespace. Explain that these capabilities are available by default and that the outer container can instead drop all capabilities and add back just those two.
- Podman requirements inside Kubernetes. Explain why Podman needs suitable Linux capabilities and access to more than one UID inside a Kubernetes container, especially for podman build. Describe why a locked-down container with one UID and no capabilities cannot run it.
- Rootful and rootless pod examples. Distinguish the section's privileged rootful example using quay.io/podman/stable from its rootless Kubernetes YAML example. Explain why the rootless example specifies runAsUser: 1000 rather than the podman username.
What it builds on
- Running pods (chapter 4) · Running pods with Podman.
- (chapter intro) (chapter 5) · Podman's configuration files are written using TOML.
- Running the containerized application (chapter 2) · Running a containerized application from the command line.
- Creating a pod (chapter 4) · Creating a Podman pod.
- Building images (chapter 2) · building images with podman build and a Containerfile
- Pushing images (chapter 2) · pushing images to a registry
- Format of a Containerfile or Dockerfile (chapter 2) · the role of a Containerfile or Dockerfile in building an image
- Using volumes with containers (chapter 3) · mounting a host directory into a container
Section by section
Introduction
Introduces Kubernetes as the tool for orchestrating containers across machines and outlines how Podman helps developers work with Kubernetes YAML and run Podman in containers.
- Podman and Kubernetes roles: Distinguish Podman’s role in creating local containers and pods from Kubernetes’s role in deploying, scaling, and managing containerized applications across machines. Explain why the chapter recommends CRI-O rather than Podman as a Kubernetes container backend.
Why it matters: This distinction clarifies what Podman can help you develop locally and what Kubernetes is meant to orchestrate. - Kubernetes YAML development bridge: Explain the difficulty of moving from Podman command-line options to Kubernetes’s declarative YAML files, and describe the two directions of the chapter’s workflow: generating YAML from local pods and containers, then running Kubernetes YAML locally with podman play kube to test or debug without a cluster.
Why it matters: The workflow connects familiar local development to Kubernetes deployment without requiring a cluster for every test. - Podman inside containerized CI: Describe why the chapter covers running Podman inside containers launched by Podman or Kubernetes: teams may need to test containers with Podman in continuous integration systems built on Kubernetes clusters.
Why it matters: It explains the practical reason for the chapter’s final topic, beyond converting YAML files.
Key terms: Podman, Kubernetes, CRI-O, container backend, microservices, Kubernetes YAML file, declarative language, podman play kube, continuous integration (CI), Podman within containers
8.1 Kubernetes YAML files
This section explains what Kubernetes YAML files do, why writing them can be difficult, and why Podman introduced `podman generate kube`.
- Kubernetes YAML purpose: Explain that Kubernetes YAML files describe the desired state of an application and are used to launch pods and containers in Kubernetes.
Why it matters: This is the role of the files that Podman generates and uses later in the chapter. - YAML authoring barrier: Explain why writing Kubernetes YAML can be a barrier when moving local containers to Kubernetes: developers may copy an existing file and paste in their container command, image, and options, risking unintended consequences and unnecessary work.
Why it matters: The authoring difficulty motivates Podman's YAML-generation command. - Podman generation motivation: State that Podman developers created `podman generate kube` to help users move from working with containers in Podman toward orchestrating them with Kubernetes.
Why it matters: It connects the YAML authoring problem to the command introduced next. - YAML and TOML syntax: Distinguish Kubernetes YAML from the Podman TOML configuration files discussed earlier: both aim to be human-readable, but YAML uses indentation for substanzas.
Why it matters: Recognizing YAML's indentation-based structure helps when reading or editing these files.
Key terms: Kubernetes YAML file, desired state, declarative language, Kubernetes YAML, container command, image, options, podman generate kube, orchestrating, Kubernetes
8.2 Generating Kubernetes YAML files with Podman
This section shows how Podman turns an existing local container or pod into Kubernetes YAML, what that YAML contains, and where Kubernetes-specific editing begins.
- Kubernetes YAML generation workflow: Explain how to recreate a local container or pod and use `podman generate kube myapp` to produce Kubernetes YAML from it. Describe the optional output-file and service-object flags.
Why it matters: This is the bridge from a workload you run with Podman to a specification you can use with Kubernetes. - Generated pod specification contents: Describe how the generated YAML represents even a single original container as a Kubernetes pod, and identify the application details carried into its container specification.
Why it matters: Reading the generated fields lets you check that Kubernetes will start the intended application. - Generated capability security context: Explain that the generated `securityContext` tells Kubernetes to drop CAP_MKNOD, CAP_NET_RAW, and CAP_AUDIT_WRITE, reflecting capabilities Podman drops by default for more secure operation.
Why it matters: The security context preserves a meaningful Podman security choice when the workload moves to Kubernetes. - Kubernetes handoff and replica limits: Explain that Kubernetes commands can launch the generated YAML in a cluster, while orchestration features such as two replicas must be added to the YAML. Distinguish those Kubernetes-specific fields from what `podman play kube` supports.
Why it matters: It clarifies what Podman generates automatically and what you must configure for Kubernetes orchestration.
Key terms: podman generate kube, podman rm --ignore, -f, --filename, -s, --service, pod specification, myapp-pod, myapp, image, command arguments, ports
8.3 Generating Podman pods and containers from Kubernetes YAML
This section shows how to start pods, containers, and volumes locally from Kubernetes YAML with Podman, inspect the result, and stop a simple pod.
- Local playback of Kubernetes YAML: Explain that `podman play kube` reads structured Kubernetes YAML and automatically creates and starts its pods, containers, and volumes locally, without setting up a Kubernetes cluster. Describe why the example starts a pod rather than a standalone container.
Why it matters: It lets you try a Kubernetes YAML file locally without first running a cluster. - Created resource names and inspection: Describe how the example YAML supplies the pod name `myapp-pod`, how the container gets the combined name `myapp-pod-myapp`, and how to inspect the running pod and its containers.
Why it matters: Recognizing the generated names helps you find the resources that playing the YAML started. - Simple pod shutdown limits: Explain that the simple example can be shut down with `podman pod stop`, while a YAML file that creates multiple distinct pods makes shutdown more complex.
Why it matters: Stopping one example pod is straightforward, but that approach does not describe the whole shutdown task for a more complex YAML file.
Key terms: podman play kube, Kubernetes YAML, pod, container, volume, myapp-pod, myapp-pod-myapp, infra container, podman pod ps, --ctr-names
8.3.1 Shutting down pods and containers based on a Kubernetes YAML file
This section shows how to tear down pods created from Kubernetes YAML with Podman and why that workflow is useful.
- YAML-based pod teardown: Explain that podman play kube --down stops and removes pods created by an earlier play kube run, while leaving created volumes intact. Describe how to verify removal and then run play kube again to create fresh pods and containers.
Why it matters: You can clean up a deployment without deleting its volumes, then recreate it from the YAML file. - Reusable Kubernetes YAML workflow: Explain how creating fresh pods from YAML and tearing them down resembles Kubernetes and docker-compose workflows. Distinguish Podman's advantage of using the same YAML file locally and in a multinode Kubernetes environment.
Why it matters: Using the same deployment file in both settings reduces the need for a separate local definition.
Key terms: podman play kube --down, podman pod ps, volumes, Kubernetes YAML file, docker-compose, multinode, orchestrated environment
8.3.2 Building images using Podman and Kubernetes YAML files
This section shows how podman play kube --build builds images from local Containerfiles while launching an application from Kubernetes YAML, without first pushing images to a registry.
- On-demand image building: Explain how podman play kube --build replaces the usual build, push, and pull steps by building an image locally when it launches the pod. Distinguish this Podman feature from Kubernetes, which does not build images from YAML files.
Why it matters: The distinction tells you when a YAML-based application can launch without a registry and when it cannot. - Matching image build directories: Describe how podman play kube --build finds build inputs: it reads image names from the YAML, looks for matching subdirectories, and runs podman build using each directory as a context containing a Containerfile or Dockerfile.
Why it matters: Without the matching directory and build file, Podman cannot perform the on-demand build described here. - Portable YAML and build context: Describe what the example packages for another Podman user—the generated Kubernetes YAML, including its html volume, alongside the mysystemd build directory—and explain why running it in Kubernetes instead requires a registry image and an updated YAML image reference.
Why it matters: Sharing files for Podman’s local build is different from preparing an image for deployment in Kubernetes.
Key terms: podman play kube --build, podman build, container registry, image names, context directory, Containerfile, Dockerfile, mysystemd, podman generate kube, volumes
8.4 Running Podman within a container
This section introduces why people run Podman inside containers or Kubernetes pods and sets up an experiment with a purpose-built image and the requirements for nested containers.
- Reasons for nested Podman: Explain why users run Podman inside a container or Kubernetes cluster: to test container images and tools in container-based CI/CD, build images with podman build, or try a newer Podman version.
Why it matters: These use cases explain why running a container engine inside a container is worth setting up. - Nested Podman setup choices: Describe the section's setup for learning nested Podman: the quay.io/podman/stable image simplifies a configuration-heavy task, Podman can run rootful or rootless, and the upcoming Podman-within-Podman experiment considers the capabilities needed for the inner Podman to run a container.
Why it matters: The setup and mode distinctions frame the experiments that follow.
Key terms: CI/CD, podman build, quay.io/podman/stable, rootful, rootless, container root, user namespace, capabilities
8.4.1 Running Podman within a Podman container
This section shows how to run Podman inside a container, including the capabilities it needs and the seccomp adjustment required when Docker runs the outer container.
- Rootful Podman mounting requirements: Explain why running rootful Podman inside a rootless Podman container requires --privileged: the inner Podman must mount filesystems, and mounting as root requires CAP_SYS_ADMIN.
Why it matters: This explains why the rootful example needs a more permissive outer container. - Rootless Podman capability choices: Describe how --user podman runs rootless Podman inside the container and why it needs CAP_SETUID and CAP_SETGID to set up a user namespace. Explain that these capabilities are available by default and that the outer container can instead drop all capabilities and add back just those two.
Why it matters: This distinguishes the rootless setup from the privileged rootful example and shows how to limit granted capabilities. - Docker seccomp compatibility: Explain that Docker can also run Podman inside a container, but its seccomp filter blocks the unshare and mount system calls; describe disabling Docker's seccomp filtering or using Podman's seccomp filters as the two remedies given.
Why it matters: The same nested-Podman approach needs a seccomp adjustment when Docker runs the outer container.
Key terms: rootful Podman, rootless container, --privileged, CAP_SYS_ADMIN, quay.io/podman/stable, --user podman, CAP_SETUID, CAP_SETGID, --cap-drop=all, --cap-add
8.4.2 Running Podman within a Kubernetes pod
This subsection explains what Podman needs to run inside a Kubernetes pod and contrasts rootful and rootless Kubernetes YAML examples.
- Podman requirements inside Kubernetes: Explain why Podman needs suitable Linux capabilities and access to more than one UID inside a Kubernetes container, especially for podman build. Describe why a locked-down container with one UID and no capabilities cannot run it.
Why it matters: These requirements explain why Podman fails in some default Kubernetes environments. - Rootful and rootless pod examples: Distinguish the section's privileged rootful example using quay.io/podman/stable from its rootless Kubernetes YAML example. Explain why the rootless example specifies runAsUser: 1000 rather than the podman username.
Why it matters: Choosing the appropriate pod setup and a numeric UID makes the examples usable in Kubernetes.
Key terms: CAP_SYS_ADMIN, CAP_SETUID, CAP_SETGID, UID, podman build, rootful, quay.io/podman/stable, privileged, runAsUser: 1000, podman user
8.5 Summary
The summary recaps how Podman turns local workloads into Kubernetes YAML, plays that YAML locally, and can run inside containers.
Where this is used later
- Using docker-compose with the Podman service (chapter 9) · Using Kubernetes YAML with podman play kube
Concepts explained in this chapter
- PodmanPodman is a daemonless container engine that runs containers and builds images, including under an unprivileged user account.
- podman generate kubepodman generate kube is a Podman command that generates Kubernetes YAML manifests from running containers and pods.
- KubernetesKubernetes is an open-source platform for orchestrating containerized workloads across clusters of machines.
- Kubernetes manifestA Kubernetes YAML file is a YAML-formatted resource description that declares how Kubernetes should create and manage application objects such as pods and containers.
- rootful modeA rootful container is a container whose engine or processes run with host-level root privileges.
- rootless modeA rootless container is a container whose engine and processes run without host-level root privileges.
- YAMLYAML is a human-readable data-serialization standard commonly used for configuration and resource manifests.
- context directoryA context directory is a directory containing the files and build instructions made available to a container image build.
- CAP_SYS_ADMINCAP_SYS_ADMIN is a Linux capability that includes permission to perform filesystem mounts and many other system-administration operations.
- user ID namespaceA user namespace is a Linux namespace that isolates security-related identifiers and capabilities and maps host user and group identifiers to namespace identifiers.
- seccompA seccomp filter is a policy configuration that determines which system calls a process and its descendants may invoke.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.