Testar roles Ansible com Molecule e Docker

O que é Molecule (definição rápida)

Molecule é uma ferramenta para testar e validar roles e playbooks Ansible em múltiplos cenários. Fornece um fluxo automatizado para criar instâncias (máquinas virtuais ou containers), aplicar suas roles e executar verificações (verifiers) como testinfra/pytest.

Importante: Molecule não substitui ferramentas de CI — ele integra-se a CI/CD para automatizar testes em pipelines.

Variantes de busca / intenção (SEO)

Intenção principal: testar roles Ansible com Molecule Termos relacionados: Molecule com Docker, testar roles Ansible, pytest-testinfra, CI de Ansible, automação de testes Ansible

Pré-requisitos

• Sistema Linux (ex.: Ubuntu 22.04 LTS). Exemplo usa host com nome ansible-test.
• Usuário não-root com privilégios sudo (ex.: alice).
• Conhecimento básico de Ansible e roles.
• Conexão à internet para baixar pacotes e imagens Docker.

Sumário rápido do fluxo

1. Instalar dependências: Python3, pip, venv, Ansible, Docker.
2. Criar e ativar venv Python.
3. Instalar Molecule e plugin Docker via pip.
4. Inicializar role com molecule init role.
5. Customizar tasks e vars do role.
6. Configurar imagem Docker na molecule.yml.
7. Criar testes com pytest-testinfra.
8. Executar molecule test (create → converge → verify → destroy).

Instalar dependências (detalhado)

Atualize o índice de pacotes e instale os pacotes básicos:

sudo apt update

Instale Python3, pip, venv, Ansible e utilitários:

sudo apt install python3 python3-pip python3-venv ansible ca-certificates curl gnupg lsb-release

Digite y quando solicitado e pressione ENTER.

Instalar Docker (Docker CE)

Crie o diretório para a chave GPG e importe a chave do repositório Docker:

sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Adicione o repositório oficial do Docker:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Atualize o índice e instale os pacotes Docker:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Adicione seu usuário ao grupo docker para executar containers sem sudo:

sudo usermod -aG docker $USER

Verifique executando o container hello-world (pode requerer re-login para aplicar o novo grupo):

docker run hello-world

Saída esperada: mensagem de sucesso do container hello-world.

Criar ambiente Python e instalar Molecule

Crie o virtual environment e ative-o:

python3 -m venv ansible-venv
source ansible-venv/bin/activate

Instale wheel, molecule e o plugin docker para Molecule:

cd ansible-venv/
pip3 install wheel molecule 'molecule-plugins[docker]'

Observação: manter Molecule no venv evita conflitos com o Python do sistema e facilita reprodutibilidade.

Inicializar um role Ansible com Molecule

Nesta seção criaremos um role chamado test.lemp que instalará um LEMP básico (Nginx, MariaDB, PHP-FPM).

Gere o boilerplate do role usando o driver docker:

molecule init role test.lemp --driver-name docker

Será criado um diretório chamado lemp com a estrutura padrão de role + molecule.

Abra o diretório e edite as tasks:

cd lemp
nano tasks/main.yml

Conteúdo para tasks/main.yml (copie exatamente):

---
- name: "Installing LEMP Stack"
  apt:
    name: "{{ pkg_list }}"
    state: present

- name: "Ensure LEMP Services is running"
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  with_items: "{{ svc_list }}"

Salve e feche.

Edite as variáveis em vars/main.yml:

nano vars/main.yml

Adicione:

---
pkg_list:
  - nginx
  - mariadb-server
  - php-fpm
  - php-cli
svc_list:
  - nginx
  - mariadb
  - php8.1-fpm

Salve e feche.

Configurar a instância de teste (imagem Docker)

Escolhemos a imagem mipguerrero26/ubuntu-python3 que já traz Python3. Ajuste se preferir outra imagem, mas garanta que Python exista.

Puxe a imagem:

docker pull mipguerrero26/ubuntu-python3

Verifique imagens locais:

docker images

Teste abrindo um container interativo:

docker run -it mipguerrero26/ubuntu-python3 /bin/bash

Dentro do container verifique versão do Python e da distribuição:

python3 --version
cat /etc/lsb-release

Saída esperada: Ubuntu 22.04 com Python3 presente.

Edite a configuração do Molecule para usar essa imagem. Abra:

nano molecule/default/molecule.yml

Na seção platforms, altere para:

platforms:
  - name: instance-ubuntu22.04
    image: mipguerrero26/ubuntu-python3
    privileged: true

Salve o arquivo.

Verifique a lista de instâncias Molecule:

molecule list

Você deverá ver instance-ubuntu22.04 com driver Docker.

Executar converge (aplicar role na instância)

Rode:

molecule converge

O fluxo cria a instância Docker e aplica o role Ansible.

Verifique containers em execução:

docker ps

Para entrar no container:

docker exec -it instance-ubuntu22.04 /bin/bash

Verifique serviços e sockets (ex.: Nginx porta 80, MariaDB 3306, PHP-FPM socket):

ss -tulpn
ss -pl | grep php

Limpe o ambiente (destruir instância Molecule):

molecule destroy

Verifique que o container foi removido:

docker ps
docker ps -a

Escrever testes com pytest-testinfra

Instale o verificador testinfra:

pip3 install pytest-testinfra

Crie o diretório de testes e arquivo:

mkdir -p molecule/default/tests/
nano molecule/default/tests/test_default.py

Adicione o script Python abaixo (mantenha identação):

import os
import pytest
import testinfra.utils.ansible_runner

testinfra_hosts = testinfra.utils.ansible_runner.AnsibleRunner(
    os.environ['MOLECULE_INVENTORY_FILE']).get_hosts('all')

@pytest.mark.parametrize('pkg', [
  'nginx',
  'mariadb-server',
  'php-fpm'
])
def test_pkg(host, pkg):
    package = host.package(pkg)

    assert package.is_installed

@pytest.mark.parametrize('svc', [
  'nginx',
  'mariadb',
  'php8.1-fpm'
])
def test_svc(host, svc):
    service = host.service(svc)

    assert service.is_running
    assert service.is_enabled

Salve o arquivo.

Edite molecule/default/molecule.yml para definir o verifier:

nano molecule/default/molecule.yml

Altere/verifique a seção verifier:

verifier:
  name: testinfra
  directory: tests

Salve o arquivo.

Execute o ciclo completo de testes:

molecule test

O comando realiza: create → converge → verify → destroy. Saída esperada ao final: collected 6 items - 6 passed in …

Sequência visual do processo (exemplos):

Fluxo recomendado de desenvolvimento com Molecule

1. molecule init role (uma vez para gerar estrutura).
2. Adicione tasks/handlers/vars/defaults/meta.
3. Modifique molecule/default/molecule.yml para ajustar plataforma e driver.
4. Escreva testes testinfra/pytest que verifiquem estado desejado.
5. Itere localmente com molecule converge + molecule verify.
6. Automatize em CI com molecule test para cada push/merge.

Comandos úteis:

molecule converge
molecule verify
molecule destroy
molecule test
molecule list
molecule --help

Checklist rápidos

• venv ativado ao instalar Molecule
• Docker funcionando sem sudo (usuário no grupo docker)
• Imagem Docker base contém Python3
• molecule/default/molecule.yml atualizado com imagem e privileged se necessário
• testes em molecule/default/tests/ com assert claros
• CI executando molecule test em runner compatível com Docker

Critérios de aceitação (Test cases/Acceptance criteria)

• O role instala os pacotes listados em pkg_list: nginx, mariadb-server, php-fpm, php-cli.
• Os serviços listados em svc_list iniciam automaticamente e estão em estado running e enabled.
• Ao executar molecule test: o pipeline conclui sem falhas (exit code 0) e os testes pytest retornam todos passed.
• Após molecule destroy não existem containers criados pelo Molecule.

Cenários onde isso falha (quando se aplica e quando não funciona)

• Em runners CI que não suportam Docker-in-Docker você precisará de runner com acesso a Docker (ex.: GitHub Actions com permissões ou runners self-hosted).
• Imagem base sem Python impede o uso de driver Docker padrão; então escolha imagens com Python ou instale-o via playbook.
• Versões do Ubuntu/Python/packagemanager podem alterar nomes de pacotes (ex.: php8.1-fpm vs php7.4-fpm). Adapte svc_list/pkg_list ao alvo.

Boas práticas e heurísticas

• Mantenha Molecule no venv por projeto para isolar versões.
• Escreva testes idempotentes: aplicar a mesma role duas vezes não deve mudar o estado.
• Prefira imagens enxutas e reproduzíveis (use tags de versão explícitas).
• Para integração em CI, dê preferência a runners com cache de imagens para acelerar testes.

Resolução de problemas comuns

• Docker permission denied depois de adicionar ao grupo docker: efetue logout/login ou reinicie a sessão.
• testinfra não encontra MOLECULE_INVENTORY_FILE: execute a partir do diretório do role com venv ativado e verifique molecule.yml.
• Falha ao instalar pacotes apt dentro do container: confirme que apt update está sendo executado no playbook antes de apt install.
• Serviços não iniciam: verifique logs com systemctl status ou journalctl -xe dentro do container.

Mini methodology: integrar Molecule em CI (exemplo genérico)

1. No pipeline, instale dependências do runner (Docker, Python, pip).
2. Ative venv e pip install -r dev-requirements.txt (com molecule e plugins).
3. Execute molecule test.
4. Armazene logs/artifacts de teste para depuração em caso de falha.

Cheatsheet de comandos e arquivos relevantes

• Estrutura do projeto:
  • lemp/ (role)
    • tasks/main.yml
    • vars/main.yml
    • molecule/default/molecule.yml
    • molecule/default/tests/test_default.py
• Comandos:
  • python3 -m venv ansible-venv
  • source ansible-venv/bin/activate
  • pip3 install molecule ‘molecule-plugins[docker]’ pytest-testinfra
  • molecule init role NAME –driver-name docker
  • molecule converge / molecule verify / molecule test / molecule destroy

Galeria de casos de borda

• Migrar para Podman: troque driver-name para podman e instale plugin correspondente.
• Testar em cloud: use drivers para cloud providers (requere credenciais configuradas) e adapte plataformas.
• Pacotes com nomes diferentes entre distros: parametrizar pkg_list por distro e usar condicionais.

Glossário (1-linha cada)

• Molecule: ferramenta para testar roles/playbooks Ansible automaticamente.
• testinfra: biblioteca Python para testar infraestrutura via pytest.
• converge: etapa de Molecule que aplica o role na instância criada.
• verifier: componente que executa testes após converge (ex.: testinfra).

Dicas de compatibilidade e migração

• Se migrar de Docker para Podman, verifique compatibilidade do plugin e diferenças em privileged, volumes e networking.
• Ao migrar entre versões do Ubuntu, confirme nomes de pacotes PHP/MariaDB e possíveis mudanças em systemd.

Prevenção de regressões e manutenção

• Adicione molecule test ao pipeline de PR para evitar regressões.
• Atualize imagens base periodicamente e verifique testes após atualizações de SO.

Sugestão de integração social (OG)

OG title: Testar roles Ansible com Molecule e Docker OG description: Guia prático para instalar Molecule, criar roles LEMP, escrever testes com testinfra e executar molecule test localmente e em CI.

Conclusão

Você aprendeu a:

• Instalar dependências (Python, Ansible, Docker);
• Criar e ativar venv e instalar Molecule com plugin Docker;
• Inicializar um role Ansible e configurar tasks/vars;
• Definir instância Docker para Molecule e rodar converge;
• Escrever testes com pytest-testinfra e executar molecule test (create → converge → verify → destroy);
• Boas práticas, critérios de aceitação e estratégias para integrar Molecule em CI.

Continue lendo a documentação oficial do Molecule e integre esses testes ao seu fluxo de entrega contínua para garantir qualidade e confiabilidade das suas roles Ansible.

Legenda: diagrama ilustrativo do fluxo Molecule (gerar role → configurar instância → converge → verify → destroy)