Debian Codegraph @

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

raw
1 # Copyright (c) 2026 Ansible Project
2 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
3
4 from __future__ import absolute_import, division, print_function
5
6 __metaclass__ = type
7
8
9 DOCUMENTATION = r"""
10 module: podman_quadlet_build
11 author:
12 - Benjamin Vouillaume (@BenjaminVouillaume)
13 short_description: Build images for use by Podman Quadlets
14 notes: []
15 description:
16 - Build images using Quadlet.
17 options:
18 annotation:
19 description:
20 - Dictionary of key=value pairs to add to the image. Only works with OCI images.
21 Ignored for Docker containers.
22 type: dict
23 arch:
24 description:
25 - CPU architecture for the container image
26 type: str
27 authfile:
28 description:
29 - Path to file containing authorization credentials to the remote registry.
30 aliases:
31 - auth_file
32 type: path
33 build_args:
34 description:
35 - Dictionary of key=value pairs to add as build argument.
36 aliases:
37 - buildargs
38 type: dict
39 ca_cert_dir:
40 description:
41 - Path to directory containing TLS certificates and keys to use.
42 type: 'path'
43 cache:
44 description:
45 - Whether or not to use cached layers when building an image
46 type: bool
47 cmd_args:
48 description:
49 - Extra global arguments to pass to the C(podman) command (e.g., C(--log-level=debug)).
50 - These are placed after the executable and before the subcommand.
51 type: list
52 elements: str
53 dns:
54 description:
55 - Set custom DNS servers in the /etc/resolv.conf file that will be shared between
56 all containers in the pod. A special option, "none" is allowed which disables
57 creation of /etc/resolv.conf for the pod.
58 type: list
59 elements: str
60 required: false
61 dns_opt:
62 description:
63 - Set custom DNS options in the /etc/resolv.conf file that will be shared between
64 all containers in the pod.
65 type: list
66 elements: str
67 aliases:
68 - dns_option
69 required: false
70 dns_search:
71 description:
72 - Set custom DNS search domains in the /etc/resolv.conf file that will be shared
73 between all containers in the pod.
74 type: list
75 elements: str
76 required: false
77 env:
78 description:
79 - Dictionary of key=value pairs to add as environment variable.
80 type: dict
81 file:
82 description: Path to the Containerfile if it is not in the build context directory.
83 required: false
84 type: path
85 force_rm:
86 description:
87 - Always remove intermediate containers after a build, even if the build is unsuccessful.
88 type: bool
89 group_add:
90 description:
91 - Add additional groups to run as
92 type: list
93 elements: str
94 aliases:
95 - groups
96 ignore_file:
97 description: Path to an alternate .containerignore file to use when building the image.
98 type: path
99 aliases:
100 - ignorefile
101 name:
102 description:
103 - Name of the image to build. It may contain a tag using the format C(image:tag).
104 required: True
105 type: str
106 labels:
107 description:
108 - Labels to set on the image.
109 type: dict
110 network:
111 description:
112 - List of the names of CNI networks the build should join during the RUN instructions.
113 type: list
114 elements: str
115 aliases:
116 - net
117 - network_mode
118 password:
119 description:
120 - Password to use when authenticating to remote registries.
121 type: str
122 pull:
123 description:
124 - Pull image policy. The default is 'missing'.
125 type: str
126 choices:
127 - 'missing'
128 - 'always'
129 - 'never'
130 - 'newer'
131 retry:
132 description:
133 - Number of times to retry pulling or pushing images between the registry and local storage in case of failure.
134 Default is 3.
135 type: int
136 retry_delay:
137 description:
138 - Duration of delay between retry attempts when pulling or pushing images between the registry and local storage in case of failure.
139 type: str
140 aliases:
141 - retrydelay
142 secret:
143 description:
144 - Pass secret information used in Containerfile build stages in a safe way.
145 Generally has the form C(secret[,opt=opt ...]).
146 Can be specified multiple times.
147 type: list
148 elements: str
149 set_working_directory:
150 description:
151 - Provide context (a working directory) to podman build.
152 type: str
153 aliases:
154 - setworkingdirectory
155 target:
156 description:
157 - Specify the target build stage to build.
158 type: str
159 username:
160 description:
161 - username to use when authenticating to remote registries.
162 type: str
163 validate_certs:
164 description:
165 - Require HTTPS and validate certificates when pulling or pushing.
166 Also used during build if a pull or push is necessary.
167 type: bool
168 aliases:
169 - tlsverify
170 - tls_verify
171 variant:
172 description:
173 - Override the default architecture variant of the container image to be built.
174 type: str
175 volume:
176 description:
177 - Specify multiple volume / mount options to mount one or more mounts to a container.
178 type: list
179 elements: str
180 executable:
181 description:
182 - Path to C(podman) executable if it is not in the C($PATH) on the machine running C(podman).
183 default: 'podman'
184 type: str
185 quadlet_dir:
186 description:
187 - Path to the directory to write quadlet file in.
188 By default, it will be set as C(/etc/containers/systemd/) for root user,
189 C(~/.config/containers/systemd/) for non-root users.
190 type: path
191 required: false
192 quadlet_filename:
193 description:
194 - Name of quadlet file to write. By default it takes image name without prefixes and tags.
195 type: str
196 quadlet_file_mode:
197 description:
198 - The permissions of the quadlet file.
199 - The O(quadlet_file_mode) can be specified as octal numbers or as a symbolic mode
200 (for example, V(u+rwx) or V(u=rw,g=r,o=r)).
201 For octal numbers format, you must either add a leading zero so that Ansible's YAML parser knows it is an
202 octal number (like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
203 and can do its own conversion from string into number. Giving Ansible a number without following one of these
204 rules will end up with a decimal number which will have unexpected results.
205 - If O(quadlet_file_mode) is not specified and the quadlet file B(does not) exist, the default V('0640') mask
206 will be used
207 when setting the mode for the newly created file.
208 - If O(quadlet_file_mode) is not specified and the quadlet file B(does) exist, the mode of the existing file
209 will be used.
210 - Specifying O(quadlet_file_mode) is the best way to ensure files are created with the correct permissions.
211 type: raw
212 required: false
213 quadlet_options:
214 description:
215 - Options for the quadlet file. Provide missing in usual build args
216 options as a list of lines to add.
217 type: list
218 elements: str
219 required: false
220
221 """
222
223 EXAMPLES = r"""
224 - name: Build an image
225 containers.podman.podman_quadlet_build:
226 name: myimage
227 file: /tmp/Containerfile
228
229 - name: Build an image
230 containers.podman.podman_quadlet_build:
231 name: myimage
232 set_working_directory: /tmp/context
233
234 """
235
236 RETURN = r"""
237 changed:
238 description: Whether any change was made
239 returned: always
240 type: bool
241
242 """
243
244 from ansible.module_utils.basic import AnsibleModule
245 from ..module_utils.podman.quadlet import (
246 create_quadlet_state,
247 )
248
249
250 def main():
251 module = AnsibleModule(
252 argument_spec=dict(
253 annotation=dict(type="dict"),
254 arch=dict(type="str"),
255 authfile=dict(type="path", aliases=["auth_file"]),
256 build_args=dict(type="dict", aliases=["buildargs"]),
257 ca_cert_dir=dict(type="path"),
258 cache=dict(type="bool"),
259 cmd_args=dict(type="list", elements="str"),
260 dns=dict(type="list", elements="str", required=False),
261 dns_opt=dict(type="list", elements="str", aliases=["dns_option"], required=False),
262 dns_search=dict(type="list", elements="str", required=False),
263 env=dict(type="dict"),
264 file=dict(type="path", required=False),
265 force_rm=dict(type="bool"),
266 group_add=dict(type="list", elements="str", aliases=["groups"]),
267 ignore_file=dict(type="path", aliases=["ignorefile"]),
268 name=dict(type="str", required=True),
269 labels=dict(type="dict"),
270 network=dict(type="list", elements="str", aliases=["net", "network_mode"]),
271 password=dict(type="str", no_log=True),
272 pull=dict(type="str", choices=["always", "missing", "never", "newer"]),
273 retry=dict(type="int"),
274 retry_delay=dict(type="str", aliases=["retrydelay"]),
275 secret=dict(type="list", elements="str", no_log=False),
276 set_working_directory=dict(type="str", aliases=["setworkingdirectory"]),
277 target=dict(type="str"),
278 username=dict(type="str"),
279 validate_certs=dict(type="bool", aliases=["tlsverify", "tls_verify"]),
280 variant=dict(type="str"),
281 volume=dict(type="list", elements="str"),
282 executable=dict(type="str", default="podman"),
283 quadlet_dir=dict(type="path", required=False),
284 quadlet_filename=dict(type="str"),
285 quadlet_file_mode=dict(type="raw", required=False),
286 quadlet_options=dict(type="list", elements="str", required=False),
287 ),
288 supports_check_mode=True,
289 required_together=(["username", "password"],),
290 mutually_exclusive=(
291 ["authfile", "username"],
292 ["authfile", "password"],
293 ),
294 required_one_of=(["file", "set_working_directory"],),
295 )
296
297 results = create_quadlet_state(module, "build")
298 module.exit_json(**results)
299
300
301 if __name__ == "__main__":
302 main()