Configure the release command and health checks
Run a command such as a database migration once per deployment before traffic moves, and decide when a new container counts as ready.
Both settings take effect on the next deployment; the running generation keeps what it started with. Replace app-id with the app's id.
Prerequisites
- Permission for
deploy:UpdateAppon the app. Without it the console does not show the Release and health checks section. - An image with
/bin/sh: the release command runs with/bin/sh -c, replacing the image's entrypoint. - In the console, also
deploy:DescribeAppto open the app's page (without it the page is not found).
Configure them
- Open the app, then choose the Runtime tab.
- Under Release and health checks, for Release command, enter the command, for example
pnpm db:migrate. Leave it empty for none. - (Optional) For Release timeout (seconds), enter a value from 10 to 3600.
- For Health check path, enter a path the app answers, for example
/api/health. - (Optional) For Health check port, Expected status and Health check timeout (seconds), enter values. Empty fields use the defaults: the app's port, any status below 500, 60 seconds (180 for a compose app).
- Choose Save. Saved appears beside the button.
The release service and the checks of other compose services are not in the console; set them with the CLI, API or Terraform.
dcloud deploy apps update app-id \
--release-command 'pnpm db:migrate' \
--health-check '{"path":"/api/health","expectedStatus":200,"timeoutSec":120}'For a compose app, --release-service worker runs the release command from another service than
the published one, and --compose-health-checks adds checks for other services.
PATCH /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601
{
"releaseCommand": "pnpm db:migrate",
"releaseTimeoutSec": 600,
"healthCheck": { "path": "/api/health", "expectedStatus": 200, "timeoutSec": 120 }
}resource "dcloud_app" "web" {
name = "my-app"
builder = "image"
image_ref = "org-example1234.ecr.example.com/orders:1.4.2"
release_command = "pnpm db:migrate"
release_timeout_sec = 600
health_check = jsonencode({ path = "/api/health", expectedStatus = 200, timeoutSec = 120 })
}The update is refused with 400 for a value outside its range, and for a compose app whose pasted
file the change makes invalid (a release-only service that is not the release service, for
example); and with 409 while the app is being deleted. A release service that is not in the
compose file fails the next deployment before anything is rolled out.
How the release command runs
The machine pulls the new image, then runs the release command in a throwaway container of it, with
the app's environment; for a compose app on the app's private network, so db resolves as it does
for the services. Its output appears in the deployment's activity line by line. Exit code 0
continues the rollout; anything else fails the deployment with Release command exited with code <n>; the previous version keeps serving. A release that succeeded is not run again when the same
deployment is retried. A rollback runs the release command that shipped with the deployment it
rolls back to. The command is stopped, and the deployment fails, after releaseTimeoutSec
(default 600).
For a compose app, the release runs before anything is stopped when every service the release service depends on is already running and unchanged. Otherwise (a first deployment, or a dependency being replaced) it runs after those dependencies have started and passed their health checks, and before the release service starts. To run it in an image the app does not serve, see Release-only services.
The release command is handed to the app's machines until one of them reports that it succeeded. Write it so that running it more than once is safe, as a migration tool's "apply pending migrations" is.
How health checks run
A new container is probed every 2 seconds until the check passes or timeoutSec runs out (default
60 seconds, 180 for a compose app's published service). With expectedStatus set, only that status
passes; without it any status below 500 passes. The same check runs with every report the machine
sends afterwards and drives the machine's health in the Deutsche Cloud Console. A compose service listed in
composeHealthChecks is waited for after it starts and before anything that depends on it starts
(default timeout 120 seconds); its port is required, and a check without one fails the
deployment on the machine. A check named for a service the file does not have fails the deployment
before anything is rolled out.
Result
The next deployment runs the release command before traffic moves, and moves traffic only once the health check passes.