Configurando a CLI da AWS e o AWS S3
Antes de começar a sincronizar arquivos com o S3, você precisará configurar corretamente a AWS CLI. Isso pode parecer intimidante se você é novo na AWS, mas só levará alguns minutos.
Configurar a CLI envolve dois passos principais: instalar a ferramenta e configurá-la. Vou explicar ambos os passos a seguir.
Instalando a AWS CLI
A instalação da AWS CLI varia ligeiramente dependendo do seu sistema operacional.
Para sistemas Windows:
- Vá para a página de download do AWS CLI
- Baixe o instalador do Windows (64 bits)
- Execute o instalador e siga as instruções
Para sistemas Linux:
Execute os seguintes três comandos pelo Terminal:
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install
Para sistemas macOS:
Assumindo que você tenha o Homebrew instalado, execute esta linha no Terminal:
brew install awscli
Se você não tiver o Homebrew, use esses dois comandos em vez disso:
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 o AWS CLI foi instalado. Aqui está o que você deve ver:
Imagem 1 – Versão do AWS CLI
Configurando o AWS CLI
Agora que você tem o CLI instalado, precisa configurá-lo com suas credenciais da AWS.
Supondo que você já tenha uma conta na AWS, faça login e vá para o serviço IAM. Uma vez lá, crie um novo usuário com acesso programático. Você deve atribuir a permissão apropriada ao usuário, que é o acesso ao S3 no mínimo:
Imagem 2 – Usuário AWS IAM
Ao terminar, vá para “Credenciais de segurança” para criar uma nova chave de acesso. Após a criação, você terá tanto o ID da chave de acesso quanto a Chave de acesso secreta. Anote-os em um local seguro, pois você não poderá acessá-los no futuro:
Imagem 3 – Credenciais de usuário AWS IAM
No Terminal, execute o comando aws configure. Ele solicitará que você insira sua ID de chave de acesso, chave de acesso secreta, região (eu-central-1 no meu caso) e formato de saída preferido (json):
Imagem 4 – Configuração da AWS CLI
Para verificar se você está conectado com êxito à sua conta da AWS a partir da CLI, execute o seguinte comando:
aws sts get-caller-identity
Este é o resultado que você deve ver:
Imagem 5 – Comando de teste de conexão da AWS CLI
E é isso – apenas mais um passo antes de começar a usar o comando de sincronização do S3!
Configurando um bucket AWS S3
O último passo é criar um bucket S3 que armazenará seus arquivos sincronizados. Você pode fazer isso através da CLI ou do Console de Gerenciamento da AWS. Eu vou escolher a última opção, só para variar um pouco.
Para começar, acesse a página do serviço S3 no Console de Gerenciamento e clique no botão “Criar bucket”. Em seguida, escolha um nome de bucket único (globalmente único em toda a AWS) e role a página até o final e clique no botão “Criar”:
Imagem 6 – Criação de bucket AWS
O bucket foi criado e você verá imediatamente no console de gerenciamento. Você também pode verificar se foi criado através 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 você pretende usar o bucket para hospedar arquivos públicos (como assets de um site), será necessário ajustar as políticas e permissões do bucket de acordo.
Agora que está tudo 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 o AWS CLI instalado, configurado e um bucket S3 pronto para uso, é hora de começar a sincronizar! A sintaxe básica para o comando de sincronização do AWS S3 é bastante simples. Deixe-me mostrar como funciona.
O comando de sincronização do S3 segue este padrão simples:
aws s3 sync <source> <destination> [options]
Ambos, a origem e o destino, podem ser um caminho de diretório local ou uma URI S3 (começando com s3://). Dependendo de como você deseja sincronizar, você organizará isso de maneira diferente.
Sincronizando arquivos do local para um bucket S3
Eu estava brincando com a pesquisa profunda da Ollama recentemente. Digamos que essa seja a pasta que eu quero sincronizar com o S3. O diretório principal está localizado na pasta Documents. Aqui está como ele se parece:
Conteúdo da pasta local
Este é o comando que preciso executar para sincronizar a pasta local code-files com a pasta backup no bucket S3:
aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup
A pasta backup no bucket 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 S3:
Imagem 10 – Conteúdo do bucket S3
A beleza da sincronização do S3 é que apenas faz o upload de arquivos que não existem no destino ou que foram modificados localmente. Se você executar o mesmo comando novamente sem alterar nada, você verá… nada! Isso porque o AWS CLI detectou que todos os arquivos já estão sincronizados e atualizados.
Agora, farei duas pequenas alterações – criar um novo arquivo (new_file.txt) e atualizar um existente (requirements.txt). Quando você executar o comando de sincronização novamente, apenas os arquivos novos ou modificados serão enviados:
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 contrário?
Sincronizando arquivos do bucket S3 para um diretório local
Se você quiser baixar 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
Este comando irá baixar todos os arquivos da pasta backup do seu bucket S3 para uma pasta local chamada code-files-from-s3. Novamente, se a pasta local não existir, o CLI a criará para você:
Imagem 12 – Sincronização de S3 para local
Vale a pena notar que A sincronização do S3 não é bidirecional. Ela sempre vai da origem para o 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 você quiser que o destino corresponda exatamente à origem (incluindo exclusões), precisará usar a flag --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 equipou com opções adicionais que oferecem mais controle sobre o processo de sincronização.
Nesta seção, vou mostrar a você algumas das bandeiras mais úteis que você pode adicionar ao comando básico.
Sincronizando apenas 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 a hora da modificação para determinar se um arquivo precisa ser sincronizado. No entanto, essa abordagem pode não capturar sempre todas as alterações, especialmente ao lidar com arquivos que foram modificados, mas permanecem do mesmo tamanho.
Para uma sincronização mais precisa, você pode usar a bandeira --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 timestamps com precisão até milissegundos. Tenha em mente que o uso dessa flag pode desacelerar ligeiramente o processo de sincronização, uma vez que requer comparações mais detalhadas.
Excluir ou incluir arquivos específicos
Às vezes, você não quer sincronizar todos os arquivos em um diretório. Talvez você queira excluir arquivos temporários, logs ou certos tipos de arquivos (como .DS_Store no meu caso). É aí que entram em jogo as flags --exclude e --include.
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 com o S3 excluindo arquivos Python
Você também pode combinar --exclude e --include para criar padrões mais complexos. Por exemplo, excluir 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, então a ordem importa! Aqui está o que você verá ao usar essas flags:
Imagem 14 – Flags de exclusão e inclusão
Agora apenas os arquivos Python são sincronizados, e arquivos de configuração importantes estão ausentes.
Excluindo arquivos do destino
Por padrão, a sincronização do S3 apenas adiciona ou atualiza arquivos no destino – nunca os deleta. Isso significa que se você excluir um arquivo da origem, ele ainda permanecerá no destino após a sincronização.
Para fazer com que o destino seja exatamente espelhado com a origem, incluindo exclusões, use a flag --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 – Flag de exclusão
Isso é particularmente útil para manter réplicas exatas de diretórios. Mas tenha cuidado – essa flag pode levar à perda de dados se usada incorretamente.
Vamos supor que eu exclua config.py da minha pasta local e execute o comando de sincronização com a flag --delete:
Imagem 16 – Flag de exclusão (2)
Como você pode ver, o comando não apenas sincroniza arquivos novos e modificados, mas também exclui arquivos do bucket S3 que não existem mais no diretório local.
Configurando execução seca para sincronização segura
As operações de sincronização S3 mais perigosas são aquelas que envolvem a flag --delete. Para evitar excluir acidentalmente arquivos importantes, você pode usar a flag --dryrun para simular a operação sem realizar realmente nenhuma alteração:
aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backup --delete --dryrun
Para demonstrar, eu deletei os arquivos requirements.txt e settings.toml de uma pasta local e então executei o comando:
Imagem 17 – Simulação
Isso mostrará exatamente o que aconteceria se você executasse o comando de verdade, incluindo quais arquivos seriam enviados, baixados ou excluídos.
Sempre recomendo usar a flag --dryrun antes de executar qualquer comando de sincronização S3 com a flag --delete, especialmente ao trabalhar com dados importantes.
Há muitas outras opções disponíveis para o comando de sincronização do S3, como --acl para definir permissões, --storage-class para escolher o nível de armazenamento do S3 e --recursive para percorrer subdiretórios. Confira a documentação oficial da AWS CLI para obter uma lista completa de opções.
Agora que você está familiarizado com as opções básicas e avançadas de sincronização do S3, vamos ver como usar esses comandos para 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 para o AWS S3 Sync é 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 de sincronização.
Criando backups no S3
Criar backups com o S3 sync é simples—você só precisa executar o comando de sincronização do seu diretório local para um bucket S3. No entanto, existem algumas melhores práticas a serem seguidas para backups eficazes.
Primeiro, é uma boa ideia organizar seus backups por data ou versão. Aqui está uma abordagem simples usando um timestamp no caminho S3:
# Crie uma variável de timestamp TIMESTAMP=$(date +%Y-%m-%d-%H-%M-%S) # Execute o backup aws s3 sync /Users/dradecic/Documents/code-files s3://testbucket-dradecic/backups/$TIMESTAMP
Isso cria uma nova pasta para cada backup com um timestamp como 2025-03-10-18-56-42. Aqui está o que você verá no S3:
Imagem 18 – Backups com carimbo de data/hora
Para dados críticos, você pode querer manter várias versões de backup. Isso é fácil de fazer executando o backup baseado em carimbo de data/hora regularmente.
Você também pode usar a opção --storage-class para especificar uma classe de armazenamento 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 a longo prazo, você poderia até usar a classe de armazenamento Glacier:
aws s3 sync /Users/dradecic/Documents/important-data s3://testbucket-dradecic/backups/$TIMESTAMP --storage-class GLACIER
Mas lembre-se de que os arquivos armazenados no Glacier levam horas para serem recuperados, então não são adequados para dados que você possa precisar rapidamente.
Restaurando arquivos do S3
Restaurar de um backup é tão fácil – basta inverter a origem e o destino no seu comando de sincronização:
# Restaurar do backup mais recente (supondo que você saiba o timestamp) aws s3 sync s3://testbucket-dradecic/backups/2025-03-10-18-56-42 /Users/dradecic/Documents/restored-data
Isso irá baixar todos os arquivos daquele backup específico para o seu diretório local restored-data:
Imagem 20 – Restaurando arquivos do S3
Se você não se lembrar do timestamp exato, pode listar todos os seus backups primeiro:
aws s3 ls s3://testbucket-dradecic/backups/
O que mostrará algo como:
Imagem 21 – Lista de backups
Você também pode restaurar arquivos ou diretórios específicos de um backup usando as flags de exclusão/inclusão que discutimos anteriormente:
# Restaurar apenas os arquivos de configuração 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 críticos, recomendo automatizar seus backups com tarefas agendadas (como jobs cron no Linux/macOS ou Agendador de Tarefas no Windows). Isso garante que você esteja fazendo backup dos seus dados de forma consistente, sem precisar lembrar de fazê-lo manualmente.
Resolução de Problemas com AWS S3 Sync
O AWS S3 sync é uma ferramenta confiável, mas você pode ocasionalmente encontrar problemas. No entanto, a maioria dos erros que você verá são baseados em ações humanas.
Erros comuns de sincronização
Vamos passar por 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 realizar operações específicas. Para corrigir isso, tente uma das seguintes opções:
- Verifique se o seu usuário IAM tem as permissões apropriadas do S3 (
s3:ListBucket,s3:GetObject,s3:PutObject). - Verifique se a política do bucket não nega explicitamente o acesso do seu usuário.
- Garanta que o próprio bucket não esteja bloqueando o acesso público se você precisar de operações públicas.
- Arquivo ou diretório não encontrado erro geralmente aparece quando o caminho de origem especificado no comando de sincronização não existe. A solução é simples – verifique novamente seus caminhos e certifique-se de que eles existem. Preste atenção especial a erros de digitação nos nomes de buckets ou diretórios locais.
- Limite de tamanho de arquivo erros podem ocorrer quando você tenta sincronizar arquivos grandes. Por padrão, a sincronização S3 pode lidar com arquivos de até 5GB. Para arquivos maiores, você verá timeouts ou transferências incompletas.
- Para arquivos maiores que 5GB, você deve usar a flag
--only-show-errorscombinada com a flag--size-only. Esta combinação ajuda nas transferências de arquivos grandes ao minimizar a saída e comparar apenas os tamanhos dos arquivos:
aws s3 sync /Users/dradecic/large-files s3://testbucket-dradecic/large-files --only-show-errors --size-only
Otimização de desempenho de sincronização
Se a sua sincronização S3 estiver mais lenta do que o esperado, há algumas ajustes que você pode fazer para acelerar as coisas.
- 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 chunk. Para arquivos grandes, você pode otimizar a velocidade de transferência ajustando o tamanho do chunk. Isso divide arquivos grandes em chunks de 16MB em vez dos 8MB padrão, o que pode ser mais rápido para 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-progresspara scripts. Se você estiver executando a sincronização do S3 em um script automatizado, use a flag--no-progresspara 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 seus recursos da AWS estiverem na mesma região, especificar o ponto de extremidade regional pode 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 para grandes transferências de dados ou ao executar em máquinas menos potentes.
Se você ainda estiver enfrentando problemas após tentar essas soluções, a AWS CLI possui uma opção de depuração embutida. 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
Espere ver muitas mensagens de log detalhadas, semelhantes a estas:
Imagem 22 – Executando sincronização em modo de depuração
E isso é basicamente tudo quando se trata de solucionar problemas de sincronização do AWS S3. Claro, podem ocorrer outros erros, mas 99% das vezes, você encontrará a solução nesta seção.
Resumindo a Sincronização do AWS S3
Para resumir, a sincronização do AWS S3 é uma daquelas ferramentas raras que são tanto simples de usar quanto incrivelmente poderosas. Você aprendeu 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 a AWS, o comando S3 sync é uma ferramenta essencial – ela economiza tempo, reduz o uso de largura de banda e garante que seus arquivos estejam onde você precisa, quando precisa.
Esteja você fazendo backup de dados críticos, implantando ativos da web ou simplesmente mantendo diferentes ambientes em sincronia, o AWS S3 sync torna o processo simples e confiável.
A melhor maneira de se familiarizar 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 a flag --delete. É melhor levar um minuto extra para verificar o que acontecerá do que excluir acidentalmente arquivos importantes.
Para saber mais sobre a AWS, confira esses cursos da DataCamp:
- Introdução à AWS
- Tecnologia e Serviços em Nuvem da AWS
- Segurança e Gestão de Custos da AWS
- Introdução ao AWS Boto em Python
Você também pode usar o DataCamp para se preparar para os exames de certificação da AWS – Praticante de Nuvem da AWS (CLF-C02).