Debian Codegraph @

ansible_collections/containers/podman/playbooks/examples/README.md

raw
1 ### Podman connection examples (with podman_containers inventory)
2
3 This folder shows practical playbooks that execute directly inside running Podman containers using the connection plugin `containers.podman.podman` and inventory plugin `containers.podman.podman_containers`.
4
5 How to use
6 1) Create a simple inventory source that discovers running containers:
7 - See `inventory/podman_all.yml`
8 - Adjust `label_selectors` or `name_patterns` if you want to target a subset
9
10 2) Run an example, e.g. basic exec:
11 ```bash
12 ansible-playbook -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_exec_basic.yml
13 ```
14
15 Examples included
16 - `podman_exec_basic.yml` — Run common commands (uptime, os-release), demonstrate environment variables and idempotent checks
17 - `podman_copy_fetch.yml` — Copy files into a container and fetch them back (works with rootless or root)
18 - `podman_multiuser_tasks.yml` — Execute tasks as different users inside containers (root and non-root), with optional become
19 - `podman_pkg_manage.yml` — Install a package using apk/apt/yum depending on detected distro (no Python required)
20
21 Notes
22 - The inventory plugin assigns the connection automatically; no SSH is used
23 - To run as non-root, set `ansible_user` (e.g. `nobody` or a numeric UID) on hosts or in a task/role scope
24 - You can inject environment variables into exec using `ansible_podman_extra_env`
25
26 ### Buildah connection playbook examples
27
28 This folder contains self-contained Ansible playbooks demonstrating how to build images with Buildah while executing steps inside a working container through the Buildah connection plugin (`ansible_connection: containers.podman.buildah`). Each example shows a realistic workflow and explains the options used.
29
30 Prerequisites
31 - Podman and Buildah installed (rootless supported)
32 - Ansible installed (`ansible-core` recommended)
33 - Network access to pull base images
34
35 How these playbooks work
36 - A working container is created on localhost using `buildah from <image>`.
37 - The playbook dynamically adds a temporary inventory host whose `ansible_connection` is `containers.podman.buildah` and `remote_addr` is the Buildah working container ID.
38 - File operations and commands within the container use the Buildah connection plugin (no SSH), so modules like `copy`, `command`, and `shell` act inside the container.
39 - Image metadata/commit/push operations are executed on localhost with `buildah config/commit/push` referencing the same container ID.
40
41 Common variables
42 - `buildah_base_image`: base image to start the working container (varies per example)
43 - `image_name`: final image name (and optional tag)
44 - `ansible_buildah_working_directory`: working directory inside the container for all build steps (passed to the connection plugin)
45
46 Examples
47 1) build_node_ai_api.yml — Node.js AI prediction API image without a Dockerfile
48 - Starts from `node:14`, copies `package.json` and app sources to `/app`, runs `npm install`, sets image metadata, commits to `my-ai-node-app:latest`.
49 - Options highlighted:
50 - `ansible_connection: containers.podman.buildah`
51 - `ansible_buildah_working_directory: /app`
52
53 2) build_go_ai_multistage.yml — Multi-stage Go build to a minimal runtime image
54 - Stage 1: compile inside `golang:1.21` working container, fetch the compiled binary to host.
55 - Stage 2: start `alpine:latest`, copy binary into the container, configure CMD and exposed port, commit `minimal-ai-inference:latest`.
56 - Shows how to move artifacts between stages using the connection plugin’s `fetch_file` and normal `copy`.
57
58 3) build_ai_env_with_ansible.yml — Create a consistent AI dev environment image with an Ansible role
59 - Starts from `python:3.11-slim`, then applies role `roles/ai-dev-env` which installs common data-science packages inside the container using raw/pip commands.
60 - Demonstrates layering higher-level Ansible logic on top of a Buildah working container.
61
62 4) gitlab_ci_build_model_image.yml — CI-friendly image build using Buildah connection (template)
63 - Builds and optionally pushes an image for a simple model serving app (`app.py`, `requirements.txt`).
64 - Designed to be called from GitLab CI; see the included `.gitlab-ci.yml` for a minimal job that runs `ansible-playbook`.
65
66 Running an example
67 ```bash
68 cd playbook/examples
69 ansible-playbook build_node_ai_api.yml -e image_name=my-ai-node-app:latest
70 ```
71
72 Notes
73 - The Buildah connection runs commands with `buildah run <container> …` under the hood; metadata operations such as `buildah config`, `commit`, and `push` still run on localhost and reference the working container ID.
74 - If you prefer persistent names, set `container_name` (Buildah will use named working containers). Otherwise, the container ID returned by `buildah from` is used.
75
76