Debian Codegraph @

ansible_collections/containers/podman/CLAUDE.md

raw
1 # CLAUDE.md
2
3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5 ## Repository Overview
6
7 This is the `containers.podman` Ansible Collection — modules, plugins, and connection plugins for managing Podman containers. Published on [Ansible Galaxy](https://galaxy.ansible.com/containers/podman) from <https://github.com/containers/ansible-podman-collections>.
8
9 **The collection is currently in maintenance mode** — mostly accepting bugfixes and security patches. New features might not be merged.
10
11 **Requirements:** `ansible-core >= 2.12`, `python >= 3.9`, and a working Podman installation on the target.
12
13 ## Git Commits
14
15 All commits in this repository require a **Signed-off-by** line (DCO). Always use `git commit -s` when committing.
16
17 ## Development Commands
18
19 ### Testing
20
21 - **Run specific module integration tests**: `TEST2RUN=<module_name> ./ci/run_containers_tests.sh`
22 - Example: `TEST2RUN=podman_container ./ci/run_containers_tests.sh`
23 - Available tests correspond to playbooks in `ci/playbooks/containers/`
24 - Runs with `-vv` first, retries with `-vvvvv` on failure for debugging
25
26 - **Run connection tests**: `./ci/run_connection_test.sh [podman|buildah]`
27 - Use `ROOT=1` for root-privileged testing
28
29 - **Run sanity checks**: `bash contrib/ansible-lint.sh`
30 - Builds collection to `/tmp`, installs it, runs `ansible-test sanity` in Docker
31 - Max line length: 120 characters
32
33 - **Run unit tests**: `bash contrib/ansible-unit.sh`
34 - Builds collection to `/tmp`, runs `ansible-test unit`
35 - Can also run directly: `python -m pytest tests/unit/plugins/modules/`
36
37 - **Debug module execution**:
38 - Check `podman_actions` in results to see actual podman commands executed
39 - Use `check_mode: true` for dry-run testing without making changes
40
41 ### Building and Packaging
42
43 - **Build collection**: `ansible-galaxy collection build`
44 - **Build RPM**: `make rpm`
45 - **Set version**: `sed -i 's/^version: .*/version: <version>/' galaxy.yml`
46 - **Publish to Galaxy**: `bash contrib/publish.sh <version>` (use `DRYRUN=1` for testing)
47
48 ## Code Architecture
49
50 ### Module Pattern
51
52 All modules in `plugins/modules/` follow the pattern `podman_<resource>.py` (mutating) and `podman_<resource>_info.py` (read-only).
53
54 Every module file must contain three docstring constants at the top: `DOCUMENTATION` (YAML-formatted module docs with options, author, description), `RETURN` (return value documentation), and `EXAMPLES` (usage examples using full `containers.podman.<module>` namespace). These are required by `ansible-test sanity`.
55
56 Standard module structure:
57
58 1. `DOCUMENTATION`, `RETURN`, `EXAMPLES` docstring constants
59 2. Imports after docstrings (use `# noqa: E402` on post-docstring imports)
60 3. `main()` function creating `AnsibleModule` with `argument_spec`, `supports_check_mode=True`
61 4. Get executable path: `module.get_bin_path(module.params["executable"], required=True)`
62 5. Every module has an `executable` parameter (default: `"podman"`) for custom podman paths
63 6. Return results with `changed`, and typically `stdout`, `stderr`, or resource-specific data
64
65 ### Module Utilities (`plugins/module_utils/podman/`)
66
67 - **`common.py`** — Core shared functions: `run_podman_command()`, `get_podman_version()`, `diff_generic()`, `createcommand()`, `generate_systemd()`, `lower_keys()`, `ARGUMENTS_OPTS_DICT` (long/short CLI arg mapping)
68 - **`podman_container_lib.py`** — The most complex module utility; see "Convention-Based Method Dispatch" below
69 - **`podman_pod_lib.py`** — Similar pattern to container lib for pod management
70 - **`podman_image_lib.py`** — `ImageRepository` (image name/tag/digest parsing and URL formation), `PodmanImageManager`, `PodmanImagePuller`, `PodmanImagePusher`
71 - **`quadlet.py`** — Systemd Quadlet integration for container/network/volume unit files
72
73 ### Convention-Based Method Dispatch (Key Pattern)
74
75 The container and pod libraries use a **naming-convention-based dispatch** pattern that is critical to understand when adding or modifying parameters:
76
77 **`PodmanModuleParams`** — Converts module parameters to CLI arguments. For each parameter `foo`, define a method `addparam_foo(self, c)` that appends CLI flags to the command list `c` and returns it. The `construct_command_from_params()` method auto-discovers all `addparam_*` methods via reflection.
78
79 **`PodmanContainerDiff`** — Checks if a running container differs from desired state. For each parameter `foo`, define a method `diffparam_foo(self)` that compares the current container's state against the desired value. Returns `True` if different. The `is_different()` method auto-discovers all `diffparam_*` methods via reflection.
80
81 **Adding a new parameter to an existing module requires three changes:**
82
83 1. Add to `ARGUMENTS_SPEC_CONTAINER` (or equivalent) dict — defines the Ansible parameter type
84 2. Add `addparam_<name>` method to `PodmanModuleParams` — maps parameter to podman CLI flag
85 3. Add `diffparam_<name>` method to `PodmanContainerDiff` — implements idempotency check
86
87 For simple parameters, `diffparam_*` can delegate to `self._diff_generic("module_arg", "--cli-arg")` which uses `createcommand()` to extract the current value from podman inspect's `CreateCommand` output.
88
89 ### Import Conventions
90
91 - Module files use **relative imports** for module_utils: `from ..module_utils.podman.common import run_podman_command`
92 - Module utility files (`plugins/module_utils/`) use **absolute imports** with full collection namespace: `from ansible_collections.containers.podman.plugins.module_utils.podman.common import lower_keys`
93 - All imports after the `DOCUMENTATION`/`RETURN`/`EXAMPLES` blocks need `# noqa: E402`
94
95 ### Connection Plugins (`plugins/connection/`)
96
97 - `podman.py` — Execute commands inside Podman containers
98 - `buildah.py` — Execute commands inside Buildah containers
99
100 ### Become Plugin (`plugins/become/`)
101
102 - `podman_unshare.py` — Execute commands in container user namespace via `podman unshare` (for accessing files with UIDs mapped in rootless containers)
103
104 ### Testing Architecture
105
106 - **Integration tests**: `tests/integration/targets/<module_name>/tasks/main.yml` — the primary test mechanism. Specific issue regression tests use `tasks/test_issue_<number>.yml` included from `main.yml`
107 - **Unit tests**: `tests/unit/plugins/modules/` — limited coverage, most testing is via integration tests
108 - **CI playbooks**: `ci/playbooks/containers/<module_name>.yml` — wrapper playbooks that include integration test tasks
109
110 ### Build System
111
112 - `galaxy.yml` — collection metadata including version
113 - `Makefile` — RPM packaging target
114
115 ## Adding CI for a New Module
116
117 When creating a new module, you need to set up four things for CI:
118
119 ### 1. Integration test role
120
121 Create `tests/integration/targets/<module_name>/tasks/main.yml` with test tasks using `assert` to verify behavior. Organize regression tests as separate files (`test_issue_<number>.yml`) included from `main.yml`.
122
123 ### 2. CI playbook
124
125 Create `ci/playbooks/containers/<module_name>.yml`:
126
127 ```yaml
128 ---
129 - hosts: all
130 gather_facts: true
131 tasks:
132 - include_role:
133 name: <module_name>
134 vars:
135 ansible_python_interpreter: "{{ _ansible_python_interpreter }}"
136 ```
137
138 ### 3. GitHub Actions workflow
139
140 Create `.github/workflows/<module_name>.yml` using the reusable template:
141
142 ```yaml
143 name: Podman <module_name>
144
145 on:
146 push:
147 paths:
148 - ".github/workflows/<module_name>.yml"
149 - ".github/workflows/reusable-module-test.yml"
150 - ci/playbooks/*.yml
151 - "ci/run_containers_tests.sh"
152 - "ci/playbooks/containers/<module_name>.yml"
153 - "plugins/modules/<module_name>.py"
154 - "tests/integration/targets/<module_name>/**"
155 branches:
156 - main
157 pull_request:
158 paths:
159 - ".github/workflows/<module_name>.yml"
160 - ".github/workflows/reusable-module-test.yml"
161 - ci/playbooks/*.yml
162 - "ci/run_containers_tests.sh"
163 - "ci/playbooks/containers/<module_name>.yml"
164 - "plugins/modules/<module_name>.py"
165 - "tests/integration/targets/<module_name>/**"
166 schedule:
167 - cron: 7 0 * * *
168
169 jobs:
170 test:
171 uses: ./.github/workflows/reusable-module-test.yml
172 with:
173 module_name: "<module_name>"
174 display_name: "Podman <module_name>"
175 ```
176
177 The reusable template (`.github/workflows/reusable-module-test.yml`) also accepts optional inputs: `python_version`, `os_matrix` (JSON array), `ansible_versions` (JSON array), and `extra_collections` (space-separated list).
178
179 ### 4. Module utilities (if needed)
180
181 If the module has complex state management, add a library in `plugins/module_utils/podman/` following the convention-based dispatch pattern described above.
182
183 ## Release Process
184
185 Full details are in [RELEASING.md](RELEASING.md). Summary:
186
187 1. **Add a release section** in `changelogs/changelog.yaml` describing all user-facing changes since the previous release. Skip maintenance-only changes (CI, test infra, internal refactoring).
188 2. **Set the version**: `sed -i 's/^version: .*/version: X.Y.Z/' galaxy.yml`
189 3. **Generate CHANGELOG**: `antsibull-changelog release` — regenerates `CHANGELOG.rst` from `changelogs/changelog.yaml`.
190 4. **Update docs (major releases only)**: Run `contrib/build_docs.sh` to regenerate HTML docs. If new modules were added, `git add` their generated doc files first. Skip for patch releases.
191 5. **Create a PR** with the changelog, galaxy.yml, and CHANGELOG.rst changes. Merge to `main`.
192 6. **Tag the merge commit**: `git tag X.Y.Z && git push origin X.Y.Z` — this triggers the `collection-publish.yml` workflow which publishes to Galaxy.
193
194 ### Changelog Entry Format
195
196 Each release entry in `changelogs/changelog.yaml` uses categories: `release_summary`, `major_changes`, `minor_changes`, `breaking_changes`, `deprecated_features`, `removed_features`, `security_fixes`, `bugfixes`, `known_issues`. New modules get a `modules:` section; new plugins get a `plugins:` section.
197
198 ## Integration Test Best Practices
199
200 - **Idempotency**: Resources may already exist. Assert like: `result.podman_actions | length == 0 or 'expected' in result.podman_actions[0]`
201 - **Dynamic digests**: Never hardcode SHA256 hashes. Pull a real image, extract digest with `podman_image_info`, use `{{ image_info.images[0].Digest }}`
202 - **Cleanup**: Use `always:` blocks to clean up test images/containers for reliability
203 - **Image URL delimiters**: Pure digests (`sha256:...`) use `@`, tags with digests use `:`