Transferindo Arquivos com Segurança: Usando os Módulos Copy e Fetch do Ansible

Mover arquivos é uma das primeiras tarefas práticas do Ansible que você precisa: enviar uma configuração para seus servidores, coletar um arquivo de log ou fazer backup de um arquivo remoto antes de uma alteração. Os módulos copy e fetch lidam com essas duas direções de forma clara.

Este guia usa comandos ad-hoc, para que você possa executar transferências pontuais sem escrever um playbook completo. Os mesmos argumentos do módulo também funcionam em playbooks quando você deseja que a tarefa seja repetível.

Pré-requisitos

Antes de executar os exemplos abaixo, certifique-se de ter o seguinte:

1. Nó de Controle Ansible: Uma máquina com Ansible instalado.
2. Arquivo de Inventário: Um arquivo de inventário operacional (ex.: /etc/ansible/hosts) definindo seus nós gerenciados.
3. Conectividade: Acesso SSH configurado com chave para seus hosts remotos.

Todos os exemplos assumirão que o grupo de destino se chama webservers no inventário.

Entendendo Comandos Ad-Hoc para Transferência de Arquivos

Comandos ad-hoc são comandos de linha única executados diretamente do terminal, ideais para tarefas rápidas que não justificam um playbook permanente. A estrutura básica é:

ansible <grupo-de-hosts> -m <nome-do-modulo> -a "chave=valor chave2=valor2 ..."

Para transferência de arquivos, usamos os nomes de módulo -m copy ou -m fetch, passando os argumentos necessários usando a flag -a.

O Módulo copy: Enviando Arquivos para Nós Remotos

O módulo copy é usado para transferir um arquivo localizado na máquina de controle Ansible para um ou mais nós gerenciados. Este é o método padrão para implantar arquivos de configuração, scripts ou pequenos ativos.

Argumentos Chave para copy

O módulo copy requer dois argumentos essenciais e aceita vários argumentos opcionais para gerenciamento de configuração:

Argumento	Descrição	Obrigatório?	Exemplo de Valor
src	O caminho do arquivo local na máquina de controle Ansible. Caminhos absolutos são mais claros para comandos ad-hoc.	Sim	/tmp/config.conf
dest	O caminho onde o arquivo será colocado no nó gerenciado remoto.	Sim	/etc/app/config.conf
owner	Nome do usuário que deve ser o proprietário do arquivo no nó remoto.	Não	nginx
group	Nome do grupo que deve ser o proprietário do arquivo no nó remoto.	Não	www-data
mode	Permissões (octal) a serem definidas no arquivo de destino.	Não	0644
backup	Se yes, cria um arquivo de backup antes de sobrescrever o original.	Não	yes

Exemplo 1: Implantação Simples de Arquivo

Suponha que você tenha um arquivo personalizado de Mensagem do Dia (motd) localmente e queira enviá-lo para todos os servidores web.

# Caminho do arquivo local: /home/usuario/ansible/motd_banner
# Destino remoto: /etc/motd

ansible webservers -m copy -a "src=/home/usuario/ansible/motd_banner dest=/etc/motd"

Exemplo 2: Definindo Permissões e Propriedade

Se você estiver implantando um arquivo de configuração seguro, deve especificar o proprietário, o grupo e as permissões restritas (ex.: apenas o proprietário pode ler/escrever).

# Implantando um arquivo de configuração de aplicativo, de propriedade de 'app_user', grupo 'devops',
# com permissões de leitura/escrita apenas para o proprietário (0600).

ansible webservers -m copy -b -a "src=/tmp/app_settings.yaml dest=/etc/app/settings.yaml owner=app_user group=devops mode=0600"

Nota sobre -b: A flag -b (ou --become) é necessária quando o destino remoto requer permissões elevadas (como escrever em /etc).

O Módulo fetch: Recuperando Arquivos de Nós Remotos

O módulo fetch executa a operação inversa do copy: ele recupera um arquivo do nó gerenciado de volta para a máquina de controle Ansible. Isso é útil para fazer backup de arquivos de configuração, recuperar logs ou coletar informações de diagnóstico.

Argumentos Chave para fetch

O módulo fetch requer o arquivo de origem no nó remoto e um diretório de destino na máquina de controle.

Argumento	Descrição	Obrigatório?	Exemplo de Valor
src	O caminho absoluto para o arquivo no nó gerenciado remoto.	Sim	/var/log/nginx/error.log
dest	O caminho absoluto para o diretório na máquina de controle onde os arquivos serão salvos.	Sim	/tmp/backups/logs
flat	Se yes, o nome do arquivo resultante não conterá a estrutura do nome do host (não recomendado ao recuperar de múltiplos hosts).	Não	no (padrão)

Diferença Crítica: Estrutura de Destino

Ao contrário do módulo copy, o módulo fetch cria automaticamente um caminho de subdiretório estruturado com base no nome do host remoto para evitar colisões de nomes de arquivos ao recuperar arquivos de vários servidores.

O caminho resultante na máquina de controle será assim:

<dest>/<nome-do-host>/<src>

Por exemplo, recuperar /etc/nginx/nginx.conf de host1 para /tmp/backups resulta em:

/tmp/backups/host1/etc/nginx/nginx.conf

Exemplo 3: Recuperando Backups de Configuração Remota

Para recuperar o arquivo de configuração em execução de todos os servidores web para um diretório de backup local:

# Recuperar nginx.conf de todos os servidores web para o diretório local /tmp/config_backups

ansible webservers -m fetch -a "src=/etc/nginx/nginx.conf dest=/tmp/config_backups"

Após executar este comando, se você segmentou webserver1 e webserver2, sua estrutura de diretório local seria:

/tmp/config_backups/
├── webserver1
│   └── etc
│       └── nginx
│           └── nginx.conf
└── webserver2
    └── etc
        └── nginx
            └── nginx.conf

Exemplo 4: Recuperando um Único Arquivo Sem Estrutura de Host (flat=yes)

Se você tem absoluta certeza de que está recuperando um arquivo de um único host, ou se você só precisa do conteúdo do arquivo (não da estrutura de origem), pode usar flat=yes. Isso resulta no arquivo sendo colocado diretamente na pasta de destino, nomeado após o arquivo remoto original.

# Recuperar um relatório de status de saúde local de um único host, salvando-o diretamente.

ansible webserver1 -m fetch -a "src=/tmp/health_status.txt dest=/tmp/reports flat=yes"

# Caminho resultante: /tmp/reports/health_status.txt

Aviso: Use flat=yes apenas ao segmentar um único host ou se você pretende sobrescrever o arquivo em execuções subsequentes, pois o Ansible não impedirá conflitos.

Melhores Práticas e Considerações de Segurança

Pequenos erros na transferência de arquivos podem se tornar incidentes de produção, especialmente quando os arquivos vão parar em /etc ou contêm segredos.

Sempre Defina Permissões com copy

Nunca envie um arquivo de configuração sem definir explicitamente o mode e o owner. Se você confiar no umask padrão do sistema remoto, arquivos sensíveis (como chaves SSH ou credenciais de banco de dados) podem acabar com direitos de acesso excessivamente permissivos.

# Má Prática (Modo derivado do umask)
- name: Implantar chave insegura
  ansible.builtin.copy:
    src: private.key
    dest: /etc/app/private.key

# Boa Prática (Restringir acesso explicitamente)
- name: Implantar chave segura
  ansible.builtin.copy:
    src: private.key
    dest: /etc/app/private.key
    mode: '0600'
    owner: root

Use backup=yes para Alterações Críticas

Ao usar copy para sobrescrever um arquivo crítico existente (ex.: /etc/sudoers), inclua backup=yes. O Ansible criará uma cópia de backup com timestamp no nó remoto antes de sobrescrever o arquivo, fornecendo uma opção fácil de reversão.

Considere synchronize para Grandes Transferências

Embora copy e fetch funcionem bem para operações rápidas e arquivos pequenos, use ansible.posix.synchronize para grandes árvores de diretório ou transferências delta eficientes. Ele envolve o rsync, então o nó de controle e o ambiente de destino precisam do rsync e acesso SSH corretos.

Conclusão

Use copy quando a origem estiver no seu nó de controle e o destino estiver no nó gerenciado. Use fetch quando a origem estiver no nó gerenciado e você quiser o arquivo salvo localmente.

Módulo	Direção	Exemplo de Comando Ad-Hoc
copy	Nó de Controle -> Nó Gerenciado	ansible all -m copy -a "src=/local/file dest=/remote/path mode=0644"
fetch	Nó Gerenciado -> Nó de Controle	ansible all -m fetch -a "src=/remote/file dest=/local/dir"

Para um servidor, flat=yes pode tornar os arquivos recuperados mais fáceis de ler. Para um grupo de servidores, mantenha a estrutura de diretórios padrão baseada em host para que o log de um host não sobrescreva o de outro.