Debian Codegraph @

ansible_collections/containers/podman/plugins/modules/podman_pod.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 from __future__ import absolute_import, division, print_function
7
8 __metaclass__ = type
9
10 DOCUMENTATION = """
11 ---
12 module: podman_pod
13 short_description: Manage Podman pods
14 author:
15 - "Sagi Shnaidman (@sshnaidm)"
16 version_added: '1.0.0'
17 description:
18 - Manage podman pods.
19 options:
20 state:
21 description:
22 - This variable is set for state
23 type: str
24 default: created
25 choices:
26 - created
27 - killed
28 - restarted
29 - absent
30 - started
31 - stopped
32 - paused
33 - unpaused
34 - quadlet
35 recreate:
36 description:
37 - Use with present and started states to force the re-creation of an
38 existing pod.
39 type: bool
40 default: False
41 add_host:
42 description:
43 - Add a host to the /etc/hosts file shared between all containers in the pod.
44 type: list
45 elements: str
46 required: false
47 blkio_weight:
48 description:
49 - Block IO relative weight. The weight is a value between 10 and 1000.
50 - This option is not supported on cgroups V1 rootless systems.
51 type: str
52 required: false
53 blkio_weight_device:
54 description:
55 - Block IO relative device weight.
56 type: list
57 elements: str
58 required: false
59 cgroup_parent:
60 description:
61 - Path to cgroups under which the cgroup for the pod will be created. If the path
62 is not absolute, he path is considered to be relative to the cgroups path of the
63 init process. Cgroups will be created if they do not already exist.
64 type: str
65 required: false
66 cpus:
67 description:
68 - Set the total number of CPUs delegated to the pod.
69 Default is 0.000 which indicates that there is no limit on computation power.
70 required: false
71 type: str
72 cpuset_cpus:
73 description:
74 - Limit the CPUs to support execution. First CPU is numbered 0.
75 Unlike `cpus` this is of type string and parsed as a list of numbers. Format is 0-3,0,1
76 required: false
77 type: str
78 cpuset_mems:
79 description:
80 - Memory nodes in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
81 required: false
82 type: str
83 cpu_shares:
84 description:
85 - CPU shares (relative weight).
86 required: false
87 type: str
88 device:
89 description:
90 - Add a host device to the pod. Optional permissions parameter can be used to specify
91 device permissions. It is a combination of r for read, w for write, and m for mknod(2)
92 elements: str
93 required: false
94 type: list
95 device_read_bps:
96 description:
97 - Limit read rate (bytes per second) from a device (e.g. device-read-bps=/dev/sda:1mb)
98 elements: str
99 required: false
100 type: list
101 device_write_bps:
102 description:
103 - Limit write rate (in bytes per second) to a device.
104 type: list
105 elements: str
106 required: false
107 dns:
108 description:
109 - Set custom DNS servers in the /etc/resolv.conf file that will be shared between
110 all containers in the pod. A special option, "none" is allowed which disables
111 creation of /etc/resolv.conf for the pod.
112 type: list
113 elements: str
114 required: false
115 dns_opt:
116 description:
117 - Set custom DNS options in the /etc/resolv.conf file that will be shared between
118 all containers in the pod.
119 type: list
120 elements: str
121 aliases:
122 - dns_option
123 required: false
124 dns_search:
125 description:
126 - Set custom DNS search domains in the /etc/resolv.conf file that will be shared
127 between all containers in the pod.
128 type: list
129 elements: str
130 required: false
131 exit_policy:
132 description:
133 - Set the exit policy of the pod when the last container exits. Supported policies are stop and continue
134 choices:
135 - stop
136 - continue
137 type: str
138 required: false
139 generate_systemd:
140 description:
141 - Generate systemd unit file for container.
142 type: dict
143 default: {}
144 suboptions:
145 path:
146 description:
147 - Specify a path to the directory where unit files will be generated.
148 Required for this option. If it doesn't exist, the directory will be created.
149 type: str
150 required: false
151 restart_policy:
152 description:
153 - Specify a restart policy for the service. The restart-policy must be one of
154 "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-abort", or "always".
155 The default policy is "on-failure".
156 type: str
157 required: false
158 choices:
159 - 'no'
160 - 'on-success'
161 - 'on-failure'
162 - 'on-abnormal'
163 - 'on-watchdog'
164 - 'on-abort'
165 - 'always'
166 restart_sec:
167 description: Set the systemd service restartsec value.
168 type: int
169 required: false
170 start_timeout:
171 description: Override the default start timeout for the container with the given value.
172 type: int
173 required: false
174 stop_timeout:
175 description:
176 - Override the default stop timeout for the container with the given value. Called `time` before version 4.
177 type: int
178 required: false
179 aliases:
180 - time
181 no_header:
182 description:
183 - Do not generate the header including meta data such as the Podman version and the timestamp.
184 From podman version 3.1.0.
185 type: bool
186 default: false
187 names:
188 description:
189 - Use names of the containers for the start, stop, and description in the unit file.
190 Default is true.
191 type: bool
192 default: true
193 container_prefix:
194 description:
195 - Set the systemd unit name prefix for containers. The default is "container".
196 type: str
197 required: false
198 pod_prefix:
199 description:
200 - Set the systemd unit name prefix for pods. The default is "pod".
201 type: str
202 required: false
203 separator:
204 description:
205 - Set the systemd unit name separator between the name/id of a
206 container/pod and the prefix. The default is "-" (dash).
207 type: str
208 required: false
209 new:
210 description:
211 - Create containers and pods when the unit is started instead of
212 expecting them to exist. The default is "false".
213 Refer to podman-generate-systemd(1) for more information.
214 type: bool
215 default: false
216 after:
217 type: list
218 elements: str
219 required: false
220 description:
221 - Add the systemd unit after (After=) option, that ordering dependencies between the list of dependencies and this service.
222 wants:
223 type: list
224 elements: str
225 required: false
226 description:
227 - Add the systemd unit wants (Wants=) option, that this service is (weak) dependent on.
228 requires:
229 type: list
230 elements: str
231 required: false
232 description:
233 - Set the systemd unit requires (Requires=) option. Similar to wants, but declares a stronger requirement dependency.
234 gidmap:
235 description:
236 - GID map for the user namespace. Using this flag will run the container with
237 user namespace enabled. It conflicts with the `userns` and `subgidname` flags.
238 elements: str
239 required: false
240 type: list
241 gpus:
242 description:
243 - GPU devices to add to the container ('all' to pass all GPUs).
244 type: str
245 required: false
246 hostname:
247 description:
248 - Set a hostname to the pod
249 type: str
250 required: false
251 infra:
252 description:
253 - Create an infra container and associate it with the pod. An infra container is
254 a lightweight container used to coordinate the shared kernel namespace of a pod.
255 Default is true.
256 type: bool
257 required: false
258 infra_conmon_pidfile:
259 description:
260 - Write the pid of the infra container's conmon process to a file. As conmon runs
261 in a separate process than Podman, this is necessary when using systemd to manage
262 Podman containers and pods.
263 type: str
264 required: false
265 infra_command:
266 description:
267 - The command that will be run to start the infra container. Default is "/pause".
268 type: str
269 required: false
270 infra_image:
271 description:
272 - The image that will be created for the infra container. Default is "k8s.gcr.io/pause:3.1".
273 type: str
274 required: false
275 infra_name:
276 description:
277 - The name that will be used for the pod's infra container.
278 type: str
279 required: false
280 ip:
281 description:
282 - Set a static IP for the pod's shared network.
283 type: str
284 required: false
285 ip6:
286 description:
287 - Set a static IPv6 for the pod's shared network.
288 type: str
289 required: false
290 label:
291 description:
292 - Add metadata to a pod, pass dictionary of label keys and values.
293 type: dict
294 required: false
295 label_file:
296 description:
297 - Read in a line delimited file of labels.
298 type: str
299 required: false
300 mac_address:
301 description:
302 - Set a static MAC address for the pod's shared network.
303 type: str
304 required: false
305 memory:
306 description:
307 - Set memory limit.
308 - A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
309 type: str
310 required: false
311 memory_swap:
312 description:
313 - Set limit value equal to memory plus swap.
314 - A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
315 type: str
316 required: false
317 name:
318 description:
319 - Assign a name to the pod.
320 type: str
321 required: true
322 network:
323 description:
324 - Set network mode for the pod. Supported values are bridge (the default), host
325 (do not create a network namespace, all containers in the pod will use the host's
326 network), or a list of names of CNI networks to join.
327 type: list
328 elements: str
329 required: false
330 network_alias:
331 description:
332 - Add a network-scoped alias for the pod, setting the alias for all networks that the pod joins.
333 To set a name only for a specific network, use the alias option as described under the -`network` option.
334 Network aliases work only with the bridge networking mode.
335 This option can be specified multiple times.
336 elements: str
337 required: false
338 type: list
339 aliases:
340 - network_aliases
341 no_hosts:
342 description:
343 - Disable creation of /etc/hosts for the pod.
344 type: bool
345 required: false
346 pid:
347 description:
348 - Set the PID mode for the pod. The default is to create a private PID namespace
349 for the pod. Requires the PID namespace to be shared via `share` option.
350 required: false
351 type: str
352 pod_id_file:
353 description:
354 - Write the pod ID to the file.
355 type: str
356 required: false
357 publish:
358 description:
359 - Publish a port or range of ports from the pod to the host.
360 type: list
361 elements: str
362 required: false
363 aliases:
364 - ports
365 quadlet_dir:
366 description:
367 - Path to the directory to write quadlet file in.
368 By default, it will be set as C(/etc/containers/systemd/) for root user,
369 C(~/.config/containers/systemd/) for non-root users.
370 type: path
371 quadlet_filename:
372 description:
373 - Name of quadlet file to write. By default it takes I(name) value.
374 type: str
375 quadlet_file_mode:
376 description:
377 - The permissions of the quadlet file.
378 - 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)).
379 For octal numbers format, you must either add a leading zero so that Ansible's YAML parser knows it is an
380 octal number (like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
381 and can do its own conversion from string into number. Giving Ansible a number without following one of these
382 rules will end up with a decimal number which will have unexpected results.
383 - If O(quadlet_file_mode) is not specified and the quadlet file B(does not) exist, the default C(umask) on the system will be used
384 when setting the mode for the newly created file.
385 - If O(quadlet_file_mode) is not specified and the quadlet file B(does) exist, the mode of the existing file will be used.
386 - Specifying O(quadlet_file_mode) is the best way to ensure files are created with the correct permissions.
387 type: raw
388 required: false
389 quadlet_options:
390 description:
391 - Options for the quadlet file. Provide missing in usual container args
392 options as a list of lines to add.
393 type: list
394 elements: str
395 restart_policy:
396 description:
397 - Restart policy to follow when containers exit.
398 type: str
399 security_opt:
400 description:
401 - Security options for the pod.
402 type: list
403 elements: str
404 required: false
405 share:
406 description:
407 - A comma delimited list of kernel namespaces to share. If none or "" is specified,
408 no namespaces will be shared. The namespaces to choose from are ipc, net, pid,
409 user, uts.
410 type: str
411 required: false
412 share_parent:
413 description:
414 - This boolean determines whether or not all containers entering the pod use the pod as their cgroup parent.
415 The default value of this option in Podman is true.
416 type: bool
417 required: false
418 shm_size:
419 description:
420 - Set the size of the /dev/shm shared memory space.
421 A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
422 If the unit is omitted, the system uses bytes.
423 If the size is omitted, the default is 64m.
424 When size is 0, there is no limit on the amount of memory used for IPC by the pod.
425 type: str
426 required: false
427 shm_size_systemd:
428 description:
429 - Size of systemd-specific tmpfs mounts such as /run, /run/lock, /var/log/journal and /tmp.
430 A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes).
431 If the unit is omitted, the system uses bytes.
432 If the size is omitted, the default is 64m.
433 When size is 0, the usage is limited to 50 percents of the host's available memory.
434 type: str
435 required: false
436 subgidname:
437 description:
438 - Name for GID map from the /etc/subgid file. Using this flag will run the container
439 with user namespace enabled. This flag conflicts with `userns` and `gidmap`.
440 required: false
441 type: str
442 subuidname:
443 description:
444 - Name for UID map from the /etc/subuid file.
445 Using this flag will run the container with user namespace enabled.
446 This flag conflicts with `userns` and `uidmap`.
447 required: false
448 type: str
449 sysctl:
450 description:
451 - Set kernel parameters for the pod.
452 type: dict
453 required: false
454 uidmap:
455 description:
456 - Run the container in a new user namespace using the supplied mapping.
457 This option conflicts with the `userns` and `subuidname` options.
458 This option provides a way to map host UIDs to container UIDs.
459 It can be passed several times to map different ranges.
460 elements: str
461 required: false
462 type: list
463 userns:
464 description:
465 - Set the user namespace mode for all the containers in a pod.
466 It defaults to the PODMAN_USERNS environment variable.
467 An empty value ("") means user namespaces are disabled.
468 required: false
469 type: str
470 uts:
471 description:
472 - Set the UTS namespace mode for the pod.
473 required: false
474 type: str
475 volume:
476 description:
477 - Create a bind mount.
478 aliases:
479 - volumes
480 elements: str
481 required: false
482 type: list
483 volumes_from:
484 description:
485 - Mount volumes from the specified container.
486 elements: str
487 required: false
488 type: list
489 executable:
490 description:
491 - Path to C(podman) executable if it is not in the C($PATH) on the
492 machine running C(podman)
493 default: 'podman'
494 type: str
495 debug:
496 description:
497 - Return additional information which can be helpful for investigations.
498 type: bool
499 default: False
500
501 requirements:
502 - "podman"
503
504 """
505
506 RETURN = r"""
507 pod:
508 description: Pod inspection results for the given pod
509 built.
510 returned: always
511 type: dict
512 sample:
513 {
514 "Id": "a99a41b8fa77d8c7ff1c432a7a21bc0c2afd8c13b94a9d9b9b19b66ae97920c1",
515 "Name": "pod_name",
516 "Created": "2024-05-28T20:41:09.946926613+03:00",
517 "CreateCommand": [
518 "podman",
519 "pod",
520 "create",
521 "--name",
522 "pod_name",
523 "--infra=True",
524 "--userns",
525 "auto",
526 "--security-opt",
527 "seccomp=unconfined",
528 "--security-opt",
529 "apparmor=unconfined",
530 "--hostname",
531 "mypod",
532 "--dns",
533 "1.1.1.2",
534 "--label",
535 "key=cval",
536 "--label",
537 "otherkey=kddkdk",
538 "--label",
539 "somekey=someval",
540 "--add-host",
541 "google:5.5.5.5",
542 "--volume",
543 "/tmp/test//:/data2"
544 ],
545 "ExitPolicy": "continue",
546 "State": "Created",
547 "Hostname": "mypod",
548 "Labels": {
549 "key": "cval",
550 "otherkey": "kddkdk",
551 "somekey": "someval"
552 },
553 "CreateCgroup": true,
554 "CgroupParent": "user.slice",
555 "CgroupPath": "user.slice/user-1000.slice/[email protected]/user.slice/....slice",
556 "CreateInfra": true,
557 "InfraContainerID": "37f960e6c8accc6b5b41945b1dcf03a28d3a366f7f37049748f18b21c44f577e",
558 "InfraConfig": {
559 "PortBindings": {},
560 "HostNetwork": false,
561 "StaticIP": "",
562 "StaticMAC": "",
563 "NoManageResolvConf": false,
564 "DNSServer": [
565 "1.1.1.2"
566 ],
567 "DNSSearch": null,
568 "DNSOption": null,
569 "NoManageHosts": false,
570 "HostAdd": [
571 "google:5.5.5.5"
572 ],
573 "Networks": null,
574 "NetworkOptions": null,
575 "pid_ns": "private",
576 "userns": "host",
577 "uts_ns": "private"
578 },
579 "SharedNamespaces": [
580 "user",
581 "uts",
582 "ipc",
583 "net"
584 ],
585 "NumContainers": 1,
586 "Containers": [
587 {
588 "Id": "37f960e6c8accc6b5b41945b1dcf03a28d3a366f7f37049748f18b21c44f577e",
589 "Name": "a99a49b8fa77-infra",
590 "State": "created"
591 }
592 ],
593 "mounts": [
594 {
595 "Type": "bind",
596 "Source": "/tmp/test",
597 "Destination": "/data2",
598 "Driver": "",
599 "Mode": "",
600 "Options": [
601 "nosuid",
602 "nodev",
603 "rbind"
604 ],
605 "RW": true,
606 "Propagation": "rprivate"
607 }
608 ],
609 "security_opt": [
610 "seccomp=unconfined",
611 "apparmor=unconfined"
612 ],
613 "LockNumber": 1
614 }
615 """
616
617 EXAMPLES = r"""
618 # What modules does for example
619 - containers.podman.podman_pod:
620 name: pod1
621 state: started
622 ports:
623 - "4444:5555"
624
625 # Connect random port from localhost to port 80 on pod2
626 - name: Connect random port from localhost to port 80 on pod2
627 containers.podman.podman_pod:
628 name: pod2
629 state: started
630 publish: "127.0.0.1::80"
631
632 # Full workflow example with pod and containers
633 - name: Create a pod with parameters
634 containers.podman.podman_pod:
635 name: mypod
636 state: created
637 network: host
638 share: net
639 userns: auto
640 security_opt:
641 - seccomp=unconfined
642 - apparmor=unconfined
643 hostname: mypod
644 dns:
645 - 1.1.1.1
646 volumes:
647 - /tmp:/tmp/:ro
648 label:
649 key: cval
650 otherkey: kddkdk
651 somekey: someval
652 add_host:
653 - "google:5.5.5.5"
654
655 - name: Create containers attached to the pod
656 containers.podman.podman_container:
657 name: "{{ item }}"
658 state: created
659 pod: mypod
660 image: alpine
661 command: sleep 1h
662 loop:
663 - "container1"
664 - "container2"
665
666 - name: Start pod
667 containers.podman.podman_pod:
668 name: mypod
669 state: started
670 network: host
671 share: net
672 userns: auto
673 security_opt:
674 - seccomp=unconfined
675 - apparmor=unconfined
676 hostname: mypod
677 dns:
678 - 1.1.1.1
679 volumes:
680 - /tmp:/tmp/:ro
681 label:
682 key: cval
683 otherkey: kddkdk
684 somekey: someval
685 add_host:
686 - "google:5.5.5.5"
687
688 # Create a Quadlet file for a pod
689 - containers.podman.podman_pod:
690 name: qpod
691 state: quadlet
692 ports:
693 - "4444:5555"
694 volume:
695 - /var/run/docker.sock:/var/run/docker.sock
696 quadlet_dir: /custom/dir
697 """
698 from ansible.module_utils.basic import AnsibleModule # noqa: F402
699 from ..module_utils.podman.podman_pod_lib import PodmanPodManager # noqa: F402
700 from ..module_utils.podman.podman_pod_lib import ARGUMENTS_SPEC_POD # noqa: F402
701
702
703 def main():
704 module = AnsibleModule(argument_spec=ARGUMENTS_SPEC_POD, supports_check_mode=True)
705 results = PodmanPodManager(module, module.params).execute()
706 module.exit_json(**results)
707
708
709 if __name__ == "__main__":
710 main()