| 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 `:` |