Debian Codegraph @

ansible_collections/containers/podman/plugins/modules/podman_volume.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_volume
13 short_description: Manage Podman volumes
14 author:
15 - "Sagi Shnaidman (@sshnaidm)"
16 version_added: '1.1.0'
17 description:
18 - Manage Podman volumes
19 options:
20 state:
21 description:
22 - State of volume, default 'present'
23 type: str
24 default: present
25 choices:
26 - present
27 - absent
28 - mounted
29 - unmounted
30 - quadlet
31 recreate:
32 description:
33 - Recreate volume even if exists.
34 type: bool
35 default: false
36 name:
37 description:
38 - Name of volume.
39 type: str
40 required: true
41 label:
42 description:
43 - Add metadata to a pod volume (e.g., label com.example.key=value).
44 type: dict
45 required: false
46 driver:
47 description:
48 - Specify volume driver name (default local).
49 type: str
50 required: false
51 options:
52 description:
53 - Set driver specific options. For example 'device=tpmfs', 'type=tmpfs'.
54 UID and GID idempotency is not supported due to changes in podman.
55 type: list
56 elements: str
57 required: false
58 executable:
59 description:
60 - Path to C(podman) executable if it is not in the C($PATH) on the
61 machine running C(podman)
62 default: 'podman'
63 type: str
64 debug:
65 description:
66 - Return additional information which can be helpful for investigations.
67 type: bool
68 default: False
69 quadlet_dir:
70 description:
71 - Path to the directory to write quadlet file in.
72 By default, it will be set as C(/etc/containers/systemd/) for root user,
73 C(~/.config/containers/systemd/) for non-root users.
74 type: path
75 required: false
76 quadlet_filename:
77 description:
78 - Name of quadlet file to write. By default it takes I(name) value.
79 type: str
80 quadlet_file_mode:
81 description:
82 - The permissions of the quadlet file.
83 - 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)).
84 For octal numbers format, you must either add a leading zero so that Ansible's YAML parser knows it is an
85 octal number (like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
86 and can do its own conversion from string into number. Giving Ansible a number without following one of these
87 rules will end up with a decimal number which will have unexpected results.
88 - If O(quadlet_file_mode) is not specified and the quadlet file B(does not) exist, the default V('0640') mask will be used
89 when setting the mode for the newly created file.
90 - If O(quadlet_file_mode) is not specified and the quadlet file B(does) exist, the mode of the existing file will be used.
91 - Specifying O(quadlet_file_mode) is the best way to ensure files are created with the correct permissions.
92 type: raw
93 required: false
94 quadlet_options:
95 description:
96 - Options for the quadlet file. Provide missing in usual network args
97 options as a list of lines to add.
98 type: list
99 elements: str
100 required: false
101
102 requirements:
103 - "podman"
104
105 """
106
107 RETURN = """
108 volume:
109 description: Volume inspection results if exists.
110 returned: always
111 type: dict
112 sample:
113 CreatedAt: '2023-11-30T16:41:31.310865559+02:00'
114 Driver: local
115 Labels: {}
116 LockNumber: 18
117 MountCount: 0
118 Mountpoint: /home/user/.local/share/containers/storage/volumes/volname/_data
119 Name: volname
120 NeedsChown: true
121 NeedsCopyUp: true
122 Options: {}
123 Scope: local
124
125 """
126
127 EXAMPLES = """
128 # What modules does for example
129 - name: Create a volume
130 containers.podman.podman_volume:
131 state: present
132 name: volume1
133 label:
134 key: value
135 key2: value2
136 options:
137 - "device=/dev/loop1"
138 - "type=ext4"
139
140 - name: Create a Quadlet file for a volume
141 containers.podman.podman_volume:
142 state: quadlet
143 name: quadlet_volume
144 quadlet_filename: custom-name
145 quadlet_file_mode: '0640'
146 quadlet_options:
147 - Group=192
148 - Copy=true
149 - Image=quay.io/centos/centos:latest
150
151 """
152 # noqa: F402
153 import json # noqa: F402
154 import os # noqa: F402
155
156 from ansible.module_utils.basic import AnsibleModule # noqa: F402
157 try:
158 from ansible.module_utils.common.text.converters import to_native, to_bytes # noqa: F402
159 except ImportError:
160 from ansible.module_utils.common.text import to_native, to_bytes # noqa: F402
161 from ansible_collections.containers.podman.plugins.module_utils.podman.common import (
162 LooseVersion,
163 )
164 from ansible_collections.containers.podman.plugins.module_utils.podman.common import (
165 lower_keys,
166 )
167 from ansible_collections.containers.podman.plugins.module_utils.podman.quadlet import (
168 create_quadlet_state,
169 )
170
171
172 class PodmanVolumeModuleParams:
173 """Creates list of arguments for podman CLI command.
174
175 Arguments:
176 action {str} -- action type from 'create', 'delete'
177 params {dict} -- dictionary of module parameters
178
179 """
180
181 def __init__(self, action, params, podman_version, module):
182 self.params = params
183 self.action = action
184 self.podman_version = podman_version
185 self.module = module
186
187 def construct_command_from_params(self):
188 """Create a podman command from given module parameters.
189
190 Returns:
191 list -- list of byte strings for Popen command
192 """
193 if self.action in ["delete", "mount", "unmount"]:
194 return self._simple_action()
195 if self.action in ["create"]:
196 return self._create_action()
197
198 def _simple_action(self):
199 if self.action == "delete":
200 cmd = ["rm", "-f", self.params["name"]]
201 return [to_bytes(i, errors="surrogate_or_strict") for i in cmd]
202 if self.action == "mount":
203 cmd = ["mount", self.params["name"]]
204 return [to_bytes(i, errors="surrogate_or_strict") for i in cmd]
205 if self.action == "unmount":
206 cmd = ["unmount", self.params["name"]]
207 return [to_bytes(i, errors="surrogate_or_strict") for i in cmd]
208
209 def _create_action(self):
210 cmd = [self.action, self.params["name"]]
211 all_param_methods = [
212 func for func in dir(self) if callable(getattr(self, func)) and func.startswith("addparam")
213 ]
214 params_set = (i for i in self.params if self.params[i] is not None)
215 for param in params_set:
216 func_name = "_".join(["addparam", param])
217 if func_name in all_param_methods:
218 cmd = getattr(self, func_name)(cmd)
219 return [to_bytes(i, errors="surrogate_or_strict") for i in cmd]
220
221 def check_version(self, param, minv=None, maxv=None):
222 if minv and LooseVersion(minv) > LooseVersion(self.podman_version):
223 self.module.fail_json(
224 msg="Parameter %s is supported from podman "
225 "version %s only! Current version is %s" % (param, minv, self.podman_version)
226 )
227 if maxv and LooseVersion(maxv) < LooseVersion(self.podman_version):
228 self.module.fail_json(
229 msg="Parameter %s is supported till podman "
230 "version %s only! Current version is %s" % (param, minv, self.podman_version)
231 )
232
233 def addparam_label(self, c):
234 for label in self.params["label"].items():
235 c += [
236 "--label",
237 b"=".join([to_bytes(l, errors="surrogate_or_strict") for l in label]),
238 ]
239 return c
240
241 def addparam_driver(self, c):
242 return c + ["--driver", self.params["driver"]]
243
244 def addparam_options(self, c):
245 for opt in self.params["options"]:
246 c += ["--opt", opt]
247 return c
248
249
250 class PodmanVolumeDefaults:
251 def __init__(self, module, podman_version):
252 self.module = module
253 self.version = podman_version
254 self.defaults = {"driver": "local", "label": {}, "options": {}}
255
256 def default_dict(self):
257 # make here any changes to self.defaults related to podman version
258 return self.defaults
259
260
261 class PodmanVolumeDiff:
262 def __init__(self, module, info, podman_version):
263 self.module = module
264 self.version = podman_version
265 self.default_dict = None
266 self.info = lower_keys(info)
267 self.params = self.defaultize()
268 self.diff = {"before": {}, "after": {}}
269 self.non_idempotent = {}
270
271 def defaultize(self):
272 params_with_defaults = {}
273 self.default_dict = PodmanVolumeDefaults(self.module, self.version).default_dict()
274 for p in self.module.params:
275 if self.module.params[p] is None and p in self.default_dict:
276 params_with_defaults[p] = self.default_dict[p]
277 else:
278 params_with_defaults[p] = self.module.params[p]
279 return params_with_defaults
280
281 def _diff_update_and_compare(self, param_name, before, after):
282 if before != after:
283 self.diff["before"].update({param_name: before})
284 self.diff["after"].update({param_name: after})
285 return True
286 return False
287
288 def diffparam_label(self):
289 before = self.info["labels"] if "labels" in self.info else {}
290 after = self.params["label"]
291 return self._diff_update_and_compare("label", before, after)
292
293 def diffparam_driver(self):
294 before = self.info["driver"]
295 after = self.params["driver"]
296 return self._diff_update_and_compare("driver", before, after)
297
298 def diffparam_options(self):
299 before = self.info["options"] if "options" in self.info else {}
300 # Removing GID and UID from options list
301 before.pop("uid", None)
302 before.pop("gid", None)
303 # Collecting all other options in the list
304 before = ["=".join((k, v)) for k, v in before.items()]
305 after = self.params["options"]
306 # # For UID, GID
307 # if 'uid' in self.info or 'gid' in self.info:
308 # ids = []
309 # if 'uid' in self.info and self.info['uid']:
310 # before = [i for i in before if 'uid' not in i]
311 # before += ['uid=%s' % str(self.info['uid'])]
312 # if 'gid' in self.info and self.info['gid']:
313 # before = [i for i in before if 'gid' not in i]
314 # before += ['gid=%s' % str(self.info['gid'])]
315 # if self.params['options']:
316 # for opt in self.params['options']:
317 # if 'uid=' in opt or 'gid=' in opt:
318 # ids += opt.split("o=")[1].split(",")
319 # after = [i for i in after if 'gid' not in i and 'uid' not in i]
320 # after += ids
321 before, after = sorted(list(set(before))), sorted(list(set(after)))
322 return self._diff_update_and_compare("options", before, after)
323
324 def is_different(self):
325 diff_func_list = [func for func in dir(self) if callable(getattr(self, func)) and func.startswith("diffparam")]
326 fail_fast = not bool(self.module._diff)
327 different = False
328 for func_name in diff_func_list:
329 dff_func = getattr(self, func_name)
330 if dff_func():
331 if fail_fast:
332 return True
333 else:
334 different = True
335 # Check non idempotent parameters
336 for p in self.non_idempotent:
337 if self.module.params[p] is not None and self.module.params[p] not in [
338 {},
339 [],
340 "",
341 ]:
342 different = True
343 return different
344
345
346 class PodmanVolume:
347 """Perform volume tasks.
348
349 Manages podman volume, inspects it and checks its current state
350 """
351
352 def __init__(self, module, name):
353 """Initialize PodmanVolume class.
354
355 Arguments:
356 module {obj} -- ansible module object
357 name {str} -- name of volume
358 """
359
360 super(PodmanVolume, self).__init__()
361 self.module = module
362 self.name = name
363 self.stdout, self.stderr = "", ""
364 self.mount_point = None
365 self.info = self.get_info()
366 self.version = self._get_podman_version()
367 self.diff = {}
368 self.actions = []
369
370 @property
371 def exists(self):
372 """Check if volume exists."""
373 return bool(self.info != {})
374
375 @property
376 def different(self):
377 """Check if volume is different."""
378 diffcheck = PodmanVolumeDiff(self.module, self.info, self.version)
379 is_different = diffcheck.is_different()
380 diffs = diffcheck.diff
381 if self.module._diff and is_different and diffs["before"] and diffs["after"]:
382 self.diff["before"] = "\n".join(["%s - %s" % (k, v) for k, v in sorted(diffs["before"].items())]) + "\n"
383 self.diff["after"] = "\n".join(["%s - %s" % (k, v) for k, v in sorted(diffs["after"].items())]) + "\n"
384 return is_different
385
386 def get_info(self):
387 """Inspect volume and gather info about it."""
388 # pylint: disable=unused-variable
389 rc, out, err = self.module.run_command([self.module.params["executable"], b"volume", b"inspect", self.name])
390 if rc == 0:
391 data = json.loads(out)
392 if data:
393 data = data[0]
394 if data.get("Name") == self.name:
395 return data
396 return {}
397
398 def _get_podman_version(self):
399 # pylint: disable=unused-variable
400 rc, out, err = self.module.run_command([self.module.params["executable"], b"--version"])
401 if rc != 0 or not out or "version" not in out:
402 self.module.fail_json(msg="%s run failed!" % self.module.params["executable"])
403 return out.split("version")[1].strip()
404
405 def _perform_action(self, action):
406 """Perform action with volume.
407
408 Arguments:
409 action {str} -- action to perform - create, delete, mount, unmout
410 """
411 b_command = PodmanVolumeModuleParams(
412 action,
413 self.module.params,
414 self.version,
415 self.module,
416 ).construct_command_from_params()
417 full_cmd = " ".join([self.module.params["executable"], "volume"] + [to_native(i) for i in b_command])
418 # check if running not from root
419 if os.getuid() != 0 and action == "mount":
420 full_cmd = f"{self.module.params['executable']} unshare {full_cmd}"
421 self.module.log("PODMAN-VOLUME-DEBUG: %s" % full_cmd)
422 self.actions.append(full_cmd)
423 if not self.module.check_mode:
424 rc, out, err = self.module.run_command(full_cmd, expand_user_and_vars=False)
425 self.stdout = out
426 self.stderr = err
427 if rc != 0:
428 self.module.fail_json(
429 msg="Can't %s volume %s" % (action, self.name),
430 stdout=out,
431 stderr=err,
432 )
433 # in case of mount/unmount, return path to the volume from stdout
434 if action in ["mount"]:
435 self.mount_point = out.strip()
436
437 def delete(self):
438 """Delete the volume."""
439 self._perform_action("delete")
440
441 def create(self):
442 """Create the volume."""
443 self._perform_action("create")
444
445 def mount(self):
446 """Delete the volume."""
447 self._perform_action("mount")
448
449 def unmount(self):
450 """Create the volume."""
451 self._perform_action("unmount")
452
453 def recreate(self):
454 """Recreate the volume."""
455 self.delete()
456 self.create()
457
458
459 class PodmanVolumeManager:
460 """Module manager class.
461
462 Defines according to parameters what actions should be applied to volume
463 """
464
465 def __init__(self, module):
466 """Initialize PodmanManager class.
467
468 Arguments:
469 module {obj} -- ansible module object
470 """
471
472 super(PodmanVolumeManager, self).__init__()
473
474 self.module = module
475 self.results = {
476 "changed": False,
477 "actions": [],
478 "volume": {},
479 }
480 self.name = self.module.params["name"]
481 self.executable = self.module.get_bin_path(self.module.params["executable"], required=True)
482 self.state = self.module.params["state"]
483 self.recreate = self.module.params["recreate"]
484 self.volume = PodmanVolume(self.module, self.name)
485
486 def update_volume_result(self, changed=True):
487 """Inspect the current volume, update results with last info, exit.
488
489 Keyword Arguments:
490 changed {bool} -- whether any action was performed
491 (default: {True})
492 """
493 facts = self.volume.get_info() if changed else self.volume.info
494 out, err = self.volume.stdout, self.volume.stderr
495 self.results.update(
496 {
497 "changed": changed,
498 "volume": facts,
499 "podman_actions": self.volume.actions,
500 },
501 stdout=out,
502 stderr=err,
503 )
504 if self.volume.diff:
505 self.results.update({"diff": self.volume.diff})
506 if self.module.params["debug"]:
507 self.results.update({"podman_version": self.volume.version})
508 self.module.exit_json(**self.results)
509
510 def execute(self):
511 """Execute the desired action according to map of actions & states."""
512 states_map = {
513 "present": self.make_present,
514 "absent": self.make_absent,
515 "mounted": self.make_mount,
516 "unmounted": self.make_unmount,
517 "quadlet": self.make_quadlet,
518 }
519 process_action = states_map[self.state]
520 process_action()
521 self.module.fail_json(msg="Unexpected logic error happened, " "please contact maintainers ASAP!")
522
523 def make_present(self):
524 """Run actions if desired state is 'started'."""
525 if not self.volume.exists:
526 self.volume.create()
527 self.results["actions"].append("created %s" % self.volume.name)
528 self.update_volume_result()
529 elif self.recreate or self.volume.different:
530 self.volume.recreate()
531 self.results["actions"].append("recreated %s" % self.volume.name)
532 self.update_volume_result()
533 else:
534 self.update_volume_result(changed=False)
535
536 def make_absent(self):
537 """Run actions if desired state is 'absent'."""
538 if not self.volume.exists:
539 self.results.update({"changed": False})
540 elif self.volume.exists:
541 self.volume.delete()
542 self.results["actions"].append("deleted %s" % self.volume.name)
543 self.results.update({"changed": True})
544 self.results.update({"volume": {}, "podman_actions": self.volume.actions})
545 self.module.exit_json(**self.results)
546
547 def make_mount(self):
548 """Run actions if desired state is 'mounted'."""
549 if not self.volume.exists:
550 self.volume.create()
551 self.results["actions"].append("created %s" % self.volume.name)
552 self.volume.mount()
553 self.results["actions"].append("mounted %s" % self.volume.name)
554 if self.volume.mount_point:
555 self.results.update({"mount_point": self.volume.mount_point})
556 self.update_volume_result()
557
558 def make_unmount(self):
559 """Run actions if desired state is 'unmounted'."""
560 if self.volume.exists:
561 self.volume.unmount()
562 self.results["actions"].append("unmounted %s" % self.volume.name)
563 self.update_volume_result()
564 else:
565 self.module.fail_json(msg="Volume %s does not exist!" % self.name)
566
567 def make_quadlet(self):
568 results_update = create_quadlet_state(self.module, "volume")
569 self.results.update(results_update)
570 self.module.exit_json(**self.results)
571
572
573 def main():
574 module = AnsibleModule(
575 argument_spec=dict(
576 state=dict(
577 type="str",
578 default="present",
579 choices=["present", "absent", "mounted", "unmounted", "quadlet"],
580 ),
581 name=dict(type="str", required=True),
582 label=dict(type="dict", required=False),
583 driver=dict(type="str", required=False),
584 options=dict(type="list", elements="str", required=False),
585 recreate=dict(type="bool", default=False),
586 executable=dict(type="str", required=False, default="podman"),
587 debug=dict(type="bool", default=False),
588 quadlet_dir=dict(type="path", required=False),
589 quadlet_filename=dict(type="str", required=False),
590 quadlet_file_mode=dict(type="raw", required=False),
591 quadlet_options=dict(type="list", elements="str", required=False),
592 )
593 )
594
595 PodmanVolumeManager(module).execute()
596
597
598 if __name__ == "__main__":
599 main()