Guia 08 / 3
Comandos Ansible
Encontrar os comandos operacionais e as suas opções para trabalhar com cuidado em servidores.
Testar o acesso, visar os anfitriões, simular, aplicar e diagnosticar um playbook Ansible.
01 · Instalar e verificar
A partir de uma máquina Linux de controlo: isolar as dependências do projeto e verificar a configuração ativa.
Criar um ambiente Python
Evita modificar os pacotes Python do sistema e isola o Ansible para o projeto.
Exemplo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ansible
O comando source destina-se ao bash/zsh; no Windows, utilizar um ambiente compatível.
ansible --version
Indica a versão da ferramenta, o Python utilizado e o caminho de ansible.cfg.
Exemplo
ansible --version
ansible-config dump --only-changed
Apresenta os parâmetros que diferem dos valores por omissão.
Exemplo
ansible-config dump --only-changed
ansible-config view
Apresenta o conteúdo do ficheiro de configuração carregado.
Exemplo
ansible-config view
ansible-doc -l
Lista os módulos e plugins documentados disponíveis.
Exemplo
ansible-doc -l | grep ansible.builtin.apt
ansible-doc [módulo]
Abre a documentação detalhada e os parâmetros de um módulo.
Exemplo
ansible-doc ansible.builtin.template
02 · Inventário, alvos e conectividade
Começar por visualizar os anfitriões visados e testar a sua acessibilidade antes de uma intervenção.
ansible-inventory --graph
Mostra a estrutura dos grupos do inventário.
Exemplo
ansible-inventory -i inventory.ini --graph
ansible-inventory --list
Produz a vista completa do inventário, com variáveis, tal como o Ansible o interpreta.
Exemplo
ansible-inventory -i inventory.ini --list
A saída pode incluir informações sensíveis presentes no inventário.
ansible [grupo] --list-hosts
Apresenta os anfitriões correspondentes ao alvo sem lançar nenhum módulo remoto.
Exemplo
ansible web -i inventory.ini --list-hosts
ansible [grupo] -m ping
Testa o acesso e a execução de um módulo Python nos anfitriões.
Exemplo
ansible web -i inventory.ini -m ansible.builtin.ping
Este ping não é um pacote ICMP: exige autenticação e Python do lado do alvo.
ansible [grupo] -m setup
Recupera os factos do sistema de um ou mais servidores.
Exemplo
ansible web -i inventory.ini -m ansible.builtin.setup
Visar um único anfitrião com --limit
Restringe um grupo ou uma execução a um subconjunto.
Exemplo
ansible-playbook -i inventory.ini site.yml --limit web1
Selecionar a conta (-u)
Indica a conta de ligação SSH.
Exemplo
ansible web -i inventory.ini -m ping -u deployer
Escolher uma chave SSH (--private-key)
Designa uma chave privada SSH em particular.
Exemplo
ansible web -i inventory.ini -m ping --private-key ~/.ssh/id_ed25519
Pedir a palavra-passe (-k)
Solicita a introdução de uma palavra-passe para a ligação.
Exemplo
ansible web -i inventory.ini -m ping -k
Privilegiar as chaves SSH nos ambientes geridos.
03 · Comandos pontuais (ad hoc)
Para uma verificação ou uma ação simples, um comando ansible pode lançar um módulo sem criar um playbook.
Apresentar a identidade remota
Lança o módulo command para saber qual a conta que executa o comando.
Exemplo
ansible web -i inventory.ini -a "whoami"
-a sem -m explícito utiliza ansible.builtin.command por omissão.
Testar a presença de um pacote
Interroga os pacotes presentes com package_facts, sem os modificar.
Exemplo
ansible web -i inventory.ini -m ansible.builtin.package_facts
Instalar um pacote com apt
Pede a instalação de um pacote num alvo Debian/Ubuntu.
Exemplo
ansible web -i inventory.ini -b -m ansible.builtin.apt -a "name=curl state=present"
Ação modificadora: começar com --limit web1 e um ambiente de TP.
Criar uma pasta
Assegura que um diretório existe e possui as permissões indicadas.
Exemplo
ansible web -i inventory.ini -b -m ansible.builtin.file -a "path=/opt/demo state=directory mode=0755"
Consultar o estado de um serviço
Recolhe informações sobre os serviços sem impor uma alteração.
Exemplo
ansible web -i inventory.ini -b -m ansible.builtin.service_facts
ansible [grupo] -m command
Executa um programa remoto sem interpretação por uma shell.
Exemplo
ansible web -i inventory.ini -m ansible.builtin.command -a "uptime"
ansible [grupo] -m shell
Executa uma cadeia através de uma shell remota, útil para pipes ou redirecionamentos.
Exemplo
ansible web -i inventory.ini -m ansible.builtin.shell -a "df -h | tail -n 3"
A shell aumenta os riscos de injeção e de ausência de idempotência; limitar a sua utilização.
04 · Ler, controlar e executar playbooks
Ordem recomendada: identificar os anfitriões, validar a sintaxe, simular, examinar as diferenças e depois aplicar.
ansible-playbook -i ...
Executa o playbook nos alvos do inventário.
Exemplo
ansible-playbook -i inventory.ini site.yml
--syntax-check
Analisa a estrutura e a sintaxe do playbook sem executar as tarefas.
Exemplo
ansible-playbook -i inventory.ini site.yml --syntax-check
Não garante nem a conectividade, nem as permissões, nem o êxito do negócio.
--check
Tenta simular as alterações de um playbook sem as aplicar.
Exemplo
ansible-playbook -i inventory.ini site.yml --check
--diff
Apresenta as diferenças de ficheiros e de modelos quando os módulos o suportam.
Exemplo
ansible-playbook -i inventory.ini site.yml --check --diff
--list-hosts
Lista os alvos do playbook antes da sua execução.
Exemplo
ansible-playbook -i inventory.ini site.yml --list-hosts
--list-tasks
Apresenta as tarefas do playbook conhecidas antes da execução.
Exemplo
ansible-playbook -i inventory.ini site.yml --list-tasks
As inclusões dinâmicas nem sempre são visíveis nesta fase.
--start-at-task
Retoma a partir de uma tarefa com nome.
Exemplo
ansible-playbook site.yml --start-at-task "Installer nginx"
Não substitui a validação dos pré-requisitos das etapas anteriores.
--step
Pede uma confirmação interativa antes de cada tarefa.
Exemplo
ansible-playbook site.yml --step
-b / -K
Ativa become e, com -K, pede a palavra-passe de elevação, se necessário.
Exemplo
ansible-playbook -i inventory.ini site.yml -b -K
-e (extra-vars)
Fornece uma variável que tem prioridade elevada sobre as outras definições.
Exemplo
ansible-playbook site.yml -e "env=staging"
Não escrever segredos em claro no histórico de comandos.
-v / -vvv
Apresenta um nível crescente de detalhe para compreender as falhas.
Exemplo
ansible-playbook -i inventory.ini site.yml -vvv
Os rastos detalhados podem divulgar parâmetros; manusear com precaução.
05 · Papéis, coleções e segredos
Trabalhar em equipa pressupõe documentar as dependências e proteger as variáveis confidenciais.
ansible-galaxy collection list
Lista as coleções instaladas e a sua versão.
Exemplo
ansible-galaxy collection list
ansible-galaxy collection install
Instala uma coleção adicional.
Exemplo
ansible-galaxy collection install community.docker
Instalar coleções através de requirements.yml
Instala as dependências listadas no repositório.
Exemplo
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role init
Cria a arborescência padrão de um papel.
Exemplo
ansible-galaxy role init roles/nginx
ansible-vault create
Cria um ficheiro YAML cifrado e abre-o num editor.
Exemplo
ansible-vault create group_vars/prod/vault.yml
ansible-vault encrypt
Cifra um ficheiro existente.
Exemplo
ansible-vault encrypt group_vars/prod/vault.yml
ansible-vault edit
Abre um ficheiro cifrado para o modificar sem conservar uma cópia em claro.
Exemplo
ansible-vault edit group_vars/prod/vault.yml
ansible-vault rekey
Renova a palavra-passe de cifragem de um ficheiro Vault.
Exemplo
ansible-vault rekey group_vars/prod/vault.yml
--ask-vault-pass
Pede a palavra-passe do Vault durante uma execução.
Exemplo
ansible-playbook site.yml --ask-vault-pass
06 · Diagnosticar e explorar
Perante uma falha, confirmar o alvo, o acesso, o módulo utilizado e a parte exata da tarefa em erro.
PLAY RECAP
Resumo final por anfitrião: ok, changed, unreachable, failed, skipped, rescued, ignored.
Exemplo
failed=0 et unreachable=0 : pas d’erreur détectée pendant l’exécution.
unreachable
O Ansible não conseguiu estabelecer uma ligação utilizável com o anfitrião.
Exemplo
Vérifier IP, SSH, clé, utilisateur et pare-feu.
failed
Uma tarefa foi executada mas falhou.
Exemplo
Vérifier le message détaillé, les permissions et les prérequis.
ansible-config dump
Apresenta os valores de configuração efetivos.
Exemplo
ansible-config dump | grep DEFAULT_TIMEOUT
ansible-playbook --help
Apresenta a ajuda geral sobre as opções da linha de comandos.
Exemplo
ansible-playbook --help
Controlar os desvios sem implementar
Voltar a executar o playbook com --check --diff após uma intervenção para detetar um desvio.
Exemplo
ansible-playbook -i inventory.ini site.yml --check --diff
Os módulos que não suportam o modo de verificação podem limitar o alcance do controlo.