AWS S3 Sync: O guia completo para sincronização de arquivos

Configuração da CLI do AWS e do AWS S3

Antes de começar a sincronizar arquivos com o S3, você precisará instalar e configurar corretamente a CLI do AWS. Isso pode parecer intimidador se você for novo na AWS, mas levará apenas alguns minutos.

A configuração da CLI envolve duas etapas principais: instalar a ferramenta e configurá-la. A seguir, examinarei as duas etapas.

Instalando a CLI do AWS

A instalação da CLI do AWS varia um pouco, dependendo do seu sistema operacional.

Para sistemas Windows:

• Acesse a página de downloaddo AWSCLI
• Faça o download do instalador do Windows (64 bits)
• Execute o instalador e siga as instruções

Para sistemas Linux:

Execute os três comandos a seguir no Terminal:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Para sistemas macOS:

Supondo que você tenha o Homebrew instalado, execute esta linha a partir do Terminal:

brew install awscli

Se você não tiver o Homebrew, use esses dois comandos:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Você pode executar o comando aws --version em todos os sistemas operacionais para verificar se a AWS CLI foi instalada. Aqui está o que você deve ver:

Imagem 1 - Versão da CLI do AWS

Configuração da CLI do AWS

Agora que a CLI está instalada, você precisa configurá-la com suas credenciais do AWS.

Supondo que você já tenha uma conta do AWS, faça login e acesse o serviço IAM. Lá, crie um novo usuário com acesso programático. Você deve atribuir a permissão apropriada ao usuário, que é, no mínimo, acesso S3:

Imagem 2 - Usuário do AWS IAM

Depois disso, vá para "Credenciais de segurança" para criar uma nova chave de acesso. Após a criação, você terá oID da chave de acesso e achave de acesso secreta. Anote-as em algum lugar seguro, pois você não poderá acessá-las no futuro:

Imagem 3 - Credenciais de usuário do AWS IAM

De volta ao Terminal, execute o comando aws configure. Ele solicitará que você insira o ID da chave de acesso, a chave de acesso secreta, a região (no meu caso,eu-central-1 ) e o formato de saída preferido (json):

Imagem 4 - Configuração da CLI do AWS

Para verificar se você se conectou com êxito à sua conta do AWS na CLI, execute o seguinte comando:

aws sts get-caller-identity

Este é o resultado que você deve ver:

Imagem 5 - Comando de conexão de teste da CLI da AWS

E é isso - apenas mais uma etapa antes que você possa começar a usar o comando de sincronização do S3!

Configuração de um bucket do AWS S3

A etapa final é criar um bucket S3 que armazenará os arquivos sincronizados. Você pode fazer isso na CLI ou no Console de gerenciamento do AWS. Vou escolher a última opção, só para misturar as coisas.

Para começar, acesse a página do serviço S3 no Management Console e clique no botão "Create bucket". Lá, escolha um nome de bucket exclusivo (exclusivo globalmente em toda a AWS) e, em seguida, role até a parte inferior e clique no botão "Create" (Criar):

Imagem 6 - Criação de um balde do AWS

O bucket foi criado e você o verá imediatamente no console de gerenciamento. Você também pode verificar se ele foi criado por meio da CLI:

aws s3 ls

Imagem 7 - Todos os buckets S3 disponíveis

Lembre-se de que os buckets do S3 são privados por padrão. Se estiver planejando usar o bucket para hospedar arquivos públicos (como ativos do site), você precisará ajustar as políticas e permissões do bucket de acordo.

Agora você está configurado e pronto para começar a sincronizar arquivos entre sua máquina local e o AWS S3!

Comando básico de sincronização do AWS S3

Agora que você tem a CLI do AWS instalada, configurada e um bucket S3 pronto para uso, é hora de começar a sincronizar! A sintaxe básica do comando de sincronização do AWS S3 é bastante simples. Vou mostrar a você como isso funciona.

O comando S3 sync segue esse padrão simples:

aws s3 sync <source> <destination> [options]

Tanto a origem quanto o destino podem ser um caminho de diretório local ou um URI S3 (começando com s3://). Dependendo do modo como você deseja sincronizar, você os organizará de forma diferente.

Sincronização de arquivos do local para um bucket S3

Recentemente, eu estava brincando com a pesquisa profunda do Ollama. Digamos que essa seja a pasta que você deseja sincronizar com o S3. O diretório principal está localizado na pasta Documents. Aqui está o que você vê:

Conteúdo da pasta local

Este é o comando que preciso executar para sincronizar a pasta local code-files com a pasta backup no bucket do S3:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup

A pasta backup no bucket do S3 será criada automaticamente se não existir.

Aqui está o que você verá impresso no console:

Imagem 9 - Processo de sincronização do S3

Após alguns segundos, o conteúdo da pasta local code-files estará disponível no bucket do S3:

Imagem 10 - Conteúdo do bucket S3

A vantagem da sincronização do S3 é que ela só faz upload de arquivos que não existem no destino ou que foram modificados localmente. Se você executar o mesmo comando novamente sem alterar nada, verá... nada! Isso ocorre porque a CLI do AWS detectou que todos os arquivos já estão sincronizados e atualizados.

Agora, farei duas pequenas alterações: criarei um novo arquivo (new_file.txt) e atualizarei um arquivo existente (requirements.txt). Quando você executar o comando sync novamente, somente os arquivos novos ou modificados serão carregados:

Imagem 11 - Processo de sincronização do S3 (2)

E isso é tudo o que você precisa saber ao sincronizar pastas locais com o S3. Mas e se você quiser fazer o caminho inverso?

Sincronização de arquivos do bucket S3 para um diretório local

Se você quiser fazer download de arquivos do seu bucket S3 para sua máquina local, basta inverter a origem e o destino:

aws s3 sync s3://testbucket-dradecic/backup /Users/dradecic/Documents/code-files-from-s3 

Esse comando fará o download de todos os arquivos da pasta backup no seu bucket S3 para uma pasta local chamada code-files-from-s3 . Novamente, se a pasta local não existir, a CLI a criará para você:

Imagem 12 - S3 para sincronização local

Vale a pena observar que a sincronização do S3 não é bidirecional. Ele sempre vai da origem ao destino, fazendo com que o destino corresponda à origem. Se você excluir um arquivo localmente e depois sincronizá-lo com o S3, ele ainda existirá no S3. Da mesma forma, se você excluir um arquivo no S3 e sincronizar do S3 para o local, o arquivo local permanecerá intacto.

Se quiser fazer com que o destino corresponda exatamente à origem (inclusive exclusões), você precisará usar o sinalizador --delete, que abordarei na seção de opções avançadas.

Opções avançadas de sincronização do AWS S3

O comando básico de sincronização do S3 explorado anteriormente é poderoso por si só, mas a AWS o incluiu com opções adicionais que dão a você mais controle sobre o processo de sincronização. 

Nesta seção, mostrarei alguns dos sinalizadores mais úteis que você pode adicionar ao comando básico.

Sincronização apenas de arquivos novos ou modificados

Por padrão, a sincronização do S3 usa um mecanismo de comparação básico que verifica o tamanho do arquivo e o tempo de modificação para determinar se um arquivo precisa ser sincronizado. No entanto, essa abordagem pode nem sempre capturar todas as alterações, especialmente quando se trata de arquivos que foram modificados, mas que permanecem com o mesmo tamanho.

Para obter uma sincronização mais precisa, você pode usar o sinalizador --exact-timestamps:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exact-timestamps

Isso força a sincronização do S3 a comparar registros de data e hora com precisão de até milissegundos. Lembre-se de que o uso desse sinalizador pode tornar o processo de sincronização um pouco mais lento, pois exige comparações mais detalhadas.

Exclusão ou inclusão de arquivos específicos

Às vezes, você não quer sincronizar todos os arquivos de um diretório. Talvez você queira excluir arquivos temporários, logs ou determinados tipos de arquivos (como .DS_Store, no meu caso). É nesse ponto que as bandeiras --exclude e --include são úteis.

Mas, para ilustrar um ponto, digamos que eu queira sincronizar meu diretório de código, mas excluir todos os arquivos Python:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exclude "*.py"

Agora, muito menos arquivos são sincronizados com o S3:

Imagem 13 - Sincronização do S3 com arquivos Python excluídos

Você também pode combinar --exclude e --include para criar padrões mais complexos. Por exemplo, exclua tudo, exceto os arquivos Python:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --exclude "*" --include "*.py"

Os padrões são avaliados na ordem especificada, portanto, a ordem é importante! Veja o que você verá ao usar esses sinalizadores:

Figura 14 - Bandeiras de exclusão e inclusão

Agora, apenas os arquivos Python são sincronizados, e arquivos de configuração importantes estão faltando.

Exclusão de arquivos do destino

Por padrão, o S3 sync apenas adiciona ou atualiza arquivos no destino - nunca os exclui. Isso significa que, se você excluir um arquivo da origem, ele ainda permanecerá no destino após a sincronização.

Para que o destino espelhe exatamente a origem, inclusive as exclusões, use o sinalizador --delete:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --delete

Se você executar isso pela primeira vez, todos os arquivos locais serão sincronizados com o S3:

Imagem 15 - Excluir bandeira

Isso é particularmente útil para manter réplicas exatas de diretórios. Mas tenha cuidado - esse sinalizador pode levar à perda de dados se for usado incorretamente.

Digamos que eu exclua config.py da minha pasta local e execute o comando sync com o sinalizador --delete:

Imagem 16 - Excluir bandeira (2)

Como você pode ver, o comando não apenas sincroniza arquivos novos e modificados, mas também exclui arquivos do bucket do S3 que não existem mais no diretório local.

Configurando a execução seca para sincronização segura

As operações de sincronização do S3 mais perigosas são aquelas que envolvem o sinalizador --delete. Para evitar a exclusão acidental de arquivos importantes, você pode usar o sinalizador --dryrun para simular a operação sem realmente fazer nenhuma alteração:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --delete --dryrun

Para demonstrar, excluí os arquivos requirements.txt e settings.toml de uma pasta local e, em seguida, executei o comando:

Imagem 17 - Funcionamento a seco

Isso mostrará exatamente o que aconteceria se você executasse o comando de verdade, inclusive quais arquivos seriam carregados, baixados ou excluídos.

Eu sempre recomendo que você use --dryrun antes de executar qualquer comando de sincronização do S3 com o sinalizador --delete, especialmente quando estiver trabalhando com dados importantes.

Há muitas outras opções disponíveis para o comando S3 sync, como --acl para definir permissões, --storage-class para escolher a camada de armazenamento do S3 e --recursive para percorrer subdiretórios. Consulte a documentação oficial da AWS CLI para obter uma lista completa de opções.

Agora que você já conhece as opções básicas e avançadas de sincronização do S3, vamos ver como usar esses comandos em cenários práticos, como backups e restaurações.

Usando o AWS S3 Sync para backup e restauração

Um dos casos de uso mais populares da sincronização do AWS S3 é fazer backup de arquivos importantes e restaurá-los quando necessário. Vamos explorar como você pode implementar uma estratégia simples de backup e restauração usando o comando sync.

Criação de backups no S3

A criação de backups com o S3 sync é simples: você só precisa executar o comando sync do seu diretório local para um bucket do S3. No entanto, existem algumas práticas recomendadas que você deve seguir para fazer backups eficazes.

Primeiro, é uma boa ideia você organizar seus backups por data ou versão. Aqui está uma abordagem simples que usa um carimbo de data/hora no caminho do S3:

# Create a timestamp variable
TIMESTAMP=$(date +%Y-%m-%d-%H-%M-%S)

# Run the backup
aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backups/$TIMESTAMP

Isso cria uma nova pasta para cada backup com um registro de data e hora como 2025-03-10-18-56-42. Aqui está o que você verá no S3:

Imagem 18 - Backups com registro de data e hora

Para dados críticos, talvez você queira manter várias versões de backup. Isso é fácil de fazer, basta executar regularmente o backup baseado em carimbo de data/hora.

Você também pode usar a opção --storage-class para especificar uma classe de armazenamento mais econômica. classe de armazenamento mais econômica mais econômica para seus backups:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backups/$TIMESTAMP --storage-class STANDARD_IA

Imagem 19 - Conteúdo do backup com uma classe de armazenamento personalizada

Isso usa a classe de armazenamento S3 Infrequent Access, que custa menos, mas tem uma pequena taxa de recuperação. Para arquivamento de longo prazo, você pode até usar a classe de armazenamento Glacier:

aws s3 sync /Users/dradecic/Documents/important-data s3://testbucket-dradecic/backups/$TIMESTAMP --storage-class GLACIER

Lembre-se de que os arquivos armazenados no Glacier levam horas para serem recuperados, portanto, não são adequados para dados que você possa precisar rapidamente.

Restaurar arquivos do S3

A restauração a partir de um backup é igualmente fácil - basta você inverter a origem e o destino. inverta a origem e o destino em seu comando de sincronização:

# Restore from the most recent backup (assuming you know the timestamp)
aws s3 sync s3://testbucket-dradecic/backups/2025-03-10-18-56-42 /Users/dradecic/Documents/restored-data

Isso fará o download de todos os arquivos desse backup específico para o diretório local restored-data:

Imagem 20 - Restaurando arquivos do S3

Se você não se lembrar do registro de data e hora exato, poderá listar todos os seus backups primeiro:

aws s3 ls s3://testbucket-dradecic/backups/

O que mostrará a você algo como:

Imagem 21 - Lista de backups

Você também pode restaurar arquivos ou diretórios específicos de um backup usando os sinalizadores de exclusão/inclusão que discutimos anteriormente:

# Restore only the config files
aws s3 sync s3://testbucket-dradecic/backups/2025-03-10-18-56-42 /Users/dradecic/Documents/restored-configs --exclude "*" --include "*.config" --include "*.toml" --include "*.yaml"

Para sistemas de missão crítica, recomendo que você automatize seus backups com tarefas agendadas (como cron jobs no Linux/macOS ou Task Scheduler no Windows). Isso garante que você faça backup dos seus dados de forma consistente, sem precisar se lembrar de fazer isso manualmente.

Solução de problemas do AWS S3 Sync

A sincronização do AWS S3 é uma ferramenta confiável, mas você pode encontrar problemas ocasionalmente. Ainda assim, a maioria dos erros que você verá é de origem humana.

Erros comuns de sincronização

Vamos examinar alguns problemas comuns e suas soluções.

• Erro de acesso negado geralmente significa que seu usuário IAM não tem as permissões necessárias para acessar o bucket S3 ou executar operações específicas. Para corrigir isso, tente uma das seguintes opções:
• Verifique se o usuário do IAM tem as permissões S3 apropriadas (s3:ListBucket, s3:GetObject, s3:PutObject).
• Verifique se a política de bucket não nega explicitamente o acesso do usuário.
• Certifique-se de que o próprio balde não esteja bloqueando o acesso público se você precisar de operações públicas.

• Não existe tal arquivo ou diretório O erro normalmente aparece quando o caminho de origem que você especificou no comando sync não existe. A solução é simples: verifique novamente seus caminhos e certifique-se de que eles existam. Preste atenção especial a erros de digitação em nomes de buckets ou diretórios locais.

• Limite de tamanho de arquivo erros podem ocorrer quando você deseja sincronizar arquivos grandes. Por padrão, a sincronização S3 pode lidar com arquivos de até 5 GB de tamanho. Para arquivos maiores, você verá tempos limite ou transferências incompletas.
• Para arquivos maiores que 5 GB, você deve usar o sinalizador --only-show-errors combinado com o sinalizador --size-only. Essa combinação ajuda nas transferências de arquivos grandes, minimizando a saída e comparando apenas os tamanhos dos arquivos:

aws s3 sync /Users/dradecic/large-files s3://testbucket-dradecic/large-files --only-show-errors --size-only

Otimização do desempenho da sincronização

Se a sincronização do S3 estiver mais lenta do que o esperado, há alguns ajustes que você pode fazer para acelerar o processo.

• Use transferências paralelas. Por padrão, a sincronização do S3 usa um número limitado de operações paralelas. Você pode aumentar isso com o parâmetro --max-concurrent-requests:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --max-concurrent-requests 20

• Ajuste o tamanho do bloco. Para arquivos grandes, você pode otimizar a velocidade de transferência ajustando o tamanho do bloco. Isso divide arquivos grandes em blocos de 16 MB em vez dos 8 MB padrão, o que pode ser mais rápido em boas conexões de rede:

aws s3 sync /Users/dradecic/large-files s3://testbucket-dradecic/backup --cli-read-timeout 120 --multipart-threshold 64MB --multipart-chunksize 16MB

• Use --no-progress para os scripts. Se você estiver executando a sincronização S3 em um script automatizado, use o sinalizador --no-progress para reduzir a saída e melhorar o desempenho:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --no-progress

• Use pontos de extremidade locais. Se os seus recursos do AWS estiverem na mesma região, a especificação do endpoint regional poderá reduzir a latência:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --endpoint-url https://s3.eu-central-1.amazonaws.com

Essas otimizações podem melhorar significativamente o desempenho da sincronização, especialmente no caso de grandes transferências de dados ou quando executadas em máquinas menos potentes.

Se você ainda tiver problemas depois de tentar essas soluções, a CLI do AWS tem uma opção de depuração integrada. Basta adicionar --debug ao seu comando para ver informações detalhadas sobre o que está acontecendo durante o processo de sincronização:

aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --debug

Você verá muitas mensagens de registro detalhadas, semelhantes a estas:

Imagem 22 - Executando a sincronização no modo de depuração

E isso é tudo quando se trata de solucionar problemas de sincronização do AWS S3. Claro, há outros erros que podem ocorrer, mas 99% das vezes você encontrará a solução nesta seção.

Resumindo o AWS S3 Sync

Para resumir, a sincronização do AWS S3 é uma daquelas raras ferramentas que são simples de usar e incrivelmente eficientes. Você aprendeu tudo, desde comandos básicos até opções avançadas, estratégias de backup e dicas de solução de problemas.

Para desenvolvedores, administradores de sistemas ou qualquer pessoa que trabalhe com o AWS, o comando de sincronização do S3 é uma ferramenta essencial - ele economiza tempo, reduz o uso de largura de banda e garante que seus arquivos estejam onde você precisa deles, quando você precisa deles.

Se você estiver fazendo backup de dados críticos, implantando ativos da Web ou apenas mantendo diferentes ambientes sincronizados, a sincronização do AWS S3 torna o processo simples e confiável.

A melhor maneira de você se sentir confortável com a sincronização S3 é começar a usá-la. Tente configurar uma operação de sincronização simples com seus próprios arquivos e, em seguida, explore gradualmente as opções avançadas para atender às suas necessidades específicas.

Lembre-se de sempre usar --dryrun primeiro ao trabalhar com dados importantes, especialmente ao usar o sinalizador --delete. É melhor você perder um minuto a mais para verificar o que vai acontecer do que excluir acidentalmente arquivos importantes.

Para saber mais sobre aAWS, confira estes cursos da DataCamp:

• Introdução à AWS
• Tecnologia e serviços em nuvem da AWS
• Segurança e gerenciamento de custos da AWS
• Introdução ao AWS Boto em Python

Você pode até mesmo usar a DataCamp para se preparar para os exames de certificação da AWS - AWS Cloud Practitioner (CLF-C02).