Blue-green deployments
See how Tenkai starts the new version of a web application next to the old one, moves the traffic once it is healthy, and why an application that keeps files stops first.
Tenkai starts a new version of your web application beside the running version. It checks the new version, moves the routes to it, then stops the old one. This is a blue-green deployment. In Tenkai, blue is the Active release and green is the Candidate.
The old version keeps its routes until the new version takes traffic. Readiness checks catch startup failures, not every bug. An application that keeps files must stop before its replacement starts.
Scene 1 of 7: v1 serves
v1 is the active release. The edge router of the edge node sends every request to its replicas.
What Tenkai checks
All candidate replicas must run within a minute. Downloading the image has a separate ten-minute limit. Time spent downloading does not count toward the one-minute startup limit. An image's Docker HEALTHCHECK must pass before its replica counts as running. Tenkai sets a one-second startup check interval and a one-minute start period.
Once the replicas run, Tenkai probes the candidate over HTTP from inside the cluster, even if the image has a HEALTHCHECK:
- With a configured health check, only a
2xxresponse passes. You choose its path, timeout, attempts, interval and headers. Marketplace applications can supply a default. - Without one, Tenkai waits up to two minutes for any HTTP response on the application's configured port, 8080 by default. Even
500passes. This checks that the server answers, not that it works.
Start your HTTP server only when the application is ready. A passing probe does not prove that every replica or feature works.
What visitors see during the switch
Tenkai gives the candidate higher-priority routes while the active release keeps its routes. Traefik starts sending requests to the candidate before Tenkai removes the old routes. The switch leaves no routing gap and does not split traffic by percentage.
The switch includes the default route only if it is enabled and published. It also includes custom domains that are ready to receive traffic. Requests already in progress still depend on the old process finishing them before it exits.
Once Tenkai confirms each routed hostname points only to the candidate, it becomes the active release. Tenkai scales the old service to zero and keeps its image for rollback. This checks routing, not whether every request succeeds.
When the new version fails
Without kept files, a failed build, command or startup check leaves the active release running. Tenkai stops any candidate it started. It does not undo database changes made by commands or startup code. Those can still affect visitors.
If the switch fails, Tenkai tries to restore the previous routes. If Tenkai cannot confirm which version has the routes, it blocks new deployments until it checks and repairs the routing. Use Reconcile routes on the web application. Kept files change this rule, below.
An application that keeps files
A web application with kept directories, such as WordPress, runs one replica on the node holding its files. The old version stops first so both versions cannot write to them at once.
Scene 1 of 5: v1 writes the files
The application runs 1 replica, on the node that holds its files. Two versions must never write to the same files.
The application is unavailable until the candidate takes the routes. File copies, commands and startup all add to the wait. There is no fixed duration.
When the image changes, Tenkai copies the files before commands or the candidate start. If the candidate fails before taking the routes, Tenkai restores the copy and restarts the old version. On success, it keeps the copy as the Deployment snapshot. If the image is unchanged but the deployment runs commands, Tenkai still copies the files first. It deletes that temporary copy after a successful deployment.
Once the candidate has served traffic, Tenkai never restores old files automatically. That would erase new writes. It resumes an interrupted deployment and completes it once it confirms the candidate has the routes, even if the app returns an error.
Rollback to the snapshot's image restores its files, with your confirmation. Later writes are no longer served. Rollback to the current image keeps the files. Tenkai keeps one snapshot. See which releases allow rollback.
What your application must accept
Without kept files, two versions run at once during a deployment.
- Keep database migrations compatible with the old version. Add columns and tables first. Remove old ones in a later deployment.
- Leave CPU and memory for both versions. Otherwise, the deployment fails with Not enough free capacity.
- Handle the image's stop signal,
SIGTERMby default. Finish requests in progress, then exit.
Rollback, Apply configuration and relocation use the same checks and route switch, one operation at a time. Rollback runs rollback commands. Apply configuration and relocation run none. Applications with kept files cannot move through a drain.
A worker starts beside its old version too. All tasks must run and still be running 15 seconds later. It has no HTTP probe.
When another option suits better
- Your versions cannot run together. Use pre-deploy commands for work that runs once per deployment. Split incompatible migrations across deployments. If neither solves the overlap, blue-green deployment is not a fit.