A mostrar o Markdown sem formatação: não foi possível carregar o visualizador.
## Objetivo
Comparar o que dá um volume partilhado por dois contentores com o que um dispositivo de blocos real acrescenta, e depois executar um armazenamento de objetos local compatível com S3 e usá-lo como usaria um bucket na nuvem: carregar e listar objetos, ativar o versionamento e recuperar um objeto eliminado, escrever uma regra de ciclo de vida, partilhar um objeto com um URL pré-assinado e abrir um prefixo ao público com uma política de bucket.
## Objetivos
- Comparar um volume de um só utilizador com um volume partilhado por dois contentores e explicar o que um dispositivo de blocos real acrescenta (objetivo 1).
- Criar buckets e carregar, listar, transferir e eliminar objetos através da API S3, e ver que os prefixos não são pastas (objetivo 3).
- Ativar o versionamento, ver um marcador de eliminação e restaurar uma versão anterior (objetivo 3).
- Adicionar e ler de volta uma regra de ciclo de vida (objetivos 2 e 3).
- Partilhar um objeto com um URL pré-assinado e abrir um prefixo com uma política de bucket, e explicar por que razão os buckets públicos são arriscados (objetivo 4).
## Pré-requisitos
- Linux com Podman 4 ou posterior, sem privilégios de root, sem `sudo` (testado com Podman 5.8). O Docker funciona se se substituir `podman` por `docker`.
- `curl`. Apenas para o Passo 4 opcional: `mkfs.ext4` e `debugfs` do pacote `e2fsprogs` (instalado por omissão na maioria das distribuições).
- Acesso à Internet para descarregar três imagens na primeira utilização: `docker.io/library/alpine:3.20`, `docker.io/motoserver/moto:5.2.4` e `docker.io/amazon/aws-cli:2.38.0` (algumas centenas de MB no total).
- Porta TCP 9101 livre em `127.0.0.1`.
- [A lição](lesson.pt.md) deste módulo.
> [!WARNING]
> Tudo corre no seu computador: o armazenamento de objetos escuta apenas em `127.0.0.1`, e as chaves `test`/`test` são fictícias e só funcionam com ele. Não há conta, cartão nem recurso real na nuvem envolvidos, pelo que não há nada a faturar. Todos os contentores e volumes começam por `lab-storage-` e os ficheiros de trabalho ficam em `~/storage-lab`; a Limpeza remove-os. Nunca coloque dados reais nem credenciais reais neste laboratório.
> [!NOTE]
> As saídas foram capturadas em novembro de 2026 com o Podman 5.8.7. As datas, os ID de versão, as ETag e as assinaturas serão diferentes na sua máquina; compare a estrutura, não os valores exatos. A Parte B usa o **Moto**, um emulador de código aberto das APIs da Amazon Web Services (AWS). É uma ferramenta de ensino: funciona sem verificações de autenticação, guarda os dados em memória e não implementa todos os comportamentos de um armazenamento de objetos real. As Notas nos passos indicam onde difere.
## Arquitetura
<figure class="diagram" style="--dg-w: 1100px"><svg xmlns="http://www.w3.org/2000/svg" class="dg" viewBox="0 0 1100 440" width="1100" height="440" role="img" aria-labelledby="storage-lab-architecture-pt-title storage-lab-architecture-pt-desc" font-family="Inter, system-ui, -apple-system, Segoe UI, Roboto, sans-serif" xml:lang="pt">
<title id="storage-lab-architecture-pt-title">Arquitetura do laboratório: volumes do Podman e um servidor local compatível com S3</title>
<desc id="storage-lab-architecture-pt-desc">O seu computador Linux executa Podman sem root. Parte A: um contentor escritor, lab-storage-writer, e um contentor leitor, lab-storage-reader, montam ambos o volume com nome lab-storage-data em /data; o volume é um diretório do anfitrião, não um dispositivo de blocos. Parte B: um contentor com AWS CLI versão 2, docker.io/amazon/aws-cli:2.38.0, executado através de uma função de shell com a pasta ~/storage-lab montada como /work, envia pedidos da API S3 por HTTP para 127.0.0.1 porta 9101. Essa porta está mapeada para a porta 5000 do contentor Moto lab-storage-moto, um emulador de S3 que aceita as chaves fictícias test e test e não exige autenticação, e que contém os buckets lab-docs, lab-versioned e lab-pub.</desc>
<rect class="dg-bg" x="0.5" y="0.5" width="1099" height="439" rx="16" fill="#ffffff" stroke="#e3e3dd"/>
<g class="dg-l2"><rect class="dg-tint" x="20" y="20" width="1060" height="400" rx="16" fill="#f1f7f3" stroke="#a1ccb1" stroke-width="1.2" stroke-dasharray="6 5"/>
<g class="dg-icon" transform="translate(36 33) scale(0.7500)" fill="none" stroke="#15803d" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 16V7a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v9m16 0H4m16 0 1.28 2.55a1 1 0 0 1-.9 1.45H3.62a1 1 0 0 1-.9-1.45L4 16"/></g>
<text x="62" y="47" font-size="13" class="dg-ink" fill="#15803d" font-weight="700">O seu computador (Linux, Podman sem root)</text></g>
<g class="dg-l7"><rect class="dg-tint" x="40" y="60" width="480" height="340" rx="16" fill="#f6f2fd" stroke="#c5a9f0" stroke-width="1.2" stroke-dasharray="6 5"/>
<g class="dg-icon" transform="translate(56 73) scale(0.7500)" fill="none" stroke="#6d28d9" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></g>
<text x="82" y="87" font-size="13" class="dg-ink" fill="#6d28d9" font-weight="700">Parte A: volumes</text></g>
<g class="dg-l4"><rect class="dg-tint" x="540" y="60" width="520" height="340" rx="16" fill="#fbf4f0" stroke="#e7b39e" stroke-width="1.2" stroke-dasharray="6 5"/>
<g class="dg-icon" transform="translate(556 73) scale(0.7500)" fill="none" stroke="#c2410c" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17.5 19H9a7 7 0 1 1 6.71-9h1.79a4.5 4.5 0 1 1 0 9Z"/></g>
<text x="582" y="87" font-size="13" class="dg-ink" fill="#c2410c" font-weight="700">Parte B: armazenamento de objetos</text></g>
<rect class="dg-card" x="60" y="104" width="210" height="96" rx="12" fill="#ffffff" stroke="#cfcfc8"/>
<g class="dg-icon-neutral" transform="translate(76 120) scale(1.2500)" fill="none" stroke="#17171c" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></g>
<text x="118" y="141" font-size="15" class="dg-text" fill="#17171c" font-weight="700">Contentor: escritor</text>
<text x="78" y="172" font-size="12.5" class="dg-text" fill="#17171c" font-weight="500" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">lab-storage-writer</text>
<text x="78" y="192" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">acrescenta linhas a shared.log</text>
<rect class="dg-card" x="290" y="104" width="210" height="96" rx="12" fill="#ffffff" stroke="#cfcfc8"/>
<g class="dg-icon-neutral" transform="translate(306 120) scale(1.2500)" fill="none" stroke="#17171c" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></g>
<text x="348" y="141" font-size="15" class="dg-text" fill="#17171c" font-weight="700">Contentor: leitor</text>
<text x="308" y="172" font-size="12.5" class="dg-text" fill="#17171c" font-weight="500" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">lab-storage-reader</text>
<text x="308" y="192" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">lê os mesmos ficheiros</text>
<rect class="dg-card" x="60" y="270" width="440" height="110" rx="12" fill="#ffffff" stroke="#cfcfc8"/>
<g class="dg-l7"><g class="dg-icon" transform="translate(76 286) scale(1.2500)" fill="none" stroke="#6d28d9" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5V19A9 3 0 0 0 21 19V5"/><path d="M3 12A9 3 0 0 0 21 12"/></g></g>
<g class="dg-l7"><text x="118" y="307" font-size="15" class="dg-ink" fill="#6d28d9" font-weight="700">Volume com nome: lab-storage-data</text></g>
<text x="78" y="338" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">montado em /data nos dois contentores</text>
<text x="78" y="358" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">um diretório do anfitrião, não um dispositivo de blocos</text>
<g class="dg-l7"><path class="dg-stroke" d="M165 202V262" stroke="#6d28d9" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l7"><path class="dg-stroke" d="M159 257l6 8 6-8" stroke="#6d28d9" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l7"><path class="dg-stroke" d="M395 202V262" stroke="#6d28d9" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l7"><path class="dg-stroke" d="M389 257l6 8 6-8" stroke="#6d28d9" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l7"><rect class="dg-bg-plain" x="183.312" y="220" width="193.375" height="24" rx="12" fill="#ffffff"/><text x="280" y="236.5" font-size="11.5" class="dg-ink" fill="#6d28d9" font-weight="600" text-anchor="middle" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">-v lab-storage-data:/data</text></g>
<rect class="dg-card" x="560" y="104" width="480" height="96" rx="12" fill="#ffffff" stroke="#cfcfc8"/>
<g class="dg-icon-neutral" transform="translate(576 120) scale(1.2500)" fill="none" stroke="#17171c" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M20 16V7a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v9m16 0H4m16 0 1.28 2.55a1 1 0 0 1-.9 1.45H3.62a1 1 0 0 1-.9-1.45L4 16"/></g>
<text x="618" y="141" font-size="15" class="dg-text" fill="#17171c" font-weight="700">Contentor com AWS CLI v2</text>
<text x="578" y="172" font-size="12.5" class="dg-text" fill="#17171c" font-weight="500" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">docker.io/amazon/aws-cli:2.38.0</text>
<text x="578" y="192" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">função de shell aws() · ~/storage-lab → /work</text>
<rect class="dg-card" x="560" y="262" width="480" height="118" rx="12" fill="#ffffff" stroke="#cfcfc8"/>
<g class="dg-l4"><g class="dg-icon" transform="translate(576 278) scale(1.2500)" fill="none" stroke="#c2410c" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M17.5 19H9a7 7 0 1 1 6.71-9h1.79a4.5 4.5 0 1 1 0 9Z"/></g></g>
<g class="dg-l4"><text x="618" y="299" font-size="15" class="dg-ink" fill="#c2410c" font-weight="700">Contentor Moto: lab-storage-moto</text></g>
<text x="578" y="330" font-size="12.5" class="dg-muted" fill="#5c5c68" font-weight="500" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">porta 9101 → 5000 · chaves test/test, sem autenticação</text>
<text x="578" y="350" font-size="12.5" class="dg-text" fill="#17171c" font-weight="500" font-family="JetBrains Mono, ui-monospace, Menlo, Consolas, monospace">buckets: lab-docs · lab-versioned · lab-pub</text>
<text x="578" y="370" font-size="13" class="dg-muted" fill="#5c5c68" font-weight="500">um emulador da API S3, não um armazenamento durável</text>
<g class="dg-l4"><path class="dg-stroke" d="M800 202V254" stroke="#c2410c" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l4"><path class="dg-stroke" d="M794 249l6 8 6-8" stroke="#c2410c" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/></g>
<g class="dg-l4"><rect class="dg-bg-plain" x="681.52" y="218" width="236.96" height="24" rx="12" fill="#ffffff"/><text x="800" y="234.5" font-size="11.5" class="dg-ink" fill="#c2410c" font-weight="600" text-anchor="middle">API S3 sobre HTTP · 127.0.0.1:9101</text></g>
</svg></figure>
*Figura 1. A Parte A usa um volume do Podman a partir de dois contentores; a Parte B envia pedidos da API S3 do contentor da AWS CLI para um servidor compatível com S3 em `127.0.0.1:9101`.*
## Passos
### Parte A: armazenamento em blocos e partilha semelhante a ficheiros
### Passo 1 — Criar uma pasta de trabalho e um volume
Todos os ficheiros do laboratório ficam numa só pasta, para a limpeza ser fácil. Um **volume com nome** do Podman é armazenamento que sobrevive a um contentor. Crie um e dê-lhe um nome reconhecível.
```bash
mkdir -p ~/storage-lab && cd ~/storage-lab
podman --version
podman volume create lab-storage-data
```
Saída esperada:
```text
podman version 5.8.7
lab-storage-data
```
> [!WARNING]
> Execute todos os comandos seguintes a partir de `~/storage-lab`. Na Parte B, a função `aws` monta a pasta atual num contentor com `:Z`, o que a reetiqueta para o SELinux. Se for executada a partir da sua pasta pessoal, reetiquetaria tudo o que lá estiver.
### Passo 2 — Usar o volume a partir de um contentor
Monta-se o volume em `/data` num contentor de curta duração, escreve-se um ficheiro e depois lê-se a partir de um segundo contentor, para ver que os dados sobrevivem ao primeiro.
```bash
podman run --rm -v lab-storage-data:/data docker.io/library/alpine:3.20 \
sh -c 'echo "written by container one" > /data/note.txt; ls -l /data'
podman run --rm -v lab-storage-data:/data docker.io/library/alpine:3.20 cat /data/note.txt
podman volume inspect lab-storage-data --format '{{.Mountpoint}}'
```
Saída esperada:
```text
total 4
-rw-r--r-- 1 root root 25 Nov 7 19:02 note.txt
written by container one
/home/<user>/.local/share/containers/storage/volumes/lab-storage-data/_data
```
A última linha é o ponto essencial: um volume do Podman é **apenas um diretório no sistema de ficheiros do próprio anfitrião** (`<user>` é o seu nome de utilizador). Não é um dispositivo de blocos: não tem tamanho fixo, nome de dispositivo nem sistema de ficheiros próprio. É um substituto prático da ideia de «armazenamento que sobrevive à computação».
### Passo 3 — Partilhar o volume entre dois contentores em simultâneo
Uma partilha de ficheiros real (NFS ou SMB) permite que muitas máquinas usem os mesmos ficheiros ao mesmo tempo. Aqui, as duas «máquinas» são contentores no mesmo anfitrião. Inicie um escritor em segundo plano e depois leia a partir de um segundo contentor enquanto ele corre.
```bash
podman run -d --name lab-storage-writer -v lab-storage-data:/data docker.io/library/alpine:3.20 \
sh -c 'i=0; while true; do i=$((i+1)); echo "writer line $i" >> /data/shared.log; sleep 1; done'
sleep 3
podman run --rm --name lab-storage-reader -v lab-storage-data:/data docker.io/library/alpine:3.20 \
sh -c 'cat /data/shared.log; echo "reader was here" > /data/reader.txt; ls /data'
```
Saída esperada (o número de linhas depende do tempo):
```text
writer line 1
writer line 2
writer line 3
writer line 4
note.txt
reader.txt
shared.log
```
O leitor vê o ficheiro do escritor enquanto este ainda está a correr, e o seu próprio ficheiro fica visível para o escritor. Pare agora o escritor e veja o que acontece quando dois contentores acrescentam dados ao mesmo ficheiro em simultâneo:
```bash
podman rm -f -t 0 lab-storage-writer
podman run -d --name lab-storage-appender -v lab-storage-data:/data docker.io/library/alpine:3.20 \
sh -c 'for i in 1 2 3 4 5; do echo "A$i" >> /data/both.log; sleep 1; done'
podman run --rm -v lab-storage-data:/data docker.io/library/alpine:3.20 \
sh -c 'for i in 1 2 3 4 5; do echo "B$i" >> /data/both.log; sleep 1; done; cat /data/both.log'
podman rm -f -t 0 lab-storage-appender
```
Saída esperada (as linhas A e B intercalam-se; a ordem exata pode diferir):
```text
A1
B1
A2
B2
A3
B3
A4
B4
A5
B5
```
Ambos os contentores escreveram num só ficheiro sem o corromper. Isso funciona porque o **sistema de ficheiros** (o do anfitrião) está por baixo dos dois contentores e coordena-os: é o mesmo trabalho que os servidores NFS ou SMB fazem numa partilha de ficheiros em rede. Uma partilha de ficheiros dá-lhe isto entre muitas máquinas.
Pense agora no que é um **dispositivo de blocos** real e no que mudaria:
| | Volume do Podman (este laboratório) | Volume de blocos real (disco na nuvem) |
|---|---|---|
| O que é | Um diretório no sistema de ficheiros do anfitrião | Um dispositivo em bruto (`/dev/vdb`) de tamanho fixo |
| Quem gere o sistema de ficheiros | O anfitrião, para todos os utilizadores | A única instância que o monta |
| Vários escritores em simultâneo | Sim, o sistema de ficheiros do anfitrião coordena-os | Não com um sistema de ficheiros comum como o ext4: duas máquinas guardariam em cache e atualizariam os metadados cada uma por si, e corrompê-los-iam |
| Garantias de desempenho | Nenhumas | IOPS, débito e latência aprovisionados |
| Sobrevive à perda da instância | Só enquanto o disco do anfitrião existir | Sim, volta a ligar-se a outra instância |
### Passo 4 — Ver um sistema de ficheiros num dispositivo de blocos (opcional)
Sem direitos de administrador não se consegue criar um dispositivo de blocos real, mas um ficheiro comum serve como «disco virtual»: um dispositivo de blocos é apenas uma matriz de blocos, e um ficheiro pode contê-la. Formata-se o ficheiro com ext4 e lê-se com o `debugfs`, uma ferramenta que inspeciona uma imagem ext4 sem a montar. Salte este passo se `mkfs.ext4` ou `debugfs` não estiverem instalados.
```bash
truncate -s 64M lab-storage-disk.img
mkfs.ext4 -q -F lab-storage-disk.img
file lab-storage-disk.img
echo "hello block" > note.txt
debugfs -w -R "write note.txt note.txt" lab-storage-disk.img
debugfs -R "ls -l" lab-storage-disk.img
debugfs -R "cat note.txt" lab-storage-disk.img
```
Saída esperada (abreviada; o UUID e as horas diferem):
```text
lab-storage-disk.img: Linux rev 1.0 ext4 filesystem data, UUID=<uuid> (extents) (64bit) (large files) (huge files)
debugfs 1.47.3 (8-Jul-2025)
Allocated inode: 13
debugfs 1.47.3 (8-Jul-2025)
2 40755 (2) 0 0 1024 7-Nov-2026 19:55 .
2 40755 (2) 0 0 1024 7-Nov-2026 19:55 ..
11 40700 (2) 0 0 12288 7-Nov-2026 19:55 lost+found
13 100644 (1) 0 0 12 7-Nov-2026 19:55 note.txt
debugfs 1.47.3 (8-Jul-2025)
hello block
```
O ficheiro de 64 MiB contém agora um sistema de ficheiros completo, com uma tabela de inodes, um diretório `lost+found` e o seu ficheiro. Na nuvem, um volume de blocos é a mesma coisa em escala maior: recebe capacidade em bruto e *é você* quem decide que sistema de ficheiros nela coloca.
### Passo 5 — Medir IOPS e débito
O mesmo disco pode parecer rápido ou lento consoante o tamanho de cada operação. Escreve-se a mesma quantidade de dados de duas maneiras com o `dd`, contornando a cache (`oflag=direct`) para medir o armazenamento e não a memória.
```bash
dd if=/dev/zero of=lab-storage-test.bin bs=1M count=256 oflag=direct 2>&1 | tail -1
dd if=/dev/zero of=lab-storage-test.bin bs=4k count=20000 oflag=direct 2>&1 | tail -1
rm -f lab-storage-test.bin
```
Saída esperada (os seus números serão diferentes; alguns idiomas imprimem uma vírgula decimal):
```text
268435456 bytes (268 MB, 256 MiB) copied, 0.181368 s, 1.5 GB/s
81920000 bytes (82 MB, 78 MiB) copied, 1.00239 s, 81.7 MB/s
```
O primeiro comando faz 256 operações de 1 MiB; o segundo faz 20 000 operações de 4 KiB. Nesta captura, o segundo fez cerca de 20 000 operações num segundo (cerca de 20 000 IOPS), mas moveu muito menos bytes por segundo. **Débito = IOPS × tamanho da operação**: as operações pequenas são limitadas pelas IOPS, as grandes pelo débito. É por isso que uma base de dados (muitas operações pequenas) e uma tarefa de cópia de segurança (poucas operações grandes) precisam de definições de volume diferentes.
> [!NOTE]
> Isto mede o disco e o sistema de ficheiros do seu computador, não um volume na nuvem. Serve apenas para mostrar a relação entre o tamanho da operação, as IOPS e o débito. Os volumes reais publicam os seus limites de IOPS e de débito aprovisionados.
### Parte B: armazenamento de objetos
### Passo 6 — Iniciar o armazenamento de objetos e definir o cliente
Executa-se o Moto, um servidor compatível com S3, num contentor. A porta 5000 dentro do contentor é publicada apenas em `127.0.0.1:9101` do seu computador. Depois define-se `aws`, uma função de shell que executa a interface de linha de comandos (CLI) da AWS versão 2 num contentor, apontada ao seu servidor, com chaves fictícias. O `:Z` reetiqueta a pasta para o SELinux e é inofensivo noutros sistemas.
```bash
podman run -d --name lab-storage-moto -p 127.0.0.1:9101:5000 docker.io/motoserver/moto:5.2.4
aws() { podman run --rm --network host -v "$PWD:/work:Z" -w /work \
-e AWS_ACCESS_KEY_ID=test -e AWS_SECRET_ACCESS_KEY=test -e AWS_DEFAULT_REGION=us-east-1 -e AWS_PAGER= \
docker.io/amazon/aws-cli:2.38.0 --endpoint-url http://127.0.0.1:9101 "$@"; }
sleep 4
aws --version
```
Saída esperada:
```text
aws-cli/2.38.0 Python/3.14.6 Linux/7.2.4-ogc3.1.fc44.x86_64 docker/x86_64.amzn.2023
```
> [!IMPORTANT]
> A função só existe neste terminal. Se abrir outro, defina-a de novo (e faça `cd ~/storage-lab`). Como a CLI corre num contentor, cada chamada inicia um contentor (cerca de um segundo).
A única diferença em relação a usar uma nuvem real é o `--endpoint-url`: retire-o, use chaves reais e os mesmos comandos comunicam com um fornecedor real. É isto que significa, na prática, «a API S3 como norma».
### Passo 7 — Buckets, objetos, prefixos e metadados
Cria-se um bucket, carregam-se dois objetos e listam-se. Observe como `reports/2026/q3.txt` aparece como uma «pasta».
```bash
aws s3 mb s3://lab-docs
echo "Quarterly report v1" > report.txt
aws s3 cp --no-progress report.txt s3://lab-docs/reports/2026/q3.txt
aws s3 cp --no-progress report.txt s3://lab-docs/readme.txt --metadata project=apollo,owner=ana --content-type text/plain
aws s3 ls s3://lab-docs
aws s3 ls s3://lab-docs/reports/
aws s3 ls s3://lab-docs --recursive
```
Saída esperada:
```text
make_bucket: lab-docs
upload: ./report.txt to s3://lab-docs/reports/2026/q3.txt
upload: ./report.txt to s3://lab-docs/readme.txt
PRE reports/
2026-11-07 19:02:42 20 readme.txt
PRE 2026/
2026-11-07 19:02:42 20 readme.txt
2026-11-07 19:02:41 20 reports/2026/q3.txt
```
A listagem mostra `PRE reports/` («prefixo»), não uma pasta. Com `--recursive` vê-se o que está realmente guardado: dois objetos cujas **chaves** são `readme.txt` e `reports/2026/q3.txt`. Agora leia os metadados, transfira um objeto e elimine-o:
```bash
aws s3api head-object --bucket lab-docs --key readme.txt
aws s3 cp --no-progress s3://lab-docs/readme.txt downloaded.txt
cat downloaded.txt
aws s3 rm s3://lab-docs/readme.txt
aws s3 ls s3://lab-docs --recursive
```
Saída esperada (a `ETag` e a data variam):
```text
{
"AcceptRanges": "bytes",
"LastModified": "2026-11-07T19:02:42+00:00",
"ContentLength": 20,
"ETag": "\"b9ee29d4dddd352401ae31295dbe672d\"",
"ContentType": "text/plain",
"Metadata": {
"project": "apollo",
"owner": "ana"
}
}
download: s3://lab-docs/readme.txt to ./downloaded.txt
Quarterly report v1
delete: s3://lab-docs/readme.txt
2026-11-07 19:02:41 20 reports/2026/q3.txt
```
A `ETag` é o identificador do conteúdo (um hash MD5 num carregamento simples). O bloco `Metadata` contém os pares personalizados que definiu. Sem versionamento, a eliminação é definitiva: o objeto desaparece.
> [!NOTE]
> Os nomes de bucket têm de ter pelo menos 3 carateres (`aws s3 mb s3://ab` falha com `InvalidBucketName`). Num fornecedor real, os nomes são também globalmente únicos e seguem as regras de nomes DNS, pelo que `lab-docs` provavelmente já está ocupado: acrescente um sufixo aleatório.
### Passo 8 — Versionamento, um marcador de eliminação e um restauro
Cria-se um segundo bucket, ativa-se o versionamento, substitui-se um objeto e elimina-se, e depois recupera-se a primeira versão.
```bash
aws s3 mb s3://lab-versioned
aws s3api put-bucket-versioning --bucket lab-versioned --versioning-configuration Status=Enabled
aws s3api get-bucket-versioning --bucket lab-versioned
echo "version one" > notes.txt
aws s3 cp --no-progress notes.txt s3://lab-versioned/notes.txt
echo "version two, edited" > notes.txt
aws s3 cp --no-progress notes.txt s3://lab-versioned/notes.txt
aws s3api list-object-versions --bucket lab-versioned --query 'Versions[].[VersionId,IsLatest,Size]' --output text
```
Saída esperada (os ID de versão diferem; a primeira linha é a mais recente):
```text
make_bucket: lab-versioned
{
"Status": "Enabled"
}
upload: ./notes.txt to s3://lab-versioned/notes.txt
upload: ./notes.txt to s3://lab-versioned/notes.txt
1ca2a323-276d-4987-b27c-b8496e1ef123 True 20
35cfc607-5f97-489e-acb7-5e775f48bedf False 12
```
Dois carregamentos para a mesma chave criaram **duas versões**: a de 20 bytes («version two, edited») é a atual, e a de 12 bytes («version one») fica guardada. Copie o ID da versão de 12 bytes: vai precisar dele mais abaixo como `<version-id-1>`. Agora elimine o objeto:
```bash
aws s3 rm s3://lab-versioned/notes.txt
aws s3 ls s3://lab-versioned
aws s3 cp --no-progress s3://lab-versioned/notes.txt - ; echo "exit code: $?"
aws s3api list-object-versions --bucket lab-versioned --query 'Versions[].[VersionId,IsLatest,Size]' --output text
aws s3api list-object-versions --bucket lab-versioned --query 'DeleteMarkers[].[VersionId,IsLatest]' --output text
```
Saída esperada:
```text
delete: s3://lab-versioned/notes.txt
download failed: s3://lab-versioned/notes.txt to - An error occurred (404) when calling the HeadObject operation: Not Found
exit code: 1
1ca2a323-276d-4987-b27c-b8496e1ef123 False 20
35cfc607-5f97-489e-acb7-5e775f48bedf False 12
bbe0b185-3e0a-496d-a569-e5b1387c43b5 True
```
A listagem do bucket está vazia e uma transferência diz `404 Not Found`, mas as duas versões continuam lá e um **marcador de eliminação** (a linha com um único `True`) é agora a versão atual. Nada foi apagado. Restaure a primeira versão copiando-a de volta para que passe a ser a versão mais recente:
```bash
aws s3api get-object --bucket lab-versioned --key notes.txt --version-id <version-id-1> old-notes.txt
cat old-notes.txt
aws s3api copy-object --bucket lab-versioned --key notes.txt \
--copy-source "lab-versioned/notes.txt?versionId=<version-id-1>" --query VersionId
aws s3 cp --no-progress s3://lab-versioned/notes.txt -
aws s3api list-object-versions --bucket lab-versioned --query 'Versions[].[VersionId,IsLatest,Size]' --output text
```
`<version-id-1>` é o ID da versão de 12 bytes da listagem. Saída esperada:
```text
{
"AcceptRanges": "bytes",
"LastModified": "2026-11-07T18:56:28+00:00",
"ContentLength": 12,
"ETag": "\"dd8f100298ff923592ab35dc15788abc\"",
"VersionId": "35cfc607-5f97-489e-acb7-5e775f48bedf",
"ContentType": "text/plain",
"Metadata": {}
}
version one
"806268d5-a59a-4468-bfa7-7e724ba7de22"
version one
806268d5-a59a-4468-bfa7-7e724ba7de22 True 12
1ca2a323-276d-4987-b27c-b8496e1ef123 False 20
35cfc607-5f97-489e-acb7-5e775f48bedf False 12
```
Recuperou o objeto: a cópia é uma terceira versão, nova, com o conteúdo antigo, e volta a ser a atual (o marcador de eliminação continua no histórico, oculto por baixo dela). Para remover os dados definitivamente, eliminaria uma versão específica com `aws s3api delete-object --bucket lab-versioned --key notes.txt --version-id <id>`.
> [!NOTE]
> Eliminar o próprio marcador de eliminação (`delete-object` com o `--version-id` do marcador) é a outra forma de desfazer uma eliminação: a versão anterior volta a ser a atual. Funcionou no nosso teste com o Moto, tal como no S3 real.
### Passo 9 — Adicionar uma regra de ciclo de vida
Escrevem-se duas regras: fazer expirar os objetos em `tmp/` após 30 dias e fazer expirar as versões não atuais após 90 dias. O ficheiro JSON contém as regras, e a CLI guarda-as e lê-as de volta.
```bash
cat > lifecycle.json <<'EOF'
{
"Rules": [
{
"ID": "expire-tmp-after-30-days",
"Status": "Enabled",
"Filter": { "Prefix": "tmp/" },
"Expiration": { "Days": 30 }
},
{
"ID": "clean-old-versions",
"Status": "Enabled",
"Filter": { "Prefix": "" },
"NoncurrentVersionExpiration": { "NoncurrentDays": 90 }
}
]
}
EOF
aws s3api put-bucket-lifecycle-configuration --bucket lab-versioned --lifecycle-configuration file://lifecycle.json
aws s3api get-bucket-lifecycle-configuration --bucket lab-versioned
```
Saída esperada (a ordem dos campos e a primeira linha podem diferir):
```text
{
"TransitionDefaultMinimumObjectSize": "all_storage_classes_128K",
"Rules": [
{
"Expiration": {
"Days": 30
},
"ID": "expire-tmp-after-30-days",
"Filter": {
"Prefix": "tmp/"
},
"Status": "Enabled"
},
{
"ID": "clean-old-versions",
"Filter": {
"Prefix": ""
},
"Status": "Enabled",
"NoncurrentVersionExpiration": {
"NoncurrentDays": 90
}
}
]
}
```
> [!NOTE]
> O Moto guarda e devolve as regras de ciclo de vida, mas **nunca as executa**: aqui os objetos não expiram, e não é possível esperar 30 dias para o ver. Num fornecedor real, um processo em segundo plano aplica as regras, normalmente uma vez por dia. Praticou a parte que lhe cabe controlar: escrever uma regra correta. Uma regra com `Prefix` vazio e `NoncurrentVersionExpiration` é a companheira habitual do versionamento, para que as versões antigas não se acumulem para sempre.
### Passo 10 — Partilhar um objeto com um URL pré-assinado
O objeto `lab-docs/reports/2026/q3.txt` é privado. Tenta-se lê-lo sem credenciais e depois cria-se um URL que concede um minuto de acesso.
```bash
curl -s -o /dev/null -w "unsigned request: HTTP %{http_code}\n" http://127.0.0.1:9101/lab-docs/reports/2026/q3.txt
URL=$(aws s3 presign s3://lab-docs/reports/2026/q3.txt --expires-in 60)
echo "$URL"
curl -s -w "pre-signed request: HTTP %{http_code}\n" "$URL"
```
Saída esperada (`X-Amz-Date` e a assinatura diferem):
```text
unsigned request: HTTP 403
http://127.0.0.1:9101/lab-docs/reports/2026/q3.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test%2F20261107%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261107T185711Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
Quarterly report v1
pre-signed request: HTTP 200
```
Observe o URL. O caminho é o objeto. `X-Amz-Expires=60` é a duração em segundos, `X-Amz-Credential` indica a chave que o assinou (mas nunca o segredo) e `X-Amz-Signature` prova que quem assinou autorizou exatamente este pedido. O bucket continuou privado, e o `curl` não usou credenciais: quem tiver o URL obtém o objeto. Altere um carater do caminho ou da assinatura e o pedido é recusado.
> [!NOTE]
> O Moto **não** impõe o prazo de validade: o URL continua a funcionar depois dos 60 segundos. Um fornecedor real devolve `403 Forbidden` após a expiração, e é isso que torna úteis os URL de curta duração. Não confie neste emulador para testar a lógica de expiração.
### Passo 11 — Abrir um prefixo com uma política de bucket
Cria-se um bucket com um objeto público e um privado, confirma-se que ambos são recusados a utilizadores anónimos e depois acrescenta-se uma **política de bucket** que permite a toda a gente ler apenas `reports/*`.
```bash
aws s3 mb s3://lab-pub
echo "public report" > hi.txt
echo "private note" > other.txt
aws s3 cp --no-progress hi.txt s3://lab-pub/reports/hi.txt
aws s3 cp --no-progress other.txt s3://lab-pub/other.txt
for k in reports/hi.txt other.txt; do curl -s -o /dev/null -w "$k before the policy: HTTP %{http_code}\n" http://127.0.0.1:9101/lab-pub/$k; done
```
Saída esperada:
```text
make_bucket: lab-pub
upload: ./hi.txt to s3://lab-pub/reports/hi.txt
upload: ./other.txt to s3://lab-pub/other.txt
reports/hi.txt before the policy: HTTP 403
other.txt before the policy: HTTP 403
```
Escreva agora a política. `"Principal": "*"` significa toda a gente, incluindo quem não tem conta:
```bash
cat > policy.json <<'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PublicReadReportsOnly",
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::lab-pub/reports/*"
}
]
}
EOF
aws s3api put-bucket-policy --bucket lab-pub --policy file://policy.json
for k in reports/hi.txt other.txt; do curl -s -o /dev/null -w "$k after the policy: HTTP %{http_code}\n" http://127.0.0.1:9101/lab-pub/$k; done
curl -s http://127.0.0.1:9101/lab-pub/reports/hi.txt
aws s3api delete-bucket-policy --bucket lab-pub
curl -s -o /dev/null -w "reports/hi.txt after removing the policy: HTTP %{http_code}\n" http://127.0.0.1:9101/lab-pub/reports/hi.txt
```
Saída esperada:
```text
reports/hi.txt after the policy: HTTP 200
other.txt after the policy: HTTP 403
public report
reports/hi.txt after removing the policy: HTTP 403
```
Uma declaração expôs um prefixo a toda a Internet, e outro objeto do mesmo bucket continuou privado. Imagine agora a mesma política com `"Resource": "arn:aws:s3:::lab-pub/*"`: todos os objetos, incluindo o que alguém carregar para o ano. Essa diferença de um só carater é como acontece a maioria das fugas por buckets públicos. Na política, o `Resource` é onde se controla o dano; num fornecedor real, o **bloqueio de acesso público** (block public access) é a rede de segurança que recusa por completo uma política destas.
> [!NOTE]
> O Moto não impõe o bloqueio de acesso público. Se executar `aws s3api put-public-access-block --bucket lab-pub --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true`, ele guarda e devolve as definições, mas uma política pública continua a ser aceite e servida. Num fornecedor real com `BlockPublicPolicy` ativo, o `put-bucket-policy` acima é rejeitado, e `RestrictPublicBuckets` bloqueia o acesso público mesmo a partir de uma política já existente. Não conseguimos verificar esses efeitos aqui, pelo que deve confirmá-los na documentação do seu fornecedor.
## Verificação
Verifique cada resultado; todas as linhas devem coincidir.
1. Parte A: `podman volume inspect lab-storage-data --format '{{.Mountpoint}}'` imprime um caminho dentro da sua pasta pessoal, e `ls "$(podman volume inspect lab-storage-data --format '{{.Mountpoint}}')"` lista `both.log`, `note.txt`, `reader.txt` e `shared.log`.
2. Parte B, objetos: `aws s3 ls s3://lab-docs --recursive` lista exatamente uma chave, `reports/2026/q3.txt`.
3. Versionamento: `aws s3 cp --no-progress s3://lab-versioned/notes.txt -` imprime `version one`, e `aws s3api list-object-versions --bucket lab-versioned --query 'length(Versions)'` imprime `3`.
4. Ciclo de vida: `aws s3api get-bucket-lifecycle-configuration --bucket lab-versioned --query 'Rules[].ID'` lista `expire-tmp-after-30-days` e `clean-old-versions`.
5. URL pré-assinado: um novo URL de `aws s3 presign` obtido com `curl` devolve o texto, enquanto o URL sem assinatura devolve `403`.
6. Política: com a política aplicada, `reports/hi.txt` devolve `200` e `other.txt` devolve `403` (repita o comando da política do Passo 11 se a tiver removido).
## Resolução de problemas
| Sintoma | Causa provável | Solução |
|---|---|---|
| `Could not connect to the endpoint URL: "http://127.0.0.1:9101/"` | O contentor do Moto não está a correr, ou reiniciou-o | `podman ps --filter name=lab-storage`; inicie-o com `podman start lab-storage-moto`. O Moto guarda os dados em memória, pelo que um reinício esvazia todos os buckets: refaça os Passos 7 a 11 |
| `Error: ... address already in use` para a porta 9101 | Outro programa ou contentor usa a porta | Encontre-o com `ss -ltn \| grep 9101`; pare o seu contentor anterior ou altere o primeiro número em `-p 127.0.0.1:9101:5000` e em `--endpoint-url` |
| `aws: command not found` | A função de shell só está definida no terminal onde executou o Passo 6 | Defina-a de novo neste terminal |
| `Permission denied` quando o contentor da AWS CLI lê `report.txt` | O SELinux bloqueia a montagem, ou removeu `:Z` | Mantenha `:Z` na função e execute a partir de `~/storage-lab` |
| `make_bucket failed ... InvalidBucketName` | O nome tem menos de 3 carateres ou carateres inválidos | Use letras minúsculas, dígitos e hífenes, com 3 ou mais carateres |
| `dd: failed to open ... Invalid argument` no Passo 5 | A pasta está num sistema de ficheiros sem suporte de E/S direta, como `tmpfs` | Execute o laboratório a partir de uma pasta num disco normal, ou retire `oflag=direct` (os números passam a medir a cache) |
| `debugfs: command not found` ou `mkfs.ext4: command not found` | O `e2fsprogs` não está instalado | Instale-o, ou salte o Passo 4 opcional |
| O `curl` devolve `403` para o URL pré-assinado | O URL foi cortado pela shell (os carateres `&`), ou foi alterado | Guarde-o numa variável e coloque-o entre aspas: `curl "$URL"` |
## Desafio (opcional)
Crie um bucket chamado `lab-site` e carregue um pequeno `index.html` sob o prefixo `site/`. Escreva uma política de bucket que permita `GET` anónimo apenas para `site/*`, confirme-o com o `curl` e depois altere o `Resource` para que exponha também um prefixo `private/`. Compare as duas políticas e indique quais dos controlos da lição (bloqueio de acesso público, política de menor privilégio, URL pré-assinados) teriam travado a segunda num fornecedor real. Depois use `aws s3 sync ./site s3://lab-site/site` para carregar uma pasta e `aws s3 rm s3://lab-site --recursive` para a remover.
## Limpeza
Remova todos os contentores, volumes e ficheiros que o laboratório criou. O último comando, que remove as três imagens, é opcional: salte-o se as usar para outra coisa.
```bash
podman rm -f -t 0 lab-storage-moto lab-storage-writer lab-storage-reader lab-storage-appender 2>/dev/null
podman volume rm lab-storage-data
cd ~ && rm -rf ~/storage-lab
unset -f aws
# Optional: remove the downloaded images
podman rmi docker.io/motoserver/moto:5.2.4 docker.io/amazon/aws-cli:2.38.0 docker.io/library/alpine:3.20
```
Confirme que não ficou nada:
```bash
podman ps -a --filter name=lab-storage --format '{{.Names}}'
podman volume ls --filter name=lab-storage
```
Ambos os comandos não devem imprimir nada, além do cabeçalho da tabela de volumes.
## O que aprendeu
- Um volume do Podman é um diretório, não um dispositivo de blocos. Um volume de blocos real dá-lhe capacidade em bruto com IOPS, débito e latência próprios, e uma instância gere o sistema de ficheiros nele; uma partilha de ficheiros gere o sistema de ficheiros para muitos clientes.
- O débito é igual às IOPS vezes o tamanho da operação, pelo que as operações pequenas são limitadas pelas IOPS e as grandes pelo débito.
- O armazenamento de objetos acede-se através de uma API HTTP (a API S3) com um bucket, uma chave e metadados; os prefixos só parecem pastas. Mudar o endpoint é tudo o que é preciso para passar de um serviço compatível com S3 para outro.
- O versionamento transforma uma eliminação num marcador de eliminação e mantém todas as versões, pelo que um restauro é uma cópia de uma versão anterior. As regras de ciclo de vida, escritas uma vez, fazem expirar os dados automaticamente num fornecedor real.
- Um URL pré-assinado dá acesso de curta duração a um objeto privado, enquanto uma política de bucket ampla torna os dados públicos para toda a gente: mantenha o bloqueio de acesso público ativo e restrinja bem o `Resource`.