Gerador de comando AWS S3

AWS S3 CLI a fundo: buckets, chaves, classes de armazenamento e padrões de CLI

O Amazon S3 (Simple Storage Service) foi lançado em março de 2006 como o primeiro serviço público da AWS, antes mesmo do EC2. Ele apresentou ao mundo o armazenamento em larga escala baseado em objetos — um terceiro paradigma, distinto de block storage (EBS, discos crus) e file storage (NFS, EFS). Em vez de montar um sistema de arquivos, você conversa com o S3 via uma API HTTP plana: PUT, GET, DELETE, LIST. Duas décadas depois, o S3 guarda trilhões de objetos, atende dezenas de milhões de requisições por segundo por região, e é a base de tudo — das fitas-mestre da Netflix ao seu state do Terraform.

O AWS CLI é o invólucro oficial de linha de comando para a API do S3. A versão 2 (lançada em 2020) é a distribuição recomendada — instalada como binário self-contained, com auto-completar, suporte a SSO e parser JSON mais rápido. A versão 1 (Python wheel) ainda funciona, mas está em modo manutenção.

Conceitos centrais: bucket, key, region, storage class

• Bucket — namespace de topo, único globalmente em todas as contas AWS. Nomes de 3 a 63 caracteres, minúsculas, dígitos, hífens e pontos; deve começar e terminar com letra ou dígito. Compatível com DNS (usado como bucket.s3.region.amazonaws.com).
• Key — o caminho do objeto dentro do bucket. Máximo 1024 bytes UTF-8. O S3 não tem diretórios de verdade; logs/2026/05/27.log é uma única key, mas o console simula pastas dividindo por /.
• Region — casa geográfica do bucket. us-east-1 (Virgínia do Norte, padrão), sa-east-1 (São Paulo), eu-west-1 (Irlanda), etc. Os dados nunca saem da região, exceto se você replicar.
• Storage class — tier que troca velocidade de retrieval por custo: STANDARD (padrão), STANDARD_IA (acesso infrequente, ~45% mais barato, taxa de recuperação), ONEZONE_IA (uma única AZ), GLACIER_IR (recuperação instantânea), GLACIER (minutos a horas), DEEP_ARCHIVE (~R$5/TB/mês, recuperação em 12 h), INTELLIGENT_TIERING (move sozinho com base no acesso).

Alto nível vs baixo nível: aws s3 vs aws s3api

O CLI expõe dois namespaces S3:

• aws s3 — comandos em estilo filesystem de alto nível: cp, mv, rm, ls, sync, mb, rb. Use para uploads, downloads e syncs do dia a dia.
• aws s3api — invólucro fino sobre a API HTTP crua. Cada operação mapeia 1:1 para um método (put-object, get-object-acl, list-objects-v2, create-multipart-upload). Use para controle fino: tags, lifecycle, replicação, object lock, presigned URLs com expiração customizada.

Comandos comuns

# Listar objetos
aws s3 ls s3://meu-bucket/path/

# Subir um arquivo
aws s3 cp arquivo.txt s3://meu-bucket/uploads/

# Baixar uma árvore inteira
aws s3 cp s3://meu-bucket/logs/ ./logs/ --recursive

# Espelhar pasta local, apagando remotos que sumiram localmente
aws s3 sync ./dist s3://meu-bucket --delete --exclude '.DS_Store'

# Apagar objeto
aws s3 rm s3://meu-bucket/old/file.log

# Criar / remover bucket
aws s3 mb s3://novo-bucket --region sa-east-1
aws s3 rb s3://velho-bucket --force

Flags úteis

• --profile nome — usar perfil não-default de ~/.aws/credentials.
• --region us-east-2 — sobrescrever a região padrão em uma chamada.
• --storage-class GLACIER — subir já em tier frio (economiza transição de lifecycle).
• --sse AES256 ou --sse aws:kms --sse-kms-key-id alias/minha-chave — criptografia server-side.
• --acl public-read — ACL legado; prefira bucket policies em buckets novos.
• --metadata Chave=Valor — metadados de usuário (gravados como cabeçalhos x-amz-meta-*).
• --dryrun — pré-visualizar o que sync/cp fariam sem tocar no S3.
• --exact-timestamps / --size-only — mudar como o sync decide se um arquivo está atualizado.
• --exclude '*.tmp' --include 'logs/*' — combinar padrões; a ordem importa (o último vence).

Performance e custos

O CLI usa multipart upload automaticamente em arquivos acima de ~8 MB (ajustável via aws configure set default.s3.multipart_threshold 16MB) e roda até 10 threads paralelas de upload. Para transferências muito grandes, ative o S3 Transfer Acceleration (uploads chegam pela CloudFront edge mais próxima) e suba max_concurrent_requests. Para uploads do browser, gere presigned URLs com aws s3 presign s3://bucket/key --expires-in 3600 — o usuário sobe direto para o S3 sem passar pelo seu servidor.

O custo tem três componentes: armazenamento ($0,023/GB/mês STANDARD, $0,00099 DEEP_ARCHIVE), requisições ($0,005/1000 PUT, $0,0004/1000 GET) e transferência de saída (grátis para AWS na mesma região, $0,09/GB para a internet). Regras de lifecycle podem migrar objetos para tiers mais baratos sozinhas — configure-as desde o dia um.

FAQ

cp ou sync — qual usar? Use cp --recursive para uma cópia única. Use sync quando for repetir: ele compara timestamps e tamanhos e só envia o que mudou, ficando bem mais rápido para backups incrementais.

O mesmo CLI fala com serviços S3-compatíveis não-AWS? Sim — Wasabi, Backblaze B2, MinIO e Cloudflare R2 expõem API compatível. Acrescente --endpoint-url https://s3.us-west-002.backblazeb2.com que o CLI roteia para lá.

Como acelerar um upload de vários gigabytes? Aumente o chunk e a concorrência do multipart: aws configure set default.s3.multipart_chunksize 64MB e default.s3.max_concurrent_requests 30. Se o gargalo for latência (não banda), ative Transfer Acceleration no bucket.

Como deixar um objeto público? A prática moderna é uma bucket policy dando s3:GetObject a * em um prefixo específico, junto com desligar o S3 Block Public Access. O legado --acl public-read ainda funciona mas vem bloqueado por padrão em buckets novos desde 2023.

Por que meu aws s3 ls retorna vazio se o bucket existe? Ou sua identidade IAM não tem s3:ListBucket, ou o bucket está em região diferente do seu default — tente --region ou confira com aws s3api get-bucket-location --bucket nome.

Os dados são criptografados em repouso? Desde janeiro de 2023, todo objeto novo já é criptografado com SSE-S3 por padrão. Para controle mais estrito, configure o bucket com SSE-KMS usando chave gerenciada pelo cliente — você ganha log de acesso por chave e rotação.