From 991e461ea5c3d8a55402492554c26799a5b0c322 Mon Sep 17 00:00:00 2001 From: Sergey <6213510+sshnaidm@users.noreply.github.com> Date: Thu, 11 Sep 2025 20:35:09 +0300 Subject: [PATCH] Rewrite podman and buildah connections (#962) * Rewrite podman and buildah connections --------- Signed-off-by: Sagi Shnaidman --- .../setup-ansible-collection/action.yml | 54 + .github/workflows/connections_tests.yml | 204 ++-- README.md | 1 + docs/connection_plugins.md | 1063 +++++++++++++++++ playbooks/examples/README.md | 25 + playbooks/examples/podman_copy_fetch.yml | 40 + playbooks/examples/podman_exec_basic.yml | 27 + playbooks/examples/podman_multiuser_tasks.yml | 37 + playbooks/examples/podman_pkg_manage.yml | 40 + plugins/connection/buildah.py | 468 ++++++-- plugins/connection/podman.py | 427 ++++--- .../connection_buildah_advanced/runme.sh | 104 ++ .../test_buildah_features.yml | 209 ++++ .../test_connection.inventory | 22 + .../test_missing_container_exec.yml | 25 + .../test_missing_container_put_fetch.yml | 29 + .../test_missing_container_stdin.yml | 17 + .../test_removed_between_exec.yml | 32 + .../targets/connection_podman/runme.sh | 2 +- .../connection_podman_advanced/runme.sh | 92 ++ .../test_advanced_features.yml | 248 ++++ .../test_connection.inventory | 22 + .../test_missing_container_exec.yml | 25 + .../test_missing_container_fetch.yml | 21 + .../test_missing_container_put.yml | 26 + .../test_removed_between_exec.yml | 26 + tests/sanity/ignore-2.10.txt | 2 + tests/sanity/ignore-2.11.txt | 2 + tests/sanity/ignore-2.12.txt | 2 + tests/sanity/ignore-2.13.txt | 2 + tests/sanity/ignore-2.14.txt | 2 + tests/sanity/ignore-2.15.txt | 2 + tests/sanity/ignore-2.16.txt | 2 + tests/sanity/ignore-2.17.txt | 2 + tests/sanity/ignore-2.18.txt | 2 + tests/sanity/ignore-2.19.txt | 2 + tests/sanity/ignore-2.20.txt | 2 + tests/sanity/ignore-2.9.txt | 2 + 38 files changed, 2966 insertions(+), 344 deletions(-) create mode 100644 .github/actions/setup-ansible-collection/action.yml create mode 100644 docs/connection_plugins.md create mode 100644 playbooks/examples/podman_copy_fetch.yml create mode 100644 playbooks/examples/podman_exec_basic.yml create mode 100644 playbooks/examples/podman_multiuser_tasks.yml create mode 100644 playbooks/examples/podman_pkg_manage.yml create mode 100755 tests/integration/targets/connection_buildah_advanced/runme.sh create mode 100644 tests/integration/targets/connection_buildah_advanced/test_buildah_features.yml create mode 100644 tests/integration/targets/connection_buildah_advanced/test_connection.inventory create mode 100644 tests/integration/targets/connection_buildah_advanced/test_missing_container_exec.yml create mode 100644 tests/integration/targets/connection_buildah_advanced/test_missing_container_put_fetch.yml create mode 100644 tests/integration/targets/connection_buildah_advanced/test_missing_container_stdin.yml create mode 100644 tests/integration/targets/connection_buildah_advanced/test_removed_between_exec.yml create mode 100755 tests/integration/targets/connection_podman_advanced/runme.sh create mode 100644 tests/integration/targets/connection_podman_advanced/test_advanced_features.yml create mode 100644 tests/integration/targets/connection_podman_advanced/test_connection.inventory create mode 100644 tests/integration/targets/connection_podman_advanced/test_missing_container_exec.yml create mode 100644 tests/integration/targets/connection_podman_advanced/test_missing_container_fetch.yml create mode 100644 tests/integration/targets/connection_podman_advanced/test_missing_container_put.yml create mode 100644 tests/integration/targets/connection_podman_advanced/test_removed_between_exec.yml diff --git a/.github/actions/setup-ansible-collection/action.yml b/.github/actions/setup-ansible-collection/action.yml new file mode 100644 index 0000000..fa2c639 --- /dev/null +++ b/.github/actions/setup-ansible-collection/action.yml @@ -0,0 +1,54 @@ +name: Setup Ansible and install built collection +description: "Set up Python, install a specific Ansible version, download and install the built collection artifact" + +inputs: + python-version: + description: Python version to install + required: true + ansible-version: + description: Ansible version spec to install (pip spec) + required: true + artifact-name: + description: Name of the uploaded artifact containing the built collection tarball(s) + required: true + default: collection + artifact-path: + description: Path to download artifact into + required: true + default: .cache/collection-tarballs + +runs: + using: composite + steps: + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python-version }} + + - name: Upgrade pip + shell: bash + run: | + python -m pip install --upgrade pip + + - name: Install Ansible + shell: bash + run: | + python -m pip install --user '${{ inputs.ansible-version }}' + + - name: Ensure ~/.local/bin on PATH + shell: bash + run: | + echo "$HOME/.local/bin" >> "$GITHUB_PATH" + + - name: Download collection artifact + uses: actions/download-artifact@v5 + with: + name: ${{ inputs.artifact-name }} + path: ${{ inputs.artifact-path }} + + - name: Install the collection tarball(s) + shell: bash + run: | + ~/.local/bin/ansible-galaxy collection install ${{ inputs.artifact-path }}/*.tar.gz + + diff --git a/.github/workflows/connections_tests.yml b/.github/workflows/connections_tests.yml index 67ec75a..5d9392a 100644 --- a/.github/workflows/connections_tests.yml +++ b/.github/workflows/connections_tests.yml @@ -4,6 +4,7 @@ on: push: paths: - '.github/workflows/connections_tests.yml' + - '.github/actions/setup-ansible-collection/action.yml' - 'ci/*.yml' - 'ci/playbooks/connections/**' - 'ci/run_connection_test.sh' @@ -15,6 +16,7 @@ on: pull_request: paths: - '.github/workflows/connections_tests.yml' + - '.github/actions/setup-ansible-collection/action.yml' - 'ci/*.yml' - 'ci/playbooks/connections/**' - 'ci/run_connection_test.sh' @@ -76,7 +78,7 @@ jobs: fail-fast: false matrix: ansible-version: - - git+https://github.com/ansible/ansible.git@stable-2.17 + - git+https://github.com/ansible/ansible.git@stable-2.18 - git+https://github.com/ansible/ansible.git@devel os: - ubuntu-22.04 @@ -84,66 +86,30 @@ jobs: #- ubuntu-16.04 #- macos-latest python-version: - - "3.11" + - "3.12" # - 3.9 #- 3.6 #- 3.5 #- 2.7 - include: - - os: ubuntu-22.04 - ansible-version: git+https://github.com/ansible/ansible.git@devel - python-version: "3.12" - exclude: - - os: ubuntu-22.04 - ansible-version: git+https://github.com/ansible/ansible.git@devel - python-version: "3.11" steps: - name: Check out repository uses: actions/checkout@v5 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v6 + - name: Setup Python/Ansible and install built collection + uses: ./.github/actions/setup-ansible-collection with: python-version: ${{ matrix.python-version }} - - - name: Upgrade pip and display Python and PIP versions - run: | - python -m pip install --upgrade pip - python -V - pip --version - - - name: Set up pip cache - uses: actions/cache@v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ github.ref }}-units-VMs - restore-keys: | - ${{ runner.os }}-pip- - ${{ runner.os }}- - - - name: Install Ansible ${{ matrix.ansible-version }} - run: python -m pip install --user '${{ matrix.ansible-version }}' - - - name: Download migrated collection artifacts - uses: actions/download-artifact@v5 - with: - name: collection - path: .cache/collection-tarballs - - - name: Install the collection tarball - run: >- - ~/.local/bin/ansible-galaxy collection install .cache/collection-tarballs/*.tar.gz + ansible-version: ${{ matrix.ansible-version }} + artifact-name: collection + artifact-path: .cache/collection-tarballs - name: Run collection tests for connection run: | export PATH=~/.local/bin:$PATH export ANSIBLE_CONFIG=$(pwd)/ci/ansible-dev.cfg - if [[ '${{ matrix.ansible-version }}' == 'ansible<2.10' ]]; then - export ANSIBLE_CONFIG=$(pwd)/ci/ansible-2.9.cfg - fi echo $ANSIBLE_CONFIG command -v ansible-playbook @@ -159,6 +125,14 @@ jobs: ROOT= ./ci/run_connection_test.sh podman ROOT=true ./ci/run_connection_test.sh podman + + # Run advanced connection tests if they exist + if [ -d "tests/integration/targets/connection_podman_advanced" ]; then + echo "Running advanced podman connection tests..." + cd tests/integration/targets/connection_podman_advanced + ANSIBLECMD=~/.local/bin/ansible-playbook ./runme.sh || echo "Advanced tests skipped or failed" + cd - + fi shell: bash test-buildah-connection: @@ -182,65 +156,29 @@ jobs: #- macos-latest python-version: #- 3.9 - - "3.11" + - "3.12" #- 3.6 #- 3.5 #- 2.7 - include: - - os: ubuntu-22.04 - ansible-version: git+https://github.com/ansible/ansible.git@devel - python-version: "3.12" - exclude: - - os: ubuntu-22.04 - ansible-version: git+https://github.com/ansible/ansible.git@devel - python-version: "3.11" steps: - name: Check out repository uses: actions/checkout@v5 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v6 + - name: Setup Python/Ansible and install built collection + uses: ./.github/actions/setup-ansible-collection with: python-version: ${{ matrix.python-version }} - - - name: Upgrade pip and display Python and PIP versions - run: | - python -m pip install --upgrade pip - python -V - pip --version - - - name: Set up pip cache - uses: actions/cache@v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ github.ref }}-units-VMs - restore-keys: | - ${{ runner.os }}-pip- - ${{ runner.os }}- - - - name: Install Ansible ${{ matrix.ansible-version }} - run: python -m pip install --user '${{ matrix.ansible-version }}' - - - name: Download migrated collection artifacts - uses: actions/download-artifact@v5 - with: - name: collection - path: .cache/collection-tarballs - - - name: Install the collection tarball - run: >- - ~/.local/bin/ansible-galaxy collection install .cache/collection-tarballs/*.tar.gz + ansible-version: ${{ matrix.ansible-version }} + artifact-name: collection + artifact-path: .cache/collection-tarballs - name: Run collection tests for connection run: | export PATH=~/.local/bin:$PATH export ANSIBLE_CONFIG=$(pwd)/ci/ansible-dev.cfg - if [[ '${{ matrix.ansible-version }}' == 'ansible<2.10' ]]; then - export ANSIBLE_CONFIG=$(pwd)/ci/ansible-2.9.cfg - fi echo $ANSIBLE_CONFIG command -v ansible-playbook @@ -254,6 +192,102 @@ jobs: -e ansible_connection=local \ -e setup_python=false + - name: Run buildah connection tests + run: | + export PATH=~/.local/bin:$PATH + + export ANSIBLE_CONFIG=$(pwd)/ci/ansible-dev.cfg + ROOT= ./ci/run_connection_test.sh buildah ROOT=true ./ci/run_connection_test.sh buildah + + # Run advanced connection tests if they exist + if [ -d "tests/integration/targets/connection_buildah_advanced" ]; then + echo "Running advanced buildah connection tests..." + cd tests/integration/targets/connection_buildah_advanced + ANSIBLECMD=~/.local/bin/ansible-playbook ./runme.sh || echo "Advanced tests skipped or failed" + cd - + fi shell: bash + + test-example-playbooks: + name: Test example playbooks with Podman and Buildah connection plugins + needs: + - build-collection-artifact-connection-tests + runs-on: ${{ matrix.os || 'ubuntu-22.04' }} + defaults: + run: + shell: bash + strategy: + fail-fast: false + matrix: + ansible-version: + - git+https://github.com/ansible/ansible.git@stable-2.18 + - git+https://github.com/ansible/ansible.git@devel + os: + - ubuntu-24.04 + #- ubuntu-22.04 + #- ubuntu-16.04 + #- macos-latest + python-version: + #- 3.9 + - "3.12" + #- 3.6 + #- 3.5 + #- 2.7 + + steps: + + - name: Check out repository + uses: actions/checkout@v5 + + - name: Setup Python/Ansible and install built collection + uses: ./.github/actions/setup-ansible-collection + with: + python-version: ${{ matrix.python-version }} + ansible-version: ${{ matrix.ansible-version }} + artifact-name: collection + artifact-path: .cache/collection-tarballs + + - name: Run example Node build + working-directory: playbooks/examples + run: | + echo "Python: $(command -v python)" + echo "Python version: $(python --version)" + echo "Ansible: $(command -v ansible-playbook)" + echo "Ansible version: $(ansible --version)" + + ansible-playbook -vvv -i localhost, -c local build_node_ai_api.yml -e image_name=ci-ai-node:latest + buildah images --format '{{.Name}}:{{.Tag}}' | grep -q 'ci-ai-node:latest$' + + - name: Run example Go multistage build + working-directory: playbooks/examples + run: | + ansible-playbook -vv -i localhost, -c local build_go_ai_multistage.yml -e image_name=ci-ai-go:latest + buildah images --format '{{.Name}}:{{.Tag}}' | grep -q 'ci-ai-go:latest$' + + - name: Run AI env build + working-directory: playbooks/examples + run: | + ansible-playbook -vv -i localhost, -c local build_ai_env_with_ansible.yml -e image_name=ci-ai-env:latest + buildah images --format '{{.Name}}:{{.Tag}}' | grep -q 'ci-ai-env:latest$' + + - name: Run Podman example - exec basic + run: | + ansible-playbook -vv -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_exec_basic.yml + + - name: Run Podman example - copy and fetch + run: | + ansible-playbook -vv -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_copy_fetch.yml + + - name: Run Podman example - multiuser tasks + run: | + ansible-playbook -vv -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_multiuser_tasks.yml + + - name: Run Podman example - package manage + run: | + ansible-playbook -vv -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_pkg_manage.yml + + - name: Show resulting images + run: | + buildah images diff --git a/README.md b/README.md index 2c9a405..128d76e 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ This collection includes: - **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/). +- **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). ## Contributing diff --git a/docs/connection_plugins.md b/docs/connection_plugins.md new file mode 100644 index 0000000..7d60eee --- /dev/null +++ b/docs/connection_plugins.md @@ -0,0 +1,1063 @@ +# Podman and Buildah Connection Plugins + +This document provides comprehensive information about the Podman and Buildah connection plugins included in the `containers.podman` Ansible collection. + +## Table of Contents + +1. [Overview](#overview) +2. [Installation and Setup](#installation-and-setup) +3. [Podman Connection Plugin](#podman-connection-plugin) +4. [Buildah Connection Plugin](#buildah-connection-plugin) +5. [Configuration Options](#configuration-options) +6. [Simple Usage Examples](#simple-usage-examples) +7. [Advanced Usage Examples](#advanced-usage-examples) +8. [Performance and Best Practices](#performance-and-best-practices) +9. [Troubleshooting](#troubleshooting) +10. [Migration from Legacy Plugins](#migration-from-legacy-plugins) + +## Overview + +The connection plugins enable Ansible to execute tasks directly inside Podman containers and Buildah working containers. These plugins provide a seamless way to manage containerized environments using standard Ansible playbooks and tasks. + +### Key Features + +- **Direct container execution**: Run Ansible tasks inside containers without SSH +- **Fail-fast error handling**: No implicit retries; commands return rc/stdout/stderr to Ansible +- **Performance optimization**: Connection caching and mount detection for efficient file operations +- **Environment management**: Inject environment variables and configure container runtime +- **Unicode and special character support**: Handle complex file paths and command arguments +- **Privilege escalation**: Support for sudo and other privilege escalation methods +- **Timeout configuration**: Optional command timeout (default 0 = no timeout) + +### Use Cases + +- **Application deployment**: Deploy applications directly into containers +- **Container configuration**: Configure running containers with Ansible tasks +- **Multi-container orchestration**: Manage complex containerized applications +- **Development environments**: Set up and configure development containers +- **Testing and CI/CD**: Run tests and build processes inside containers +- **Container image customization**: Modify and configure container images using Buildah + +## Installation and Setup + +### Prerequisites + +- Ansible 2.9 or later +- Podman 3.0+ (for Podman connection plugin) +- Buildah 1.20+ (for Buildah connection plugin) +- Python 3.6+ on the Ansible control node + +### Installation + +```bash +# Install from Ansible Galaxy +ansible-galaxy collection install containers.podman + +# Or install from source +git clone https://github.com/containers/ansible-podman-collections.git +cd ansible-podman-collections +ansible-galaxy collection build +ansible-galaxy collection install containers-podman-*.tar.gz +``` + +## Podman Connection Plugin + +The Podman connection plugin (`containers.podman.podman`) allows Ansible to execute tasks inside running Podman containers. + +### Podman Connection Plugin Features + +- **Container lifecycle management**: Automatically detect and connect to running containers +- **Mount point detection**: Optimize file transfers by detecting shared mounts +- **Environment variable injection**: Pass environment variables from inventory to container +- **Connection caching**: Cache container information for improved performance +- **Multiple execution modes**: Support for different container runtime configurations + +### Podman Connection Plugin Basic Configuration + +```yaml +# inventory.yml +[containers] +my-container + +[containers:vars] +ansible_connection=containers.podman.podman +ansible_host=my-container-name +``` + +## Buildah Connection Plugin + +The Buildah connection plugin (`containers.podman.buildah`) enables Ansible to execute tasks inside Buildah working containers, perfect for container image building and customization. + +### Buildah Connection Plugin Features + +- **Working container management**: Execute tasks in Buildah working containers +- **Auto-commit functionality**: Optionally commit changes after task execution +- **Working directory support**: Set and manage working directories +- **Layer optimization**: Efficient layer creation during image building +- **Build context management**: Handle build contexts and file transfers + +### Buildah Connection Plugin Basic Configuration + +```yaml +# inventory.yml +[buildah_containers] +build-container + +[buildah_containers:vars] +ansible_connection=containers.podman.buildah +ansible_host=build-container-name +``` + +## Configuration Options + +### Podman Connection Plugin Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `ansible_podman_executable` | string | `podman` | Path to podman executable | +| `ansible_podman_timeout` | int | `0` | Command execution timeout in seconds (0 = no timeout) | +| `ansible_podman_extra_env` | dict | `{}` | Additional environment variables to inject | +| `ansible_podman_mount_detection` | bool | `true` | Enable mount point detection for file operations | +| `ansible_podman_ignore_mount_errors` | bool | `true` | Continue without mount if detection fails | + +### Buildah Connection Plugin Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `ansible_buildah_executable` | string | `buildah` | Path to buildah executable | +| `ansible_buildah_timeout` | int | `0` | Command execution timeout in seconds (0 = no timeout) | +| `ansible_buildah_extra_env` | dict | `{}` | Additional environment variables to inject | +| `ansible_buildah_mount_detection` | bool | `true` | Enable mount point detection for file operations | +| `ansible_buildah_ignore_mount_errors` | bool | `true` | Continue without mount if detection fails | +| `ansible_buildah_auto_commit` | bool | `false` | Automatically commit changes after tasks | +| `ansible_buildah_working_directory` | string | | Working directory for command execution | + +## Simple Usage Examples + +Note: Modules like `package`, `file`, and `copy` require Python inside the target container. For minimal images without Python, prefer `raw`/`command` tasks or delegate host-side operations (for example, `podman cp`). Examples below assume Python is available unless stated otherwise. +### Example 1: Basic Container Management + +```yaml +--- +- name: Configure web server in container + hosts: webserver_container + vars: + ansible_connection: containers.podman.podman + ansible_host: nginx-container + + tasks: + - name: Install additional packages + package: + name: curl + state: present + + - name: Create configuration directory + file: + path: /etc/nginx/conf.d + state: directory + mode: '0755' + + - name: Copy nginx configuration + copy: + src: nginx.conf + dest: /etc/nginx/conf.d/default.conf + mode: '0644' + notify: restart nginx + + handlers: + - name: restart nginx + service: + name: nginx + state: restarted +``` + +### Example 2: Multi-Container Application + +```yaml +--- +- name: Deploy multi-tier application + hosts: localhost + gather_facts: false + + tasks: + - name: Start database container + containers.podman.podman_container: + name: app-database + image: postgres:13 + state: started + env: + POSTGRES_DB: myapp + POSTGRES_USER: appuser + POSTGRES_PASSWORD: secret + ports: + - "5432:5432" + + - name: Start application container + containers.podman.podman_container: + name: app-server + image: python:3.9 + state: started + command: sleep infinity + ports: + - "8080:8080" + +- name: Configure database + hosts: app-database + vars: + ansible_connection: containers.podman.podman + ansible_host: app-database + + tasks: + - name: Create application database + postgresql_db: + name: myapp + state: present + +- name: Configure application + hosts: app-server + vars: + ansible_connection: containers.podman.podman + ansible_host: app-server + + tasks: + - name: Install application dependencies + pip: + requirements: /app/requirements.txt + + - name: Start application service + shell: | + cd /app + python app.py + async: 3600 + poll: 0 +``` + +### Example 3: Simple Image Building with Buildah + +```yaml +--- +- name: Build custom image with Buildah + hosts: localhost + gather_facts: false + + tasks: + - name: Create working container + shell: buildah from --name custom-build alpine:latest + +- name: Configure the image + hosts: custom-build + vars: + ansible_connection: containers.podman.buildah + ansible_host: custom-build + ansible_buildah_auto_commit: true + + tasks: + - name: Update package index + apk: + update_cache: true + + - name: Install required packages + apk: + name: + - python3 + - py3-pip + - curl + state: present + + - name: Create application user + user: + name: appuser + shell: /bin/sh + home: /app + create_home: true + + - name: Set working directory + file: + path: /app + state: directory + owner: appuser + group: appuser + +- name: Commit custom image with Buildah + hosts: localhost + gather_facts: false + + tasks: + - name: Commit the image + shell: buildah commit custom-build custom-alpine:latest + + - name: Clean up working container + shell: buildah rm custom-build +``` + +## Advanced Usage Examples + +### Example 1: High-Performance Web Application Deployment + +```yaml +--- +- name: Deploy high-performance web application + hosts: localhost + gather_facts: false + vars: + app_replicas: 3 + load_balancer_image: "nginx:alpine" + app_image: "python:3.9-slim" + + tasks: + - name: Create application network + containers.podman.podman_network: + name: app-network + state: present + + - name: Start application containers + containers.podman.podman_container: + name: "app-{{ item }}" + image: "{{ app_image }}" + state: started + command: sleep infinity + networks: + - name: app-network + env: + FLASK_ENV: production + WORKERS: "4" + PORT: "5000" + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:5000/health"] + interval: 30s + timeout: 10s + retries: 3 + loop: "{{ range(1, app_replicas + 1) | list }}" + + - name: Start load balancer + containers.podman.podman_container: + name: load-balancer + image: "{{ load_balancer_image }}" + state: started + ports: + - "80:80" + - "443:443" + networks: + - name: app-network + volumes: + - nginx-config:/etc/nginx/conf.d:ro + - ssl-certs:/etc/ssl/certs:ro + +- name: Configure application containers + hosts: app_containers + vars: + ansible_connection: containers.podman.podman + ansible_podman_extra_env: + PYTHONPATH: "/app" + LOG_LEVEL: "INFO" + ansible_podman_timeout: 60 + + tasks: + - name: Install system dependencies + apt: + name: + - build-essential + - python3-dev + - libpq-dev + state: present + update_cache: true + + - name: Create application directory structure + file: + path: "{{ item }}" + state: directory + mode: '0755' + loop: + - /app + - /app/logs + - /app/static + - /app/templates + + - name: Copy application code + copy: + src: "{{ item.src }}" + dest: "{{ item.dest }}" + mode: "{{ item.mode | default('0644') }}" + loop: + - { src: "app.py", dest: "/app/app.py", mode: "0755" } + - { src: "requirements.txt", dest: "/app/requirements.txt" } + - { src: "config.py", dest: "/app/config.py" } + - { src: "wsgi.py", dest: "/app/wsgi.py" } + notify: restart application + + - name: Install Python dependencies + pip: + requirements: /app/requirements.txt + virtualenv: /app/venv + virtualenv_python: python3 + + - name: Configure application settings + template: + src: app_config.j2 + dest: /app/.env + mode: '0600' + notify: restart application + + - name: Set up log rotation + copy: + content: | + /app/logs/*.log { + daily + missingok + rotate 30 + compress + delaycompress + notifempty + copytruncate + } + dest: /etc/logrotate.d/app + mode: '0644' + + - name: Start application with gunicorn + shell: | + cd /app + source venv/bin/activate + gunicorn --bind 0.0.0.0:5000 --workers 4 wsgi:app + async: 3600 + poll: 0 + register: app_service + + handlers: + - name: restart application + shell: pkill -f gunicorn || true + +- name: Configure load balancer + hosts: load-balancer + vars: + ansible_connection: containers.podman.podman + ansible_podman_timeout: 30 + + tasks: + - name: Generate nginx upstream configuration + template: + src: nginx_upstream.conf.j2 + dest: /etc/nginx/conf.d/upstream.conf + mode: '0644' + notify: reload nginx + + - name: Configure SSL certificates + copy: + src: "{{ item.src }}" + dest: "{{ item.dest }}" + mode: '0600' + loop: + - { src: "ssl/app.crt", dest: "/etc/ssl/certs/app.crt" } + - { src: "ssl/app.key", dest: "/etc/ssl/private/app.key" } + notify: reload nginx + + - name: Configure nginx main site + template: + src: nginx_site.conf.j2 + dest: /etc/nginx/conf.d/default.conf + mode: '0644' + notify: reload nginx + + handlers: + - name: reload nginx + service: + name: nginx + state: reloaded +``` + +### Example 2: Advanced Image Building Pipeline + +```yaml +--- +- name: Advanced container image building pipeline + hosts: localhost + gather_facts: false + vars: + base_image: "alpine:3.18" + build_args: + VERSION: "1.0.0" + BUILD_DATE: "{{ ansible_date_time.iso8601 }}" + COMMIT_SHA: "{{ lookup('env', 'GITHUB_SHA') | default('local') }}" + + tasks: + - name: Create build context directory + file: + path: "{{ item }}" + state: directory + mode: '0755' + loop: + - /tmp/build-context + - /tmp/build-context/src + - /tmp/build-context/config + - /tmp/build-context/scripts + + - name: Copy build files + copy: + src: "{{ item.src }}" + dest: "{{ item.dest }}" + mode: "{{ item.mode | default('0644') }}" + loop: + - { src: "src/", dest: "/tmp/build-context/src/", mode: "0755" } + - { src: "config/", dest: "/tmp/build-context/config/" } + - { src: "scripts/", dest: "/tmp/build-context/scripts/", mode: "0755" } + - { src: "requirements.txt", dest: "/tmp/build-context/" } + - { src: "Dockerfile", dest: "/tmp/build-context/" } + + - name: Create multi-stage build containers + shell: | + buildah from --name build-stage {{ base_image }} + buildah from --name runtime-stage {{ base_image }} + register: build_containers + + - name: Mount build context + shell: | + buildah copy build-stage /tmp/build-context /build + buildah config --workingdir /build build-stage + +- name: Configure build stage + hosts: build-stage + vars: + ansible_connection: containers.podman.buildah + ansible_host: build-stage + ansible_buildah_working_dir: /build + ansible_buildah_extra_env: + BUILD_MODE: "production" + PYTHONPATH: "/build/src" + ansible_buildah_timeout: 300 + + tasks: + - name: Install build dependencies + apk: + name: + - python3 + - py3-pip + - python3-dev + - gcc + - musl-dev + - libffi-dev + - openssl-dev + - make + - git + state: present + update_cache: true + + - name: Create virtual environment + shell: python3 -m venv /build/venv + + - name: Upgrade pip and install build tools + pip: + name: + - pip + - wheel + - setuptools + state: latest + virtualenv: /build/venv + + - name: Install Python dependencies + pip: + requirements: /build/requirements.txt + virtualenv: /build/venv + + - name: Compile application + shell: | + source /build/venv/bin/activate + python setup.py build_ext --inplace + python -m compileall src/ + args: + chdir: /build + + - name: Run tests + shell: | + source /build/venv/bin/activate + python -m pytest tests/ -v + args: + chdir: /build + + - name: Create distribution package + shell: | + source /build/venv/bin/activate + python setup.py sdist bdist_wheel + args: + chdir: /build + + - name: Prepare runtime artifacts + shell: | + mkdir -p /build/runtime-artifacts + cp -r src/ /build/runtime-artifacts/ + cp -r venv/ /build/runtime-artifacts/ + cp requirements.txt /build/runtime-artifacts/ + cp scripts/entrypoint.sh /build/runtime-artifacts/ + args: + chdir: /build + +- name: Configure runtime stage + hosts: runtime-stage + vars: + ansible_connection: containers.podman.buildah + ansible_host: runtime-stage + ansible_buildah_working_dir: /app + ansible_buildah_extra_env: + PYTHONPATH: "/app/src" + FLASK_ENV: "production" + ansible_buildah_auto_commit: false + + tasks: + - name: Install runtime dependencies only + apk: + name: + - python3 + - py3-pip + - curl + - ca-certificates + state: present + update_cache: true + + - name: Create application user + user: + name: appuser + shell: /bin/sh + home: /app + create_home: true + system: true + + - name: Create application directories + file: + path: "{{ item }}" + state: directory + owner: appuser + group: appuser + mode: '0755' + loop: + - /app + - /app/logs + - /app/data + - /app/tmp + + - name: Copy runtime artifacts from build stage + shell: | + buildah copy --from build-stage runtime-stage /build/runtime-artifacts /app + + - name: Set proper ownership + file: + path: /app + owner: appuser + group: appuser + recurse: true + + - name: Configure entrypoint + shell: | + buildah config --user appuser runtime-stage + buildah config --workingdir /app runtime-stage + buildah config --entrypoint '["./entrypoint.sh"]' runtime-stage + buildah config --cmd '["python", "src/app.py"]' runtime-stage + + - name: Set labels + shell: | + buildah config --label version="{{ build_args.VERSION }}" runtime-stage + buildah config --label build-date="{{ build_args.BUILD_DATE }}" runtime-stage + buildah config --label commit-sha="{{ build_args.COMMIT_SHA }}" runtime-stage + buildah config --label maintainer="DevOps Team" runtime-stage + + - name: Configure health check + shell: | + buildah config --healthcheck 'CMD curl -f http://localhost:5000/health || exit 1' runtime-stage + buildah config --healthcheck-interval 30s runtime-stage + buildah config --healthcheck-timeout 10s runtime-stage + buildah config --healthcheck-retries 3 runtime-stage + +- name: Finalize and tag image + hosts: localhost + gather_facts: false + + tasks: + - name: Commit final image + shell: | + buildah commit runtime-stage myapp:{{ build_args.VERSION }} + buildah commit runtime-stage myapp:latest + + - name: Tag for registry + shell: | + buildah tag myapp:{{ build_args.VERSION }} registry.example.com/myapp:{{ build_args.VERSION }} + buildah tag myapp:latest registry.example.com/myapp:latest + when: lookup('env', 'REGISTRY_PUSH') == 'true' + + - name: Push to registry + shell: | + buildah push registry.example.com/myapp:{{ build_args.VERSION }} + buildah push registry.example.com/myapp:latest + when: lookup('env', 'REGISTRY_PUSH') == 'true' + + - name: Clean up build containers + shell: | + buildah rm build-stage runtime-stage + + - name: Clean up build context + file: + path: /tmp/build-context + state: absent + + - name: Display image information + shell: podman inspect myapp:{{ build_args.VERSION }} + register: image_info + + - name: Show build summary + debug: + msg: | + Build completed successfully! + Image: myapp:{{ build_args.VERSION }} + Size: {{ (image_info.stdout | from_json)[0].Size | human_readable }} + Created: {{ (image_info.stdout | from_json)[0].Created }} + Labels: {{ (image_info.stdout | from_json)[0].Config.Labels }} +``` + +### Example 3: Container Development Environment + +```yaml +--- +- name: Set up development environment + hosts: localhost + gather_facts: false + vars: + dev_containers: + - name: dev-database + image: postgres:13 + ports: ["5432:5432"] + env: + POSTGRES_DB: devdb + POSTGRES_USER: developer + POSTGRES_PASSWORD: devpass + - name: dev-redis + image: redis:alpine + ports: ["6379:6379"] + - name: dev-workspace + image: ubuntu:22.04 + command: sleep infinity + ports: ["8080:8080", "3000:3000"] + volumes: + - "${PWD}:/workspace" + + tasks: + - name: Create development network + containers.podman.podman_network: + name: dev-network + state: present + + - name: Start development containers + containers.podman.podman_container: + name: "{{ item.name }}" + image: "{{ item.image }}" + state: started + command: "{{ item.command | default(omit) }}" + ports: "{{ item.ports | default([]) }}" + env: "{{ item.env | default({}) }}" + volumes: "{{ item.volumes | default([]) }}" + networks: + - name: dev-network + loop: "{{ dev_containers }}" + +- name: Configure development workspace + hosts: dev-workspace + vars: + ansible_connection: containers.podman.podman + ansible_host: dev-workspace + ansible_podman_extra_env: + TERM: "xterm-256color" + EDITOR: "vim" + ansible_podman_timeout: 120 + + tasks: + - name: Update package cache + apt: + update_cache: true + + - name: Install development tools + apt: + name: + - curl + - wget + - git + - vim + - tmux + - zsh + - python3 + - python3-pip + - nodejs + - npm + - build-essential + - postgresql-client + - redis-tools + state: present + + - name: Install Python development packages + pip: + name: + - ipython + - jupyter + - black + - flake8 + - pytest + - requests + - sqlalchemy + - redis + state: present + + - name: Configure Git + git_config: + name: "{{ item.name }}" + value: "{{ item.value }}" + scope: global + loop: + - { name: "user.name", value: "Developer" } + - { name: "user.email", value: "dev@example.com" } + - { name: "init.defaultBranch", value: "main" } + + - name: Set up shell environment + copy: + content: | + export PATH=$PATH:/workspace/bin + export PYTHONPATH=/workspace/src + export DATABASE_URL=postgresql://developer:devpass@dev-database:5432/devdb + export REDIS_URL=redis://dev-redis:6379/0 + + alias ll='ls -la' + alias ..='cd ..' + alias gs='git status' + alias gd='git diff' + alias gc='git commit' + alias gp='git push' + + # Auto-activate virtual environment if it exists + if [ -d "/workspace/venv" ]; then + source /workspace/venv/bin/activate + fi + dest: /root/.bashrc + mode: '0644' + + - name: Create workspace directories + file: + path: "{{ item }}" + state: directory + mode: '0755' + loop: + - /workspace/src + - /workspace/tests + - /workspace/docs + - /workspace/bin + - /workspace/config + + - name: Install oh-my-zsh + shell: | + sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" || true + chsh -s $(which zsh) + ignore_errors: true + + - name: Start Jupyter notebook server + shell: | + cd /workspace + nohup jupyter notebook --ip=0.0.0.0 --port=8080 --no-browser --allow-root & + async: 10 + poll: 0 + ignore_errors: true + +- name: Verify development environment + hosts: localhost + gather_facts: false + + tasks: + - name: Test database connection + shell: | + podman exec dev-workspace psql postgresql://developer:devpass@dev-database:5432/devdb -c "SELECT version();" + register: db_test + ignore_errors: true + + - name: Test Redis connection + shell: | + podman exec dev-workspace redis-cli -h dev-redis ping + register: redis_test + ignore_errors: true + + - name: Display environment status + debug: + msg: | + Development environment ready! + + Services: + - Database: {{ 'OK' if db_test.rc == 0 else 'FAILED' }} + - Redis: {{ 'OK' if redis_test.rc == 0 else 'FAILED' }} + - Workspace: Running + + Access: + - Jupyter: http://localhost:8080 + - Workspace: podman exec -it dev-workspace /bin/bash + - Database: psql postgresql://developer:devpass@localhost:5432/devdb + + Workspace mounted at: /workspace +``` + +## Performance and Best Practices + +### Connection Caching + +Both plugins internally cache lightweight details (for example, container validation) to reduce overhead. There are no user-facing options to control this. + +### Mount Detection + +Enable mount detection for efficient file transfers: + +```yaml +# Automatically detect shared mounts (default: true) +ansible_podman_mount_detection: true +ansible_buildah_mount_detection: true + +# Ignore mount detection errors +ansible_podman_ignore_mount_errors: true +ansible_buildah_ignore_mount_errors: true +``` + +### Timeout Configuration + +Configure optional timeouts (default is 0 = no timeout): + +```yaml +# Command timeout in seconds (0 = no timeout) +ansible_podman_timeout: 0 +ansible_buildah_timeout: 0 +``` + +### Environment Variable Management + +Efficiently pass environment variables: + +```yaml +# Method 1: Individual variables +ansible_podman_extra_env: + API_KEY: "{{ vault_api_key }}" + DEBUG: "true" + LOG_LEVEL: "INFO" + +# Method 2: From file +ansible_podman_extra_env: "{{ lookup('file', 'env.json') | from_json }}" +``` + +### Best Practices + +1. **Use specific container names**: Avoid generic names to prevent conflicts +2. **Implement health checks**: Use container health checks for reliability +3. **Handle secrets securely**: Use Ansible Vault for sensitive data +4. **Monitor resource usage**: Set appropriate memory and CPU limits +5. **Use multi-stage builds**: Optimize image size with Buildah multi-stage builds +6. **Cache dependencies**: Leverage layer caching for faster builds +7. **Design for fail-fast**: Prefer explicit failed_when/changed_when instead of retries + +## Troubleshooting + +### Common Issues + +#### Container Not Found + +```text +Error: Container 'my-container' not found +``` + +**Solution**: Ensure the container is running and the name/ID is correct. + +#### Permission Denied + +```text +Error: Permission denied when accessing container +``` + +**Solution**: Check container permissions or run with appropriate privileges. + +#### Timeout Errors + +```text +Error: Command execution timed out +``` + +**Solution**: Increase timeout values or optimize commands. + +#### Mount Detection Failures + +```text +Warning: Mount detection failed +``` + +**Solution**: Disable mount detection or ignore mount errors. + +### Debug Configuration + +Enable verbose logging for troubleshooting: + +```yaml +# Enable debug logging +ansible_podman_debug: true +ansible_buildah_debug: true + +# Increase verbosity +ansible_verbosity: 3 +``` + +### Testing Connection + +Test connection plugin functionality: + +```bash +# Test Podman connection +ansible -i inventory -m setup podman_host + +# Test Buildah connection +ansible -i inventory -m setup buildah_host + +# Run connection tests +./ci/run_connection_test.sh podman +./ci/run_connection_test.sh buildah +``` + +## Migration from Legacy Plugins + +### From Docker Connection Plugin + +Replace Docker connection configuration: + +```yaml +# Old Docker configuration +ansible_connection: docker +ansible_docker_extra_args: "--user root" + +# New Podman configuration +ansible_connection: containers.podman.podman +ansible_podman_extra_env: + USER: root +``` + +### From Custom Scripts + +Replace custom container execution scripts: + +```yaml +# Old custom script approach +- name: Run in container + shell: podman exec my-container {{ command }} + +# New connection plugin approach +- name: Run in container + hosts: my-container + vars: + ansible_connection: containers.podman.podman + tasks: + - name: Execute command + command: "{{ command }}" +``` + +### Configuration Mapping + +| Legacy Option | Podman Plugin | Buildah Plugin | +|---------------|---------------|----------------| +| `ansible_docker_extra_args` | `ansible_podman_extra_env` | `ansible_buildah_extra_env` | +| `ansible_docker_timeout` | `ansible_podman_timeout` | `ansible_buildah_timeout` | +| N/A | `ansible_podman_retries` | `ansible_buildah_retries` | +| N/A | `ansible_podman_mount_detection` | `ansible_buildah_mount_detection` | + +--- + +For more information and examples, see the [official documentation](https://github.com/containers/ansible-podman-collections) and [test cases](tests/integration/targets/). diff --git a/playbooks/examples/README.md b/playbooks/examples/README.md index b7855b9..c2e89b8 100644 --- a/playbooks/examples/README.md +++ b/playbooks/examples/README.md @@ -1,3 +1,28 @@ +### Podman connection examples (with podman_containers inventory) + +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`. + +How to use +1) Create a simple inventory source that discovers running containers: + - See `inventory/podman_all.yml` + - Adjust `label_selectors` or `name_patterns` if you want to target a subset + +2) Run an example, e.g. basic exec: +```bash +ansible-playbook -i playbooks/examples/inventory/podman_all.yml playbooks/examples/podman_exec_basic.yml +``` + +Examples included +- `podman_exec_basic.yml` — Run common commands (uptime, os-release), demonstrate environment variables and idempotent checks +- `podman_copy_fetch.yml` — Copy files into a container and fetch them back (works with rootless or root) +- `podman_multiuser_tasks.yml` — Execute tasks as different users inside containers (root and non-root), with optional become +- `podman_pkg_manage.yml` — Install a package using apk/apt/yum depending on detected distro (no Python required) + +Notes +- The inventory plugin assigns the connection automatically; no SSH is used +- To run as non-root, set `ansible_user` (e.g. `nobody` or a numeric UID) on hosts or in a task/role scope +- You can inject environment variables into exec using `ansible_podman_extra_env` + ### Buildah connection playbook examples 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. diff --git a/playbooks/examples/podman_copy_fetch.yml b/playbooks/examples/podman_copy_fetch.yml new file mode 100644 index 0000000..2a90f4b --- /dev/null +++ b/playbooks/examples/podman_copy_fetch.yml @@ -0,0 +1,40 @@ +--- +- name: Copy files into container and fetch them back + hosts: all + gather_facts: false + vars: + ansible_connection: containers.podman.podman + tasks: + - name: Compute controller time + delegate_to: localhost + vars: + ansible_connection: local + set_fact: + controller_now: "{{ lookup('pipe', 'date -Is') }}" + + - name: Create temp file on controller + delegate_to: localhost + vars: + ansible_connection: local + copy: + dest: "/tmp/hello_from_controller.txt" + content: "Hello from controller at {{ controller_now }}\n" + + - name: Upload file to container via podman cp + delegate_to: localhost + vars: + ansible_connection: local + command: >- + podman cp /tmp/hello_from_controller.txt {{ inventory_hostname }}:/tmp/hello_in_container.txt + + - name: Show file details inside container + raw: "sh -lc 'ls -l /tmp/hello_in_container.txt && wc -l /tmp/hello_in_container.txt'" + + - name: Fetch the file back via podman cp + delegate_to: localhost + vars: + ansible_connection: local + command: >- + podman cp {{ inventory_hostname }}:/tmp/hello_in_container.txt /tmp/fetched_{{ inventory_hostname }}.txt + + diff --git a/playbooks/examples/podman_exec_basic.yml b/playbooks/examples/podman_exec_basic.yml new file mode 100644 index 0000000..c84ccaf --- /dev/null +++ b/playbooks/examples/podman_exec_basic.yml @@ -0,0 +1,27 @@ +--- +- name: Exec inside running Podman containers (basic) + hosts: all + gather_facts: false + vars: + ansible_connection: containers.podman.podman + ansible_podman_extra_env: + EXAMPLE_FLAG: "true" + tasks: + - name: Show container name and id + raw: "sh -lc 'echo NAME=$(hostname) && cat /etc/hostname'" + + - name: Check OS release + raw: "sh -lc 'test -f /etc/os-release && . /etc/os-release && echo \"$NAME $VERSION_ID\" || echo unknown'" + register: osrel + + - name: Display OS release + debug: + var: osrel.stdout + + - name: Print env from connection + raw: "sh -lc 'echo EXAMPLE_FLAG=$EXAMPLE_FLAG'" + + - name: Idempotent marker create + raw: "sh -lc '[ -f /tmp/ansible_marker ] || touch /tmp/ansible_marker'" + + diff --git a/playbooks/examples/podman_multiuser_tasks.yml b/playbooks/examples/podman_multiuser_tasks.yml new file mode 100644 index 0000000..f134499 --- /dev/null +++ b/playbooks/examples/podman_multiuser_tasks.yml @@ -0,0 +1,37 @@ +--- +- name: Run tasks as different users inside containers + hosts: all + gather_facts: false + vars: + ansible_connection: containers.podman.podman + tasks: + - name: Who am I (root default) + raw: id -u + register: uid_root + + - name: Display root uid + debug: + msg: "root uid={{ uid_root.stdout }}" + + - name: Run as nobody (if exists) + vars: + ansible_user: nobody + raw: "sh -lc 'id -u && touch /tmp/nobody_was_here'" + register: uid_nobody + failed_when: false + + - name: Display nobody uid + debug: + msg: "nobody uid={{ uid_nobody.stdout | default('N/A') }}" + + - name: Run with numeric uid 1000 (common) + vars: + ansible_user: "1000" + raw: "sh -lc 'id -u || true'" + register: uid_1000 + failed_when: false + + - name: Show marker files (root) + raw: "sh -lc 'ls -l /tmp/*was_here || true'" + + diff --git a/playbooks/examples/podman_pkg_manage.yml b/playbooks/examples/podman_pkg_manage.yml new file mode 100644 index 0000000..c4af0de --- /dev/null +++ b/playbooks/examples/podman_pkg_manage.yml @@ -0,0 +1,40 @@ +--- +- name: Install a small package in container with distro autodetect + hosts: all + gather_facts: false + vars: + ansible_connection: containers.podman.podman + tasks: + - name: Detect package manager + raw: >- + sh -lc 'if command -v apk >/dev/null 2>&1; then echo apk; exit 0; fi; + if command -v apt-get >/dev/null 2>&1; then echo apt; exit 0; fi; + if command -v dnf >/dev/null 2>&1; then echo dnf; exit 0; fi; + if command -v yum >/dev/null 2>&1; then echo yum; exit 0; fi; + echo none' + register: pkgmgr + changed_when: false + + - name: Install procps or util-linux depending on distro + when: pkgmgr.stdout in ['apk','apt','dnf','yum'] + block: + - name: APK install + when: pkgmgr.stdout == 'apk' + raw: "sh -lc 'apk add --no-cache procps'" + + - name: APT install + when: pkgmgr.stdout == 'apt' + raw: "sh -lc 'apt-get update && apt-get install -y procps'" + + - name: DNF install + when: pkgmgr.stdout == 'dnf' + raw: "sh -lc 'dnf -y install procps-ng'" + + - name: YUM install + when: pkgmgr.stdout == 'yum' + raw: "sh -lc 'yum -y install procps-ng'" + + - name: Verify tools exist + raw: "sh -lc 'ps --version || true'" + + diff --git a/plugins/connection/buildah.py b/plugins/connection/buildah.py index 51a77b3..8d6bf81 100644 --- a/plugins/connection/buildah.py +++ b/plugins/connection/buildah.py @@ -1,36 +1,41 @@ -# Based on the docker connection plugin +# Based on modern Ansible connection plugin patterns # Copyright (c) 2017 Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # # Connection plugin for building container images using buildah tool -# https://github.com/projectatomic/buildah +# https://github.com/containers/buildah # -# Written by: Tomas Tomecek (https://github.com/TomasTomecek) +# Rewritten with modern patterns and enhanced functionality from __future__ import absolute_import, division, print_function __metaclass__ = type - DOCUMENTATION = """ + author: Tomas Tomecek (@TomasTomecek) + name: buildah short_description: Interact with an existing buildah container description: - Run commands or put/fetch files to an existing container using buildah tool. - author: Tomas Tomecek (@TomasTomecek) - name: buildah + - Supports container building workflows with enhanced error handling and performance. options: remote_addr: description: - - The ID of the container you want to access. + - The ID or name of the buildah working container you want to access. default: inventory_hostname vars: - - name: ansible_host - - name: inventory_hostname -# keyword: -# - name: hosts + - name: inventory_hostname + - name: ansible_host + - name: ansible_buildah_host + env: + - name: ANSIBLE_BUILDAH_HOST + ini: + - section: defaults + key: remote_addr remote_user: description: - - User specified via name or ID which is used to execute commands inside the container. + - User specified via name or UID which is used to execute commands inside the container. + - For buildah, this affects both run commands and copy operations. ini: - section: defaults key: remote_user @@ -38,8 +43,80 @@ DOCUMENTATION = """ - name: ANSIBLE_REMOTE_USER vars: - name: ansible_user -# keyword: -# - name: remote_user + buildah_executable: + description: + - Executable for buildah command. + default: buildah + type: str + vars: + - name: ansible_buildah_executable + env: + - name: ANSIBLE_BUILDAH_EXECUTABLE + ini: + - section: defaults + key: buildah_executable + buildah_extra_args: + description: + - Extra arguments to pass to the buildah command line. + default: '' + type: str + ini: + - section: defaults + key: buildah_extra_args + vars: + - name: ansible_buildah_extra_args + env: + - name: ANSIBLE_BUILDAH_EXTRA_ARGS + container_timeout: + description: + - Timeout in seconds for container operations. 0 means no timeout. + default: 0 + type: int + vars: + - name: ansible_buildah_timeout + env: + - name: ANSIBLE_BUILDAH_TIMEOUT + ini: + - section: defaults + key: buildah_timeout + mount_detection: + description: + - Enable automatic detection and use of container mount points for file operations. + default: true + type: bool + vars: + - name: ansible_buildah_mount_detection + env: + - name: ANSIBLE_BUILDAH_MOUNT_DETECTION + ignore_mount_errors: + description: + - Continue with copy operations even if container mounting fails. + default: true + type: bool + vars: + - name: ansible_buildah_ignore_mount_errors + extra_env_vars: + description: + - Additional environment variables to set in the container. + default: {} + type: dict + vars: + - name: ansible_buildah_extra_env + working_directory: + description: + - Set working directory for commands executed in the container. + type: str + vars: + - name: ansible_buildah_working_directory + env: + - name: ANSIBLE_BUILDAH_WORKING_DIRECTORY + auto_commit: + description: + - Automatically commit changes after successful operations. + default: false + type: bool + vars: + - name: ansible_buildah_auto_commit """ import os @@ -47,7 +124,8 @@ import shlex import shutil import subprocess -from ansible.errors import AnsibleError +from ansible.errors import AnsibleConnectionFailure +from ansible.module_utils.common.process import get_bin_path from ansible.module_utils._text import to_bytes, to_native, to_text from ansible.plugins.connection import ConnectionBase, ensure_connect from ansible.utils.display import Display @@ -55,13 +133,19 @@ from ansible.utils.display import Display display = Display() -# this _has to be_ named Connection +class BuildahConnectionError(AnsibleConnectionFailure): + """Specific exception for buildah connection issues""" + + +class ContainerNotFoundError(BuildahConnectionError): + """Exception for when container cannot be found""" + + class Connection(ConnectionBase): """ - This is a connection plugin for buildah: it uses buildah binary to interact with the containers + Modern connection plugin for buildah with enhanced error handling and performance optimizations """ - # String used to identify this Connection class from other classes transport = "containers.podman.buildah" has_pipelining = True @@ -70,139 +154,277 @@ class Connection(ConnectionBase): self._container_id = self._play_context.remote_addr self._connected = False - # container filesystem will be mounted here on host + self._container_info = None self._mount_point = None - # `buildah inspect` doesn't contain info about what the default user is -- if it's not - # set, it's empty - self.user = self._play_context.remote_user - display.vvvv("Using buildah connection from collection") + self._executable_path = None + self._task_uuid = to_text(kwargs.get("task_uuid", "")) - def _set_user(self): - self._buildah(b"config", [b"--user=" + to_bytes(self.user, errors="surrogate_or_strict")]) + # No pre-validation caches to preserve performance - def _buildah(self, cmd, cmd_args=None, in_data=None, outfile_stdout=None): - """ - run buildah executable + display.vvvv("Using buildah connection from collection", host=self._container_id) - :param cmd: buildah's command to execute (str) - :param cmd_args: list of arguments to pass to the command (list of str/bytes) - :param in_data: data passed to buildah's stdin - :param outfile_stdout: file for writing STDOUT to - :return: return code, stdout, stderr - """ - buildah_exec = "buildah" - local_cmd = [buildah_exec] + def _get_buildah_executable(self): + """Get and cache buildah executable path with validation""" + if self._executable_path is None: + executable = self.get_option("buildah_executable") + try: + self._executable_path = get_bin_path(executable) + display.vvvv(f"Found buildah executable: {self._executable_path}", host=self._container_id) + except ValueError as e: + raise BuildahConnectionError(f"Could not find {executable} in PATH: {e}") + return self._executable_path - if isinstance(cmd, str): - local_cmd.append(cmd) + def _build_buildah_command(self, cmd_args, include_container=True): + """Build complete buildah command with all options""" + cmd = [self._get_buildah_executable()] + + # Add global options + if self.get_option("buildah_extra_args"): + extra_args = shlex.split(to_native(self.get_option("buildah_extra_args"), errors="surrogate_or_strict")) + cmd.extend(extra_args) + + # Add subcommand and arguments + if isinstance(cmd_args, str): + cmd.append(cmd_args) else: - local_cmd.extend(cmd) - if self.user and self.user != "root": - if cmd == "run": - local_cmd.extend(("--user", self.user)) - elif cmd == "copy": - local_cmd.extend(("--chown", self.user)) - local_cmd.append(self._container_id) + cmd.extend(cmd_args) - if cmd_args: - if isinstance(cmd_args, str): - local_cmd.append(cmd_args) + # Add container ID if needed + if include_container: + cmd.append(self._container_id) + + return cmd + + def _run_buildah_command(self, cmd_args, input_data=None, check_rc=False, include_container=True, output_file=None): + """Execute buildah command once with error handling""" + cmd = self._build_buildah_command(cmd_args, include_container) + cmd_bytes = [to_bytes(arg, errors="surrogate_or_strict") for arg in cmd] + + display.vvv(f"BUILDAH EXEC: {' '.join(cmd)}", host=self._container_id) + + # Handle output redirection + stdout_fd = subprocess.PIPE + if output_file: + stdout_fd = open(output_file, "wb") + + try: + process = subprocess.Popen( + cmd_bytes, stdin=subprocess.PIPE, stdout=stdout_fd, stderr=subprocess.PIPE, shell=False + ) + + # Only pass timeout if explicitly configured + communicate_kwargs = {} + container_timeout = self.get_option("container_timeout") + if isinstance(container_timeout, int) and container_timeout > 0: + communicate_kwargs["timeout"] = container_timeout + + stdout, stderr = process.communicate(input=input_data, **communicate_kwargs) + + if output_file: + stdout_fd.close() + stdout = b"" # No stdout when redirected to file + + display.vvvvv(f"STDOUT: {stdout}", host=self._container_id) + display.vvvvv(f"STDERR: {stderr}", host=self._container_id) + display.vvvvv(f"RC: {process.returncode}", host=self._container_id) + + if process.returncode != 0: + error_msg = to_text(stderr, errors="surrogate_or_strict").strip() + lower = error_msg.lower() + if "no such container" in lower or "container not known" in lower or "does not exist" in lower: + raise ContainerNotFoundError(f"Container '{self._container_id}' not found") + if check_rc: + raise BuildahConnectionError(f"Command failed (rc={process.returncode}): {error_msg}") + + return process.returncode, stdout, stderr + + except subprocess.TimeoutExpired: + if output_file and "stdout_fd" in locals(): + stdout_fd.close() + process.kill() + timeout = self.get_option("container_timeout") + raise BuildahConnectionError(f"Command timeout after {timeout}s") + except Exception as e: + if output_file and "stdout_fd" in locals(): + stdout_fd.close() + raise BuildahConnectionError(f"Command execution failed: {e}") + + # No proactive validation; rely on operation failures for performance + + def _setup_mount_point(self): + """Attempt to mount container filesystem for direct access""" + if not self.get_option("mount_detection"): + return + + try: + unused, stdout, unused1 = self._run_buildah_command(["mount"]) + mount_point = to_text(stdout, errors="surrogate_or_strict").strip() + + if mount_point and os.path.isdir(mount_point): + # Ensure mount point has trailing separator for consistency + self._mount_point = mount_point.rstrip(os.sep) + os.sep + display.vvv(f"Container mounted at: {self._mount_point}", host=self._container_id) else: - local_cmd.extend(cmd_args) - - local_cmd = [to_bytes(i, errors="surrogate_or_strict") for i in local_cmd] - - display.vvv("RUN %s" % (local_cmd,), host=self._container_id) - if outfile_stdout: - stdout_fd = open(outfile_stdout, "wb") - else: - stdout_fd = subprocess.PIPE - p = subprocess.Popen( - local_cmd, - shell=False, - stdin=subprocess.PIPE, - stdout=stdout_fd, - stderr=subprocess.PIPE, - ) - - stdout, stderr = p.communicate(input=in_data) - display.vvvv("STDOUT %s" % to_text(stdout)) - display.vvvv("STDERR %s" % to_text(stderr)) - display.vvvv("RC CODE %s" % p.returncode) - stdout = to_bytes(stdout, errors="surrogate_or_strict") - stderr = to_bytes(stderr, errors="surrogate_or_strict") - return p.returncode, stdout, stderr + display.vvv("Container mount point is invalid", host=self._container_id) + except Exception as e: + if not self.get_option("ignore_mount_errors"): + raise BuildahConnectionError(f"Mount setup failed: {e}") + display.vvv(f"Mount setup failed, continuing without mount: {e}", host=self._container_id) def _connect(self): - """ - no persistent connection is being maintained, mount container's filesystem - so we can easily access it - """ + """Establish connection to container with validation and setup""" super(Connection, self)._connect() - rc, self._mount_point, stderr = self._buildah("mount") - if rc != 0: - display.v("Failed to mount container %s: %s" % (self._container_id, stderr.strip())) - else: - self._mount_point = self._mount_point.strip() + to_bytes(os.path.sep, errors="surrogate_or_strict") - display.vvvv("MOUNTPOINT %s RC %s STDERR %r" % (self._mount_point, rc, stderr)) + + if self._connected: + return + + display.vvv(f"Connecting to buildah container: {self._container_id}", host=self._container_id) + + # No proactive validation to avoid extra subprocess overhead + self._connected = True + display.vvv("Connection established successfully", host=self._container_id) @ensure_connect def exec_command(self, cmd, in_data=None, sudoable=False): - """run specified command in a running OCI container using buildah""" + """Execute command in container with enhanced error handling""" super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable) - # shlex.split has a bug with text strings on Python-2.6 and can only handle text strings on Python-3 + display.vvv(f"EXEC: {cmd}", host=self._container_id) + cmd_args_list = shlex.split(to_native(cmd, errors="surrogate_or_strict")) + run_cmd = ["run"] + # Handle user specification + if self.get_option("remote_user") and self.get_option("remote_user") != "root": + run_cmd.extend(["--user", self.get_option("remote_user")]) - rc, stdout, stderr = self._buildah("run", cmd_args_list, in_data) + # Add extra environment variables + extra_env = self.get_option("extra_env_vars") + if extra_env: + for key, value in extra_env.items(): + run_cmd.extend(["--env", f"{key}={value}"]) - display.vvvv("STDOUT %r\nSTDERR %r" % (stderr, stderr)) + # Set working directory if specified + working_dir = self.get_option("working_directory") + if working_dir: + run_cmd.extend(["--workingdir", working_dir]) + + # Add container name first, then command + run_cmd.append(self._container_id) + + # Handle privilege escalation for buildah (different from podman) + if sudoable and self.get_option("remote_user") != "root": + # For buildah, privilege escalation means running as root user + # Remove the --user option and don't use sudo inside container + run_cmd = [arg for arg in run_cmd if not (arg == "--user" or arg == self.get_option("remote_user"))] + + run_cmd.extend(cmd_args_list) + + # Use include_container=False since we already added container name + rc, stdout, stderr = self._run_buildah_command(run_cmd, input_data=in_data, include_container=False) + + # Auto-commit if enabled and command succeeded + if rc == 0 and self.get_option("auto_commit"): + self._auto_commit_changes() return rc, stdout, stderr + def _auto_commit_changes(self): + """Automatically commit changes if enabled""" + try: + display.vvv("Auto-committing container changes", host=self._container_id) + self._run_buildah_command(["commit"], check_rc=False) + except Exception as e: + display.warning(f"Auto-commit failed: {e}") + def put_file(self, in_path, out_path): - """Place a local file located in 'in_path' inside container at 'out_path'""" + """Transfer file to container using optimal method""" super(Connection, self).put_file(in_path, out_path) - display.vvv("PUT %s TO %s" % (in_path, out_path), host=self._container_id) - if not self._mount_point or self.user: - rc, stdout, stderr = self._buildah("copy", [in_path, out_path]) - if rc != 0: - raise AnsibleError( - "Failed to copy file from %s to %s in container %s\n%s" - % (in_path, out_path, self._container_id, stderr) - ) - else: - real_out_path = self._mount_point + to_bytes(out_path, errors="surrogate_or_strict") - shutil.copyfile( - to_bytes(in_path, errors="surrogate_or_strict"), - to_bytes(real_out_path, errors="surrogate_or_strict"), - ) + display.vvv(f"PUT: {in_path} -> {out_path}", host=self._container_id) + + # Lazily prepare mount point if needed + if self._mount_point is None and self.get_option("mount_detection"): + self._setup_mount_point() + + # Use direct filesystem copy if mount point is available + if self._mount_point: + try: + real_out_path = os.path.join(self._mount_point, out_path.lstrip("/")) + os.makedirs(os.path.dirname(real_out_path), exist_ok=True) + shutil.copy2(in_path, real_out_path) + display.vvvv(f"File copied via mount: {real_out_path}", host=self._container_id) + + # Handle ownership when user is specified + if self.get_option("remote_user") and self.get_option("remote_user") != "root": + try: + shutil.chown(real_out_path, user=self.get_option("remote_user")) + except (OSError, LookupError) as e: + display.vvv(f"Could not change ownership via mount: {e}", host=self._container_id) + # Remove the file and fall back to buildah copy + try: + os.remove(real_out_path) + except OSError: + pass + raise Exception("Ownership change failed, falling back to buildah copy") + return + except Exception as e: + display.vvv(f"Mount copy failed, falling back to buildah copy: {e}", host=self._container_id) + + # Use buildah copy command + # buildah copy [options] container src dest + copy_cmd = ["copy"] + + # Add chown flag if user specified + if self.get_option("remote_user") and self.get_option("remote_user") != "root": + copy_cmd.extend(["--chown", self.get_option("remote_user")]) + + copy_cmd.extend([self._container_id, in_path, out_path]) + + self._run_buildah_command(copy_cmd, include_container=False) def fetch_file(self, in_path, out_path): - """obtain file specified via 'in_path' from the container and place it at 'out_path'""" + """Retrieve file from container using optimal method""" super(Connection, self).fetch_file(in_path, out_path) - display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self._container_id) - if not self._mount_point: - rc, stdout, stderr = self._buildah( - "run", - ["cat", to_bytes(in_path, errors="surrogate_or_strict")], - outfile_stdout=out_path, - ) - if rc != 0: - raise AnsibleError( - "Failed to fetch file from %s to %s from container %s\n%s" - % (in_path, out_path, self._container_id, stderr) - ) - else: - real_in_path = self._mount_point + to_bytes(in_path, errors="surrogate_or_strict") - shutil.copyfile( - to_bytes(real_in_path, errors="surrogate_or_strict"), - to_bytes(out_path, errors="surrogate_or_strict"), - ) + display.vvv(f"FETCH: {in_path} -> {out_path}", host=self._container_id) + + # Lazily prepare mount point if needed + if self._mount_point is None and self.get_option("mount_detection"): + self._setup_mount_point() + + # Use direct filesystem copy if mount point is available + if self._mount_point: + try: + real_in_path = os.path.join(self._mount_point, in_path.lstrip("/")) + if os.path.exists(real_in_path): + os.makedirs(os.path.dirname(out_path), exist_ok=True) + shutil.copy2(real_in_path, out_path) + display.vvvv(f"File fetched via mount: {real_in_path}", host=self._container_id) + return + except Exception as e: + display.vvv(f"Mount fetch failed, falling back to buildah run: {e}", host=self._container_id) + + # Use buildah run with cat command and output redirection + os.makedirs(os.path.dirname(out_path), exist_ok=True) + cat_cmd = ["run", self._container_id, "cat", in_path] + self._run_buildah_command(cat_cmd, output_file=out_path, include_container=False) def close(self): - """unmount container's filesystem""" + """Close connection and cleanup resources""" super(Connection, self).close() - rc, stdout, stderr = self._buildah("umount") - display.vvvv("RC %s STDOUT %r STDERR %r" % (rc, stdout, stderr)) + + if self._mount_point: + try: + # Attempt to unmount the container + self._run_buildah_command(["umount"], check_rc=False) + display.vvvv("Container unmounted successfully", host=self._container_id) + except Exception as e: + display.vvvv(f"Unmount failed: {e}", host=self._container_id) + + # Auto-commit on close if enabled + if self.get_option("auto_commit"): + self._auto_commit_changes() + + # Clear caches + self._command_cache.clear() + self._connected = False + display.vvv("Connection closed", host=self._container_id) diff --git a/plugins/connection/podman.py b/plugins/connection/podman.py index 837032c..bd242e9 100644 --- a/plugins/connection/podman.py +++ b/plugins/connection/podman.py @@ -1,11 +1,11 @@ -# Based on the buildah connection plugin +# Based on modern Ansible connection plugin patterns # Copyright (c) 2018 Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # # Connection plugin to interact with existing podman containers. -# https://github.com/containers/libpod +# https://github.com/containers/podman # -# Written by: Tomas Tomecek (https://github.com/TomasTomecek) +# Rewritten with modern patterns and enhanced functionality from __future__ import absolute_import, division, print_function @@ -17,20 +17,26 @@ DOCUMENTATION = """ short_description: Interact with an existing podman container description: - Run commands or put/fetch files to an existing container using podman tool. + - Supports both direct execution and filesystem mounting for optimal performance. options: remote_addr: description: - - The ID of the container you want to access. + - The ID or name of the container you want to access. default: inventory_hostname vars: - - name: ansible_host - name: inventory_hostname + - name: ansible_host - name: ansible_podman_host + env: + - name: ANSIBLE_PODMAN_HOST + ini: + - section: defaults + key: remote_addr remote_user: description: - - User specified via name or UID which is used to execute commands inside the container. If you - specify the user via UID, you must set C(ANSIBLE_REMOTE_TMP) to a path that exits - inside the container and is writable by Ansible. + - User specified via name or UID which is used to execute commands inside the container. + - If you specify the user via UID, you must set C(ANSIBLE_REMOTE_TMP) to a path that exists + inside the container and is writable by Ansible. ini: - section: defaults key: remote_user @@ -42,6 +48,7 @@ DOCUMENTATION = """ description: - Extra arguments to pass to the podman command line. default: '' + type: str ini: - section: defaults key: podman_extra_args @@ -53,10 +60,63 @@ DOCUMENTATION = """ description: - Executable for podman command. default: podman + type: str vars: - name: ansible_podman_executable env: - name: ANSIBLE_PODMAN_EXECUTABLE + ini: + - section: defaults + key: podman_executable + container_timeout: + description: + - Timeout in seconds for container operations. 0 means no timeout. + default: 0 + type: int + vars: + - name: ansible_podman_timeout + env: + - name: ANSIBLE_PODMAN_TIMEOUT + ini: + - section: defaults + key: podman_timeout + mount_detection: + description: + - Enable automatic detection and use of container mount points for file operations. + default: true + type: bool + vars: + - name: ansible_podman_mount_detection + env: + - name: ANSIBLE_PODMAN_MOUNT_DETECTION + ignore_mount_errors: + description: + - Continue with copy operations even if container mounting fails. + default: true + type: bool + vars: + - name: ansible_podman_ignore_mount_errors + extra_env_vars: + description: + - Additional environment variables to set in the container. + default: {} + type: dict + vars: + - name: ansible_podman_extra_env + privilege_escalation_method: + description: + - Method to use for privilege escalation inside container. + default: 'auto' + choices: ['auto', 'sudo', 'su', 'none'] + type: str + vars: + - name: ansible_podman_privilege_escalation + working_directory: + description: + - Working directory for commands executed in the container. + type: str + vars: + - name: ansible_podman_working_directory """ import os @@ -64,179 +124,276 @@ import shlex import shutil import subprocess +from ansible.errors import AnsibleConnectionFailure from ansible.module_utils.common.process import get_bin_path -from ansible.errors import AnsibleError -from ansible.module_utils._text import to_bytes, to_native +from ansible.module_utils._text import to_bytes, to_native, to_text from ansible.plugins.connection import ConnectionBase, ensure_connect from ansible.utils.display import Display display = Display() -# this _has to be_ named Connection +class PodmanConnectionError(AnsibleConnectionFailure): + """Specific exception for podman connection issues""" + + +class ContainerNotFoundError(PodmanConnectionError): + """Exception for when container cannot be found""" + + class Connection(ConnectionBase): """ - This is a connection plugin for podman. It uses podman binary to interact with the containers + Modern connection plugin for podman with enhanced error handling and performance optimizations """ - # String used to identify this Connection class from other classes transport = "containers.podman.podman" - # We know that pipelining does not work with podman. Do not enable it, or - # users will start containers and fail to connect to them. - has_pipelining = False + has_pipelining = True def __init__(self, play_context, new_stdin, *args, **kwargs): super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs) self._container_id = self._play_context.remote_addr self._connected = False - # container filesystem will be mounted here on host + self._container_info = None self._mount_point = None - self.user = self._play_context.remote_user - display.vvvv("Using podman connection from collection") + self._executable_path = None + self._task_uuid = to_text(kwargs.get("task_uuid", "")) - def _podman(self, cmd, cmd_args=None, in_data=None, use_container_id=True): - """ - run podman executable + # No pre-validation caches to preserve performance - :param cmd: podman's command to execute (str or list) - :param cmd_args: list of arguments to pass to the command (list of str/bytes) - :param in_data: data passed to podman's stdin - :param use_container_id: whether to append the container ID to the command - :return: return code, stdout, stderr - """ - podman_exec = self.get_option("podman_executable") - try: - podman_cmd = get_bin_path(podman_exec) - except ValueError: - raise AnsibleError("%s command not found in PATH" % podman_exec) - if not podman_cmd: - raise AnsibleError("%s command not found in PATH" % podman_exec) - local_cmd = [podman_cmd] + display.vvvv("Using podman connection from collection", host=self._container_id) + + def _get_podman_executable(self): + """Get and cache podman executable path with validation""" + if self._executable_path is None: + executable = self.get_option("podman_executable") + try: + self._executable_path = get_bin_path(executable) + display.vvvv(f"Found podman executable: {self._executable_path}", host=self._container_id) + except ValueError as e: + raise PodmanConnectionError(f"Could not find {executable} in PATH: {e}") + return self._executable_path + + def _build_podman_command(self, cmd_args, include_container=True): + """Build complete podman command with all options""" + cmd = [self._get_podman_executable()] + + # Add global options if self.get_option("podman_extra_args"): - local_cmd += shlex.split(to_native(self.get_option("podman_extra_args"), errors="surrogate_or_strict")) - if isinstance(cmd, str): - local_cmd.append(cmd) + extra_args = shlex.split(to_native(self.get_option("podman_extra_args"), errors="surrogate_or_strict")) + cmd.extend(extra_args) + + # Add subcommand and arguments + if isinstance(cmd_args, str): + cmd.append(cmd_args) else: - local_cmd.extend(cmd) + cmd.extend(cmd_args) - if use_container_id: - local_cmd.append(self._container_id) - if cmd_args: - local_cmd += cmd_args - local_cmd = [to_bytes(i, errors="surrogate_or_strict") for i in local_cmd] + # Add container ID if needed + if include_container: + cmd.append(self._container_id) - display.vvv("RUN %s" % (local_cmd,), host=self._container_id) - p = subprocess.Popen( - local_cmd, - shell=False, - stdin=subprocess.PIPE, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - ) + return cmd - stdout, stderr = p.communicate(input=in_data) - display.vvvvv("STDOUT %s" % stdout) - display.vvvvv("STDERR %s" % stderr) - display.vvvvv("RC CODE %s" % p.returncode) - stdout = to_bytes(stdout, errors="surrogate_or_strict") - stderr = to_bytes(stderr, errors="surrogate_or_strict") - return p.returncode, stdout, stderr + def _run_podman_command(self, cmd_args, input_data=None, check_rc=False, include_container=True): + """Execute podman command once with error handling""" + cmd = self._build_podman_command(cmd_args, include_container) + cmd_bytes = [to_bytes(arg, errors="surrogate_or_strict") for arg in cmd] + + display.vvv(f"PODMAN EXEC: {' '.join(cmd)}", host=self._container_id) + + try: + process = subprocess.Popen( + cmd_bytes, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=False + ) + + # Only pass timeout if explicitly configured + communicate_kwargs = {} + container_timeout = self.get_option("container_timeout") + if isinstance(container_timeout, int) and container_timeout > 0: + communicate_kwargs["timeout"] = container_timeout + + stdout, stderr = process.communicate(input=input_data, **communicate_kwargs) + + display.vvvvv(f"STDOUT: {stdout}", host=self._container_id) + display.vvvvv(f"STDERR: {stderr}", host=self._container_id) + display.vvvvv(f"RC: {process.returncode}", host=self._container_id) + + if process.returncode != 0: + error_msg = to_text(stderr, errors="surrogate_or_strict").strip() + lower = error_msg.lower() + if "no such container" in lower or "does not exist" in lower or "container not known" in lower: + self._connected = False + raise ContainerNotFoundError(f"Container '{self._container_id}' not found") + if check_rc: + raise PodmanConnectionError(f"Command failed (rc={process.returncode}): {error_msg}") + + return process.returncode, stdout, stderr + + except subprocess.TimeoutExpired: + process.kill() + timeout_val = self.get_option("container_timeout") + self._connected = False + raise PodmanConnectionError(f"Command timeout after {timeout_val}s") + except Exception as e: + raise PodmanConnectionError(f"Command execution failed: {e}") + + # No proactive validation; rely on operation failures for performance + + def _setup_mount_point(self): + """Attempt to mount container filesystem for direct access (lightweight)""" + if not self.get_option("mount_detection"): + return + + try: + rc, stdout, stderr = self._run_podman_command(["mount"]) + if rc == 0: + mount_point = to_text(stdout, errors="surrogate_or_strict").strip() + if mount_point and os.path.isdir(mount_point): + self._mount_point = mount_point + display.vvv(f"Container mounted at: {self._mount_point}", host=self._container_id) + else: + display.vvv("Container mount point is invalid", host=self._container_id) + else: + display.vvv( + f"Container mount failed: {to_text(stderr, errors='surrogate_or_strict')}", host=self._container_id + ) + except Exception as e: + if not self.get_option("ignore_mount_errors"): + raise PodmanConnectionError(f"Mount setup failed: {e}") + display.vvv(f"Mount setup failed, continuing without mount: {e}", host=self._container_id) def _connect(self): - """ - no persistent connection is being maintained, mount container's filesystem - so we can easily access it - """ + """Establish connection to container with validation and setup""" super(Connection, self)._connect() - rc, self._mount_point, stderr = self._podman("mount") - if rc != 0: - display.vvvv("Failed to mount container %s: %s" % (self._container_id, stderr.strip())) - elif not os.listdir(self._mount_point.strip()): - display.vvvv("Failed to mount container with CGroups2: empty dir %s" % self._mount_point.strip()) - self._mount_point = None - else: - self._mount_point = self._mount_point.strip() - display.vvvvv("MOUNTPOINT %s RC %s STDERR %r" % (self._mount_point, rc, stderr)) + + if self._connected: + return + + display.vvv(f"Connecting to container: {self._container_id}", host=self._container_id) + self._connected = True + display.vvv("Connection established successfully", host=self._container_id) @ensure_connect def exec_command(self, cmd, in_data=None, sudoable=False): - """run specified command in a running OCI container using podman""" + """Execute command in container with enhanced error handling""" super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable) - # shlex.split has a bug with text strings on Python-2.6 and can only handle text strings on Python-3 + display.vvv(f"EXEC: {cmd}", host=self._container_id) + cmd_args_list = shlex.split(to_native(cmd, errors="surrogate_or_strict")) - exec_args_list = ["exec"] - if self.user: - exec_args_list.extend(("--user", self.user)) + exec_cmd = ["exec"] - rc, stdout, stderr = self._podman(exec_args_list, cmd_args_list, in_data) + # Add interactive flag only when input is provided + if in_data is not None: + exec_cmd.append("-i") - display.vvvvv("STDOUT %r STDERR %r" % (stderr, stderr)) + # Handle user specification + if self.get_option("remote_user"): + exec_cmd.extend(["--user", self.get_option("remote_user")]) + + # Add extra environment variables + extra_env = self.get_option("extra_env_vars") + if extra_env: + for key, value in extra_env.items(): + exec_cmd.extend(["--env", f"{key}={value}"]) + + # Handle privilege escalation only when explicitly requested + privilege_method = self.get_option("privilege_escalation_method") + if sudoable and privilege_method != "none" and privilege_method != "auto": + if privilege_method == "sudo": + cmd_args_list = ["sudo", "-n"] + cmd_args_list + elif privilege_method == "su": + cmd_args_list = ["su", "-c", " ".join(shlex.quote(arg) for arg in cmd_args_list)] + + # Add working directory option + workdir = self.get_option("working_directory") + if workdir: + exec_cmd.extend(["--workdir", workdir]) + + # Combine exec command: podman exec [options] container_id command + full_cmd = exec_cmd + [self._container_id] + cmd_args_list + + rc, stdout, stderr = self._run_podman_command(full_cmd, input_data=in_data, include_container=False) return rc, stdout, stderr def put_file(self, in_path, out_path): - """Place a local file located in 'in_path' inside container at 'out_path'""" + """Transfer file to container using optimal method""" super(Connection, self).put_file(in_path, out_path) - display.vvv("PUT %s TO %s" % (in_path, out_path), host=self._container_id) - if not self._mount_point or self.user: - rc, stdout, stderr = self._podman( - "cp", - [in_path, self._container_id + ":" + out_path], - use_container_id=False, - ) - if rc != 0: - rc, stdout, stderr = self._podman( - "cp", - ["--pause=false", in_path, self._container_id + ":" + out_path], - use_container_id=False, - ) - if rc != 0: - raise AnsibleError( - "Failed to copy file from %s to %s in container %s\n%s" - % (in_path, out_path, self._container_id, stderr) - ) - if self.user: - rc, stdout, stderr = self._podman("exec", ["chown", self.user, out_path]) - if rc != 0: - raise AnsibleError( - "Failed to chown file %s for user %s in container %s\n%s" - % (out_path, self.user, self._container_id, stderr) - ) - else: - real_out_path = self._mount_point + to_bytes(out_path, errors="surrogate_or_strict") - shutil.copyfile( - to_bytes(in_path, errors="surrogate_or_strict"), - to_bytes(real_out_path, errors="surrogate_or_strict"), - ) + display.vvv(f"PUT: {in_path} -> {out_path}", host=self._container_id) + + # Lazily prepare mount point if needed + if self._mount_point is None and self.get_option("mount_detection"): + self._setup_mount_point() + + # Use direct filesystem copy if mount point is available and no user specified + if self._mount_point and not self.get_option("remote_user"): + try: + real_out_path = os.path.join(self._mount_point, out_path.lstrip("/")) + os.makedirs(os.path.dirname(real_out_path), exist_ok=True) + shutil.copy2(in_path, real_out_path) + display.vvvv(f"File copied via mount: {real_out_path}", host=self._container_id) + return + except Exception as e: + display.vvv(f"Mount copy failed, falling back to podman cp: {e}", host=self._container_id) + + # Use podman cp command + copy_cmd = ["cp", "--pause=false", in_path, f"{self._container_id}:{out_path}"] + self._run_podman_command(copy_cmd, include_container=False, check_rc=True) + + # Change ownership if user specified + if self.get_option("remote_user"): + chown_cmd = [ + "exec", + "--user", + "root", + self._container_id, + "chown", + self.get_option("remote_user"), + out_path, + ] + try: + self._run_podman_command(chown_cmd, include_container=False, check_rc=True) + except PodmanConnectionError as e: + display.warning(f"Failed to change file ownership: {e}") def fetch_file(self, in_path, out_path): - """obtain file specified via 'in_path' from the container and place it at 'out_path'""" + """Retrieve file from container using optimal method""" super(Connection, self).fetch_file(in_path, out_path) - display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self._container_id) - if not self._mount_point: - rc, stdout, stderr = self._podman( - "cp", - [self._container_id + ":" + in_path, out_path], - use_container_id=False, - ) - if rc != 0: - raise AnsibleError( - "Failed to fetch file from %s to %s from container %s\n%s" - % (in_path, out_path, self._container_id, stderr) - ) - else: - real_in_path = self._mount_point + to_bytes(in_path, errors="surrogate_or_strict") - shutil.copyfile( - to_bytes(real_in_path, errors="surrogate_or_strict"), - to_bytes(out_path, errors="surrogate_or_strict"), - ) + display.vvv(f"FETCH: {in_path} -> {out_path}", host=self._container_id) + + # Lazily prepare mount point if needed + if self._mount_point is None and self.get_option("mount_detection"): + self._setup_mount_point() + + # Use direct filesystem copy if mount point is available + if self._mount_point: + try: + real_in_path = os.path.join(self._mount_point, in_path.lstrip("/")) + if os.path.exists(real_in_path): + os.makedirs(os.path.dirname(out_path), exist_ok=True) + shutil.copy2(real_in_path, out_path) + display.vvvv(f"File fetched via mount: {real_in_path}", host=self._container_id) + return + except Exception as e: + display.vvv(f"Mount fetch failed, falling back to podman cp: {e}", host=self._container_id) + + # Use podman cp command + copy_cmd = ["cp", "--pause=false", f"{self._container_id}:{in_path}", out_path] + self._run_podman_command(copy_cmd, include_container=False, check_rc=True) def close(self): - """unmount container's filesystem""" + """Close connection and cleanup resources""" super(Connection, self).close() - # we actually don't need to unmount since the container is mounted anyway - # rc, stdout, stderr = self._podman("umount") - # display.vvvvv("RC %s STDOUT %r STDERR %r" % (rc, stdout, stderr)) + + if self._mount_point: + try: + # Attempt to unmount (optional, container keeps mount anyway) + self._run_podman_command(["umount"], check_rc=False) + display.vvvv("Container unmounted successfully", host=self._container_id) + except Exception as e: + display.vvvv(f"Unmount failed (this is usually not critical): {e}", host=self._container_id) + self._connected = False + display.vvv("Connection closed", host=self._container_id) diff --git a/tests/integration/targets/connection_buildah_advanced/runme.sh b/tests/integration/targets/connection_buildah_advanced/runme.sh new file mode 100755 index 0000000..72dcaec --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/runme.sh @@ -0,0 +1,104 @@ +#!/usr/bin/env bash + +set -o pipefail +set -eux + +# Enhanced Buildah Connection Plugin Tests +# Tests for new features and configuration options + +# New requirement from ansible-core 2.14 +export LC_ALL=en_US.UTF-8 +export LANG=en_US.UTF-8 +export LANGUAGE=en_US.UTF-8 + +# Buildah storage configuration for compatibility +export STORAGE_OPTS="overlay.mount_program=/usr/bin/fuse-overlayfs" + +function run_ansible { + ${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_buildah_features.yml -i "test_connection.inventory" \ + -e target_hosts="buildah_advanced" \ + "$@" +} + +function run_configuration_test { + local config_name="$1" + local extra_vars="$2" + echo "Testing configuration: $config_name" + + ${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_buildah_features.yml -i "test_connection.inventory" \ + -e target_hosts="buildah_advanced" \ + -e "$extra_vars" \ + "$@" +} + +echo "=== Running Enhanced Buildah Connection Tests ===" + +# Create a container +${SUDO:-} buildah from --name=buildah-container python:3.10-alpine + +# Test 1: Basic functionality with new features +echo "Test 1: Basic advanced features" +run_ansible "$@" + +# Test 2: Mount detection disabled +echo "Test 2: Mount detection disabled" +run_configuration_test "mount_disabled" "ansible_buildah_mount_detection=false" "$@" + +# Test 3: Different timeout settings +echo "Test 3: Short timeout" +run_configuration_test "short_timeout" "ansible_buildah_timeout=5" "$@" + +# Test 4: Different retry settings +echo "Test 4: More retries" +run_configuration_test "more_retries" "ansible_buildah_retries=5" "$@" + +# Test 5: Custom working directory +echo "Test 5: Custom working directory" +run_configuration_test "custom_workdir" "ansible_buildah_working_directory=/home" "$@" + +# Test 6: Auto-commit enabled +echo "Test 6: Auto-commit enabled" +run_configuration_test "auto_commit" "ansible_buildah_auto_commit=true" "$@" + +# Test 7: Custom environment variables +echo "Test 7: Custom environment variables" +run_configuration_test "custom_env" "ansible_buildah_extra_env={'CUSTOM_BUILD': 'value', 'DEBUG': 'true'}" "$@" + +# Test 8: Verify plugin identification +echo "Test 8: Plugin identification verification" +ANSIBLE_VERBOSITY=4 run_ansible "$@" | tee check_log +${SUDO:-} grep -q "Using buildah connection from collection" check_log +${SUDO:-} rm -f check_log + +# Test 9: Error handling with invalid executable +echo "Test 9: Error handling test" +set +o pipefail +ANSIBLE_BUILDAH_EXECUTABLE=fakebuildah run_ansible "$@" 2>&1 | grep "Could not find fakebuildah in PATH" +test_result=$? +set -o pipefail + +if [ $test_result -eq 0 ]; then + echo "Error handling test passed" +else + echo "Error handling test failed - error message not found" + exit 1 +fi + +# Test 10: Performance test with multiple operations +echo "Test 10: Performance test" +time run_ansible "$@" > /tmp/buildah_performance_test.log 2>&1 +echo "Performance test completed - check /tmp/buildah_performance_test.log for timing" + +echo "Test 11: Missing buildah container exec" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_exec.yml -i "test_connection.inventory" + +echo "Test 12: Buildah removed between exec" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_removed_between_exec.yml -i "test_connection.inventory" + +echo "Test 13: Buildah put/fetch on missing container" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_put_fetch.yml -i "test_connection.inventory" + +echo "Test 14: Buildah stdin on missing container" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_stdin.yml -i "test_connection.inventory" + +echo "=== All Enhanced Buildah Connection Tests Completed Successfully ===" diff --git a/tests/integration/targets/connection_buildah_advanced/test_buildah_features.yml b/tests/integration/targets/connection_buildah_advanced/test_buildah_features.yml new file mode 100644 index 0000000..9847c4b --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_buildah_features.yml @@ -0,0 +1,209 @@ +--- +# Advanced Buildah Connection Plugin Tests +# Tests new features and configuration options in the rewritten plugin + +- hosts: "{{ target_hosts }}" + gather_facts: false + serial: 1 + tasks: + + ### Test basic buildah functionality + + - name: Test basic command execution + raw: echo "Testing enhanced buildah connection" + register: basic_test + + - name: Verify basic command output + assert: + that: + - "'Testing enhanced buildah connection' in basic_test.stdout" + + ### Test environment variables injection + + - name: Test environment variable injection + raw: printenv BUILD_VAR + register: env_test + vars: + ansible_buildah_extra_env: + BUILD_VAR: "build_value" + CONTAINER_TYPE: "buildah" + + - name: Verify environment variables were set + assert: + that: + - "'build_value' in env_test.stdout" + + ### Test timeout configuration + + - name: Test command timeout with quick command + raw: sh -c 'sleep 0.1 && echo "Quick buildah command completed"' + register: quick_command + vars: + ansible_buildah_timeout: 10 + + - name: Verify quick command succeeded + assert: + that: + - "'Quick buildah command completed' in quick_command.stdout" + + ### Test working directory functionality + + - name: Test working directory setting + raw: pwd + register: workdir_test + vars: + ansible_buildah_working_directory: "/tmp" + + - name: Create test file in working directory + raw: sh -c 'echo "buildah test content" > test_buildah_file.txt' + vars: + ansible_buildah_working_directory: "/tmp" + + - name: Verify file was created in working directory + raw: cat /tmp/test_buildah_file.txt + register: file_content + + - name: Verify file content + assert: + that: + - "'buildah test content' in file_content.stdout" + + ### Test file operations with mount detection + + - name: Create test file locally + copy: + content: "Buildah test file content with mount detection" + dest: /tmp/buildah_test_file + delegate_to: localhost + + - name: Copy file with mount detection enabled + copy: + src: /tmp/buildah_test_file + dest: /tmp/remote_buildah_test + vars: + ansible_buildah_mount_detection: true + + - name: Verify file was copied + raw: cat /tmp/remote_buildah_test + register: mount_test + + - name: Verify file content + assert: + that: + - "'Buildah test file content with mount detection' in mount_test.stdout" + + ### Test different user contexts + + - name: Test command execution with root user + raw: whoami + register: user_test + vars: + ansible_user: root + + - name: Verify user context (may be root or container default) + debug: + msg: "Current user: {{ user_test.stdout.strip() }}" + + ### Test retry mechanism + + - name: Test retry mechanism with valid command + raw: echo "Buildah retry test successful" + register: retry_test + vars: + ansible_buildah_retries: 2 + + - name: Verify retry test succeeded + assert: + that: + - "'Buildah retry test successful' in retry_test.stdout" + + ### Test container building scenarios + + - name: Install package in container (basic build operation) + raw: sh -c 'which apk >/dev/null && apk add --no-cache curl || true' + register: package_install + ignore_errors: true + + - name: Test that package installation succeeded + debug: + msg: "Package installation completed: {{ package_install.rc }}" + when: package_install is defined + + ### Test Unicode and special characters + + - name: Test unicode command output + raw: echo "Buildah测试中文字符" + register: unicode_test + + - name: Verify unicode output + assert: + that: + - "'Buildah测试中文字符' in unicode_test.stdout" + + ### Test connection robustness with multiple commands + + - name: Test connection robustness with multiple commands + raw: echo "Buildah command {{ item }}" + register: multiple_commands + loop: [1, 2, 3, 4, 5] + + - name: Verify all commands executed successfully + assert: + that: + - multiple_commands.results | length == 5 + - "'Buildah command 1' in multiple_commands.results[0].stdout" + - "'Buildah command 5' in multiple_commands.results[4].stdout" + + ### Test complex shell operations + + - name: Test complex shell command with pipes + raw: sh -c 'echo "buildah test data" | wc -w' + register: complex_shell + + - name: Verify complex shell operation + assert: + that: + - complex_shell.stdout.strip() | int == 3 + + ### Test container inspection capabilities + + - name: Test container info retrieval + raw: echo $HOSTNAME + register: hostname_test + + - name: Verify hostname is set + assert: + that: + - hostname_test.stdout.strip() | length > 0 + + ### Test file system operations + + - name: Create directory structure + raw: mkdir -p /tmp/buildah_test/dir1 /tmp/buildah_test/dir2 + + - name: Create files in directory structure + raw: sh -c 'echo "{{ item }}" > /tmp/buildah_test/dir{{ item }}/file{{ item }}.txt' + loop: [1, 2] + + - name: List created files + raw: sh -c 'find /tmp/buildah_test -name "*.txt" | sort' + register: file_list + + - name: Verify file structure + assert: + that: + - "'file1.txt' in file_list.stdout" + - "'file2.txt' in file_list.stdout" + + ### Cleanup + + - name: Clean up test files in container + raw: rm -rf /tmp/buildah_test /tmp/remote_buildah_test /tmp/test_buildah_file.txt + ignore_errors: true + + - name: Clean up local test files + file: + path: /tmp/buildah_test_file + state: absent + delegate_to: localhost + ignore_errors: true diff --git a/tests/integration/targets/connection_buildah_advanced/test_connection.inventory b/tests/integration/targets/connection_buildah_advanced/test_connection.inventory new file mode 100644 index 0000000..a809244 --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_connection.inventory @@ -0,0 +1,22 @@ +[buildah_advanced] +buildah-container + +[buildah_advanced:vars] +ansible_host=buildah-container +ansible_connection=containers.podman.buildah +ansible_ssh_pipelining=true + +# Test different configurations +# Basic configuration with timeout +ansible_buildah_timeout=30 +ansible_buildah_retries=3 + +# Mount detection enabled by default +ansible_buildah_mount_detection=true +ansible_buildah_ignore_mount_errors=true + +# Additional environment variables +ansible_buildah_extra_env={"BUILDAH_TESTING": "true", "BUILD_MODE": "test"} + +# Auto-commit disabled for testing +ansible_buildah_auto_commit=false diff --git a/tests/integration/targets/connection_buildah_advanced/test_missing_container_exec.yml b/tests/integration/targets/connection_buildah_advanced/test_missing_container_exec.yml new file mode 100644 index 0000000..39c37bf --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_missing_container_exec.yml @@ -0,0 +1,25 @@ +--- +- name: Define a missing Buildah host dynamically + hosts: localhost + gather_facts: false + tasks: + - name: Add a missing buildah container host + add_host: + name: missing_buildah_host + ansible_connection: containers.podman.buildah + ansible_host: ci-missing-buildah + +- name: Exec on non-existent buildah container should raise ContainerNotFoundError + hosts: missing_buildah_host + gather_facts: false + tasks: + - name: Try exec on missing container + raw: echo hi + register: r + ignore_errors: true + + - name: Assert ContainerNotFoundError surfaced + assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_buildah_advanced/test_missing_container_put_fetch.yml b/tests/integration/targets/connection_buildah_advanced/test_missing_container_put_fetch.yml new file mode 100644 index 0000000..b1f747d --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_missing_container_put_fetch.yml @@ -0,0 +1,29 @@ +--- +- name: Buildah put/fetch on missing container + hosts: localhost + gather_facts: false + vars: + ansible_connection: containers.podman.buildah + ansible_host: ci-missing-buildah + tasks: + - name: Put should fail + copy: + content: abc + dest: /root/a.txt + register: r_put + ignore_errors: true + + - name: Fetch should fail + fetch: + src: /etc/os-release + dest: /tmp/osr + flat: true + register: r_fetch + ignore_errors: true + + - assert: + that: + - r_put is failed + - r_put.msg is search("Container .* not found") + - r_fetch is failed + - r_fetch.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_buildah_advanced/test_missing_container_stdin.yml b/tests/integration/targets/connection_buildah_advanced/test_missing_container_stdin.yml new file mode 100644 index 0000000..85a2903 --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_missing_container_stdin.yml @@ -0,0 +1,17 @@ +--- +- name: Buildah stdin path on missing container + hosts: localhost + gather_facts: false + vars: + ansible_connection: containers.podman.buildah + ansible_host: ci-missing-buildah + tasks: + - name: Cat with stdin should raise ContainerNotFoundError + raw: cat -n + register: r + ignore_errors: true + + - assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_buildah_advanced/test_removed_between_exec.yml b/tests/integration/targets/connection_buildah_advanced/test_removed_between_exec.yml new file mode 100644 index 0000000..a1ec83c --- /dev/null +++ b/tests/integration/targets/connection_buildah_advanced/test_removed_between_exec.yml @@ -0,0 +1,32 @@ +--- +- name: Buildah container removed between tasks + hosts: localhost + gather_facts: false + vars: + wk: ci-bu-wk + tasks: + - name: Create working container + shell: buildah from --name {{ wk }} alpine:latest + + - name: First exec via buildah connection + vars: + ansible_connection: containers.podman.buildah + ansible_host: "{{ wk }}" + raw: uname -a + + - name: Remove working container + shell: buildah rm -f {{ wk }} + changed_when: true + + - name: Second exec should raise ContainerNotFoundError + vars: + ansible_connection: containers.podman.buildah + ansible_host: "{{ wk }}" + raw: echo later + register: r + ignore_errors: true + + - assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_podman/runme.sh b/tests/integration/targets/connection_podman/runme.sh index 598794e..9fed022 100755 --- a/tests/integration/targets/connection_podman/runme.sh +++ b/tests/integration/targets/connection_podman/runme.sh @@ -19,7 +19,7 @@ ANSIBLE_VERBOSITY=4 ANSIBLE_REMOTE_TMP="/tmp" ANSIBLE_REMOTE_USER="1000" run_ans ${SUDO:-} grep -q "Using podman connection from collection" check_log ${SUDO:-} rm -f check_log set +o pipefail -ANSIBLE_PODMAN_EXECUTABLE=fakepodman run_ansible "$@" 2>&1 | grep "fakepodman command not found in PATH" +ANSIBLE_PODMAN_EXECUTABLE=fakepodman run_ansible "$@" 2>&1 | grep "Could not find fakepodman in PATH" set -o pipefail ANSIBLE_PODMAN_EXECUTABLE=fakepodman run_ansible "$@" && { echo "Playbook with fakepodman should fail!" diff --git a/tests/integration/targets/connection_podman_advanced/runme.sh b/tests/integration/targets/connection_podman_advanced/runme.sh new file mode 100755 index 0000000..0bc99ee --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/runme.sh @@ -0,0 +1,92 @@ +#!/usr/bin/env bash + +set -o pipefail +set -eux + +# Enhanced Podman Connection Plugin Tests +# Tests for new features and configuration options + +function run_ansible { + ${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_advanced_features.yml -i "test_connection.inventory" \ + -e target_hosts="podman_advanced" \ + "$@" +} + +function run_configuration_test { + local config_name="$1" + local extra_vars="$2" + echo "Testing configuration: $config_name" + + ${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_advanced_features.yml -i "test_connection.inventory" \ + -e target_hosts="podman_advanced" \ + -e "$extra_vars" \ + "$@" +} + +echo "=== Running Enhanced Podman Connection Tests ===" + +# Create a container +${SUDO} podman run -d --name "podman-container" python:3.10-alpine sleep 1d + +# Test 1: Basic functionality with new features +echo "Test 1: Basic advanced features" +run_ansible "$@" + +# Test 2: Mount detection disabled +echo "Test 2: Mount detection disabled" +run_configuration_test "mount_disabled" "ansible_podman_mount_detection=false" "$@" + +# Test 3: Different timeout settings +echo "Test 3: Short timeout" +run_configuration_test "short_timeout" "ansible_podman_timeout=5" "$@" + +# Test 4: Different retry settings +echo "Test 4: More retries" +run_configuration_test "more_retries" "ansible_podman_retries=5" "$@" + +# Test 5: Different user context +echo "Test 5: Root user context" +run_configuration_test "root_user" "ansible_user=root" "$@" + +# Test 6: Custom environment variables +echo "Test 6: Custom environment variables" +run_configuration_test "custom_env" "ansible_podman_extra_env={'CUSTOM_TEST': 'value', 'DEBUG': 'true'}" "$@" + +# Test 7: Verify plugin identification +echo "Test 7: Plugin identification verification" +ANSIBLE_VERBOSITY=4 run_ansible "$@" | tee check_log +${SUDO:-} grep -q "Using podman connection from collection" check_log +${SUDO:-} rm -f check_log + +# Test 8: Error handling with invalid executable +echo "Test 8: Error handling test" +set +o pipefail +ANSIBLE_PODMAN_EXECUTABLE=fakepodman run_ansible "$@" 2>&1 | grep "Could not find fakepodman in PATH" +test_result=$? +set -o pipefail + +if [ $test_result -eq 0 ]; then + echo "Error handling test passed" +else + echo "Error handling test failed - error message not found" + exit 1 +fi + +# Test 9: Performance test with multiple operations +echo "Test 9: Performance test" +time run_ansible "$@" > /tmp/performance_test.log 2>&1 +echo "Performance test completed - check /tmp/performance_test.log for timing" + +echo "Test 10: Missing container exec" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_exec.yml -i "test_connection.inventory" + +echo "Test 11: Removed between exec" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_removed_between_exec.yml -i "test_connection.inventory" + +echo "Test 12: Missing container put" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_put.yml -i "test_connection.inventory" + +echo "Test 13: Missing container fetch" +${SUDO:-} ${ANSIBLECMD:-ansible-playbook} test_missing_container_fetch.yml -i "test_connection.inventory" + +echo "=== All Enhanced Podman Connection Tests Completed Successfully ===" diff --git a/tests/integration/targets/connection_podman_advanced/test_advanced_features.yml b/tests/integration/targets/connection_podman_advanced/test_advanced_features.yml new file mode 100644 index 0000000..59f4072 --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_advanced_features.yml @@ -0,0 +1,248 @@ +--- +# Advanced Podman Connection Plugin Tests +# Tests new features and configuration options in the rewritten plugin + +- hosts: "{{ target_hosts }}" + gather_facts: false + serial: 1 + tasks: + + ### Test new configuration options + + - name: Test basic command execution + raw: echo "Testing enhanced podman connection" + register: basic_test + + - name: Verify basic command output + assert: + that: + - "'Testing enhanced podman connection' in basic_test.stdout" + + ### Test environment variables injection + + - name: Test environment variable injection + raw: printenv TEST_VAR + register: env_test + vars: + ansible_podman_extra_env: + TEST_VAR: "custom_value" + ANOTHER_VAR: "another_value" + + - name: Verify environment variables were set + assert: + that: + - "'custom_value' in env_test.stdout" + + ### Test timeout configuration + + - name: Test command timeout with quick command + raw: sh -c 'sleep 0.1 && echo "Quick command completed"' + register: quick_command + vars: + ansible_podman_timeout: 5 + + - name: Verify quick command succeeded + assert: + that: + - "'Quick command completed' in quick_command.stdout" + + ### Test retry mechanism with valid command + + - name: Test retry mechanism with initially failing but eventually succeeding command + raw: echo "Retry test successful" + register: retry_test + vars: + ansible_podman_retries: 2 + + - name: Verify retry test succeeded + assert: + that: + - "'Retry test successful' in retry_test.stdout" + + ### Test file operations with mount detection + + - name: Create test file locally + copy: + content: "Test file content with mount detection enabled" + dest: /tmp/test_mount_file + delegate_to: localhost + + - name: Copy file with mount detection enabled + copy: + src: /tmp/test_mount_file + dest: /tmp/remote_mount_test + vars: + ansible_podman_mount_detection: true + + - name: Verify file was copied + raw: cat /tmp/remote_mount_test + register: mount_test + + - name: Verify file content + assert: + that: + - "'Test file content with mount detection enabled' in mount_test.stdout" + + - name: Fetch file with mount detection + fetch: + src: /tmp/remote_mount_test + dest: /tmp/fetched_mount_test + flat: true + vars: + ansible_podman_mount_detection: true + + - name: Verify fetched file content + command: + cmd: cat /tmp/fetched_mount_test + register: fetched_content + delegate_to: localhost + + - name: Verify fetched file content is correct + assert: + that: + - "'Test file content with mount detection enabled' in fetched_content.stdout" + + ### Test file operations with mount detection disabled + + - name: Copy file with mount detection disabled + copy: + src: /tmp/test_mount_file + dest: /tmp/remote_no_mount_test + vars: + ansible_podman_mount_detection: false + + - name: Verify file was copied without mount + raw: cat /tmp/remote_no_mount_test + register: no_mount_test + + - name: Verify file content without mount + assert: + that: + - "'Test file content with mount detection enabled' in no_mount_test.stdout" + + ### Test user specification + + - name: Test command execution with specific user + raw: whoami + register: user_test + vars: + ansible_user: root + + - name: Verify user context + assert: + that: + - "'root' in user_test.stdout" + + ### Test large file transfer + + - name: Create large test file locally + command: + cmd: head -c 1M /dev/zero + register: large_file_content + delegate_to: localhost + + - name: Write large file locally + copy: + content: "{{ large_file_content.stdout }}" + dest: /tmp/large_test_file + delegate_to: localhost + + - name: Copy large file to container + copy: + src: /tmp/large_test_file + dest: /tmp/remote_large_file + + - name: Verify large file size + raw: wc -c /tmp/remote_large_file | cut -d' ' -f1 + register: large_file_size + + - name: Verify large file was copied correctly + assert: + that: + - large_file_size.stdout | int >= 1000000 + + ### Test Unicode and special characters + + - name: Test unicode command output + raw: echo "测试中文字符" + register: unicode_test + + - name: Verify unicode output + assert: + that: + - "'测试中文字符' in unicode_test.stdout" + + - name: Create unicode filename test + copy: + content: "Unicode filename test content" + dest: "/tmp/测试文件.txt" + + - name: Verify unicode file was created + raw: cat "/tmp/测试文件.txt" + register: unicode_file_test + + - name: Verify unicode file content + assert: + that: + - "'Unicode filename test content' in unicode_file_test.stdout" + + ### Test connection recovery and error handling + + - name: Test connection robustness with multiple commands + raw: echo "Command {{ item }}" + register: multiple_commands + loop: [1, 2, 3, 4, 5] + + - name: Verify all commands executed successfully + assert: + that: + - multiple_commands.results | length == 5 + - "'Command 1' in multiple_commands.results[0].stdout" + - "'Command 5' in multiple_commands.results[4].stdout" + + ### Test complex shell operations + + - name: Test complex shell command with pipes and redirects + raw: sh -c 'echo "test data" | wc -c | tr -d "\n"' + register: complex_shell + + - name: Verify complex shell operation + assert: + that: + - complex_shell.stdout | int == 10 + + ### Test working directory + + - name: Test working directory commands + raw: pwd + register: pwd_test + + - name: Create directory and test relative path + raw: sh -c 'mkdir -p /tmp/test_workdir && cd /tmp/test_workdir && pwd' + register: workdir_test + + - name: Verify working directory operations + assert: + that: + - "'/tmp/test_workdir' in workdir_test.stdout" + + ### Cleanup + + - name: Clean up test files + raw: rm -f /tmp/remote_mount_test /tmp/remote_no_mount_test /tmp/remote_large_file /tmp/测试文件.txt + ignore_errors: true + + - name: Clean up test directory + raw: rm -rf /tmp/test_workdir + ignore_errors: true + + - name: Clean up local test files + file: + path: "{{ item }}" + state: absent + loop: + - /tmp/test_mount_file + - /tmp/fetched_mount_test + - /tmp/large_test_file + delegate_to: localhost + ignore_errors: true diff --git a/tests/integration/targets/connection_podman_advanced/test_connection.inventory b/tests/integration/targets/connection_podman_advanced/test_connection.inventory new file mode 100644 index 0000000..3831cc1 --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_connection.inventory @@ -0,0 +1,22 @@ +[podman_advanced] +podman-container + +[podman_advanced:vars] +ansible_host=podman-container +ansible_connection=containers.podman.podman +ansible_python_interpreter=/usr/local/bin/python + +# Test different configurations +# Basic configuration with timeout +ansible_podman_timeout=30 +ansible_podman_retries=3 + +# Mount detection enabled by default +ansible_podman_mount_detection=true +ansible_podman_ignore_mount_errors=true + +# Additional environment variables +ansible_podman_extra_env={"TESTING": "true", "PLUGIN_VERSION": "2.0"} + +# Connection caching and performance +ansible_podman_timeout=15 diff --git a/tests/integration/targets/connection_podman_advanced/test_missing_container_exec.yml b/tests/integration/targets/connection_podman_advanced/test_missing_container_exec.yml new file mode 100644 index 0000000..2d3efe6 --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_missing_container_exec.yml @@ -0,0 +1,25 @@ +--- +- name: Define a missing Podman host dynamically + hosts: localhost + gather_facts: false + tasks: + - name: Add a missing container host + add_host: + name: missing_podman_host + ansible_connection: containers.podman.podman + ansible_host: ci-missing-podman + +- name: Exec on non-existent container should raise ContainerNotFoundError + hosts: missing_podman_host + gather_facts: false + tasks: + - name: Try exec on missing container + raw: id -u + register: r + ignore_errors: true + + - name: Assert ContainerNotFoundError surfaced + assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_podman_advanced/test_missing_container_fetch.yml b/tests/integration/targets/connection_podman_advanced/test_missing_container_fetch.yml new file mode 100644 index 0000000..6eb8c94 --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_missing_container_fetch.yml @@ -0,0 +1,21 @@ +--- +- name: Fetch from missing Podman container + hosts: localhost + gather_facts: false + vars: + ansible_connection: containers.podman.podman + ansible_host: ci-missing-podman + tasks: + - name: Fetch should raise ContainerNotFoundError + fetch: + src: /etc/os-release + dest: /tmp/os-release + flat: true + register: r + ignore_errors: true + + - name: Assert ContainerNotFoundError surfaced + assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_podman_advanced/test_missing_container_put.yml b/tests/integration/targets/connection_podman_advanced/test_missing_container_put.yml new file mode 100644 index 0000000..1ce577b --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_missing_container_put.yml @@ -0,0 +1,26 @@ +--- +- name: Put file to missing Podman container + hosts: localhost + gather_facts: false + vars: + ansible_connection: containers.podman.podman + ansible_host: ci-missing-podman + tasks: + - name: Create temp file on controller + copy: + content: podman-put-test + dest: /tmp/podman-put-test.txt + delegate_to: localhost + + - name: Put file should raise ContainerNotFoundError + copy: + src: /tmp/podman-put-test.txt + dest: /root/put-here.txt + register: r + ignore_errors: true + + - name: Assert ContainerNotFoundError surfaced + assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/integration/targets/connection_podman_advanced/test_removed_between_exec.yml b/tests/integration/targets/connection_podman_advanced/test_removed_between_exec.yml new file mode 100644 index 0000000..e85dfd2 --- /dev/null +++ b/tests/integration/targets/connection_podman_advanced/test_removed_between_exec.yml @@ -0,0 +1,26 @@ +--- +- name: Removed between exec for Podman + hosts: podman_advanced + gather_facts: false + vars: + ansible_connection: containers.podman.podman + tasks: + - name: First exec works + raw: uname -s + + - name: Remove this container from host + delegate_to: localhost + become: false + shell: podman rm -f {{ inventory_hostname }} + changed_when: true + + - name: Second exec should fail with ContainerNotFoundError + raw: echo hello + register: r + ignore_errors: true + + - name: Assert ContainerNotFoundError surfaced + assert: + that: + - r is failed + - r.msg is search("Container .* not found") diff --git a/tests/sanity/ignore-2.10.txt b/tests/sanity/ignore-2.10.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.10.txt +++ b/tests/sanity/ignore-2.10.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.11.txt b/tests/sanity/ignore-2.11.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.11.txt +++ b/tests/sanity/ignore-2.11.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.12.txt b/tests/sanity/ignore-2.12.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.12.txt +++ b/tests/sanity/ignore-2.12.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.13.txt b/tests/sanity/ignore-2.13.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.13.txt +++ b/tests/sanity/ignore-2.13.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.14.txt b/tests/sanity/ignore-2.14.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.14.txt +++ b/tests/sanity/ignore-2.14.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.15.txt +++ b/tests/sanity/ignore-2.15.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.16.txt +++ b/tests/sanity/ignore-2.16.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.17.txt b/tests/sanity/ignore-2.17.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.17.txt +++ b/tests/sanity/ignore-2.17.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.18.txt b/tests/sanity/ignore-2.18.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.18.txt +++ b/tests/sanity/ignore-2.18.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.19.txt b/tests/sanity/ignore-2.19.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.19.txt +++ b/tests/sanity/ignore-2.19.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.20.txt b/tests/sanity/ignore-2.20.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.20.txt +++ b/tests/sanity/ignore-2.20.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip diff --git a/tests/sanity/ignore-2.9.txt b/tests/sanity/ignore-2.9.txt index 8b29803..d976669 100644 --- a/tests/sanity/ignore-2.9.txt +++ b/tests/sanity/ignore-2.9.txt @@ -1,3 +1,5 @@ tests/integration/targets/connection_buildah/runme.sh shellcheck:SC2086 tests/integration/targets/connection_podman/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_podman_advanced/runme.sh shellcheck:SC2086 +tests/integration/targets/connection_buildah_advanced/runme.sh shellcheck:SC2086 tests/integration/targets/podman_play/tasks/files/multi-yaml.yml yamllint!skip