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

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}'

{"mount_path": "/data", "size_gb": 5}

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

Ler e apagar

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"

{"mount_path": "/data", "size_gb": 5}

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

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.