Debian Codegraph @

ansible_collections/containers/podman/README.md

raw
1 <!-- omit in toc -->
2 # Ansible Collection: containers.podman
3
4 [![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)
5 [![Ansible Galaxy](https://img.shields.io/ansible/collection/d/containers/podman?style=for-the-badge&label=Ansible%20Galaxy)](https://galaxy.ansible.com/containers/podman)
6 [![License](https://img.shields.io/github/license/containers/ansible-podman-collections?style=for-the-badge)](COPYING)
7
8 > **Note:** This collection is currently in maintenance mode. We are accepting mostly bugfixes and security patches. New features might not be merged.
9
10 **Manage the full lifecycle of Podman containers, images, pods, networks, and volumes with Ansible.**
11
12 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.
13
14 ---
15
16 ### **Table of Contents**
17
18 - [Key Features](#key-features)
19 - [Requirements](#requirements)
20 - [Installation](#installation)
21 - [Getting Started: A Simple Example](#getting-started-a-simple-example)
22 - [Available Content](#available-content)
23 - [Documentation](#documentation)
24 - [Contributing](#contributing)
25 - [License](#license)
26
27 ---
28
29 ## Key Features
30
31 - **Comprehensive Management:** Control every aspect of Podman, including containers, images, pods, networks, volumes, and secrets.
32 - **Idempotent Operations:** All modules are designed to be idempotent, ensuring predictable and consistent state for your resources.
33 - **Flexible and Powerful:** Exposes a wide range of Podman options, from simple container creation to advanced features like systemd integration and Quadlet file generation.
34 - **Connection Plugin:** Includes a `podman` connection plugin to execute Ansible tasks directly inside containers.
35
36 ## Requirements
37
38 - **Ansible:** `ansible-core >= 2.12`
39 - **Python:** `python >= 3.9`
40 - **Podman:** A working installation of Podman on the target machine.
41
42 ## Installation
43
44 Install the collection from Ansible Galaxy using the `ansible-galaxy` CLI:
45
46 ```bash
47 ansible-galaxy collection install containers.podman
48 ```
49
50 You can also include it in a `requirements.yml` file, which is useful for managing project dependencies:
51
52 ```yaml
53 # requirements.yml
54 collections:
55 - name: containers.podman
56 ```
57
58 Then, install it with:
59
60 ```bash
61 ansible-galaxy collection install -r requirements.yml
62 ```
63
64 ## Getting Started: A Simple Example
65
66 Here is a quick example of how to ensure a Redis container is running using the `podman_container` module.
67
68 ```yaml
69 ---
70 - name: Deploy a Redis container with Podman
71 hosts: localhost
72 connection: local
73
74 tasks:
75 - name: Ensure the Redis container is running
76 containers.podman.podman_container:
77 name: my-redis-cache
78 image: docker.io/redis:alpine
79 state: started
80 ports:
81 - "6379:6379"
82 restart_policy: "always"
83 ```
84
85 ## Available Content
86
87 This collection includes:
88
89 - **Modules:**
90 - `podman_container`: Manage Podman containers.
91 - `podman_image`: Build, pull, and manage Podman images.
92 - `podman_pod`: Create and manage Podman pods.
93 - `podman_network`: Manage Podman networks.
94 - `podman_volume`: Manage Podman volumes.
95 - `podman_secret`: Manage Podman secrets.
96 - `podman_quadlet`: Manage Systemd service files using Quadlet.
97 - `podman_generate_systemd`: Generate Systemd unit files for containers and pods.
98 - `podman_login`/`podman_logout`: Authenticate with container registries.
99 - ...and many more!
100
101 - **Connection Plugins:**
102 - `podman`: Execute Ansible tasks directly within a container.
103 - `buildah`: Execute Ansible tasks directly within a buildah container.
104
105 - **Become Plugins:**
106 - `podman_unshare`: Execute tasks within a `podman unshare` environment.
107
108 ## Documentation
109
110 - **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).
111 - **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/).
112 - **Connection Plugins Guide:** For comprehensive information about using Podman and Buildah connection plugins, including advanced examples and best practices, see our [Connection Plugins Documentation](docs/connection_plugins.md).
113
114 ## Contributing
115
116 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.
117
118 Please read our **[Contributing Guide](CONTRIBUTING.md)** to learn how to get started with development, testing, and submitting pull requests.
119
120 ## Releasing
121
122 For maintainers: see the **[Releasing Guide](RELEASING.md)** for the full release process — changelog updates, versioning, documentation builds, and publishing to Galaxy.
123
124 ## License
125
126 This collection is licensed under the [GNU General Public License v3.0 or later](COPYING).