NAME

podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML

SYNOPSIS

podman kube play [options] file.yml|-|https://website.io/file.yml

DESCRIPTION

podman kube play reads in a structured file of Kubernetes YAML. It recreates the containers, pods, or volumes described in the YAML. Containers within a pod are then started, and the ID of the new Pod or the name of the new Volume is output. If the YAML file is specified as "-", then podman kube play reads the YAML file from stdin. The input can also be a URL that points to a YAML file such as https://podman.io/demo.yml. podman kube play reads the YAML from the URL and create pods and containers from it.

Using the --down command line option, it is also capable of tearing down the pods created by a previous run of podman kube play.

Using the --replace command line option, it tears down the pods(if any) created by a previous run of podman kube play and recreate the pods with the Kubernetes YAML file.

Ideally the input file is created by the Podman command (see podman-kube-generate(1)). This guarantees a smooth import and expected results.

Currently, the supported Kubernetes kinds are:

Kubernetes Pods or Deployments

Only three volume types are supported by kube play, the hostPath, emptyDir, and persistentVolumeClaim volume types.

Note: The default restart policy for containers is always. You can change the default by setting the restartPolicy field in the spec.

Note: When playing a kube YAML with init containers, the init container is created with init type value once. To change the default type, use the io.podman.annotations.init.container.type annotation to set the type to always.

Note: hostPath volume types created by kube play is given an SELinux shared label (z), bind mounts are not relabeled (use chcon -t container_file_t -R <directory>).

Note: To set userns of a pod, use the io.podman.annotations.userns annotation in the pod/deployment definition. For example, io.podman.annotations.userns=keep-id annotation tells Podman to create a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This can be overridden with the --userns flag.

Note: Use the io.podman.annotations.volumes-from annotation to bind mount volumes of one container to another. You can mount volumes from multiple source containers to a target container. The source containers that belong to the same pod must be defined before the source container in the kube YAML. The annotation format is io.podman.annotations.volumes-from/targetContainer: "sourceContainer1:mountOpts1;sourceContainer2:mountOpts2".

Note: If the :latest tag is used, Podman attempts to pull the image from a registry. If the image was built locally with Podman or Buildah, it has localhost as the domain, in that case, Podman uses the image from the local store even if it has the :latest tag.

Note: The command podman play kube is an alias of podman kube play, and performs the same function.

Note: The command podman kube down can be used to stop and remove pods or containers based on the same Kubernetes YAML used by podman kube play to create them.

Note: To customize the name of the infra container created during podman kube play, use the io.podman.annotations.infra.name annotation in the pod definition. This annotation is automatically set when generating a kube yaml from a pod that was created with the --infra-name flag set.

Kubernetes PersistentVolumeClaims

A Kubernetes PersistentVolumeClaim represents a Podman named volume. Only the PersistentVolumeClaim name is required by Podman to create a volume. Kubernetes annotations can be used to make use of the available options for Podman volumes.

Use volume.podman.io/import-source to import the contents of the tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) specified in the annotation's value into the created Podman volume

Kube play is capable of building images on the fly given the correct directory layout and Containerfiles. This option is not available for remote clients, including Mac and Windows (excluding WSL2) machines, yet. Consider the following excerpt from a YAML file:

apiVersion: v1
kind: Pod
metadata:
...
spec:
  containers:
  - name: container
    image: foobar
...

If there is a directory named foobar in the current working directory with a file named Containerfile or Dockerfile, Podman kube play builds that image and name it foobar. An example directory structure for this example looks like:

|- mykubefiles
    |- myplayfile.yaml
    |- foobar
         |- Containerfile

The build considers foobar to be the context directory for the build. If there is an image in local storage called foobar, the image is not built unless the --build flag is used. Use --build=false to completely disable builds.

Kubernetes ConfigMap

Kubernetes ConfigMap can be referred as a source of environment variables or volumes in Pods or Deployments. ConfigMaps aren't a standalone object in Podman; instead, when a container uses a ConfigMap, Podman creates environment variables or volumes as needed.

For example, the following YAML document defines a ConfigMap and then uses it in a Pod:

apiVersion: v1
kind: ConfigMap
metadata:
  name: foo
data:
    FOO: bar
---
apiVersion: v1
kind: Pod
metadata:
  name: foobar
spec:
  containers:
  - name: container-1
    image: foobar
    envFrom:
    - configMapRef:
        name: foo
        optional: false

and as a result environment variable FOO is set to bar for container container-1.

Kubernetes Secret

Kubernetes Secret represents a Podman named secret. The Kubernetes Secret is saved as a whole and may be referred to as a source of environment variables or volumes in Pods or Deployments.

For example, the following YAML document defines a Secret and then uses it in a Pod:

kind: Secret
apiVersion: v1
metadata:
  name: foo
data:
  foo: YmFy # base64 for bar
---
apiVersion: v1
kind: Pod
metadata:
  name: foobar
spec:
  containers:
  - name: container-1
    image: foobar
    env:
    - name: FOO
      valueFrom:
        secretKeyRef:
          name: foo
          key: foo

and as a result environment variable FOO is set to bar for container container-1.

Automounting Volumes

An image can be automatically mounted into a container if the annotation io.podman.annotations.kube.image.automount/$ctrname is given. The following rules apply:

OPTIONS

EXAMPLES

Recreate the pod and containers described in the specified host YAML file.

$ podman kube play demo.yml
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

Recreate the pod and containers specified in a YAML file sent to stdin.

$ cat demo.yml | podman kube play -
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

Tear down the pod and containers as described in the specified YAML file.

$  podman kube play --down demo.yml
Pods stopped:
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
Pods removed:
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

Provide multiple configmap files as sources for environment variables within the specified pods and containers.

$ podman kube play demo.yml --configmap configmap-foo.yml,configmap-bar.yml
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
$ podman kube play demo.yml --configmap configmap-foo.yml --configmap configmap-bar.yml
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

Create a pod connected to two networks with a static ip on each.

$ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

Please take into account that networks must be created first using podman-network-create(1).

Create and teardown from a URL pointing to a YAML file.

$ podman kube play https://podman.io/demo.yml
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
$ podman kube play --down https://podman.io/demo.yml
Pods stopped:
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
Pods removed:
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6

podman kube play --down does not work with a URL if the YAML file the URL points to has been changed or altered.

Podman Kube Play Support

This document outlines the kube yaml fields that are currently supported by the podman kube play command.

Note: N/A means that the option cannot be supported in a single-node Podman environment.

Pod Fields

Container Fields

PersistentVolumeClaim Fields

ConfigMap Fields

Deployment Fields

DaemonSet Fields

SEE ALSO

podman(1), podman-kube(1), podman-kube-down(1), podman-network-create(1), podman-kube-generate(1), podman-build(1), containers-certs.d(5)