1podman-play-kube(1)() podman-play-kube(1)()
2
6 podman-play-kube - Create containers, pods or volumes based on Kuber‐
7 netes YAML
8
11 podman play kube [options] file.yml|-
12
15 podman play kube will read in a structured file of Kubernetes YAML. It
16 will then recreate the containers, pods or volumes described in the
17 YAML. Containers within a pod are then started and the ID of the new
18 Pod or the name of the new Volume is output. If the yaml file is speci‐
19 fied as "-" then podman play kube will read the YAML file from stdin.
20 Using the --down command line option, it is also capable of tearing
21 down the pods created by a previous run of podman play kube. Using the
22 --replace command line option, it will tear down the pods(if any) cre‐
23 ated by a previous run of podman play kube and recreate the pods with
24 the Kubernetes YAML file. Ideally the input file would be one created
25 by Podman (see podman-generate-kube(1)). This would guarantee a smooth
26 import and expected results.
27 Currently, the supported Kubernetes kinds are: - Pod - Deployment -
30 PersistentVolumeClaim - ConfigMap
31 Kubernetes Pods or Deployments
34 Only two volume types are supported by play kube, the hostPath and per‐
37 sistentVolumeClaim volume types. For the hostPath volume type, only the
38 default (empty), DirectoryOrCreate, Directory, FileOrCreate, File, and
39 Socket subtypes are supported. The CharDevice and BlockDevice subtypes
40 are not supported. Podman interprets the value of hostPath path as a
41 file path when it contains at least one forward slash, otherwise Podman
42 treats the value as the name of a named volume. When using a persis‐
43 tentVolumeClaim, the value for claimName is the name for the Podman
44 named volume.
45 Note: When playing a kube YAML with init containers, the init container
48 will be created with init type value always.
49 Note: hostPath volume types created by play kube will be given an
52 SELinux shared label (z), bind mounts are not relabeled (use chcon -t
53 container_file_t -R <directory>).
54 Note: If the :latest tag is used, Podman will attempt to pull the image
57 from a registry. If the image was built locally with Podman or Buildah,
58 it will have localhost as the domain, in that case, Podman will use the
59 image from the local store even if it has the :latest tag.
60 Kubernetes PersistentVolumeClaims
63 A Kubernetes PersistentVolumeClaim represents a Podman named volume.
66 Only the PersistentVolumeClaim name is required by Podman to create a
67 volume. Kubernetes annotations can be used to make use of the available
68 options for Podman volumes.
69 • volume.podman.io/driver
72 • volume.podman.io/device
74 • volume.podman.io/type
76 • volume.podman.io/uid
78 • volume.podman.io/gid
80 • volume.podman.io/mount-options
82 Play kube is capable of building images on the fly given the correct
86 directory layout and Containerfiles. This option is not available for
87 remote clients, including Mac and Windows (excluding WSL2) machines,
88 yet. Consider the following excerpt from a YAML file:
89 apiVersion: v1
92 kind: Pod
93 metadata:
94 spec:
95 containers:
96 - command:
97 - top
98 - name: container
99 value: podman
100 image: foobar
101 If there is a directory named foobar in the current working directory
105 with a file named Containerfile or Dockerfile, Podman play kube will
106 build that image and name it foobar. An example directory structure
107 for this example would look like:
108 |- mykubefiles
111 |- myplayfile.yaml
112 |- foobar
113 |- Containerfile
114 The build will consider foobar to be the context directory for the
118 build. If there is an image in local storage called foobar, the image
119 will not be built unless the --build flag is used. Use --build=false to
120 completely disable builds.
121 Kubernetes ConfigMap
124 Kubernetes ConfigMap can be referred as a source of environment vari‐
127 ables or volumes in Pods or Deployments. ConfigMaps aren't a stand‐
128 alone object in Podman; instead, when a container uses a ConfigMap,
129 Podman will create environment variables or volumes as needed.
130 For example, the following YAML document defines a ConfigMap and then
133 uses it in a Pod:
134 apiVersion: v1
137 kind: ConfigMap
138 metadata:
139 name: foo
140 data:
141 FOO: bar
142 ---
143 apiVersion: v1
144 kind: Pod
145 metadata:
146 name: foobar
147 spec:
148 containers:
149 - command:
150 - top
151 name: container-1
152 image: foobar
153 envFrom:
154 - configMapRef:
155 name: foo
156 optional: false
157 and as a result environment variable FOO will be set to bar for con‐
161 tainer container-1.
162
165 --annotation=key=value
166 Add an annotation to the container or pod. The format is key=value.
167 The --annotation option can be set multiple times.
168 --authfile=path
171 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
172 ers/auth.json, which is set using podman login. If the authorization
173 state is not found there, $HOME/.docker/config.json is checked, which
174 is set using docker login.
175 Note: You can also override the default path of the authentication file
178 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
179 ISTRY_AUTH_FILE=path
180 --build
183 Build images even if they are found in the local storage. Use
184 --build=false to completely disable builds. (This option is not avail‐
185 able with the remote Podman client)
186 --cert-dir=path
189 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
190 istry. (Default: /etc/containers/certs.d) Please refer to containers-
191 certs.d(5) for details. (This option is not available with the remote
192 Podman client, including Mac and Windows (excluding WSL2) machines)
193 --configmap=path
196 Use Kubernetes configmap YAML at path to provide a source for environ‐
197 ment variable values within the containers of the pod. (This option is
198 not available with the remote Podman client)
199 Note: The --configmap option can be used multiple times or a comma-sep‐
202 arated list of paths can be used to pass multiple Kubernetes configmap
203 YAMLs.
204 --context-dir=path
207 Use path as the build context directory for each image. Requires
208 --build option be true. (This option is not available with the remote
209 Podman client)
210 --creds
213 The [username[:password]] to use to authenticate with the registry if
214 required. If one or both values are not supplied, a command line
215 prompt will appear and the value can be entered. The password is en‐
216 tered without echo.
217 --down
220 Tears down the pods that were created by a previous run of play kube.
221 The pods are stopped and then removed. Any volumes created are left
222 intact.
223 --help, -h
226 Print usage statement
227 --ip=IP address
230 Assign a static ip address to the pod. This option can be specified
231 several times when play kube creates more than one pod. Note: When
232 joining multiple networks you should use the --network name:ip=<ip>
233 syntax.
234 --log-driver=driver
237 Set logging driver for all created containers.
238 --log-opt=name=value
241 Set custom logging configuration. The following *name*s are supported:
242 • path: specify a path to the log file (e.g. --log-opt
245 path=/var/log/container/mycontainer.json);
246 • max-size: specify a max size of the log file (e.g. --log-opt
248 max-size=10mb);
249 • tag: specify a custom log tag for the container (e.g. --log-
251 opt tag="{{.ImageName}}".
252 It supports the same keys as podman inspect --format.
256 This option is currently supported only by the journald log driver.
259 --mac-address=MAC address
262 Assign a static mac address to the pod. This option can be specified
263 several times when play kube creates more than one pod. Note: When
264 joining multiple networks you should use the --network name:mac=<mac>
265 syntax.
266 --network=mode, --net
269 Change the network mode of the pod. The host network mode should be
270 configured in the YAML file. Valid mode values are:
271 • bridge[:OPTIONS,...]: Create a network stack on the default
274 bridge. This is the default for rootful containers. It is pos‐
275 sible to specify these additional options:
276 • alias=name: Add network-scoped alias for the container.
278 • ip=IPv4: Specify a static ipv4 address for this container.
280 • ip=IPv6: Specify a static ipv6 address for this container.
282 • mac=MAC: Specify a static mac address for this container.
284 • interface_name: Specify a name for the created network in‐
286 terface inside the container.
287 For example to set a static ipv4 address and a static mac address, use
293 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99. - <network name
294 or ID>[:OPTIONS,...]: Connect to a user-defined network; this is the
295 network name or ID from a network created by podman network create. Us‐
296 ing the network name implies the bridge network mode. It is possible to
297 specify the same options described under the bridge mode above. You can
298 use the --network option multiple times to specify additional networks.
299 - none: Create a network namespace for the container but do not config‐
300 ure network interfaces for it, thus the container has no network con‐
301 nectivity. - container:id: Reuse another container's network stack. -
302 ns:path: Path to a network namespace to join. - private: Create a new
303 namespace for the container. This will use the bridge mode for rootful
304 containers and slirp4netns for rootless ones. - slirp4netns[:OP‐
305 TIONS,...]: use slirp4netns(1) to create a user network stack. This is
306 the default for rootless containers. It is possible to specify these
307 additional options, they can also be set with network_cmd_options in
308 containers.conf:
309 - allow_host_loopback=true|false: Allow the slirp4netns to reach the
310 host loopback IP (10.0.2.2). Default is false.
311 - mtu=MTU: Specify the MTU to use for this network. (Default is
312 65520).
313 - cidr=CIDR: Specify ip range to use for this network. (Default is
314 10.0.2.0/24).
315 - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
316 outbound_addr6).
317 - outbound_addr=INTERFACE: Specify the outbound interface slirp
318 should bind to (ipv4 traffic only).
319 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
320 bind to.
321 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
322 should bind to (ipv6 traffic only).
323 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
324 bind to.
325 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
326 fault.
327 Note: Rootlesskit changes the source IP address of incoming packets
328 to an IP address in the container network namespace, usually
329 10.0.2.100. If your application requires the real source IP address,
330 e.g. web server logs, use the slirp4netns port handler. The rootlesskit
331 port handler is also used for rootless containers when connected to
332 user-defined networks.
333 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
334 is slower than rootlesskit but preserves the correct source IP address.
335 This port handler cannot be used for user-defined networks.
336 --no-hosts
339 Do not create /etc/hosts for the pod. By default, Podman will manage
340 /etc/hosts, adding the container's own IP address and any hosts from
341 --add-host. --no-hosts disables this, and the image's /etc/host will
342 be preserved unmodified. This option conflicts with host added in the
343 Kubernetes YAML.
344 --quiet, -q
347 Suppress output information when pulling images
348 --replace
351 Tears down the pods created by a previous run of play kube and recre‐
352 ates the pods. This option is used to keep the existing pods up to date
353 based upon the Kubernetes YAML.
354 --seccomp-profile-root=path
357 Directory path for seccomp profiles (default: "/var/lib/kubelet/sec‐
358 comp"). (This option is not available with the remote Podman client,
359 including Mac and Windows (excluding WSL2) machines)
360 --start
363 Start the pod after creating it, set to false to only create it.
364 --tls-verify
367 Require HTTPS and verify certificates when contacting registries (de‐
368 fault: true). If explicitly set to true, then TLS verification will be
369 used. If set to false, then TLS verification will not be used. If not
370 specified, TLS verification will be used unless the target registry is
371 listed as an insecure registry in registries.conf.
372
375 Recreate the pod and containers as described in a file called demo.yml
376 $ podman play kube demo.yml
379 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
380 Recreate the pod and containers as described in a file demo.yml sent to
384 stdin
385 $ cat demo.yml | podman play kube -
388 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
389 Teardown the pod and containers as described in a file demo.yml
394 $ podman play kube --down demo.yml
397 Pods stopped:
398 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
399 Pods removed:
400 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
401 Provide configmap-foo.yml and configmap-bar.yml as sources for environ‐
405 ment variables within the containers.
406 $ podman play kube demo.yml --configmap configmap-foo.yml,configmap-bar.yml
409 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
410 $ podman play kube demo.yml --configmap configmap-foo.yml --configmap configmap-bar.yml
412 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
413 Create a pod connected to two networks (called net1 and net2) with a
417 static ip
418 $ podman play kube demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
421 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
422 Please take into account that CNI networks must be created first using
426 podman-network-create(1).
427
430 podman(1), podman-play(1), podman-network-create(1), podman-generate-
431 kube(1), containers-certs.d(5)
432
435 December 2018, Originally compiled by Brent Baude (bbaude at redhat dot
436 com)
437 podman-play-kube(1)()