HEALTHCHECK compatibility boundary: standalone Docker to Swarm transition for zero-downtime migration

The Compatibility Boundary

Standalone Docker Engine cannot make HEALTHCHECK status actionable through documented configuration alone. While the daemon monitors the health status and updates the container state to unhealthy, it does not trigger a restart or replacement. Docker restart policies (e.g., always, unless-stopped) respond exclusively to the exit code of the primary process, not the health status.

To achieve automated recovery without manual intervention, you must move the workload into Docker Swarm or utilize an external orchestrator. In Swarm mode, the health status is integrated into the orchestration loop, allowing the manager to terminate and reschedule tasks that fail their health checks.

Swarm Migration: Version-Specific Behaviors

When migrating to Swarm for zero-downtime deployments, the behavior of the deploy key in your Compose file becomes critical. Standalone Docker ignores this section, but Swarm uses it to govern rollout and recovery. To prevent rescheduling gaps or unexpected downtime, verify the following configurations:

1. Health-Based Rollout Strategy

Ensure your update_config is tuned to prevent the orchestrator from killing healthy old tasks before new ones are fully ready. If the order is set to start-first, Swarm will launch the new task and wait for it to be healthy before stopping the old one.

2. The Startup Grace Period

Verify the start_period parameter. Without a defined start period, a slow-booting application may be marked unhealthy immediately upon launch, triggering a restart loop (flapping) before the app can ever reach a ready state.

3. Failure Thresholds

Confirm the interval and retries settings. A tight window (e.g., 5s interval, 3 retries) may cause premature task replacement during transient network spikes, whereas a window that is too wide increases the time the system spends routing traffic to a degraded container.

Verification Steps

To validate the behavior transition, perform these tests in a staging environment:

• Standalone Test: Deploy the image; manually trigger a health failure. Confirm the status changes to unhealthy via docker ps but the container remains running.
• Swarm Test: Deploy as a service; trigger the same failure. Confirm the task is terminated and a new task is provisioned by the manager.

Missing Diagnostic: Please specify the current Docker Engine version. Early versions of the Compose specification handled the deploy key differently, which may affect how your existing file is parsed during the docker stack deploy process.