# Volumes

Escopo: `volumes:write` (e `projects:read` para ler).

## Regras

- **1 volume por serviço** neste ciclo.
- `mount_path`: absoluto, não pode ser `/`, nem `/proc`, `/sys`, `/dev`, `/etc`.
- `size_gb`: de 1 a 50.
- O sistema de arquivos do serviço é somente leitura; o volume (e `/tmp`, 64 MB) são os únicos graváveis.
- **Sobrevive a redeploy.** O redeploy recria a aplicação, nunca os dados do volume.
- **Apagar** pede confirmação de identidade (step-up) **só no painel**. Com token de API, o escopo `volumes:write` é a autorização: o `DELETE` não exige step-up.

## Criar (ou substituir) o volume

```bash
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol-proj-$SUF" -d "{\"name\": \"vol-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol-svc-$SUF" \
  -d "{\"name\": \"app\", \"kind\": \"app\", \"visibility\": \"private\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.0\"}}" | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{"mount_path": "/data", "size_gb": 5}'
```
```json
{"mount_path": "/data", "size_gb": 5}
```

O volume passa a existir no próximo deploy do serviço.

## Ler e apagar

```bash
SUF=$(date +%s)-$RANDOM
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol2-proj-$SUF" -d "{\"name\": \"vol2-$SUF\"}" | jq -r .id)
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" -H "$H" -H "Content-Type: application/json" \
  -H "Idempotency-Key: vol2-svc-$SUF" \
  -d '{"name": "app", "kind": "app", "visibility": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.0"}}' | jq -r .id)
curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H" \
  -H "Content-Type: application/json" -d '{"mount_path": "/data", "size_gb": 5}' >/dev/null
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/volume" -H "$H"
```
```json
{"mount_path": "/data", "size_gb": 5}
```

Apagar (`DELETE`, resposta `204`, irreversível) exige o escopo `volumes:write`; o step-up vale só no painel:

```text
DELETE /v1/projects/{p}/services/{s}/volume   (Authorization: Bearer $NEBULAR_TOKEN)
```

## Se algo falhar

| Resposta | O que fazer |
|---|---|
| `400 invalid_request` | `mount_path` proibido ou `size_gb` fora de 1..50: corrija. |
| `403 forbidden` | Falta `volumes:write`. |
| `404 not_found` | Projeto/serviço inexistente ou sem acesso; ou o serviço não tem volume (no `GET`/`DELETE`). |
| `quota_exceeded` | Limite de armazenamento do time: veja [Limites e cotas](/operacao/limites-e-cotas/). |