optimode/ansible-core repository overview

⁠Ansible Core Docker Image

A production-ready Docker image for Ansible Core with HashiCorp Vault support and 10+ pre-installed collections for simple automation, management configuration, and more.

⁠Features

• Multiple Ansible Core versions: Choose between stable (2.18) or latest (2.19)
• HashiCorp Vault integration: Built-in hvac library for seamless secrets management
• 10+ Pre-installed collections: Ready-to-use collections
• Lightweight: Based on Python slim images
• CI/CD ready: Perfect for automated pipelines

⁠Supported Versions

⁠Quick Start

⁠Basic Usage

Run an Ansible ad-hoc command:

docker run --rm optimode/ansible-core:latest ansible --version

Run a playbook from your local directory:

docker run --rm \
  -v $(pwd):/workspace \
  optimode/ansible-core:latest \
  ansible-playbook playbook.yml

⁠Interactive Shell

Start an interactive session:

docker run --rm -it \
  -v $(pwd):/workspace \
  optimode/ansible-core:latest

⁠Pre-installed Collections

This image comes with 15+ Ansible collections covering a wide range of platforms and technologies:

⁠Container

• Docker: community.docker
• Podman: containers.podman

⁠Databases

• MySQL: community.mysql
• PostgreSQL: community.postgresql
• MongoDB: community.mongodb

⁠Security & Secrets

• HashiCorp Vault: community.hashi_vault
• Cryptography: community.crypto

⁠Virtualization

• Proxmox: community.proxmox

ansible.netcommon, ansible.posix, ansible.utils, community.crypto, 
community.dns,community.docker, community.general, community.hashi_vault,
community.mongodb, community.mysql,community.postgresql, community.proxmox, 
community.proxysql,community.routeros, containers.podman,

⁠Building the Image

⁠Quick Build

Use the provided build framework: (optibuild)[https://github.com/optimode/optibuild⁠] Install optibuild, create or modify build.conf file.

Only build:

/path/to/optibuild --verbose -c /path/to/ansible-core/build.conf build

⁠Custom Build

Build a specific version, modify build.conf or create an additional build-specific-version.conf file.

/path/to/optibuild --verbose -c /path/to/ansible-core/build-specific-version.conf build

⁠Build Arguments

⁠Advanced Usage

⁠Using SSH Keys

Mount your SSH keys for remote host access:

docker run --rm \
  -v $(pwd):/workspace \
  -v ~/.ssh:/home/ansible/.ssh:ro \
  optimode/ansible-core:latest \
  ansible-playbook -i inventory.ini playbook.yml

⁠Using Ansible Vault

Pass vault password via file:

docker run --rm \
  -v $(pwd):/workspace \
  -v $(pwd)/.vault-pass:/home/ansible/.vault-pass:ro \
  optimode/ansible-core:latest \
  ansible-playbook --vault-password-file=/home/ansible/.vault-pass playbook.yml

Or via environment variable:

docker run --rm \
  -v $(pwd):/workspace \
  -e ANSIBLE_VAULT_PASSWORD=mysecret \
  optimode/ansible-core:latest \
  ansible-playbook playbook.yml

⁠HashiCorp Vault Integration

The image includes hvac library for Vault integration. Configure via environment:

docker run --rm \
  -v $(pwd):/workspace \
  -e VAULT_ADDR=https://vault.example.com:8200 \
  -e VAULT_TOKEN=s.xxxxxxxxxxxxxx \
  optimode/ansible-core:latest \
  ansible-playbook playbook.yml

⁠Custom Inventory

Use dynamic inventory or custom inventory files:

docker run --rm \
  -v $(pwd):/workspace \
  optimode/ansible-core:latest \
  ansible-playbook -i inventory/production.yml deploy.yml

⁠Installing Additional Collections

Install collections at runtime:

docker run --rm \
  -v $(pwd):/workspace \
  optimode/ansible-core:latest \
  bash -c "ansible-galaxy collection install my.collection && ansible-playbook playbook.yml"

Or build a custom image:

FROM optimode/ansible-core:latest

COPY my-collections.yml /tmp/
RUN ansible-galaxy collection install -r /tmp/my-collections.yml

⁠Running as Different User

docker run --rm \
  --user $(id -u):$(id -g) \
  -v $(pwd):/workspace \
  optimode/ansible-core:latest \
  ansible-playbook playbook.yml

⁠CI/CD Integration

⁠GitHub Actions

name: Deploy with Ansible
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Ansible Playbook
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            -e ANSIBLE_VAULT_PASSWORD=${{ secrets.VAULT_PASSWORD }} \
            optimode/ansible-core:latest \
            ansible-playbook -i inventory/production.yml deploy.yml

⁠GitLab CI

deploy:
  image: optimode/ansible-core:latest
  script:
    - ansible-playbook -i inventory/production.yml deploy.yml
  only:
    - main

⁠Environment Variables

Common Ansible environment variables you can use:

⁠Examples

⁠Example 1: Simple Playbook Execution

# Create a simple playbook
cat > playbook.yml <<EOF
---
- hosts: localhost
  tasks:
    - name: Print Ansible version
      debug:
        msg: "Running Ansible {{ ansible_version.full }}"
EOF

# Run it
docker run --rm -v $(pwd):/workspace optimode/ansible-core:latest \
  ansible-playbook playbook.yml

⁠Installed Packages

⁠Python Packages

• ansible - Full Ansible package with core
• ansible-lint - Best practices checker for Ansible
• hvac - HashiCorp Vault client library
• jmespath - JSON query language for data parsing
• netaddr - Network address manipulation
• docker - Docker SDK for Python

⁠System Packages

• git - Version control system
• openssh-client - SSH client for remote connections
• sshpass - Non-interactive SSH password authentication
• rsync - Fast file synchronization tool

⁠Troubleshooting

⁠Permission Issues

If you encounter permission errors with mounted volumes:

# Run as your current user
docker run --rm --user $(id -u):$(id -g) -v $(pwd):/workspace optimode/ansible-core:latest ansible-playbook playbook.yml

⁠SSH Connection Issues

Enable SSH debugging:

docker run --rm -v $(pwd):/workspace optimode/ansible-core:latest \
  ansible-playbook -vvv playbook.yml

⁠Collection Not Found

Verify installed collections:

docker run --rm optimode/ansible-core:latest ansible-galaxy collection list

Install missing collection:

docker run --rm optimode/ansible-core:latest \
  ansible-galaxy collection install namespace.collection

⁠Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⁠Adding New Collections

To add collections to the base image, update requirements-collections.yml.

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Maintainer

Optimode (Laszlo Malina) GitHub: @optimode⁠

⁠Resources

• Ansible Documentation⁠
• Ansible Galaxy⁠
• HashiCorp Vault⁠
• Docker Hub⁠

⁠Support

If you encounter issues or have questions:

1. Check the Troubleshooting⁠ section
2. Review Ansible documentation⁠
3. Open an issue on GitHub⁠

Built with ❤️ by Optimode