Como usar o Ansible: Um guia de referência

Introdução

O Ansible é uma ferramenta moderna de gerenciamento de configuração que facilita a tarefa de configurar e manter servidores remotos.

Este guia no estilo de folha de referência fornece uma rápida consulta a comandos e práticas comumente usados ao trabalhar com Ansible. Para uma visão geral do Ansible e como instalá-lo e configurá-lo, por favor, consulte nosso guia sobre Como Instalar e Configurar o Ansible no Ubuntu 20.04.

Como Usar Este Guia:

• Este guia está em formato de folha de referência com trechos de linha de comando autocontidos.
• Vá para qualquer seção que seja relevante para a tarefa que você está tentando completar.
• Quando você ver texto destacado nos comandos deste guia, tenha em mente que esse texto deve se referir a hosts, nomes de usuário e endereços IP do seu próprio inventário.

Glossário do Ansible

Os seguintes termos específicos do Ansible são amplamente utilizados ao longo deste guia:

• Máquina / Nó de Controle: um sistema onde o Ansible está instalado e configurado para se conectar e executar comandos em nós.
• Nó: um servidor controlado pelo Ansible.
• Arquivo de Inventário: um arquivo que contém informações sobre os servidores controlados pelo Ansible, normalmente localizado em /etc/ansible/hosts.
• Playbook: um arquivo contendo uma série de tarefas a serem executadas em um servidor remoto.
• Função: uma coleção de playbooks e outros arquivos relevantes para um objetivo, como instalar um servidor web.
• Execução: uma execução completa do Ansible. Uma execução pode ter vários playbooks e funções, incluídos a partir de um único playbook que atua como ponto de entrada.

Se você deseja um exemplo desses comandos na prática, consulte nosso guia sobre Como Usar o Ansible para Automatizar a Configuração Inicial do Servidor no Ubuntu 20.04. Você precisará de pelo menos um servidor remoto para usar como nó.

Testando a Conectividade com os Nós

Para testar se o Ansible é capaz de conectar e executar comandos e playbooks em seus nós, você pode usar o seguinte comando:

ansible all -m ping

O módulo ping testará se você tem credenciais válidas para se conectar aos nós definidos em seu arquivo de inventário, além de testar se o Ansible é capaz de executar scripts Python no servidor remoto. Uma resposta pong de volta significa que o Ansible está pronto para executar comandos e playbooks nesse nó.

Conectando como um Usuário Diferente

Por padrão, o Ansible tenta se conectar aos nós como seu usuário de sistema atual, usando seu par de chaves SSH correspondente. Para se conectar como um usuário diferente, adicione o comando com a flag -u e o nome do usuário pretendido:

ansible all -m ping -u sammy

O mesmo é válido para ansible-playbook:

ansible-playbook myplaybook.yml -u sammy

Usando uma Chave SSH Personalizada

Se você estiver usando uma chave SSH personalizada para se conectar aos servidores remotos, você pode fornecê-la no momento da execução com a opção --private-key:

ansible all -m ping --private-key=~/.ssh/custom_id

Esta opção também é válida para ansible-playbook:

ansible-playbook myplaybook.yml --private-key=~/.ssh/custom_id

Usando Autenticação Baseada em Senha

Se você precisar usar autenticação baseada em senha para se conectar aos nós, precisará adicionar a opção --ask-pass ao seu comando Ansible.

Isso fará com que o Ansible solicite a senha do usuário no servidor remoto que você está tentando se conectar:

ansible all -m ping --ask-pass

Esta opção também é válida para ansible-playbook:

ansible-playbook myplaybook.yml --ask-pass

Fornecendo a Senha do sudo

Se o usuário remoto precisa fornecer uma senha para executar comandos sudo, você pode incluir a opção --ask-become-pass no seu comando Ansible. Isso solicitará que você forneça a senha sudo do usuário remoto:

ansible all -m ping --ask-become-pass

Esta opção também é válida para ansible-playbook:

ansible-playbook myplaybook.yml --ask-become-pass

Usando um Arquivo de Inventário Personalizado

O arquivo de inventário padrão geralmente está localizado em /etc/ansible/hosts, mas você também pode usar a opção -i para apontar para arquivos de inventário personalizados ao executar comandos e playbooks do Ansible. O Ansible também suporta scripts de inventário para construir arquivos de inventário dinâmicos, para quando seu inventário flutua, com servidores sendo criados e destruídos com frequência. Arquivos de inventário personalizados são úteis para configurar inventários por projeto que podem ser incluídos em sistemas de controle de versão como Git:

ansible all -m ping -i my_custom_inventory

A mesma opção é válida para ansible-playbook:

ansible-playbook myplaybook.yml -i my_custom_inventory

Executando Comandos Ad-Hoc

Para executar um comando em um nó, use a opção -a seguida do comando que deseja executar, entre aspas.

Isso executará uname -a em todos os nós em seu inventário:

ansible all -a "uname -a"

Também é possível executar módulos do Ansible com a opção -m. O seguinte comando instalaria o pacote vim no server1 de seu inventário:

ansible server1 -m apt -a "name=vim"

Antes de fazer alterações em seus nós, você pode realizar uma simulação para prever como os servidores seriam afetados pelo seu comando. Isso pode ser feito incluindo a opção --check:

ansible server1 -m apt -a "name=vim" --check

Executando Playbooks

Para executar um playbook e executar todas as tarefas definidas dentro dele, use o comando ansible-playbook:

ansible-playbook myplaybook.yml

Para sobrescrever a opção padrão hosts no playbook e limitar a execução a um certo grupo ou host, inclua a opção -l em seu comando:

ansible-playbook -l server1 myplaybook.yml

Obtendo Informações sobre uma Tarefa

A opção --list-tasks é utilizada para listar todas as tarefas que seriam executadas por uma tarefa sem realizar quaisquer alterações nos servidores remotos:

ansible-playbook myplaybook.yml --list-tasks

Da mesma forma, é possível listar todos os hosts que seriam afetados por uma tarefa, sem executar quaisquer tarefas nos servidores remotos:

ansible-playbook myplaybook.yml --list-hosts

Você pode usar tags para limitar a execução de uma tarefa. Para listar todas as tags disponíveis em uma tarefa, utilize a opção --list-tags:

ansible-playbook myplaybook.yml --list-tags

Controlando a Execução do Playbook

Você pode utilizar a opção --start-at-task para definir um novo ponto de entrada para seu playbook. O Ansible então irá pular qualquer coisa que venha antes da tarefa especificada, executando o restante do play a partir desse ponto. Esta opção requer um nome de tarefa válido como argumento:

ansible-playbook myplaybook.yml --start-at-task="Set Up Nginx"

Para executar apenas tarefas associadas a tags específicas, você pode utilizar a opção --tags. Por exemplo, se você deseja executar apenas tarefas marcadas como nginx ou mysql, você pode usar:

ansible-playbook myplaybook.yml --tags=mysql,nginx

Se você deseja pular todas as tarefas que estão sob tags específicas, use --skip-tags. O seguinte comando executaria myplaybook.yml, pulando todas as tarefas marcadas como mysql:

ansible-playbook myplaybook.yml --skip-tags=mysql

Usando o Ansible Vault para Armazenar Dados Sensíveis

Se seus playbooks do Ansible lidam com dados sensíveis como senhas, chaves de API e credenciais, é importante manter esses dados seguros usando um mecanismo de criptografia. O Ansible fornece o ansible-vault para criptografar arquivos e variáveis.

Embora seja possível criptografar qualquer arquivo de dados do Ansible, bem como arquivos binários, é mais comum usar o ansible-vault para criptografar arquivos de variáveis contendo dados sensíveis. Após criptografar um arquivo com essa ferramenta, você só poderá executar, editar ou visualizar seu conteúdo fornecendo a senha relevante definida quando criptografou o arquivo pela primeira vez.

Criando um Novo Arquivo Criptografado

Você pode criar um novo arquivo criptografado do Ansible com:

ansible-vault create credentials.yml

Este comando realizará as seguintes ações:

• Primeiro, ele solicitará que você insira uma nova senha. Você precisará fornecer esta senha sempre que acessar o conteúdo do arquivo, seja para edição, visualização ou apenas para executar playbooks ou comandos usando esses valores.
• Em seguida, ele abrirá o editor de linha de comando padrão para que você possa preencher o arquivo com o conteúdo desejado.
• Finalmente, quando terminar de editar, o ansible-vault salvará o arquivo como dados criptografados.

Encriptando um Arquivo Ansible Existente

Para encriptar um arquivo Ansible existente, você pode usar a seguinte sintaxe:

ansible-vault encrypt credentials.yml

Isto solicitará uma senha que você precisará inserir sempre que acessar o arquivo credentials.yml.

Visualizando o Conteúdo de um Arquivo Criptografado

Se você deseja visualizar o conteúdo de um arquivo que foi previamente criptografado com ansible-vault e não precisa alterar seu conteúdo, você pode usar:

ansible-vault view credentials.yml

Isso solicitará que você forneça a senha selecionada quando criptografou o arquivo pela primeira vez com ansible-vault.

Editar um Arquivo Criptografado

Para editar o conteúdo de um arquivo que foi previamente criptografado com o Ansible Vault, execute:

ansible-vault edit credentials.yml

Isto irá solicitar que você forneça a senha que escolheu ao criptografar pela primeira vez o arquivo credentials.yml com o ansible-vault. Após a validação da senha, o seu editor de linha de comando padrão será aberto com o conteúdo descriptografado do arquivo, permitindo que você faça suas alterações. Quando terminar, você pode salvar e fechar o arquivo como faria normalmente, e o conteúdo atualizado será salvo como dados criptografados.

Descriptografando Arquivos Criptografados

Se você deseja reverter permanentemente um arquivo que foi previamente criptografado com o ansible-vault para sua versão não criptografada, você pode fazer isso com esta sintaxe:

ansible-vault decrypt credentials.yml

Isto irá solicitar que você forneça a mesma senha usada ao criptografar pela primeira vez o arquivo credentials.yml com o ansible-vault. Após a validação da senha, o conteúdo do arquivo será salvo no disco como dados não criptografados.

Usando Múltiplas Senhas de Vault

O Ansible suporta múltiplas senhas de vault agrupadas por diferentes IDs de vault. Isso é útil se você deseja ter senhas de vault dedicadas para diferentes ambientes, como desenvolvimento, teste e produção.

Para criar um novo arquivo criptografado usando um ID de vault personalizado, inclua a opção --vault-id juntamente com um rótulo e o local onde o ansible-vault pode encontrar a senha para esse vault. O rótulo pode ser qualquer identificador, e o local pode ser prompt, significando que o comando deve solicitar que você insira uma senha, ou um caminho válido para um arquivo de senha.

ansible-vault create --vault-id dev@prompt credentials_dev.yml

Isso criará um novo ID de vault chamado dev que usa prompt como fonte de senha. Ao combinar este método com arquivos de variáveis de grupo, você será capaz de ter vaults ansible separados para cada ambiente de aplicativo:

ansible-vault create --vault-id prod@prompt credentials_prod.yml

Nós usamos dev e prod como IDs de vault para demonstrar como você pode criar vaults separados por ambiente, mas você pode criar quantos vaults quiser e pode usar qualquer identificador de sua escolha como ID de vault.

Agora, para visualizar, editar ou descriptografar esses arquivos, você precisará fornecer o mesmo ID de vault e fonte de senha juntamente com o comando ansible-vault:

ansible-vault edit credentials_dev.yml --vault-id dev@prompt

Usando um Arquivo de Senha

Se você precisa automatizar o processo de provisionamento de servidores com o Ansible usando uma ferramenta de terceiros, precisará fornecer a senha do cofre sem ser solicitado. Você pode fazer isso usando um arquivo de senha com o ansible-vault.

A password file can be a plain text file or an executable script. If the file is an executable script, the output produced by this script will be used as the vault password. Otherwise, the raw contents of the file will be used as vault password.

Para usar um arquivo de senha com o ansible-vault, você precisa fornecer o caminho para um arquivo de senha ao executar qualquer um dos comandos do cofre:

ansible-vault create --vault-id dev@path/to/passfile credentials_dev.yml

O Ansible não faz distinção entre o conteúdo que foi criptografado usando solicitação ou um arquivo de senha como fonte de senha, desde que a senha de entrada seja a mesma. Em termos práticos, isso significa que é OK criptografar um arquivo usando solicitação e depois usar um arquivo de senha para armazenar a mesma senha usada com o método solicitação. O oposto também é verdadeiro: você pode criptografar o conteúdo usando um arquivo de senha e depois usar o método solicitação, fornecendo a mesma senha quando solicitado pelo Ansible.

Para maior flexibilidade e segurança, em vez de ter sua senha do cofre armazenada em um arquivo de texto simples, você pode usar um script Python para obter a senha de outras fontes. O repositório oficial do Ansible contém alguns exemplos de scripts do cofre que você pode usar como referência ao criar um script personalizado que atenda às necessidades específicas do seu projeto.

Executando um Playbook com Dados Criptografados via Ansible Vault

Sempre que você executar um playbook que utilize dados previamente criptografados via ansible-vault, você precisará fornecer a senha do vault para o comando do seu playbook.

Se você usou as opções padrão e a origem de senha prompt ao criptografar os dados usados neste playbook, você pode usar a opção --ask-vault-pass para fazer o Ansible solicitar a senha:

ansible-playbook myplaybook.yml --ask-vault-pass

Se você usou um arquivo de senha em vez de solicitar a senha, você deve usar a opção --vault-password-file em vez disso:

ansible-playbook myplaybook.yml --vault-password-file my_vault_password.py

Se estiver usando dados criptografados sob um ID de vault, você precisará fornecer o mesmo ID de vault e origem de senha que usou ao criptografar os dados pela primeira vez:

ansible-playbook myplaybook.yml --vault-id dev@prompt

Se estiver usando um arquivo de senha com seu ID de vault, você deve fornecer o rótulo seguido do caminho completo para o arquivo de senha como origem de senha:

ansible-playbook myplaybook.yml --vault-id dev@vault_password.py

Se seu play usar vários vaults, você deve fornecer um parâmetro --vault-id para cada um deles, em ordem não particular:

ansible-playbook myplaybook.yml --vault-id dev@vault_password.py --vault-id test@prompt --vault-id ci@prompt

Depuração

Se você encontrar erros ao executar comandos e playbooks do Ansible, é uma boa ideia aumentar a verbosidade da saída para obter mais informações sobre o problema. Você pode fazer isso incluindo a opção -v no comando:

ansible-playbook myplaybook.yml -v

Se precisar de mais detalhes, pode usar -vvv e isso aumentará a verbosidade da saída. Se não conseguir se conectar aos nós remotos via Ansible, use -vvvv para obter informações de depuração da conexão:

ansible-playbook myplaybook.yml -vvvv

Conclusão

Este guia cobre alguns dos comandos Ansible mais comuns que você pode usar ao provisionar servidores, como executar comandos remotos em seus nós e como executar playbooks usando uma variedade de configurações personalizadas.

Existem outras variações de comando e flags que você pode achar úteis para seu fluxo de trabalho do Ansible. Para obter uma visão geral de todas as opções disponíveis, pode usar o comando help:

ansible  --help

Se quiser ver uma visão mais abrangente do Ansible e de todos os seus comandos e recursos disponíveis, consulte a documentação oficial do Ansible.

Se quiser ver outro exemplo prático de Ansible, confira nosso guia sobre Como Usar o Ansible para Instalar e Configurar o Docker no Ubuntu 20.04.