Pular para o conteúdo

Histórico de configuração

Toda mudança de configuração de um serviço vira uma versão imutável: ajustes (porta, healthcheck, recursos, build), variáveis próprias, variáveis compartilhadas que o afetam, domínios, política de domínio e volume. Cada versão guarda quem mudou, quando, o motivo e um resumo do que mudou em relação à anterior (variáveis só por nome, nunca por valor).

No serviço, abra a aba Histórico de configuração. A lista mostra as versões da mais nova para a mais antiga, e Restaurar esta versão pede confirmação de identidade (Confirmação de identidade).

Rota Escopo O que faz
GET /v1/projects/{p}/services/{s}/config-versions projects:read Lista as versões (mais nova primeiro), paginada por cursor.
GET /v1/projects/{p}/services/{s}/config-versions/{v} projects:read Devolve a versão com o config normalizado.
POST /v1/projects/{p}/services/{s}/config-versions/{v}/restore projects:write Restaura a versão {v}.
Janela do terminal
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
-d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions" -H "$H"
{"items": [{"version": 1, "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c", "parent_version": 0, "created_at": "2026-10-16T14:03:11Z", "actor": "01jb7k3a5q8r7t2v4w6x8y0a1b", "reason": "service.create", "summary": []}], "next_cursor": null, "has_more": false}

Versão que não existe e cursor inválido respondem com erro claro, e esses dois casos você pode executar:

Janela do terminal
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
-d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions/999" -H "$H"
{"error": "not_found", "message": "Recurso não encontrado."}
Janela do terminal
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
-d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions?cursor=abc" -H "$H"
{"error": "invalid_request", "message": "Cursor inválido."}

Ao consultar uma versão, cada variável própria vem com value: null e masked: true. O valor continua cifrado no servidor e só é reaplicado pelo restore, sem passar em claro.

O restore nunca reescreve o histórico: ele cria a versão N+1 igual à {v} e marca o serviço para redeploy (redeploy_required: true). Faça um deploy em seguida para a configuração valer.

Janela do terminal
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/config-versions/2/restore" \
-H "Authorization: Bearer $NEBULAR_TOKEN" \
-H "Idempotency-Key: restore-config-2"
{"version": {"version": 4, "parent_version": 2, "reason": "config_version.restore", "summary": ["port: 8080 -> 3000"]}, "redeploy_required": true}

Restaura: porta, healthcheck, comandos, recursos, source/build, auto deploy, política de domínio e as variáveis próprias com o valor original.

Não restaura: nome, slug e visibilidade, os dados do volume, os domínios (exigem DNS) e as variáveis compartilhadas do projeto.

Com token, o restore também exige a permissão destroy da política do token (Tokens e escopos).

A plataforma mantém o artefato dos 10 deploys mais recentes de cada serviço (o ativo mais nove destinos de rollback; antes eram 2), e o rollback volta a qualquer um deles sem rebuild. O histórico de configuração complementa o rollback: o rollback volta o código, e o restore de versão volta a configuração. Nenhum dos dois desfaz dados de banco ou de volume.