ansible-podman/README.md

Podman

This Ansible role installs and configures Podman container runtime, and provides comprehensive container, pod, network, and volume management capabilities.

Requirements

• Ansible 2.11 or higher
• Target systems: Ubuntu 20.04+, Debian 11+
• containers.podman collection (for container management tasks)

Role Variables

Installation Variables

• podman_install_from_repo: Install from official repositories (default: true)
• podman_packages: List of core Podman packages to install
• podman_additional_packages: Additional packages for full container support

Configuration Variables

• podman_configure_registries: Configure container registries (default: true)
• podman_registries_conf_path: Path to registries configuration (default: /etc/containers/registries.conf)
• podman_registries_additional: Additional registry configurations for special cases

Note: Registry configuration is now unified with the image signature policy through podman_policy_trusted_registries. Each registry in the policy configuration includes both security settings (signature verification) and registry behavior (insecure, blocked, unqualified search).

• podman_configure_storage: Configure storage settings (default: true)

• podman_storage_conf_path: Path to storage configuration (default: /etc/containers/storage.conf)

• podman_storage_driver: Storage driver to use (default: overlay)

• podman_storage_runroot: Runtime storage path (default: /run/containers/storage)

• podman_storage_graphroot: Persistent storage path (default: /var/lib/containers/storage)

• podman_configure_policy: Configure container policy (default: true)

• podman_policy_path: Path to policy configuration (default: /etc/containers/policy.json)

Image Signature Policy Variables

• podman_policy_default_type: Default policy for unlisted registries ("insecureAcceptAnything" or "reject")
• podman_policy_reject_unknown_registries: Reject images from unlisted registries (default: false)
• podman_policy_trusted_registries: Unified registry configuration for both policy and registries.conf

Each registry in podman_policy_trusted_registries supports:

Security Policy Options:

• type: Verification type ("insecureAcceptAnything", "signedBy", "reject")
• keyPath: Path to GPG key file (for signedBy type)
• keyData: Inline GPG key data (alternative to keyPath)

Registry Configuration Options:

• insecure: Allow insecure (HTTP) connections (default: false)
• blocked: Block access to this registry (default: false)
• unqualified_search: Include in unqualified image searches (default: true)
• mirror: List of mirror registries for redundancy/performance

# Unified registry and policy configuration
podman_policy_trusted_registries:
  - registry: "docker.io"
    # Policy settings
    type: "insecureAcceptAnything"
    # Registry settings
    insecure: false
    blocked: false
    unqualified_search: true
  
  - registry: "internal-registry.company.com"
    # Policy settings
    type: "signedBy"
    keyPath: "/etc/pki/containers/company.gpg"
    # Registry settings
    insecure: false
    blocked: false
    unqualified_search: true
    # Mirror configuration
    mirror:
      - location: "backup-registry.company.com"
        insecure: false

# Development configuration (default)
podman_policy_default_type: "insecureAcceptAnything"
podman_policy_reject_unknown_registries: false

# Production configuration with signature verification
podman_policy_default_type: "reject"
podman_policy_reject_unknown_registries: true

Service Variables

• podman_enable_socket: Enable Podman socket service (default: false)
• podman_enable_api_service: Enable Podman API service (default: false)

Container Management Variables

podman_containers:
  - name: nginx
    image: docker.io/nginx:latest
    state: started
    ports:
      - "8080:80"
    volumes:
      - "/etc/nginx/conf.d:/etc/nginx/conf.d:ro"
    env:
      NGINX_HOST: example.com
    restart_policy: always
    user: nginx
    networks:
      - podman
    labels:
      app: webserver
      version: "1.0"

Network Management Variables

podman_networks:
  - name: app-network
    driver: bridge
    subnet: "10.89.0.0/24"
    gateway: "10.89.0.1"
    state: present
    internal: false
    disable_dns: false
    dns:
      - "8.8.8.8"
    options:
      mtu: 1500
      vlan: 100
    ipam_driver: "host-local"
    interface_name: "podman1"
    route:
      - "10.10.0.0/16,192.168.1.1"
  - name: macvlan-net
    driver: macvlan
    macvlan: "eth0"
    subnet: "192.168.1.0/24"
  - name: ipv6-net
    driver: bridge
    subnet: "fd00::/64"
    ipv6: true
    recreate: false

Volume Management Variables

podman_volumes:
  - name: app-data
    state: present
    driver: local
    labels:
      environment: production
      backup: daily
    options:
      - "device=/dev/sdb1"
      - "type=ext4"
      - "o=rw"
  - name: tmpfs-volume
    state: present
    driver: tmpfs
    options:
      - "tmpfs-size=100m"
      - "tmpfs-mode=1777"
  - name: quadlet-volume
    state: quadlet
    driver: local
    quadlet_filename: "custom-volume"
    quadlet_file_mode: "0640"
    quadlet_options:
      - "Group=192"
      - "Copy=true"
    recreate: false
    debug: false

Pod Management Variables

podman_pods:
  - name: webapp-pod
    state: started
    ports:
      - "8080:80"
      - "3306:3306"
    networks:
      - frontend
    hostname: webapp
    dns:
      - "8.8.8.8"
    labels:
      app: webapp
      tier: frontend
    volumes:
      - "webapp-data:/data"
    infra: true
    infra_image: "k8s.gcr.io/pause:3.1"
    memory: "2g"
    cpu_shares: "1024"
    security_opt:
      - "seccomp=unconfined"
    add_host:
      - "database.local:127.0.0.1"
    share: "net,ipc"
    userns: "auto"
    device:
      - "/dev/sda:/dev/xvda:rwm"
    sysctl:
      net.core.somaxconn: "1024"
    exit_policy: "stop"
  - name: quadlet-pod
    state: quadlet
    quadlet_filename: "custom-pod"
    quadlet_options:
      - "AutoUpdate=registry"
    generate_systemd:
      path: "/etc/systemd/system"
      restart_policy: "always"

Dependencies

• containers.podman collection for container management tasks

Example Playbook

- hosts: servers
  roles:
    - role: keepit.podman
      vars:
        podman_enable_socket: true
        podman_containers:
          - name: web-server
            image: nginx:latest
            state: started
            ports:
              - "80:80"
            volumes:
              - "/var/www/html:/usr/share/nginx/html:ro"
        podman_networks:
          - name: web-network
            subnet: "172.20.0.0/16"

Tags

• podman - Run all tasks
• podman-install - Install packages only
• podman-configure - Configure Podman only
• podman-services - Manage services only
• podman-networks - Manage networks only
• podman-volumes - Manage volumes only
• podman-pods - Manage pods only
• podman-containers - Manage containers only

License

MIT

Author Information

Daniel Akulenok dak@keepit.com
Keepit A/S