Control deploy order
Make a service's deployments wait for the services and databases it depends on, with the Deploy after list or depends_on in nebula.toml, and read what you see while a deployment waits.
When a service and something it depends on deploy together, the service waits until that one is healthy. A service waits for what its variables already show, and for the services and databases you add to its Deploy after list.
Before you begin
- You need the
deployerrole to change a Deploy after list. - A database service has no Deploy after list: it is waited for, and waits for nothing.
- A service waits only for deployments that started before its own. It never waits for a deployment that starts later, and it never waits for a dependency that is idle.
See what a service waits for
Select the service on the canvas, open the Settings tab and find Deploy after. Each row names a service or database, tagged Service or Database, and says why it is there:
| Row says | Because |
|---|---|
| "reads KEY_A, KEY_B, KEY_C and 2 more" | A variable of the service references that service (${{ db.DATABASE_URL }}), or connects to that database. The row names up to three keys and counts the rest. These rows are marked "from its variables". |
| "you chose this" | You added it to the list. |
| "set in nebula.toml" | The service's nebula.toml lists it in depends_on. These rows are marked "from nebula.toml". |
A reference through ${{ host(api) }} is only an address and adds no row.
Add a dependency
Use this for an order no variable shows, for example an api that expects its migrator service to run first.
Under Deploy after, select the box that reads "Add a service or database" and type a name.
Choose the service or database. It joins the list at once, tagged "you chose this".
The box lists the project's other services and databases, databases first. It reads "Nothing else in this project to add" when there are none. To remove an entry you added, select Remove on its row. To remove a row that reads "from its variables", remove the reference from the variable.
A list holds at most 20 entries. A service cannot wait for itself.
What you see while a deployment waits
A held deployment stays pending. The release that runs now keeps serving. The deployment's label is the reason:
Waiting for db to finish deploying (r-4)On the service's sheet the status reads Waiting with the same line as its detail, and the Deployments tab shows it in the row of the held deployment. db is the service being waited for and r-4 its release. The deployment moves on when db becomes healthy.
If the awaited deployment ends without becoming healthy, the waiting deployment fails and says what happened and what runs now:
Not deployed: db failed to deploy (r-4). api keeps running r-3. Deploy api again once db is healthy.The first words say what happened to the dependency: failed to deploy, was cancelled or was rejected. A service with no running release reads "api has no running release yet." instead. The failed deployment carries the external-dependency blocker. A dependency that was replaced by a newer attempt does not fail the waiting deployment, and neither does one that ended before the waiting deployment was created.
A change set that deploys several services creates their deployments in dependency order, so each waits for the ones it depends on.
Resolve a cycle
A list that would make services wait for each other forever is refused when you set it, with a message that names the whole circle and what to remove:
api → db → api would never finish deploying: remove db from api's Deploy after, or the reference that makes db depend on apiRemove the entry or the reference the message names. A nebula.toml whose depends_on closes a cycle is refused when a release is made. The message starts with the service's name and nebula.toml, names the circle, and ends "fix depends_on and push again". The build is recorded as built, not deployed.
Verify
Start a deployment of the service and of the one it waits for together, for example with Deploy 2 changes on a change set that touches both. The service's deployment reads Waiting for … to finish deploying until the dependency is Healthy, then runs its own stages.
Next steps
- Deployments: the stages a deployment passes through.
- Release commands and files: run a migration inside the service instead of ordering a separate one.
- Deployment states: every state and blocker.
Run release commands and mount files
Run a command such as a database migration before each release starts, and mount a service's variables as read-only files.
Add and back up a volume
Add a persistent volume to a process, grow it, and back it up to an object store on demand or on a schedule. Download backups and restore them onto the volume.