Como Usar o Ansible: Um Guia de Referência

Introduçã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 dicas fornece uma referência rápida para comandos e práticas comumente usados ao trabalhar com o 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á no formato de folha de dicas com trechos de linha de comando autocontidos.
• Pule para qualquer seção 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 da sua própria inventário.

Glossário do Ansible

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

• Máquina de Controle / Nó: um sistema onde o Ansible está instalado e configurado para 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, geralmente 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.
• Jogada: uma execução completa do Ansible. Uma jogada pode ter vários playbooks e funções, incluídos a partir de um único playbook que age como ponto de entrada.

Se você gostaria de 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 um nó.

Testando a Conectividade com os Nós

Para testar se o Ansible é capaz de se 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ê possui 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 significa que o Ansible está pronto para executar comandos e playbooks nesse nó.

Conectar como um usuário diferente

Por padrão, o Ansible tenta se conectar aos nós como seu usuário do sistema atual, usando seu par de chaves SSH correspondente. Para se conectar como um usuário diferente, adicione o comando com a opção -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, 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, você precisa 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 ao qual 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 precisar 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 do 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, 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 o 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 pelo comando que deseja executar, entre aspas.

Isto 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 comando a seguir 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 realizar todas as tarefas definidas dentro dele, use o comando ansible-playbook:

ansible-playbook myplaybook.yml

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

ansible-playbook -l server1 myplaybook.yml

Obtenção de Informações sobre uma Peça

A opção --list-tasks é usada para listar todas as tarefas que seriam executadas por uma peça sem fazer 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 peça, sem executar quaisquer tarefas nos servidores remotos:

ansible-playbook myplaybook.yml --list-hosts

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

ansible-playbook myplaybook.yml --list-tags

Controle da Execução do Playbook

Você pode usar a opção --start-at-task para definir um novo ponto de entrada para o seu playbook. O Ansible então irá pular tudo o que vem antes da tarefa especificada, executando o restante da peça a partir desse ponto em diante. 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 usar a opção --tags. Por exemplo, se deseja apenas executar tarefas marcadas como nginx ou mysql, você pode usar:

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

Se desejar ignorar todas as tarefas que estão sob tags específicas, use --skip-tags. O comando seguinte executaria myplaybook.yml, ignorando 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 esta 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 executará 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á seu editor de linha de comando padrão para que você possa preencher o arquivo com o conteúdo desejado.
• Por fim, quando terminar de editar, o ansible-vault salvará o arquivo como dados criptografados.

Criptografando um Arquivo Ansible Existente

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

ansible-vault encrypt credentials.yml

Isso solicitará que você insira uma senha que precisará fornecer 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 o 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 que selecionou quando criptografou o arquivo pela primeira vez com o 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 primeiro criptografar 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 descriptografada, você pode fazer isso com esta sintaxe:

ansible-vault decrypt credentials.yml

Isto irá solicitar que você forneça a mesma senha usada ao primeiro criptografar 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 descriptografados.

Usando Múltiplas Senhas de Cofre

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

Para criar um novo arquivo criptografado usando um ID de cofre personalizado, inclua a opção --vault-id junto com um rótulo e a localização onde o ansible-vault pode encontrar a senha para esse cofre. O rótulo pode ser qualquer identificador, e a localização 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 cofre chamado dev que usa prompt como fonte de senha. Ao combinar este método com arquivos de variáveis de grupo, você poderá ter cofres ansible separados para cada ambiente de aplicação:

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

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

Agora, para visualizar, editar ou descriptografar esses arquivos, você precisará fornecer o mesmo ID de cofre 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á de uma maneira de fornecer a senha do cofre sem ser solicitado. Você pode fazer isso usando um arquivo de senha com 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 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 conteúdo que foi criptografado usando prompt 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 prompt e depois usar um arquivo de senha para armazenar a mesma senha usada com o método prompt. O oposto também é verdadeiro: você pode criptografar conteúdo usando um arquivo de senha e depois usar o método prompt, fornecendo a mesma senha quando solicitado pelo Ansible.

Para maior flexibilidade e segurança estendida, 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 de 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 usa dados previamente criptografados via ansible-vault, você precisará fornecer a senha do vault ao comando do seu playbook.

Se você usou as opções padrão e a origem da senha prompt ao criptografar os dados usados neste playbook, você pode usar a opção --ask-vault-pass para fazer com que o Ansible solicite 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 seu lugar:

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 usa vários vaults, você deve fornecer um parâmetro --vault-id para cada um deles, em nenhuma ordem específica:

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

Depuração

Se 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 conectar-se 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 abrange alguns dos comandos mais comuns do Ansible 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 comandos e flags que você pode achar úteis para o seu fluxo de trabalho com o Ansible. Para obter uma visão geral de todas as opções disponíveis, você pode usar o comando help:

ansible  --help

Se desejar 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 do Ansible, confira nosso guia sobre Como Usar o Ansible para Instalar e Configurar o Docker no Ubuntu 20.04.