Debian Codegraph @

ansible_collections/containers/podman/plugins/modules/podman_container.py

raw
1 #!/usr/bin/python
2 # Copyright (c) 2020 Red Hat
3 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
4
5 # flake8: noqa: E501
6
7 from __future__ import absolute_import, division, print_function
8
9 __metaclass__ = type
10
11
12 DOCUMENTATION = r"""
13 module: podman_container
14 author:
15 - "Sagi Shnaidman (@sshnaidm)"
16 version_added: '1.0.0'
17 short_description: Manage podman containers
18 notes: []
19 description:
20 - Start, stop, restart and manage Podman containers
21 requirements:
22 - podman
23 options:
24 name:
25 description:
26 - Name of the container
27 required: True
28 type: str
29 executable:
30 description:
31 - Path to C(podman) executable if it is not in the C($PATH) on the
32 machine running C(podman)
33 default: 'podman'
34 type: str
35 state:
36 description:
37 - I(absent) - A container matching the specified name will be stopped and
38 removed.
39 - I(present) - Asserts the existence of a container matching the name and
40 any provided configuration parameters. If no container matches the
41 name, a container will be created. If a container matches the name but
42 the provided configuration does not match, the container will be
43 updated, if it can be. If it cannot be updated, it will be removed and
44 re-created with the requested config. Image version will be taken into
45 account when comparing configuration. Use the recreate option to force
46 the re-creation of the matching container.
47 - I(started) - Asserts there is a running container matching the name and
48 any provided configuration. If no container matches the name, a
49 container will be created and started. Use recreate to always re-create
50 a matching container, even if it is running. Use force_restart to force
51 a matching container to be stopped and restarted.
52 - I(stopped) - Asserts that the container is first I(present), and then
53 if the container is running moves it to a stopped state.
54 - I(created) - Asserts that the container exists with given configuration.
55 If container doesn't exist, the module creates it and leaves it in
56 'created' state. If configuration doesn't match or 'recreate' option is
57 set, the container will be recreated
58 - I(quadlet) - Write a quadlet file with the specified configuration.
59 type: str
60 default: started
61 choices:
62 - absent
63 - present
64 - stopped
65 - started
66 - created
67 - quadlet
68 image:
69 description:
70 - Repository path (or image name) and tag used to create the container.
71 If an image is not found, the image will be pulled from the registry.
72 If no tag is included, C(latest) will be used.
73 - Can also be an image ID. If this is the case, the image is assumed to
74 be available locally.
75 type: str
76 annotation:
77 description:
78 - Add an annotation to the container. The format is key value, multiple
79 times.
80 type: dict
81 arch:
82 description:
83 - Set the architecture for the container.
84 Override the architecture, defaults to hosts, of the image to be pulled. For example, arm.
85 type: str
86 attach:
87 description:
88 - Attach to STDIN, STDOUT or STDERR. The default in Podman is false.
89 type: list
90 elements: str
91 choices:
92 - stdin
93 - stdout
94 - stderr
95 authfile:
96 description:
97 - Path of the authentication file. Default is
98 ``${XDG_RUNTIME_DIR}/containers/auth.json``
99 (Not available for remote commands) You can also override the default
100 path of the authentication file by setting the ``REGISTRY_AUTH_FILE``
101 environment variable. ``export REGISTRY_AUTH_FILE=path``
102 type: path
103 blkio_weight:
104 description:
105 - Block IO weight (relative weight) accepts a weight value between 10 and
106 1000
107 type: int
108 blkio_weight_device:
109 description:
110 - Block IO weight (relative device weight, format DEVICE_NAME[:]WEIGHT).
111 type: dict
112 cap_add:
113 description:
114 - List of capabilities to add to the container.
115 type: list
116 elements: str
117 aliases:
118 - capabilities
119 cap_drop:
120 description:
121 - List of capabilities to drop from the container.
122 type: list
123 elements: str
124 cgroup_parent:
125 description:
126 - Path to cgroups under which the cgroup for the container will be
127 created.
128 If the path is not absolute, the path is considered to be relative to
129 the cgroups path of the init process. Cgroups will be created if they
130 do not already exist.
131 type: path
132 cgroup_conf:
133 description:
134 - When running on cgroup v2, specify the cgroup file to write to and its value.
135 type: dict
136 cgroupns:
137 description:
138 - Path to cgroups under which the cgroup for the container will be
139 created.
140 type: str
141 cgroups:
142 description:
143 - Determines whether the container will create CGroups.
144 Valid values are enabled and disabled, which the default being enabled.
145 The disabled option will force the container to not create CGroups,
146 and thus conflicts with CGroup options cgroupns and cgroup-parent.
147 type: str
148 chrootdirs:
149 description:
150 - Path to a directory inside the container that is treated as a chroot directory.
151 type: str
152 cidfile:
153 description:
154 - Write the container ID to the file
155 type: path
156 cmd_args:
157 description:
158 - Any additional command options you want to pass to podman command itself,
159 for example C(--log-level=debug) or C(--syslog). This is NOT command to
160 run in container, but rather options for podman itself.
161 For container command please use I(command) option.
162 type: list
163 elements: str
164 conmon_pidfile:
165 description:
166 - Write the pid of the conmon process to a file.
167 conmon runs in a separate process than Podman,
168 so this is necessary when using systemd to restart Podman containers.
169 type: path
170 command:
171 description:
172 - Override command of container. Can be a string or a list.
173 type: raw
174 cpu_period:
175 description:
176 - Limit the CPU CFS (Completely Fair Scheduler) period
177 type: int
178 cpu_quota:
179 description:
180 - Limit the CPU CFS (Completely Fair Scheduler) quota
181 type: int
182 cpu_rt_period:
183 description:
184 - Limit the CPU real-time period in microseconds.
185 Limit the container's Real Time CPU usage. This flag tell the kernel to
186 restrict the container's Real Time CPU usage to the period you specify.
187 type: int
188 cpu_rt_runtime:
189 description:
190 - Limit the CPU real-time runtime in microseconds.
191 This flag tells the kernel to limit the amount of time in a given CPU
192 period Real Time tasks may consume.
193 type: int
194 cpu_shares:
195 description:
196 - CPU shares (relative weight)
197 type: int
198 cpus:
199 description:
200 - Number of CPUs. The default is 0.0 which means no limit.
201 type: str
202 cpuset_cpus:
203 description:
204 - CPUs in which to allow execution (0-3, 0,1)
205 type: str
206 cpuset_mems:
207 description:
208 - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
209 effective on NUMA systems.
210 type: str
211 decryption_key:
212 description:
213 - The "key-passphrase" to be used for decryption of images. Key can point to keys and/or certificates.
214 type: str
215 delete_depend:
216 description:
217 - Remove selected container and recursively remove all containers that depend on it.
218 Applies to "delete" command.
219 type: bool
220 delete_time:
221 description:
222 - Seconds to wait before forcibly stopping the container. Use -1 for infinite wait.
223 Applies to "delete" command.
224 type: str
225 delete_volumes:
226 description:
227 - Remove anonymous volumes associated with the container.
228 This does not include named volumes created with podman volume create,
229 or the --volume option of podman run and podman create.
230 type: bool
231 detach:
232 description:
233 - Run container in detach mode
234 type: bool
235 default: True
236 debug:
237 description:
238 - Return additional information which can be helpful for investigations.
239 type: bool
240 default: False
241 detach_keys:
242 description:
243 - Override the key sequence for detaching a container. Format is a single
244 character or ctrl-value
245 type: str
246 device:
247 description:
248 - Add a host device to the container.
249 The format is <device-on-host>[:<device-on-container>][:<permissions>]
250 (e.g. device /dev/sdc:/dev/xvdc:rwm)
251 type: list
252 elements: str
253 device_cgroup_rule:
254 description:
255 - Add a rule to the cgroup allowed devices list.
256 The rule is expected to be in the format specified in the Linux kernel
257 documentation admin-guide/cgroup-v1/devices.
258 type: str
259 device_read_bps:
260 description:
261 - Limit read rate (bytes per second) from a device
262 (e.g. device-read-bps /dev/sda:1mb)
263 type: list
264 elements: str
265 device_read_iops:
266 description:
267 - Limit read rate (IO per second) from a device
268 (e.g. device-read-iops /dev/sda:1000)
269 type: list
270 elements: str
271 device_write_bps:
272 description:
273 - Limit write rate (bytes per second) to a device
274 (e.g. device-write-bps /dev/sda:1mb)
275 type: list
276 elements: str
277 device_write_iops:
278 description:
279 - Limit write rate (IO per second) to a device
280 (e.g. device-write-iops /dev/sda:1000)
281 type: list
282 elements: str
283 dns:
284 description:
285 - Set custom DNS servers
286 type: list
287 elements: str
288 aliases:
289 - dns_servers
290 dns_option:
291 description:
292 - Set custom DNS options
293 type: str
294 aliases:
295 - dns_opts
296 dns_search:
297 description:
298 - Set custom DNS search domains (Use dns_search with '' if you don't wish
299 to set the search domain)
300 type: list
301 elements: str
302 aliases:
303 - dns_search_domains
304 entrypoint:
305 description:
306 - Overwrite the default ENTRYPOINT of the image
307 type: str
308 env:
309 description:
310 - Set environment variables.
311 This option allows you to specify arbitrary environment variables that
312 are available for the process that will be launched inside of the
313 container.
314 type: dict
315 env_file:
316 description:
317 - Read in a line delimited file of environment variables. Doesn't support
318 idempotency. If users changes the file with environment variables it's
319 on them to recreate the container.
320 The file must be present on the REMOTE machine where actual podman is
321 running, not on the controller machine where Ansible is executing.
322 If you need to copy the file from controller to remote machine, use the
323 copy or slurp module.
324 type: list
325 elements: path
326 aliases:
327 - env_files
328 env_host:
329 description:
330 - Use all current host environment variables in container.
331 Defaults to false.
332 type: bool
333 env_merge:
334 description:
335 - Preprocess default environment variables for the containers
336 type: dict
337 etc_hosts:
338 description:
339 - Dict of host-to-IP mappings, where each host name is a key in the
340 dictionary. Each host name will be added to the container's
341 ``/etc/hosts`` file.
342 type: dict
343 aliases:
344 - add_hosts
345 expose:
346 description:
347 - Expose a port, or a range of ports (e.g. expose "3300-3310") to set up
348 port redirection on the host system.
349 type: list
350 elements: str
351 aliases:
352 - exposed
353 - exposed_ports
354 force_restart:
355 description:
356 - Force restart of container.
357 type: bool
358 default: False
359 aliases:
360 - restart
361 force_delete:
362 description:
363 - Force deletion of container when it's being deleted.
364 type: bool
365 default: True
366 generate_systemd:
367 description:
368 - Generate systemd unit file for container.
369 type: dict
370 default: {}
371 suboptions:
372 path:
373 description:
374 - Specify a path to the directory where unit files will be generated.
375 Required for this option. If it doesn't exist, the directory will be created.
376 type: str
377 required: false
378 restart_policy:
379 description:
380 - Specify a restart policy for the service. The restart-policy must be one of
381 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-abort", or "always".
382 The default policy is "on-failure".
383 type: str
384 required: false
385 choices:
386 - 'no'
387 - 'on-success'
388 - 'on-failure'
389 - 'on-abnormal'
390 - 'on-watchdog'
391 - 'on-abort'
392 - 'always'
393 restart_sec:
394 description: Set the systemd service restartsec value.
395 type: int
396 required: false
397 start_timeout:
398 description: Override the default start timeout for the container with the given value.
399 type: int
400 required: false
401 stop_timeout:
402 description:
403 - Override the default stop timeout for the container with the given value. Called `time` before version 4.
404 type: int
405 required: false
406 aliases:
407 - time
408 no_header:
409 description:
410 - Do not generate the header including meta data such as the Podman version and the timestamp.
411 From podman version 3.1.0.
412 type: bool
413 default: false
414 names:
415 description:
416 - Use names of the containers for the start, stop, and description in the unit file.
417 Default is true.
418 type: bool
419 default: true
420 container_prefix:
421 description:
422 - Set the systemd unit name prefix for containers. The default is "container".
423 type: str
424 required: false
425 pod_prefix:
426 description:
427 - Set the systemd unit name prefix for pods. The default is "pod".
428 type: str
429 required: false
430 separator:
431 description:
432 - Set the systemd unit name separator between the name/id of a
433 container/pod and the prefix. The default is "-" (dash).
434 type: str
435 required: false
436 new:
437 description:
438 - Create containers and pods when the unit is started instead of
439 expecting them to exist. The default is "false".
440 Refer to podman-generate-systemd(1) for more information.
441 type: bool
442 default: false
443 after:
444 type: list
445 elements: str
446 required: false
447 description:
448 - Add the systemd unit after (After=) option, that ordering dependencies between the list of dependencies and this service.
449 wants:
450 type: list
451 elements: str
452 required: false
453 description:
454 - Add the systemd unit wants (Wants=) option, that this service is (weak) dependent on.
455 requires:
456 type: list
457 elements: str
458 required: false
459 description:
460 - Set the systemd unit requires (Requires=) option. Similar to wants, but declares a stronger requirement dependency.
461 gidmap:
462 description:
463 - Run the container in a new user namespace using the supplied mapping.
464 type: list
465 elements: str
466 gpus:
467 description:
468 - GPU devices to add to the container.
469 type: str
470 group_add:
471 description:
472 - Add additional groups to run as
473 type: list
474 elements: str
475 aliases:
476 - groups
477 group_entry:
478 description:
479 - Customize the entry that is written to the /etc/group file within the container when --user is used.
480 type: str
481 healthcheck:
482 description:
483 - Set or alter a healthcheck command for a container.
484 type: str
485 aliases:
486 - health_cmd
487 healthcheck_interval:
488 description:
489 - Set an interval for the healthchecks
490 (a value of disable results in no automatic timer setup)
491 (default "30s")
492 type: str
493 aliases:
494 - health_interval
495 healthcheck_retries:
496 description:
497 - The number of retries allowed before a healthcheck is considered to be
498 unhealthy. The default value is 3.
499 type: int
500 aliases:
501 - health_retries
502 healthcheck_start_period:
503 description:
504 - The initialization time needed for a container to bootstrap.
505 The value can be expressed in time format like 2m3s. The default value
506 is 0s
507 type: str
508 aliases:
509 - health_start_period
510 health_startup_cmd:
511 description:
512 - Set a startup healthcheck command for a container.
513 type: str
514 health_startup_interval:
515 description:
516 - Set an interval for the startup healthcheck.
517 type: str
518 health_startup_retries:
519 description:
520 - The number of attempts allowed before the startup healthcheck restarts the container.
521 If set to 0, the container is never restarted. The default is 0.
522 type: int
523 health_startup_success:
524 description:
525 - The number of successful runs required before the startup healthcheck succeeds
526 and the regular healthcheck begins. A value of 0 means that any success begins the regular healthcheck.
527 The default is 0.
528 type: int
529 health_startup_timeout:
530 description:
531 - The maximum time a startup healthcheck command has to complete before it is marked as failed.
532 type: str
533 healthcheck_timeout:
534 description:
535 - The maximum time allowed to complete the healthcheck before an interval
536 is considered failed. Like start-period, the value can be expressed in
537 a time format such as 1m22s. The default value is 30s
538 type: str
539 aliases:
540 - health_timeout
541 healthcheck_failure_action:
542 description:
543 - The action to be taken when the container is considered unhealthy. The action must be one of
544 "none", "kill", "restart", or "stop".
545 The default policy is "none".
546 type: str
547 choices:
548 - 'none'
549 - 'kill'
550 - 'restart'
551 - 'stop'
552 aliases:
553 - health_on_failure
554 hooks_dir:
555 description:
556 - Each .json file in the path configures a hook for Podman containers.
557 For more details on the syntax of the JSON files and the semantics of
558 hook injection, see oci-hooks(5). Can be set multiple times.
559 type: list
560 elements: str
561 hostname:
562 description:
563 - Container host name. Sets the container host name that is available
564 inside the container.
565 type: str
566 hostuser:
567 description:
568 - Add a user account to /etc/passwd from the host to the container.
569 The Username or UID must exist on the host system.
570 type: str
571 http_proxy:
572 description:
573 - By default proxy environment variables are passed into the container if
574 set for the podman process. This can be disabled by setting the
575 http_proxy option to false. The environment variables passed in
576 include http_proxy, https_proxy, ftp_proxy, no_proxy, and also the
577 upper case versions of those.
578 Defaults to true
579 type: bool
580 image_volume:
581 description:
582 - Tells podman how to handle the builtin image volumes.
583 The options are bind, tmpfs, or ignore (default bind)
584 type: str
585 choices:
586 - 'bind'
587 - 'tmpfs'
588 - 'ignore'
589 image_strict:
590 description:
591 - Whether to compare images in idempotency by taking into account a full
592 name with registry and namespaces.
593 type: bool
594 default: False
595 init:
596 description:
597 - Run an init inside the container that forwards signals and reaps
598 processes. The default is false.
599 type: bool
600 init_ctr:
601 description:
602 - (Pods only). When using pods, create an init style container,
603 which is run after the infra container is started but before regular pod containers are started.
604 type: str
605 choices:
606 - 'once'
607 - 'always'
608 init_path:
609 description:
610 - Path to the container-init binary.
611 type: str
612 interactive:
613 description:
614 - Keep STDIN open even if not attached. The default is false.
615 When set to true, keep stdin open even if not attached.
616 The default is false.
617 type: bool
618 ip:
619 description:
620 - Specify a static IP address for the container, for example
621 '10.88.64.128'.
622 Can only be used if no additional CNI networks to join were specified
623 via 'network:', and if the container is not joining another container's
624 network namespace via 'network container:<name|id>'.
625 The address must be within the default CNI network's pool
626 (default 10.88.0.0/16).
627 type: str
628 ip6:
629 description:
630 - Specify a static IPv6 address for the container
631 type: str
632 ipc:
633 description:
634 - Default is to create a private IPC namespace (POSIX SysV IPC) for the
635 container
636 type: str
637 aliases:
638 - ipc_mode
639 kernel_memory:
640 description:
641 - Kernel memory limit
642 (format <number>[<unit>], where unit = b, k, m or g)
643 Note - idempotency is supported for integers only.
644 type: str
645 label:
646 description:
647 - Add metadata to a container, pass dictionary of label names and values
648 aliases:
649 - labels
650 type: dict
651 label_file:
652 description:
653 - Read in a line delimited file of labels
654 type: str
655 log_driver:
656 description:
657 - Logging driver. Used to set the log driver for the container.
658 For example log_driver "k8s-file".
659 type: str
660 choices:
661 - k8s-file
662 - journald
663 - json-file
664 - passthrough
665 - none
666 log_level:
667 description:
668 - Logging level for Podman. Log messages above specified level
669 ("debug"|"info"|"warn"|"error"|"fatal"|"panic") (default "error")
670 type: str
671 choices:
672 - debug
673 - info
674 - warn
675 - error
676 - fatal
677 - panic
678 log_opt:
679 description:
680 - Logging driver specific options. Used to set the path to the container
681 log file.
682 type: dict
683 aliases:
684 - log_options
685 suboptions:
686 path:
687 description:
688 - Specify a path to the log file (e.g. /var/log/container/mycontainer.json).
689 type: str
690 required: false
691 max_size:
692 description:
693 - Specify a max size of the log file (e.g 10mb).
694 type: str
695 required: false
696 tag:
697 description:
698 - Specify a custom log tag for the container.
699 type: str
700 required: false
701
702 mac_address:
703 description:
704 - Specify a MAC address for the container, for example
705 '92:d0:c6:0a:29:33'.
706 Don't forget that it must be unique within one Ethernet network.
707 type: str
708 memory:
709 description:
710 - Memory limit (format 10k, where unit = b, k, m or g)
711 Note - idempotency is supported for integers only.
712 type: str
713 memory_reservation:
714 description:
715 - Memory soft limit (format 100m, where unit = b, k, m or g)
716 Note - idempotency is supported for integers only.
717 type: str
718 memory_swap:
719 description:
720 - A limit value equal to memory plus swap. Must be used with the -m
721 (--memory) flag.
722 The swap LIMIT should always be larger than -m (--memory) value.
723 By default, the swap LIMIT will be set to double the value of --memory
724 Note - idempotency is supported for integers only.
725 type: str
726 memory_swappiness:
727 description:
728 - Tune a container's memory swappiness behavior. Accepts an integer
729 between 0 and 100.
730 type: int
731 mount:
732 description:
733 - Attach a filesystem mount to the container. bind or tmpfs
734 For example mount
735 "type=bind,source=/path/on/host,destination=/path/in/container"
736 type: list
737 elements: str
738 aliases:
739 - mounts
740 network:
741 description:
742 - Set the Network mode for the container.
743 - I(bridge) - create a network stack on the default bridge.
744 - I(none) - no networking.
745 - I(container:<name|id>) - reuse another container's network stack.
746 - I(host) - use the podman host network stack.
747 - I(<network-name>|<network-id>) - connect to a user-defined network.
748 - I(ns:<path>) - path to a network namespace to join.
749 - I(slirp4netns) - use slirp4netns to create a user network stack.
750 This is the default for rootless containers.
751 type: list
752 elements: str
753 aliases:
754 - net
755 - network_mode
756 network_aliases:
757 description:
758 - Add network-scoped alias for the container.
759 A container will only have access to aliases on the first network that it joins.
760 This is a limitation that will be removed in a later release.
761 type: list
762 elements: str
763 aliases:
764 - network_alias
765 no_healthcheck:
766 description:
767 - Disable any defined healthchecks for container.
768 type: bool
769 no_hosts:
770 description:
771 - Do not create /etc/hosts for the container
772 Default is false.
773 type: bool
774 oom_kill_disable:
775 description:
776 - Whether to disable OOM Killer for the container or not.
777 Default is false.
778 type: bool
779 oom_score_adj:
780 description:
781 - Tune the host's OOM preferences for containers (accepts -1000 to 1000)
782 type: int
783 os:
784 description:
785 - Override the OS, defaults to hosts, of the image to be pulled. For example, windows.
786 type: str
787 passwd:
788 description:
789 - Allow Podman to add entries to /etc/passwd and /etc/group when used in conjunction with the --user option.
790 This is used to override the Podman provided user setup in favor of entrypoint configurations
791 such as libnss-extrausers.
792 type: bool
793 passwd_entry:
794 description:
795 - Customize the entry that is written to the /etc/passwd file within the container when --passwd is used.
796 type: str
797 personality:
798 description:
799 - Personality sets the execution domain via Linux personality(2).
800 type: str
801 pid:
802 description:
803 - Set the PID mode for the container
804 type: str
805 aliases:
806 - pid_mode
807 pid_file:
808 description:
809 - When the pidfile location is specified, the container process' PID is written to the pidfile.
810 type: path
811 pids_limit:
812 description:
813 - Tune the container's PIDs limit. Set -1 to have unlimited PIDs for the
814 container.
815 type: str
816 platform:
817 description:
818 - Specify the platform for selecting the image.
819 type: str
820 pod:
821 description:
822 - Run container in an existing pod.
823 If you want podman to make the pod for you, prefix the pod name
824 with "new:"
825 type: str
826 pod_id_file:
827 description:
828 - Run container in an existing pod and read the pod's ID from the specified file.
829 When a container is run within a pod which has an infra-container,
830 the infra-container starts first.
831 type: path
832 preserve_fd:
833 description:
834 - Pass down to the process the additional file descriptors specified in the comma separated list.
835 type: list
836 elements: str
837 preserve_fds:
838 description:
839 - Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs are 3\+N.
840 type: str
841 privileged:
842 description:
843 - Give extended privileges to this container. The default is false.
844 type: bool
845 publish:
846 description:
847 - Publish a container's port, or range of ports, to the host.
848 Format - ip:hostPort:containerPort | ip::containerPort |
849 hostPort:containerPort | containerPort
850 In case of only containerPort is set, the hostPort will chosen
851 randomly by Podman.
852 type: list
853 elements: str
854 aliases:
855 - ports
856 - published
857 - published_ports
858 publish_all:
859 description:
860 - Publish all exposed ports to random ports on the host interfaces. The
861 default is false.
862 type: bool
863 pull:
864 description:
865 - Pull image policy. The default is 'missing'.
866 type: str
867 choices:
868 - 'missing'
869 - 'always'
870 - 'never'
871 - 'newer'
872 quadlet_dir:
873 description:
874 - Path to the directory to write quadlet file in.
875 By default, it will be set as C(/etc/containers/systemd/) for root user,
876 C(~/.config/containers/systemd/) for non-root users.
877 type: path
878 quadlet_filename:
879 description:
880 - Name of quadlet file to write. By default it takes C(name) value.
881 type: str
882 quadlet_file_mode:
883 description:
884 - The permissions of the quadlet file.
885 - The O(quadlet_file_mode) can be specified as octal numbers or as a symbolic mode (for example, V(u+rwx) or V(u=rw,g=r,o=r)).
886 For octal numbers format, you must either add a leading zero so that Ansible's YAML parser knows it is an
887 octal number (like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
888 and can do its own conversion from string into number. Giving Ansible a number without following one of these
889 rules will end up with a decimal number which will have unexpected results.
890 - If O(quadlet_file_mode) is not specified and the quadlet file B(does not) exist, the default V('0640') mask will be used
891 when setting the mode for the newly created file.
892 - If O(quadlet_file_mode) is not specified and the quadlet file B(does) exist, the mode of the existing file will be used.
893 - Specifying O(quadlet_file_mode) is the best way to ensure files are created with the correct permissions.
894 type: raw
895 required: false
896 quadlet_options:
897 description:
898 - Options for the quadlet file. Provide missing in usual container args
899 options as a list of lines to add.
900 type: list
901 elements: str
902 rdt_class:
903 description:
904 - Rdt-class sets the class of service (CLOS or COS) for the container to run in. Requires root.
905 type: str
906 read_only:
907 description:
908 - Mount the container's root filesystem as read only. Default is false
909 type: bool
910 read_only_tmpfs:
911 description:
912 - If container is running in --read-only mode, then mount a read-write
913 tmpfs on /run, /tmp, and /var/tmp. The default is true
914 type: bool
915 recreate:
916 description:
917 - Use with present and started states to force the re-creation of an
918 existing container.
919 type: bool
920 default: False
921 requires:
922 description:
923 - Specify one or more requirements. A requirement is a dependency
924 container that will be started before this container.
925 Containers can be specified by name or ID.
926 type: list
927 elements: str
928 restart_policy:
929 description:
930 - Restart policy to follow when containers exit.
931 Restart policy will not take effect if a container is stopped via the
932 podman kill or podman stop commands. Valid values are
933 * no - Do not restart containers on exit
934 * on-failure[:max_retries] - Restart containers when they exit with a
935 non-0 exit code, retrying indefinitely
936 or until the optional max_retries count is hit
937 * always - Restart containers when they exit, regardless of status,
938 retrying indefinitely
939 type: str
940 restart_time:
941 description:
942 - Seconds to wait before forcibly stopping the container when restarting. Use -1 for infinite wait.
943 Applies to "restarted" status.
944 type: str
945 retry:
946 description:
947 - Number of times to retry pulling or pushing images between the registry and local storage in case of failure.
948 Default is 3.
949 type: int
950 retry_delay:
951 description:
952 - Duration of delay between retry attempts when pulling or pushing images between the registry and local storage in case of failure.
953 type: str
954 rm:
955 description:
956 - Automatically remove the container when it exits. The default is false.
957 type: bool
958 aliases:
959 - remove
960 - auto_remove
961 rmi:
962 description:
963 - After exit of the container, remove the image unless another container is using it.
964 Implies --rm on the new container. The default is false.
965 type: bool
966 rootfs:
967 description:
968 - If true, the first argument refers to an exploded container on the file
969 system. The default is false.
970 type: bool
971 sdnotify:
972 description:
973 - Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify.
974 Can be container, conmon, ignore.
975 For quadlets it can also be healthy to use the built in health checks, see
976 L(documentation,https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html#notify-defaults-to-false)
977 for more details.
978 type: str
979 secrets:
980 description:
981 - Add the named secrets into the container.
982 The format is C(secret[,opt=opt...]), see
983 L(documentation,https://docs.podman.io/en/latest/markdown/podman-run.1.html#secret-secret-opt-opt) for more details.
984 type: list
985 elements: str
986 seccomp_policy:
987 description:
988 - Specify the policy to select the seccomp profile.
989 type: str
990 security_opt:
991 description:
992 - Security Options. For example security_opt "seccomp=unconfined"
993 type: list
994 elements: str
995 shm_size:
996 description:
997 - Size of /dev/shm. The format is <number><unit>. number must be greater
998 than 0.
999 Unit is optional and can be b (bytes), k (kilobytes), m(megabytes), or
1000 g (gigabytes).
1001 If you omit the unit, the system uses bytes. If you omit the size
1002 entirely, the system uses 64m
1003 type: str
1004 shm_size_systemd:
1005 description:
1006 - Size of systemd-specific tmpfs mounts such as /run, /run/lock, /var/log/journal and /tmp.
1007 type: str
1008 sig_proxy:
1009 description:
1010 - Proxy signals sent to the podman run command to the container process.
1011 SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is true.
1012 type: bool
1013 stop_signal:
1014 description:
1015 - Signal to stop a container. Default is SIGTERM.
1016 type: int
1017 stop_time:
1018 description:
1019 - Seconds to wait before forcibly stopping the container. Use -1 for infinite wait.
1020 Applies to "stopped" status.
1021 type: str
1022 stop_timeout:
1023 description:
1024 - Timeout (in seconds) to stop a container. Default is 10.
1025 type: int
1026 subgidname:
1027 description:
1028 - Run the container in a new user namespace using the map with 'name' in
1029 the /etc/subgid file.
1030 type: str
1031 subuidname:
1032 description:
1033 - Run the container in a new user namespace using the map with 'name' in
1034 the /etc/subuid file.
1035 type: str
1036 sysctl:
1037 description:
1038 - Configure namespaced kernel parameters at runtime
1039 type: dict
1040 systemd:
1041 description:
1042 - Run container in systemd mode. The default is true.
1043 type: str
1044 timeout:
1045 description:
1046 - Maximum time (in seconds) a container is allowed to run before conmon sends it the kill signal.
1047 By default containers run until they exit or are stopped by "podman stop".
1048 type: int
1049 timezone:
1050 description:
1051 - Set timezone in container. This flag takes area-based timezones,
1052 GMT time, as well as local, which sets the timezone in the container to
1053 match the host machine.
1054 See /usr/share/zoneinfo/ for valid timezones.
1055 Remote connections use local containers.conf for defaults.
1056 type: str
1057 tls_verify:
1058 description:
1059 - Require HTTPS and verify certificates when pulling images.
1060 type: bool
1061 tmpfs:
1062 description:
1063 - Create a tmpfs mount. For example tmpfs
1064 "/tmp" "rw,size=787448k,mode=1777"
1065 type: dict
1066 tty:
1067 description:
1068 - Allocate a pseudo-TTY. The default is false.
1069 type: bool
1070 uidmap:
1071 description:
1072 - Run the container in a new user namespace using the supplied mapping.
1073 type: list
1074 elements: str
1075 ulimit:
1076 description:
1077 - Ulimit options
1078 type: list
1079 elements: str
1080 aliases:
1081 - ulimits
1082 umask:
1083 description:
1084 - Set the umask inside the container. Defaults to 0022.
1085 Remote connections use local containers.conf for defaults.
1086 type: str
1087 unsetenv:
1088 description:
1089 - Unset default environment variables for the container.
1090 type: list
1091 elements: str
1092 unsetenv_all:
1093 description:
1094 - Unset all default environment variables for the container.
1095 type: bool
1096 user:
1097 description:
1098 - Sets the username or UID used and optionally the groupname or GID for
1099 the specified command.
1100 type: str
1101 userns:
1102 description:
1103 - Set the user namespace mode for the container.
1104 It defaults to the PODMAN_USERNS environment variable.
1105 An empty value means user namespaces are disabled.
1106 type: str
1107 aliases:
1108 - userns_mode
1109 uts:
1110 description:
1111 - Set the UTS mode for the container
1112 type: str
1113 variant:
1114 description:
1115 - Use VARIANT instead of the default architecture variant of the container image.
1116 type: str
1117 volume:
1118 description:
1119 - Create a bind mount. If you specify, volume /HOST-DIR:/CONTAINER-DIR,
1120 podman bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the
1121 podman container.
1122 type: list
1123 elements: str
1124 aliases:
1125 - volumes
1126 volumes_from:
1127 description:
1128 - Mount volumes from the specified container(s).
1129 type: list
1130 elements: str
1131 workdir:
1132 description:
1133 - Working directory inside the container.
1134 The default working directory for running binaries within a container
1135 is the root directory (/).
1136 type: str
1137 aliases:
1138 - working_dir
1139 """
1140
1141 EXAMPLES = r"""
1142 - name: Run container
1143 containers.podman.podman_container:
1144 name: container
1145 image: quay.io/bitnami/wildfly
1146 state: started
1147
1148 - name: Create a data container
1149 containers.podman.podman_container:
1150 name: mydata
1151 image: busybox
1152 volume:
1153 - /tmp/data
1154
1155 - name: Re-create a redis container with systemd service file generated in /tmp/
1156 containers.podman.podman_container:
1157 name: myredis
1158 image: redis
1159 command: redis-server --appendonly yes
1160 state: present
1161 recreate: true
1162 expose:
1163 - 6379
1164 volumes_from:
1165 - mydata
1166 generate_systemd:
1167 path: /tmp/
1168 restart_policy: always
1169 stop_timeout: 120
1170 names: true
1171 container_prefix: ainer
1172
1173 - name: Restart a container
1174 containers.podman.podman_container:
1175 name: myapplication
1176 image: redis
1177 state: started
1178 restart: true
1179 etc_hosts:
1180 other: "127.0.0.1"
1181 restart_policy: "no"
1182 device: "/dev/sda:/dev/xvda:rwm"
1183 ports:
1184 - "8080:9000"
1185 - "127.0.0.1:8081:9001/udp"
1186 env:
1187 SECRET_KEY: "ssssh"
1188 BOOLEAN_KEY: "yes"
1189
1190 - name: Container present
1191 containers.podman.podman_container:
1192 name: mycontainer
1193 state: present
1194 image: ubuntu:14.04
1195 command: "sleep 1d"
1196
1197 - name: Stop a container
1198 containers.podman.podman_container:
1199 name: mycontainer
1200 state: stopped
1201
1202 - name: Start 4 load-balanced containers
1203 containers.podman.podman_container:
1204 name: "container{{ item }}"
1205 recreate: true
1206 image: someuser/anotherappimage
1207 command: sleep 1d
1208 with_sequence: count=4
1209
1210 - name: remove container
1211 containers.podman.podman_container:
1212 name: ohno
1213 state: absent
1214
1215 - name: Writing output
1216 containers.podman.podman_container:
1217 name: myservice
1218 image: busybox
1219 log_options: path=/var/log/container/mycontainer.json
1220 log_driver: k8s-file
1221
1222 - name: Run container with complex command with quotes
1223 containers.podman.podman_container:
1224 name: mycontainer
1225 image: certbot/certbot
1226 command:
1227 - renew
1228 - --deploy-hook
1229 - "echo 1 > /var/lib/letsencrypt/complete"
1230
1231 - name: Create a Quadlet file
1232 containers.podman.podman_container:
1233 name: quadlet-container
1234 image: nginx
1235 state: quadlet
1236 quadlet_filename: custome-container
1237 quadlet_file_mode: '0640'
1238 device: "/dev/sda:/dev/xvda:rwm"
1239 ports:
1240 - "8080:80"
1241 volumes:
1242 - "/var/www:/usr/share/nginx/html"
1243 quadlet_options:
1244 - "AutoUpdate=registry"
1245 - "Pull=newer"
1246 - |
1247 [Install]
1248 WantedBy=default.target
1249 """
1250
1251 RETURN = r"""
1252 container:
1253 description:
1254 - Facts representing the current state of the container. Matches the
1255 podman inspection output.
1256 - Note that facts are part of the registered vars since Ansible 2.8. For
1257 compatibility reasons, the facts
1258 are also accessible directly as C(podman_container). Note that the
1259 returned fact will be removed in Ansible 2.12.
1260 - Empty if C(state) is I(absent).
1261 returned: always
1262 type: dict
1263 sample: '{
1264 "Id": "d38a8fcd61ab7e0754355e8fb3acc201e07770f3d1fd8fed36556941ac458ce",
1265 "Created": "2024-08-14T00:04:33.127266655+03:00",
1266 "Path": "/entrypoint.sh",
1267 "Args": [
1268 "/entrypoint.sh"
1269 ],
1270 "State": {
1271 "OciVersion": "1.1.0+dev",
1272 "Status": "running",
1273 "Running": true,
1274 "Paused": false,
1275 "Restarting": false,
1276 "OOMKilled": false,
1277 "Dead": false,
1278 "Pid": 2434164,
1279 "ConmonPid": 2434162,
1280 "ExitCode": 0,
1281 "Error": "",
1282 "StartedAt": "2024-08-14T00:04:33.237286439+03:00",
1283 "FinishedAt": "0001-01-01T00:00:00Z",
1284 "Health": {
1285 "Status": "",
1286 "FailingStreak": 0,
1287 "Log": null
1288 },
1289 "CgroupPath": "/user.slice/user-1000.slice/[email protected]/user.slice/libpod-d38a....scope",
1290 "CheckpointedAt": "0001-01-01T00:00:00Z",
1291 "RestoredAt": "0001-01-01T00:00:00Z"
1292 },
1293 "Image": "fe2ba3a8ede60e5938e666b483c3a812ba902dac2303341930fbadc0482592b7",
1294 "ImageDigest": "sha256:1222865ed7489298ee28414ddedb63a0c6405938c3a38adf21c8656d7f532271",
1295 "ImageName": "registry/org/image:latest",
1296 "Rootfs": "",
1297 "Pod": "",
1298 "ResolvConfPath": "/run/user/1000/containers/overlay-containers/d38a.../userdata/resolv.conf",
1299 "HostnamePath": "/run/user/1000/containers/overlay-containers/d38a.../userdata/hostname",
1300 "HostsPath": "/run/user/1000/containers/overlay-containers/d38a.../userdata/hosts",
1301 "StaticDir": "/home/podman/.local/share/containers/storage/overlay-containers/d38a.../userdata",
1302 "OCIConfigPath": "/home/podman/.local/share/containers/....json",
1303 "OCIRuntime": "crun",
1304 "ConmonPidFile": "/run/user/1000/containers/overlay-containers/d38a.../userdata/conmon.pid",
1305 "PidFile": "/run/user/1000/containers/overlay-containers/d38a.../userdata/pidfile",
1306 "Name": "costapp",
1307 "RestartCount": 0,
1308 "Driver": "overlay",
1309 "MountLabel": "system_u:object_r:container_file_t:s0:c493,c986",
1310 "ProcessLabel": "system_u:system_r:container_t:s0:c493,c986",
1311 "AppArmorProfile": "",
1312 "EffectiveCaps": [
1313 "CAP_CHOWN",
1314 "CAP_DAC_OVERRIDE",
1315 "CAP_FOWNER",
1316 "CAP_FSETID",
1317 "CAP_KILL",
1318 "CAP_NET_BIND_SERVICE",
1319 "CAP_SETFCAP",
1320 "CAP_SETGID",
1321 "CAP_SETPCAP",
1322 "CAP_SETUID",
1323 "CAP_SYS_CHROOT"
1324 ],
1325 "BoundingCaps": [
1326 "CAP_CHOWN",
1327 "CAP_DAC_OVERRIDE",
1328 "CAP_FOWNER",
1329 "CAP_FSETID",
1330 "CAP_KILL",
1331 "CAP_NET_BIND_SERVICE",
1332 "CAP_SETFCAP",
1333 "CAP_SETGID",
1334 "CAP_SETPCAP",
1335 "CAP_SETUID",
1336 "CAP_SYS_CHROOT"
1337 ],
1338 "ExecIDs": [],
1339 "GraphDriver": {
1340 "Name": "overlay",
1341 "Data": {
1342 "LowerDir": "/home/podman/.local/share/containers/storage/overlay/29e2.../diff:...",
1343 "MergedDir": "/home/podman/.local/share/containers/storage/overlay/865909.../merged",
1344 "UpperDir": "/home/podman/.local/share/containers/storage/overlay/865909.../diff",
1345 "WorkDir": "/home/podman/.local/share/containers/storage/overlay/865909.../work"
1346 }
1347 },
1348 "Mounts": [],
1349 "Dependencies": [],
1350 "NetworkSettings": {
1351 "EndpointID": "",
1352 "Gateway": "",
1353 "IPAddress": "",
1354 "IPPrefixLen": 0,
1355 "IPv6Gateway": "",
1356 "GlobalIPv6Address": "",
1357 "GlobalIPv6PrefixLen": 0,
1358 "MacAddress": "",
1359 "Bridge": "",
1360 "SandboxID": "",
1361 "HairpinMode": false,
1362 "LinkLocalIPv6Address": "",
1363 "LinkLocalIPv6PrefixLen": 0,
1364 "Ports": {
1365 "80/tcp": [
1366 {
1367 "HostIp": "",
1368 "HostPort": "8888"
1369 }
1370 ]
1371 },
1372 "SandboxKey": "/run/user/1000/netns/netns-2343321-795a-8289-14c0-77ee2556ebf1"
1373 },
1374 "Namespace": "",
1375 "IsInfra": false,
1376 "IsService": false,
1377 "KubeExitCodePropagation": "invalid",
1378 "lockNumber": 1417,
1379 "Config": {
1380 "Hostname": "444a8274863a",
1381 "Domainname": "",
1382 "User": "",
1383 "AttachStdin": false,
1384 "AttachStdout": false,
1385 "AttachStderr": false,
1386 "Tty": false,
1387 "OpenStdin": false,
1388 "StdinOnce": false,
1389 "Env": [
1390 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
1391 "container=podman",
1392 "HOME=/root",
1393 "HOSTNAME=444a8274863a"
1394 ],
1395 "Cmd": null,
1396 "Image": "registry/org/image:latest",
1397 "Volumes": null,
1398 "WorkingDir": "/",
1399 "Entrypoint": "/entrypoint.sh",
1400 "OnBuild": null,
1401 "Labels": {
1402 "io.buildah.version": "1.31.2"
1403 },
1404 "Annotations": {
1405 "io.container.manager": "libpod",
1406 "org.opencontainers.image.stopSignal": "15"
1407 },
1408 "StopSignal": 15,
1409 "HealthcheckOnFailureAction": "none",
1410 "CreateCommand": [
1411 "podman",
1412 "run",
1413 "-d",
1414 "--name",
1415 "test",
1416 "-p",
1417 "8888:80",
1418 "registry/org/image:latest"
1419 ],
1420 "Umask": "0022",
1421 "Timeout": 0,
1422 "StopTimeout": 10,
1423 "Passwd": true,
1424 "sdNotifyMode": "container"
1425 },
1426 "HostConfig": {
1427 "Binds": [],
1428 "CgroupManager": "systemd",
1429 "CgroupMode": "private",
1430 "ContainerIDFile": "",
1431 "LogConfig": {
1432 "Type": "journald",
1433 "Config": null,
1434 "Path": "",
1435 "Tag": "",
1436 "Size": "0B"
1437 },
1438 "NetworkMode": "slirp4netns",
1439 "PortBindings": {
1440 "80/tcp": [
1441 {
1442 "HostIp": "",
1443 "HostPort": "8888"
1444 }
1445 ]
1446 },
1447 "RestartPolicy": {
1448 "Name": "",
1449 "MaximumRetryCount": 0
1450 },
1451 "AutoRemove": false,
1452 "VolumeDriver": "",
1453 "VolumesFrom": null,
1454 "CapAdd": [],
1455 "CapDrop": [],
1456 "Dns": [],
1457 "DnsOptions": [],
1458 "DnsSearch": [],
1459 "ExtraHosts": [],
1460 "GroupAdd": [],
1461 "IpcMode": "shareable",
1462 "Cgroup": "",
1463 "Cgroups": "default",
1464 "Links": null,
1465 "OomScoreAdj": 0,
1466 "PidMode": "private",
1467 "Privileged": false,
1468 "PublishAllPorts": false,
1469 "ReadonlyRootfs": false,
1470 "SecurityOpt": [],
1471 "Tmpfs": {},
1472 "UTSMode": "private",
1473 "UsernsMode": "",
1474 "ShmSize": 65536000,
1475 "Runtime": "oci",
1476 "ConsoleSize": [
1477 0,
1478 0
1479 ],
1480 "Isolation": "",
1481 "CpuShares": 0,
1482 "Memory": 0,
1483 "NanoCpus": 0,
1484 "CgroupParent": "user.slice",
1485 "BlkioWeight": 0,
1486 "BlkioWeightDevice": null,
1487 "BlkioDeviceReadBps": null,
1488 "BlkioDeviceWriteBps": null,
1489 "BlkioDeviceReadIOps": null,
1490 "BlkioDeviceWriteIOps": null,
1491 "CpuPeriod": 0,
1492 "CpuQuota": 0,
1493 "CpuRealtimePeriod": 0,
1494 "CpuRealtimeRuntime": 0,
1495 "CpusetCpus": "",
1496 "CpusetMems": "",
1497 "Devices": [],
1498 "DiskQuota": 0,
1499 "KernelMemory": 0,
1500 "MemoryReservation": 0,
1501 "MemorySwap": 0,
1502 "MemorySwappiness": 0,
1503 "OomKillDisable": false,
1504 "PidsLimit": 2048,
1505 "Ulimits": [
1506 {
1507 "Name": "RLIMIT_NOFILE",
1508 "Soft": 524288,
1509 "Hard": 524288
1510 },
1511 {
1512 "Name": "RLIMIT_NPROC",
1513 "Soft": 256018,
1514 "Hard": 256018
1515 }
1516 ],
1517 "CpuCount": 0,
1518 "CpuPercent": 0,
1519 "IOMaximumIOps": 0,
1520 "IOMaximumBandwidth": 0,
1521 "CgroupConf": null,
1522 }'
1523 """
1524
1525 from ansible.module_utils.basic import AnsibleModule # noqa: F402
1526 from ..module_utils.podman.podman_container_lib import PodmanManager # noqa: F402
1527 from ..module_utils.podman.podman_container_lib import (
1528 ARGUMENTS_SPEC_CONTAINER,
1529 ) # noqa: F402
1530
1531
1532 def main():
1533 module = AnsibleModule(
1534 argument_spec=ARGUMENTS_SPEC_CONTAINER,
1535 mutually_exclusive=(["no_hosts", "etc_hosts"],),
1536 supports_check_mode=True,
1537 )
1538
1539 # work on input vars
1540 if (
1541 module.params["state"] in ["present", "created"]
1542 and not module.params["force_restart"]
1543 and not module.params["image"]
1544 ):
1545 module.fail_json(msg="State '%s' required image to be configured!" % module.params["state"])
1546
1547 results = PodmanManager(module, module.params).execute()
1548 module.exit_json(**results)
1549
1550
1551 if __name__ == "__main__":
1552 main()