From 5bb0395e9e9da7417a6d76c838ce14b0d3f4677b Mon Sep 17 00:00:00 2001 From: Sergey <6213510+sshnaidm@users.noreply.github.com> Date: Sun, 3 Aug 2025 14:22:57 +0300 Subject: [PATCH] Improve docs and guides (#958) Signed-off-by: Sagi Shnaidman --- CONTRIBUTING.md | 197 ++++++++++++++++++++++++++++++++++++++ README.md | 204 ++++++++++++++++++++-------------------- contrib/ansible-lint.sh | 2 +- contrib/ansible-unit.sh | 11 +++ 4 files changed, 313 insertions(+), 101 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100755 contrib/ansible-unit.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a292001 --- /dev/null +++ b/CONTRIBUTING.md @@ -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! diff --git a/README.md b/README.md index e5f4c05..90ca825 100644 --- a/README.md +++ b/README.md @@ -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) - + # 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.** + +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. + +--- + +### **Table of Contents** + +- [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) + +--- + +## Key Features + +- **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. + +## 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 +``` + +Then, install it with: + +```bash +ansible-galaxy collection install -r requirements.yml +``` + +## Getting Started: A Simple Example + +Here is a quick example of how to ensure a Redis container is running using the `podman_container` module. + +```yaml +--- +- name: Deploy a Redis container with Podman + hosts: localhost + connection: local + + tasks: + - name: Ensure the Redis container is running + containers.podman.podman_container: + name: my-redis-cache + image: redis:alpine + state: started + ports: + - "6379:6379" + restart_policy: "always" +``` + +## Available Content + +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 -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. - -## Installation and Usage - -### Installing the Collection from Ansible Galaxy - -Before using the Podman collection, you need to install the collection with the `ansible-galaxy` CLI: - -`ansible-galaxy collection install containers.podman` - -You can also include it in a `requirements.yml` file and install it via -`ansible-galaxy collection install -r requirements.yml` using the format: - -```yaml -collections: -- name: containers.podman -``` - -or clone by your own: - -```bash -mkdir -p ~/.ansible/collections/ansible_collections/containers -git clone https://github.com/containers/ansible-podman-collections.git ~/.ansible/collections/ansible_collections/containers/podman -``` - -### Playbooks - -To use a module from Podman collection, please reference the full namespace, collection name, -and modules name that you want to use: - -```yaml ---- -- name: Using Podman collection - hosts: localhost - tasks: - - name: Run redis container - containers.podman.podman_container: - name: myredis - image: redis - command: redis-server --appendonly yes - state: present - recreate: true - expose: - - 6379 - volumes_from: - - mydata -``` - -Or you can add full namespace and collection name in the `collections` element: - -```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 -``` +- **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). diff --git a/contrib/ansible-lint.sh b/contrib/ansible-lint.sh index 88ed7ac..b65c051 100755 --- a/contrib/ansible-lint.sh +++ b/contrib/ansible-lint.sh @@ -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 diff --git a/contrib/ansible-unit.sh b/contrib/ansible-unit.sh new file mode 100755 index 0000000..ccff2ac --- /dev/null +++ b/contrib/ansible-unit.sh @@ -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