6 Kubernetes Files

Use the podman kube commands to generate and use YAML files that can be used in both Podman and Kubernetes to move pods, containers, volumes and other objects between the two container platforms.

Using Kubernetes YAML files provides several benefits, such as:

  • Portability: You can move pods between Podman and Kubernetes, or run the same containers and pods on both container platforms.

  • Readability: You can use the YAML files in programming languages.

  • Convenience: The YAML files can contain all the necessary configuration information for the pods or containers. Thus, you don't need to specify different parameters when issuing Podman commands.

The following Podman commands are available to work with Kubernetes YAML files:

podman kube generate

Generates a Kubernetes YAML file of an existing pod. The YAML file contains a description of a Podman pod that can contain many containers, volumes, or other objects. You can use this YAML file to create pods in either Podman or Kubernetes.

podman kube play

Deploys a pod in Podman, based on a Kubernetes YAML file.

podman kube apply

Deploys a pod into a Kubernetes cluster, based on a Kubernetes YAML file.

podman kube down

Stops the containers in a pod, and removes the pod in Podman, using a Kubernetes YAML file.

To get more information about these commands, use the --help flag when issuing the commands. You can also see the podman-kube(1) manual page.

The examples in this section show you how to generate Kubernetes YAML files in Podman, and use the YAML files in both Podman and Kubernetes.

Tip:

For Oracle Linux 8 and Oracle Linux 9 systems, the Oracle Cloud Native Environment libvirt provider can be useful for testing Kubernetes YAML files. For more information, see Oracle Cloud Native Environment Quick Start for Release 2.

Some examples in this section use the Kubernetes CLI (kubectl) to interact with a Kubernetes cluster. You can install the kubectl software package to the local system and use the Kubernetes configuration file (the kubeconfig file) to connect to the cluster. Information on installing kubectl is available in the Oracle Cloud Native Environment documentation or in the upstream Kubernetes documentation.

Podman has commands to generate a Kubernetes YAML file and deploy it to a Kubernetes cluster, but any further management of Kubernetes objects (such as pods and volumes) must be done using kubectl commands. For information on kubectl commands and how to use them, see the Kubernetes upstream documentation.

Example 6-1 Creating and using a Kubernetes YAML file

This example steps through creating a Podman pod, creating a Kubernetes YAML file from the pod, then deploying the pod to both Podman and Kubernetes using the YAML file.

  1. Create a pod and add an NGINX container to the pod.

    podman run --pod new:mypod -dt --name nginxcontainer quay.io/libpod/alpine_nginx:latest

  2. Verify the creation of the pod and the container.

    List all the pods:

    podman pod list

    The output looks similar to:

    POD ID        NAME        STATUS      CREATED        INFRA ID      # OF CONTAINERS
8f7088f859da  mypod       Running     2 minutes ago  d2bb22029ec9  2

    Show the containers in the pod:

    podman pod ps --ctr-names --filter name=mypod

    The output lists the container names in the pod, and looks similar to:

    POD ID        NAME        STATUS      CREATED         INFRA ID      NAMES
8f7088f859da  mypod       Running     13 minutes ago  d2bb22029ec9  8f7088f859da-infra,nginxcontainer

    The infra and nginxcontainer are listed in the pod.

  3. Create a Kubernetes YAML file from the pod.

    podman generate kube mypod --filename mypod.yaml

  4. Check the contents of the YAML file. The mypod.yaml file might look similar to: 

    # Save the output of this file and use kubectl create -f to import
# it into Kubernetes.
#
# Created with podman-5.4.0
apiVersion: v1
kind: Pod
metadata:
  annotations:
    io.kubernetes.cri-o.SandboxID/nginxcontainer: d2bb22029ec98f7...
  creationTimestamp: "2025-07-15T02:18:18Z"
  labels:
    app: mypod
  name: mypod
spec:
  containers:
  - env:
    - name: TERM
      value: xterm
    image: quay.io/libpod/alpine_nginx:latest
    name: nginxcontainer
    tty: true

  5. Remove the containers and pod before trying to run this YAML file in Podman: 

    podman stop nginxcontainer
    podman rm nginxcontainer
    podman pod rm mypod

  6. Run the YAML in Podman to deploy the pod and its containers:

    podman kube play mypod.yaml

    You can see the pod is and the containers are running using the steps to verify the pod shown earlier. For example:

    podman pod list
    podman pod ps --ctr-names --filter name=mypod

  7. Stop the Podman pod using the YAML file:

    podman kube down mypod.yaml

  8. Run the YAML file in Kubernetes to deploy the pod.

    If you have the kubeconfig file for the Kubernetes cluster, you can use the podman kube apply command. For example: 

    podman kube apply --kubeconfig mykubeconfig --file mypod.yaml

    If you have access to the Kubernetes cluster, you can copy the YAML file to a system that has access to the Kubernetes CLI, and use the kubectl create command to deploy the pod. For example: 

    kubectl create -f mypod.yaml

  9. To confirm the pod is running in Kubernetes, run the following command:

    kubectl get pods

  10. To remove the Kubernetes pod, run the following command:

    kubectl delete pod mypod

Creating a Kubernetes YAML File

Use the podman kube generate command to generate a Kubernetes YAML file for a Podman container, pod, or volume.

The YAML file can be used in a Kubernetes environment to start a Pod, Service, or PersistentVolumeClaim. It can also be used in Podman to test the Kubernetes objects are created correctly.

For pods that include volume mounts to start in Kubernetes, a StorageClass must be set up in Kubernetes with the appropriate configuration for the PersistentVolumeClaim. If the StorageClass is set up, a volume is automatically created when you run the pod.

For more information on the podman kube generate command, see the podman-kube-generate(1) manual page.

Example 6-2 Create a YAML file from a container

  1. Create a Podman container:

    podman create --name myoracle oraclelinux:9-slim

  2. Generate a Kubernetes YAML file of the container:

    podman generate kube myoracle --filename myoracle.yaml

  3. Verify the resulting myoracle.yaml file looks similar to: 

    # Save the output of this file and use kubectl create -f to import
# it into Kubernetes.
#
# Created with podman-5.4.0
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: "2025-07-14T07:09:20Z"
  labels:
    app: myoracle-pod
  name: myoracle-pod
spec:
  containers:
  - image: container-registry.oracle.com/os/oraclelinux:9-slim
    name: myoracle

Example 6-3 Create a YAML file from a container with a volume mount

  1. Create a Podman container that includes a volume mount:

    podman run --name myvolumepod --volume mydata:/data oraclelinux:9-slim

  2. Generate a Kubernetes YAML file of the container:

    podman generate kube myvolumepod --filename myvolumepod.yaml

  3. Verify the resulting myvolumepod.yaml file looks similar to: 

    # Save the output of this file and use kubectl create -f to import
# it into Kubernetes.
#
# Created with podman-5.4.0

# NOTE: If you generated this yaml from an unprivileged and rootless podman container on an SELinux
# enabled system, check the podman generate kube manual page for steps to follow to ensure that your pod/container
# has the right permissions to access the volumes added.
---
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: "2025-07-14T07:12:40Z"
  labels:
    app: myvolumepod-pod
  name: myvolumepod-pod
spec:
  containers:
  - image: container-registry.oracle.com/os/oraclelinux:9-slim
    name: myvolumepod
    volumeMounts:
    - mountPath: /data
      name: mydata-pvc
  volumes:
  - name: mydata-pvc
    persistentVolumeClaim:
      claimName: mydata

Example 6-4 Creating a YAML file from a pod

  1. Create a pod and add an NGINX container to the pod.

    podman run --pod new:mypod -dt --name nginxcontainer quay.io/libpod/alpine_nginx:latest

  2. Create a Kubernetes YAML file from the pod.

    podman generate kube mypod --filename mypod.yaml

  3. Verify the resulting mypod.yaml file looks similar to: 

    # Save the output of this file and use kubectl create -f to import
# it into Kubernetes.
#
# Created with podman-5.4.0
apiVersion: v1
kind: Pod
metadata:
  annotations:
    io.kubernetes.cri-o.SandboxID/nginxcontainer: d2bb22029ec98f7...
  creationTimestamp: "2025-07-15T02:18:18Z"
  labels:
    app: mypod
  name: mypod
spec:
  containers:
  - env:
    - name: TERM
      value: xterm
    image: quay.io/libpod/alpine_nginx:latest
    name: nginxcontainer
    tty: true

Running a Kubernetes YAML File

Use the podman kube play command to run a Kubernetes YAML file in Podman. This is useful to verify the file is generated correctly.

Use the podman kube play command to run a Kubernetes YAML file in Podman.

For more information on the podman kube play command, see the podman-kube-play(1) manual page.

Example 6-5 Run a Kubernetes YAML file in Podman

podman kube play mypod.yaml

You can verify the pod and containers are running using podman pod commands such as: 

podman pod list
podman pod ps --ctr-names --filter name=mypod

Removing Pods Using a Kubernetes YAML File

Use the podman kube down command to stop and remove Podman pods using a Kubernetes YAML file.

The example here shows you how to stop and remove Podman pods that were created using a YAML file generated using the podman kube generate command. The podman kube down command is most likely to be used with the podman kube play command when testing Kubernetes YAML files. The podman kube down command stops and removes the pod and associated objects listed in the YAML file, such as secrets and volumes.

For more information on the podman kube down command, see the podman-kube-down(1) manual page.

Example 6-6 Stop and remove a pod using a YAML file

podman kube down mypod.yaml

Deploying to a Kubernetes Cluster

Use the podman kube apply command to run a Kubernetes YAML file and create pods and the associated objects in a Kubernetes cluster.

Use the podman kube apply command to run the YAML file generated in Podman.

The example here shows how to run a YAML file generated in Podman to create pods and containers in a Kubernetes cluster. This assumes you have set up a Kubernetes cluster. You need to provide the Kubernetes configuration file (the kubeconfig file) for the destination cluster, and this can be copied from the Kubernetes cluster to the local system. You also need to ensure the Kubernetes Server API port is open on the server running Kubernetes.

When you deploy a YAML file to a Kubernetes cluster, the pods are running on that cluster, not Podman, so any management of the Kubernetes objects needs to be done using kubectl. No Podman commands are available to manage objects in a Kubernetes cluster, other than as shown here, to deploy a YAML file.

For more information on the podman kube apply command, see the podman-kube-apply(1) manual page.

Example 6-7 Deploy a YAML file to a Kubernetes cluster

podman kube apply --kubeconfig mykubeconfig --file mypod.yaml

If you have access to the Kubernetes cluster, use the Kubernetes CLI (kubectl) to verify the pod is created using: 

kubectl get pods

Deploying to a Kubernetes Cluster Using kubectl

Use the Kubernetes CLI (kubectl) to deploy a Kubernetes YAML file into a Kubernetes cluster.

The example here shows how to run a YAML file generated in Podman to create pods and associated objects in a Kubernetes cluster. This assumes you have set up a Kubernetes cluster, and the Kubernetes CLI (kubectl) is configured to access the cluster.

  1. Copy the YAML file to the system where kubectl is set up to access the cluster.
  2. Use the kubectl create command to run the YAML file generated in Podman.

    For example:

    kubectl create -f mypod.yaml
  3. Verify the pod is created.
    kubectl get pods