Ansible

Ansible automatiza a configuração de servidores e serviços com playbooks YAML e módulos idempotentes. Equipes Python o utilizam para inicializar hosts, implantar aplicativos e impor o endurecimento básico do sistema operacional sem manter scripts shell imperativos.

Receita

Cartão de referência rápida - pronto para copiar e colar.

# playbook.yml
- hosts: web
  become: true
  tasks:
    - name: Ensure app directory exists
      ansible.builtin.file:
        path: /opt/myapp
        state: directory
        mode: "0755"
    - name: Deploy config
      ansible.builtin.template:
        src: templates/app.env.j2
        dest: /opt/myapp/.env
        mode: "0600"

ansible-playbook -i inventory.ini playbook.yml --check
ansible-playbook -i inventory.ini playbook.yml

Quando usar:

Configuração de SO e pacotes em VMs ou bare metal
Fluxos de trabalho SSH sem agente sem instalar daemons nos alvos
Convergência ad-hoc quando você precisa de relatórios de idempotência changed=0
Conexão entre IaC e aplicativos - a nuvem cria instâncias, o Ansible as configura
Pequenas equipes que preferem YAML a um programa completo Pulumi/Terraform

Exemplo de Trabalho

Um projeto mínimo com inventário, role e template Jinja2 implantado via ansible-playbook.

# inventory.ini
[web]
web1 ansible_host=127.0.0.1 ansible_connection=local

# site.yml
- hosts: web
  roles:
    - myapp

# roles/myapp/tasks/main.yml
- name: Create app user
  ansible.builtin.user:
    name: myapp
    system: true
    shell: /usr/sbin/nologin
 
- name: Install Python venv package (Debian family)
  ansible.builtin.apt:
    name: python3-venv
    state: present
  become: true
 
- name: Deploy environment file
  ansible.builtin.template:
    src: app.env.j2
    dest: /etc/myapp.env
    owner: root
    group: myapp
    mode: "0640"

# roles/myapp/templates/app.env.j2
APP_ENV={{ app_env | default('dev') }}
LOG_LEVEL={{ log_level | default('info') }}

ansible-playbook -i inventory.ini site.yml -e app_env=prod -e log_level=warning

O que isso demonstra:

O inventário agrupa hosts; ansible_connection=local executa em sua máquina para demonstrações
Roles agrupam tarefas, templates e padrões em unidades reutilizáveis
ansible.builtin.template renderiza Jinja2 com variáveis de -e ou group_vars
Módulos relatam changed apenas quando o estado realmente difere

Mergulho Profundo

Como Funciona

O Ansible se conecta via SSH (ou local) e envia módulos de tarefa para o alvo
Cada módulo compara o estado desejado (argumentos YAML) com o estado real e converge
Fatos são coletados uma vez por play, a menos que gather_facts: false
Handlers são executados no final do play, apenas se notificados por uma tarefa alterada
Vault criptografa segredos no repositório; descriptografa em tempo de execução com --ask-vault-pass ou arquivo de chave

Conceitos Principais

Conceito	Propósito
Inventário	Grupos de hosts e variáveis de conexão
Playbook	Plays e tarefas ordenadas
Role	Bundle reutilizável de tarefas/templates
Módulo	Unidade de trabalho idempotente (`apt`, `file`, `service`)
Handler	Reinicia o serviço apenas quando a configuração é alterada

Notas sobre Python

# Chama o Ansible do Python via ansible-runner (orquestração opcional)
import ansible_runner
 
result = ansible_runner.run(
    playbook="site.yml",
    inventory="inventory.ini",
    extravars={"app_env": "staging"},
)
assert result.status == "successful", result.stdout.read()

Armadilhas

Usar shell para tudo - perde idempotência e relatórios de changed. Correção: encontre primeiro o módulo ansible.builtin.* correspondente.
Segredos em group_vars simples - credenciais vão para o histórico do git. Correção: ansible-vault encrypt_string ou plugins de lookup de armazenamento de segredos externos.
Executar sem --check primeiro - surpresas em hosts compartilhados. Correção: simulação em CI e exigir aprovação para plays de produção.
Coleções sem versão fixada - ansible-galaxy collection install baixa a mais recente e quebra playbooks. Correção: fixe versões em requirements.yml.
Senha do Become em CI - prompts interativos falham em pipelines. Correção: sudo sem senha para o usuário de implantação ou use AWX/Tower com credenciais armazenadas.

Alternativas

Alternativa	Use Quando	Não Use Quando
Pulumi/Terraform	Ciclo de vida de recursos na nuvem	Apenas precisa de configuração de pacotes de SO em VMs existentes
Scripts Fabric/paramiko	Comandos remotos únicos	Você precisa de relatórios de convergência idempotentes
cloud-init	Apenas na primeira inicialização em novas instâncias	Correção contínua de desvio de configuração
Salt/Chef	Grande frota com agentes aceitáveis	Você quer a simplicidade do SSH sem agente

FAQs

Por que Ansible em vez de scripts shell via SSH?

Módulos comparam o estado desejado com o real e relatam contagens de changed. Scripts shell são executados cegamente e ocultam o desvio.

Posso gerenciar recursos AWS com Ansible?

Sim - use módulos da coleção amazon.aws (ec2_instance, s3_bucket). Para topologias de VPC complexas, combine Terraform/Pulumi para a nuvem e Ansible para configuração do host.

Qual a diferença entre um play e uma role?

Um play tem como alvo grupos de hosts e lista tarefas ou roles. Uma role é uma pasta reutilizável de tarefas, handlers, templates e padrões incluída por plays.

Como testar playbooks localmente?

Use ansible_connection=local no inventário ou Molecule com drivers Docker/Podman para convergir instâncias de teste efêmeras.

Quando os handlers devem ser executados?

Handlers executam uma vez no final do play, apenas se uma tarefa os notificou e relatou changed. Use para reinícios de serviço após atualizações de configuração.

Como passar valores específicos do ambiente?

Use group_vars/<group>.yml, host_vars/, ou -e key=value em tempo de execução. Mantenha a estrutura idêntica entre os ambientes, altere apenas os valores.

O Ansible requer Python no alvo?

A maioria dos módulos precisa de Python no host remoto (pré-instalado no Linux mainstream). Módulos command/shell brutos funcionam sem ele, mas perdem a idempotência.

Como acelerar grandes inventários?

Habilite o pipelining SSH, use strategy: free para hosts independentes e limite a coleta de fatos com gather_subset quando fatos completos não são necessários.

Posso executar Ansible de um venv Python 3.14?

Sim - instale ansible no venv do seu projeto com uv pip install ansible e invoque ansible-playbook desse ambiente para versões reproduzíveis.

O que é o modo de verificação?

--check simula alterações sem aplicá-las. Combine com --diff para visualizar as alterações de conteúdo de arquivo antes das execuções de produção.

Relacionado

Noções Básicas de Automação de Infraestrutura - Mentalidade de IaC e idempotência
Gerenciamento de Configuração - templating e segredos
Provisionamento de Recursos na Nuvem - ciclo de vida de recursos na nuvem
Testando Código de Infraestrutura - Molecule e verificações de política
Melhores Práticas de Automação de Infraestrutura - regras de automação auditáveis

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.

Ansible

Receita

Cartão de referência rápida - pronto para copiar e colar.

# playbook.yml
- hosts: web
  become: true
  tasks:
    - name: Ensure app directory exists
      ansible.builtin.file:
        path: /opt/myapp
        state: directory
        mode: "0755"
    - name: Deploy config
      ansible.builtin.template:
        src: templates/app.env.j2
        dest: /opt/myapp/.env
        mode: "0600"

ansible-playbook -i inventory.ini playbook.yml --check
ansible-playbook -i inventory.ini playbook.yml

Quando usar:

Configuração de SO e pacotes em VMs ou bare metal
Fluxos de trabalho SSH sem agente sem instalar daemons nos alvos
Convergência ad-hoc quando você precisa de relatórios de idempotência changed=0
Conexão entre IaC e aplicativos - a nuvem cria instâncias, o Ansible as configura
Pequenas equipes que preferem YAML a um programa completo Pulumi/Terraform

Exemplo de Trabalho

Um projeto mínimo com inventário, role e template Jinja2 implantado via ansible-playbook.

# inventory.ini
[web]
web1 ansible_host=127.0.0.1 ansible_connection=local

# site.yml
- hosts: web
  roles:
    - myapp

# roles/myapp/tasks/main.yml
- name: Create app user
  ansible.builtin.user:
    name: myapp
    system: true
    shell: /usr/sbin/nologin
 
- name: Install Python venv package (Debian family)
  ansible.builtin.apt:
    name: python3-venv
    state: present
  become: true
 
- name: Deploy environment file
  ansible.builtin.template:
    src: app.env.j2
    dest: /etc/myapp.env
    owner: root
    group: myapp
    mode: "0640"

# roles/myapp/templates/app.env.j2
APP_ENV={{ app_env | default('dev') }}
LOG_LEVEL={{ log_level | default('info') }}

ansible-playbook -i inventory.ini site.yml -e app_env=prod -e log_level=warning

O que isso demonstra:

O inventário agrupa hosts; ansible_connection=local executa em sua máquina para demonstrações
Roles agrupam tarefas, templates e padrões em unidades reutilizáveis
ansible.builtin.template renderiza Jinja2 com variáveis de -e ou group_vars
Módulos relatam changed apenas quando o estado realmente difere

Mergulho Profundo

Como Funciona

O Ansible se conecta via SSH (ou local) e envia módulos de tarefa para o alvo
Cada módulo compara o estado desejado (argumentos YAML) com o estado real e converge
Fatos são coletados uma vez por play, a menos que gather_facts: false
Handlers são executados no final do play, apenas se notificados por uma tarefa alterada
Vault criptografa segredos no repositório; descriptografa em tempo de execução com --ask-vault-pass ou arquivo de chave

Conceitos Principais

Conceito	Propósito
Inventário	Grupos de hosts e variáveis de conexão
Playbook	Plays e tarefas ordenadas
Role	Bundle reutilizável de tarefas/templates
Módulo	Unidade de trabalho idempotente (`apt`, `file`, `service`)
Handler	Reinicia o serviço apenas quando a configuração é alterada

Notas sobre Python

# Chama o Ansible do Python via ansible-runner (orquestração opcional)
import ansible_runner
 
result = ansible_runner.run(
    playbook="site.yml",
    inventory="inventory.ini",
    extravars={"app_env": "staging"},
)
assert result.status == "successful", result.stdout.read()

Armadilhas

Usar shell para tudo - perde idempotência e relatórios de changed. Correção: encontre primeiro o módulo ansible.builtin.* correspondente.
Segredos em group_vars simples - credenciais vão para o histórico do git. Correção: ansible-vault encrypt_string ou plugins de lookup de armazenamento de segredos externos.
Executar sem --check primeiro - surpresas em hosts compartilhados. Correção: simulação em CI e exigir aprovação para plays de produção.
Coleções sem versão fixada - ansible-galaxy collection install baixa a mais recente e quebra playbooks. Correção: fixe versões em requirements.yml.
Senha do Become em CI - prompts interativos falham em pipelines. Correção: sudo sem senha para o usuário de implantação ou use AWX/Tower com credenciais armazenadas.

Alternativas

Alternativa	Use Quando	Não Use Quando
Pulumi/Terraform	Ciclo de vida de recursos na nuvem	Apenas precisa de configuração de pacotes de SO em VMs existentes
Scripts Fabric/paramiko	Comandos remotos únicos	Você precisa de relatórios de convergência idempotentes
cloud-init	Apenas na primeira inicialização em novas instâncias	Correção contínua de desvio de configuração
Salt/Chef	Grande frota com agentes aceitáveis	Você quer a simplicidade do SSH sem agente

FAQs

Por que Ansible em vez de scripts shell via SSH?

Módulos comparam o estado desejado com o real e relatam contagens de changed. Scripts shell são executados cegamente e ocultam o desvio.

Posso gerenciar recursos AWS com Ansible?

Sim - use módulos da coleção amazon.aws (ec2_instance, s3_bucket). Para topologias de VPC complexas, combine Terraform/Pulumi para a nuvem e Ansible para configuração do host.

Qual a diferença entre um play e uma role?

Um play tem como alvo grupos de hosts e lista tarefas ou roles. Uma role é uma pasta reutilizável de tarefas, handlers, templates e padrões incluída por plays.

Como testar playbooks localmente?

Use ansible_connection=local no inventário ou Molecule com drivers Docker/Podman para convergir instâncias de teste efêmeras.

Quando os handlers devem ser executados?

Handlers executam uma vez no final do play, apenas se uma tarefa os notificou e relatou changed. Use para reinícios de serviço após atualizações de configuração.

Como passar valores específicos do ambiente?

Use group_vars/<group>.yml, host_vars/, ou -e key=value em tempo de execução. Mantenha a estrutura idêntica entre os ambientes, altere apenas os valores.

O Ansible requer Python no alvo?

A maioria dos módulos precisa de Python no host remoto (pré-instalado no Linux mainstream). Módulos command/shell brutos funcionam sem ele, mas perdem a idempotência.

Como acelerar grandes inventários?

Habilite o pipelining SSH, use strategy: free para hosts independentes e limite a coleta de fatos com gather_subset quando fatos completos não são necessários.

Posso executar Ansible de um venv Python 3.14?

Sim - instale ansible no venv do seu projeto com uv pip install ansible e invoque ansible-playbook desse ambiente para versões reproduzíveis.

O que é o modo de verificação?

--check simula alterações sem aplicá-las. Combine com --diff para visualizar as alterações de conteúdo de arquivo antes das execuções de produção.

Relacionado

Noções Básicas de Automação de Infraestrutura - Mentalidade de IaC e idempotência
Gerenciamento de Configuração - templating e segredos
Provisionamento de Recursos na Nuvem - ciclo de vida de recursos na nuvem
Testando Código de Infraestrutura - Molecule e verificações de política
Melhores Práticas de Automação de Infraestrutura - regras de automação auditáveis

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.

Ansible

Buscar na documentação

Ansible