Ansible Collection: containers.podman

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 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
• Requirements
• Installation
• Getting Started: A Simple Example
• Available Content
• Documentation
• Contributing
• 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:

ansible-galaxy collection install containers.podman

You can also include it in a requirements.yml file, which is useful for managing project dependencies:

# requirements.yml
collections:
  - name: containers.podman

Then, install it with:

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.

---
- 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: docker.io/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

• Official Ansible Docs: For stable, released versions of the collection, see the documentation on the official Ansible documentation site.
• Latest Development Version: For the most up-to-date documentation based on the main branch of this repository, visit our GitHub Pages site.
• Connection Plugins Guide: For comprehensive information about using Podman and Buildah connection plugins, including advanced examples and best practices, see our Connection Plugins Documentation.

Contributing

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.

Please read our Contributing Guide to learn how to get started with development, testing, and submitting pull requests.

License

This collection is licensed under the GNU General Public License v3.0 or later.