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"

Systemd Service Generation

The role can automatically generate systemd service files for containers and pods. This functionality helps in managing container lifecycle through systemd.

• podman_generate_systemd: Enable systemd service generation (default: true)
• podman_systemd_dir: Directory for generated service files (default: /etc/systemd/system)

Global Systemd Options (podman_systemd_options):

podman_systemd_options:
  new: true              # Generate new service files
  force: true           # Overwrite existing files
  restart_policy: unless-stopped  # Default restart policy
  time: 120             # Stop timeout in seconds
  no_header: false      # Include header in service files
  wants: []             # Systemd unit Wants
  after: []             # Systemd unit After
  requires: []          # Systemd unit Requires
  container_prefix: ""  # Prefix for container service names
  pod_prefix: ""        # Prefix for pod service names
  restart_sec: 30       # Restart delay in seconds

Per-Container/Pod Configuration:

You can override global systemd options for individual containers or pods:

podman_containers:
  - name: webapp
    image: nginx:latest
    systemd:
      restart_policy: always
      after: ["network.target"]
      wants: ["network-online.target"]
      restart_sec: 10

podman_pods:
  - name: database
    systemd:
      restart_policy: on-failure
      requires: ["network.target"]
      time: 180

When systemd is defined for a container or pod, the role will:

1. Generate a systemd service file
2. Place it in the specified directory
3. Reload systemd daemon
4. (Optional) Enable and start the service

Note: Container/pod-specific options take precedence over global options defined in podman_systemd_options.

Resource Pruning

The role can automatically clean up unused Podman resources to free up disk space and maintain system hygiene.

• podman_prune_enabled: Enable automatic pruning of unused resources (default: true)
• podman_prune_options: Configuration for what should be pruned

podman_prune_options:
  container: true    # Remove stopped containers
  image: true        # Remove unused images
  network: true      # Remove unused networks
  system: true       # Prune all unused data
  system_all: true   # Prune all unused data including build cache
  volume: true       # Remove unused volumes

You can selectively disable certain types of pruning by setting their values to false:

podman_prune_options:
  container: true    # Still remove containers
  image: false      # Keep all images
  network: true     # Remove unused networks
  system: false     # Keep system data
  system_all: false # Keep build cache
  volume: false     # Keep all volumes

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