ansible/ansible-podman-collections
1
0
Fork 0
mirror of https://github.com/containers/ansible-podman-collections.git synced 2026-02-03 23:01:48 +00:00
Code Activity

Improve docs and guides (#958)

Browse source 
Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>
This commit is contained in:
Sergey 2025-08-03 14:22:57 +03:00 • committed by GitHub
parent 91d991f95b
commit 5bb0395e9e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 313 additions and 101 deletions
Download patch file Download diff file Expand all files Collapse all files

197
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,197 @@
# Contributing to the Podman Ansible Collection
First off, thank you for considering contributing to this collection! We welcome any help, from reporting a bug to submitting a new feature. Every contribution is valuable.
This document provides guidelines to help you get started. Please read it carefully to ensure a smooth and effective contribution process.
## Code of Conduct
All contributors are expected to follow our [Code of Conduct](CODE-OF-CONDUCT.md). Please make sure you are familiar with its contents.
## How to Contribute
You can contribute in several ways:
* **Reporting Bugs:** If you find a bug, please [open an issue](https://github.com/containers/ansible-podman-collections/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml) and provide as much detail as possible, including your Podman version, Ansible version, the playbook you are using, and the full error output.
* **Suggesting Enhancements:** If you have an idea for a new feature or an improvement to an existing one, please [open a feature request](https://github.com/containers/ansible-podman-collections/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml).
* **Submitting Pull Requests:** If you want to fix a bug or add a feature yourself, please follow the guidelines below.
## Development Setup
1. **Fork and Clone:** Fork the repository on GitHub and clone your fork locally.
```bash
git clone https://github.com/YOUR-USERNAME/ansible-podman-collections.git
cd ansible-podman-collections
```
2. **Set up a Virtual Environment:** It's highly recommended to work in a Python virtual environment.
```bash
python3 -m venv venv
source venv/bin/activate
```
3. **Install Dependencies:** The collection's testing dependencies are listed in `test-requirements.txt`.
```bash
pip install -r test-requirements.txt
```
## Guidelines for Pull Requests
### General Workflow
1. Create a new branch for your changes: `git checkout -b my-feature-or-fix`.
2. Make your changes. Follow the coding and testing guidelines below.
3. Commit your changes with a clear and descriptive message. See existing commit messages for style (`git log --oneline`).
4. Push your branch to your fork: `git push origin my-feature-or-fix`.
5. Open a pull request against the `main` branch of the original repository.
### Fixing a Bug
1. If an issue for the bug doesn't already exist, please create one.
2. Ideally, add an integration test case to `tests/integration/targets/` that reproduces the bug and fails before your fix.
3. Implement the code change that fixes the bug.
4. Run the tests to ensure your fix works and doesn't break anything else.
5. In your PR description, use the "Fixes #123" syntax to link it to the issue.
### Adding a New Module
We have a script to help you scaffold a new module.
1. **Define Module Variables:** Copy `contrib/my_module_template_vars.yaml` and customize it with your new module's details (name, author, options, etc.).
2. **Generate the Module:** Run the `contrib/generate_module.sh` script. This will create a new module file in the `contrib` directory.
3. **Place the Module:** Move the generated file into `plugins/modules/`.
4. **Add Logic:** Implement the core logic for your module. If you need to share code with other modules, consider adding it to `plugins/module_utils/`.
5. **Document:** Ensure the `DOCUMENTATION`, `EXAMPLES`, and `RETURN` sections are thorough and accurate. This is critical for users.
6. **Add Tests:** Create a new integration test role and a new CI workflow for your module (see below).
## Testing Strategy
This collection uses three types of tests. All tests must pass before a PR can be merged.
### 1. Sanity Tests
These tests check for code style, syntax errors, and other common issues. Sanity tests must pass in pull requests in opder to merge.
* **How to Run:**
```bash
bash contrib/ansible-lint.sh
```
* **Guidelines:**
* This will install collection in `/tmp` directory and run `ansible-test` sanity in docker.
* The maximum line length is 120 characters.
### 2. Unit Tests
Unit tests are for testing specific functions in isolation, often by mocking external dependencies. This is an area we are actively working to improve.
* **Location:** `tests/unit/plugins/modules/`
* **How to Run:**
```bash
bash contrib/ansible-unit.sh
```
* **Guidelines:**
* This will install collection in `/tmp` directory and run `ansible-test` unit tests.
### 3. Integration Tests
These are the most important tests in the collection. They run Ansible playbooks to test modules against a live Podman instance.
* **Location:** `tests/integration/targets/`
* **Structure:** Each subdirectory in `targets` is an Ansible role that tests a specific module or feature. The main logic is in `tasks/main.yml`.
* **Adding a New Integration Test:**
1. Create a new directory (role) for your module: `tests/integration/targets/my_new_module/tasks`.
2. Create a `main.yml` file inside that directory.
3. Write Ansible tasks that execute your module and verify its behavior. Use the `assert` or `fail` modules to check for expected outcomes.
```yaml
- name: Run my_new_module
my_new_module:
name: test_container
state: present
register: result
- name: Assert that the container was created
assert:
that:
- result.changed
- result.container.State.Status == "running"
```
* **Running Locally:** You can run a specific test role using `ansible-playbook`. This requires a working Podman installation.
* Create a testing playbook with your tests like:
```yaml
- hosts: all
gather_facts: false
tasks:
- include_tasks: tests/integration/targets/my_new_module/tasks/main.yml
```
Install the collection version you develop with:
```bash
ansible-galaxy collection install -vvv --force .
```
and then run the playbook it with:
```bash
ansible-playbook -vv -i localhost, my_playbook.yml
```
## Continuous Integration (CI)
We use GitHub Actions to run all our tests automatically.
### Adding a CI Job for a New Module
To ensure your new module is tested on every PR, you must add a new workflow file. We use a reusable workflow to make this easy.
1. Go to the `.github/workflows/` directory.
2. Create a new file named after your module, e.g., `podman_my_new_module.yml`.
3. Copy the content from an existing module workflow, like `podman_export.yml`, and adapt it. You only need to change a few lines:
```yaml
name: Podman my_new_module
on:
push:
paths:
- 'plugins/modules/podman_my_new_module.py'
- 'tests/integration/targets/podman_my_new_module/**'
pull_request:
paths:
- 'plugins/modules/podman_my_new_module.py'
- 'tests/integration/targets/podman_my_new_module/**'
jobs:
test:
uses: ./.github/workflows/reusable-module-test.yml
with:
module_name: podman_my_new_module # The name of your test role
display_name: "Podman my_new_module" # A friendly name for the job
```
4. Commit this new workflow file along with your module and test code.
## Final Checklist for Pull Requests
Before you submit your PR, please make sure you have:
* [ ] Read this `CONTRIBUTING.md` guide.
* [ ] Added or updated tests for your changes.
* [ ] Run `ansible-test sanity` and fixed any issues.
* [ ] Ensured all CI checks are passing on your PR.
* [ ] Updated the `DOCUMENTATION` block in the module if you changed any parameters.
Thank you for your contribution!

154
README.md
View file

@ -1,113 +1,117 @@
[![GitHub Actions CI/CD build status — Collection test suite](https://github.com/containers/ansible-podman-collections/workflows/Collection%20build%20and%20tests/badge.svg?branch=main)](https://github.com/containers/ansible-podman-collections/actions?query=workflow%3A%22Collection%20build%20and%20tests)
<!-- omit in toc -->
# Ansible Collection: containers.podman
This repo hosts the `containers.podman` Ansible Collection.
[![CI/CD Status](https://img.shields.io/github/actions/workflow/status/containers/ansible-podman-collections/.github/workflows/collection-continuous-integration.yml?branch=main&style=for-the-badge&label=CI%2FCD)](https://github.com/containers/ansible-podman-collections/actions/workflows/collection-continuous-integration.yml)
[![Ansible Galaxy](https://img.shields.io/ansible/collection/d/containers/podman?style=for-the-badge&label=Ansible%20Galaxy)](https://galaxy.ansible.com/containers/podman)
[![License](https://img.shields.io/github/license/containers/ansible-podman-collections?style=for-the-badge)](COPYING)
The collection includes the Podman container plugins to help the build and management of Podman containers.
**Manage the full lifecycle of Podman containers, images, pods, networks, and volumes with Ansible.**
## Documentation
This collection provides a suite of powerful and flexible Ansible modules to automate the management of your [Podman](https://podman.io/) environment. Whether you are running a single container or orchestrating complex, multi-container applications, these modules give you the tools to do it idempotently and efficiently.
For collection versions that are parts of Ansible releases, the documentation can be found on
Ansible docs site: https://docs.ansible.com/ansible/latest/collections/containers/podman
---
The latest documentation for current collection version in the repository is hosted on github.io docs
site: https://containers.github.io/ansible-podman-collections.
### **Table of Contents**
## Installation and Usage
- [Key Features](#key-features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Getting Started: A Simple Example](#getting-started-a-simple-example)
- [Available Content](#available-content)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
### Installing the Collection from Ansible Galaxy
---
Before using the Podman collection, you need to install the collection with the `ansible-galaxy` CLI:
## Key Features
`ansible-galaxy collection install containers.podman`
- **Comprehensive Management:** Control every aspect of Podman, including containers, images, pods, networks, volumes, and secrets.
- **Idempotent Operations:** All modules are designed to be idempotent, ensuring predictable and consistent state for your resources.
- **Flexible and Powerful:** Exposes a wide range of Podman options, from simple container creation to advanced features like systemd integration and Quadlet file generation.
- **Connection Plugin:** Includes a `podman` connection plugin to execute Ansible tasks directly inside containers.
You can also include it in a `requirements.yml` file and install it via
`ansible-galaxy collection install -r requirements.yml` using the format:
## Requirements
- **Ansible:** `ansible-core >= 2.12`
- **Python:** `python >= 3.9`
- **Podman:** A working installation of Podman on the target machine.
## Installation
Install the collection from Ansible Galaxy using the `ansible-galaxy` CLI:
```bash
ansible-galaxy collection install containers.podman
```
You can also include it in a `requirements.yml` file, which is useful for managing project dependencies:
```yaml
# requirements.yml
collections:
- name: containers.podman
```
or clone by your own:
Then, install it with:
```bash
mkdir -p ~/.ansible/collections/ansible_collections/containers
git clone https://github.com/containers/ansible-podman-collections.git ~/.ansible/collections/ansible_collections/containers/podman
ansible-galaxy collection install -r requirements.yml
```
### Playbooks
## Getting Started: A Simple Example
To use a module from Podman collection, please reference the full namespace, collection name,
and modules name that you want to use:
Here is a quick example of how to ensure a Redis container is running using the `podman_container` module.
```yaml
---
- name: Using Podman collection
- name: Deploy a Redis container with Podman
hosts: localhost
connection: local
tasks:
- name: Run redis container
- name: Ensure the Redis container is running
containers.podman.podman_container:
name: myredis
image: redis
command: redis-server --appendonly yes
state: present
recreate: true
expose:
- 6379
volumes_from:
- mydata
name: my-redis-cache
image: redis:alpine
state: started
ports:
- "6379:6379"
restart_policy: "always"
```
Or you can add full namespace and collection name in the `collections` element:
## Available Content
```yaml
---
- name: Using Podman collection
hosts: localhost
collections:
- containers.podman
tasks:
- name: Build and push an image using existing credentials
podman_image:
name: nginx
path: /path/to/build/dir
push: true
push_args:
dest: quay.io/acme
```
This collection includes:
- **Modules:**
- `podman_container`: Manage Podman containers.
- `podman_image`: Build, pull, and manage Podman images.
- `podman_pod`: Create and manage Podman pods.
- `podman_network`: Manage Podman networks.
- `podman_volume`: Manage Podman volumes.
- `podman_secret`: Manage Podman secrets.
- `podman_login`/`podman_logout`: Authenticate with container registries.
- ...and many more!
- **Connection Plugins:**
- `podman`: Execute Ansible tasks directly within a container.
- `buildah`: Execute Ansible tasks directly within a buildah container.
- **Become Plugins:**
- `podman_unshare`: Execute tasks within a `podman unshare` environment.
## Documentation
- **Official Ansible Docs:** For stable, released versions of the collection, see the documentation on the [official Ansible documentation site](https://docs.ansible.com/ansible/latest/collections/containers/podman/index.html).
- **Latest Development Version:** For the most up-to-date documentation based on the `main` branch of this repository, visit our [GitHub Pages site](https://containers.github.io/ansible-podman-collections/).
## Contributing
We are accepting Github pull requests and issues.
There are many ways in which you can participate in the project, for example:
We welcome contributions from the community! Whether you want to fix a bug, add a new feature, or improve our documentation, your help is valuable.
- Submit bugs and feature requests, and help us verify them
- Submit and review source code changes in Github pull requests
- Add new modules for Podman containers and images
## Testing and Development
If you want to develop new content for this collection or improve what is already
here, the easiest way to work on the collection is to clone it into one of the configured
[`COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths),
and work on it there.
### Testing with `ansible-test`
We use `ansible-test` for sanity.
## More Information
TBD
## Communication
Please submit Github issues for communication any issues.
You can ask Podman related questions on `#podman` channel of Ansible Podman questions
on `#ansible-podman` channel on Freenode IRC.
Please read our **[Contributing Guide](CONTRIBUTING.md)** to learn how to get started with development, testing, and submitting pull requests.
## License
GPL-3.0-or-later
This collection is licensed under the [GNU General Public License v3.0 or later](COPYING).

2
contrib/ansible-lint.sh
View file

@ -6,6 +6,6 @@ ansible-galaxy collection build --output-path /tmp/ansible-lint-collection --for
pushd /tmp/ansible-lint-collection/
ansible-galaxy collection install -vvv --force $(ls /tmp/ansible-lint-collection/) -p /tmp/ansible-lint-installs
pushd /tmp/ansible-lint-installs/ansible_collections/containers/podman
ansible-test sanity --docker --color --truncate 0 --no-redact --no-pip-check --python 3.9 -v plugins/ tests/
ansible-test sanity --docker --color --truncate 0 --no-redact --python 3.12 -v plugins/ tests/
popd
popd

11
contrib/ansible-unit.sh Executable file
View file

@ -0,0 +1,11 @@
#!/bin/bash
mkdir -p /tmp/ansible-lint-installs
mkdir -p /tmp/ansible-lint-collection
rm -rf /tmp/ansible-lint-collection/*
ansible-galaxy collection build --output-path /tmp/ansible-lint-collection --force
pushd /tmp/ansible-lint-collection/
ansible-galaxy collection install -vvv --force $(ls /tmp/ansible-lint-collection/) -p /tmp/ansible-lint-installs
pushd /tmp/ansible-lint-installs/ansible_collections/containers/podman
ansible-test units --python 3.12 -vvv
popd
popd