Restore a deleted resource
Restore a service, database, volume, environment or project you deleted within the recovery window, delete it for good before the window ends, and change how long NebulaCtrl keeps deleted resources.
Deleting a service, database, volume, environment or project is not immediate. NebulaCtrl keeps it restorable until a deadline. This guide restores a deleted resource, deletes it for good ahead of the deadline, and sets the length of the window.
Before you begin
- Know the recovery window of your organization. The default is 48 hours. The delete dialogs of a project and an environment state it: "You can restore it for 48 hours from Settings > Recently deleted."
- To change the recovery window or to use Delete now, you need the
adminorownerrole. - An API token can delete and restore. Its role must still allow the underlying action:
deployerfor a service, database or volume,adminfor an environment or project.
What happens when you delete
When you delete a service, database, volume, environment or project, NebulaCtrl marks it deleted and starts the recovery window.
- The resource stops serving. Its pods are scaled to zero and its domains are withdrawn.
- Its data, volumes, database cluster and namespace stay.
- It disappears from lists and from the canvas, and its API endpoints answer
404. - It keeps holding its name. See Name conflicts.
- The activity log records
service.deleted,volume.deleted,environment.deletedorproject.deleted.
Deleting a service is still refused while a variable of another service references it. Remove or change that variable first.
Deleting an environment also hides the services that only its draft staged, the ones created in its staged changes and never applied. Restoring the environment restores them with their draft, and the purge deletes them. They never appear as services of the project's other environments in between.
When the window ends, the control plane purges the resource automatically. The purge removes its data, volumes, backups and namespace objects, and records a .purged event, such as service.purged.
Restore a resource
Select Settings > Recently deleted. The table has the columns Deleted item, Lived in, Deleted and Window. Each row shows the kind (Service, Database, Volume, Environment or Project), the name and slug, where it lived, who deleted it (a person, API token NAME, agent NAME or "the platform"), when, and how long it stays restorable, for example "Restorable for 41h 12m". Once the deadline passes the row reads "Window ended; being removed" and Restore is disabled.
Select Restore on the row. A toast reads "Restored NAME. It is stopped; start it when you are ready." For a volume it reads "Restored volume NAME."
Start the resource yourself. On a service or database, open its Settings tab and select Start in ENVIRONMENT.
A restored service, database, environment or project comes back stopped. Nothing starts until you start it. A restored volume has nothing to start.
A restore can fail with a conflict, and the message says what to do. In the API a conflict answers 409.
- If the parent is deleted, restore the parent project or environment first, then restore the resource.
- If another resource has taken the name, rename that resource, then restore.
Delete now
Delete now ends the wait. It runs the same full delete that runs when the window ends: it removes data, volumes, backups and the namespace objects.
Delete now cannot be undone. Nothing is restorable afterwards.
Select Settings > Recently deleted.
Select Delete now on the row. Only an admin sees it.
The dialog is titled "Delete NAME now?" and lists what goes. Type the slug shown under the resource's name to confirm, then select Delete now.
Over the API, send POST /api/v1/deleted/KIND/ID/purge with the body {"confirm":"SLUG"}, where SLUG is the resource's name. It needs the admin role.
Change the recovery window
Select Settings > Recently deleted.
In the Recovery window panel, choose Delete at once, 1 hour, 6 hours, 24 hours, 48 hours, 3 days or 7 days. The choice saves as soon as you pick it, and a toast reads "Recovery window set to 3 days." The panel applies to deletes from then on; what is already deleted keeps its deadline.
The setting ranges from 0 hours to 7 days. With Delete at once, a delete is final and the delete dialogs say it cannot be undone. Over the API, GET and PUT /api/v1/organizations/ORGANIZATION_ID/deleted-retention read and set it with a body such as {"hours":48}.
What is not recoverable
NebulaCtrl removes these at once, whatever the window:
- A preview environment of a closed pull request.
- A service staged in a draft that you discard.
Name conflicts
A deleted resource keeps its name during the window. Creating a new service, volume or project with the same name is refused. The message names the deleted resource and tells you to restore it or delete it now.
To reuse the name, restore the old resource and rename it, or select Delete now on it.
The API
| Call | Purpose |
|---|---|
GET /api/v1/deleted | List what is restorable. |
POST /api/v1/deleted/KIND/ID/restore | Restore a resource, stopped. Answers 409 on a conflict. |
POST /api/v1/deleted/KIND/ID/purge | Delete now. Body {"confirm":"SLUG"}. Admin. |
GET /api/v1/organizations/ORGANIZATION_ID/deleted-retention | Read the recovery window. |
PUT /api/v1/organizations/ORGANIZATION_ID/deleted-retention | Set it. Body {"hours":48}. |
The existing DELETE endpoints still answer 204. They start the recovery window instead of removing the resource.
Verify
After a restore, the row leaves Recently deleted and the resource is back in its list and on the canvas, stopped. After you start it, it serves again. The activity log shows service.restored, volume.restored, environment.restored or project.restored.
Next steps
Deploy a preview for each pull request
Turn on pull request previews for a project so every same-repository pull request gets its own environment, deployed from its branch and deleted when the pull request closes or goes idle.
Approve changes and set deploy freezes
Decide pending approvals for protected environments, set the organization's change policy, skip approval for one service, schedule weekly deploy freezes and cap concurrent deployments in a project.