A background worker receives a payment notification and begins processing it. Before the operation finishes, Kubernetes starts replacing the Pod during a deployment. The worker receives a termination signal. If the application exits immediately, the job may be interrupted halfway through execution.
For queue-driven applications, graceful shutdown is not simply a container-management detail. It is part of the reliability contract between the worker, message broker and business operation.
What Kubernetes does during termination
When a Pod is terminated, Kubernetes begins its shutdown sequence. The kubelet may execute a configured preStop hook and then ask the container runtime to send a termination signal to the container’s main process. For many Linux workloads, this is SIGTERM.
The Pod has a termination grace period, commonly thirty seconds by default. Once that period expires, remaining processes may be forcibly terminated. A worker cannot assume it will have unlimited time to finish its current job.
Stop accepting work before exiting
The first responsibility of a terminating worker is to stop claiming new jobs. The second is to finish or safely abandon work already in progress. The exact mechanism depends on the queue system, but the principle is consistent.
For a PHP CLI worker, a signal handler can set a shutdown flag. The main loop checks that flag between jobs and exits without starting another operation. This is a conceptual structure using PHP’s PCNTL extension on a supported Unix-like runtime.
<?php
declare(strict_types=1);
$stopping = false;
pcntl_async_signals(true);
pcntl_signal(
SIGTERM,
function () use (&$stopping): void {
$stopping = true;
}
);
while (!$stopping) {
$job = $queue->reserve(timeout: 2);
if ($job === null) {
continue;
}
try {
processJob($job);
$queue->acknowledge($job);
} catch (Throwable $e) {
$queue->releaseOrRetry($job, $e);
}
}The queue methods are illustrative rather than a specific library API. A real implementation must follow the broker’s acknowledgment, visibility timeout and retry semantics. The loop also assumes the signal handler can run between operations; blocking extensions and external processes may require additional care.
Acknowledgment timing matters
Many queues support acknowledging a message after successful processing. If a worker acknowledges before completing the business operation and then crashes, the broker may consider the message finished even though the operation failed.
Acknowledging after processing reduces that risk, but introduces another possibility: the operation succeeds and the worker crashes before acknowledgment. The message may be delivered again. This is why at-least-once delivery and idempotent handlers are closely related.
Idempotency protects against duplicate delivery
A handler is idempotent when repeating the same logical operation does not produce unintended additional effects. A payment notification, for example, should not create two invoices simply because the broker redelivered a message.
Applications can use stable message identifiers, database uniqueness constraints and transactional state transitions to detect repeated work. The correct design depends on whether the operation touches one database or several external systems. A database transaction cannot automatically make an unrelated HTTP API call atomic.
Choosing a grace period
The terminationGracePeriodSeconds setting should reflect realistic job duration and shutdown behavior. If most jobs finish within ten seconds but a few take several minutes, increasing the grace period may help, but it is not a complete solution.
Long-running jobs may need checkpoints, resumable execution or smaller units of work. Otherwise, deployments and node maintenance can remain blocked by a single slow operation. Design for interruption instead of assuming it will never occur.
Container entrypoints can hide signals
Signal handling also depends on how the container starts its application. A shell wrapper that launches PHP without replacing itself may interfere with signal forwarding. Prefer an entrypoint that executes the worker as the intended main process, or use a suitable init process that forwards signals correctly.
Test the actual container image rather than relying on local PHP CLI behavior alone. The container runtime, shell and process hierarchy are all relevant to shutdown reliability.
Test termination under load
A useful integration test starts several workers, publishes a controlled batch of jobs and initiates a rolling deployment while processing is active. Verify that completed jobs are acknowledged, interrupted jobs are retried according to policy and no business operation is applied twice.
Measure the number of jobs in flight, shutdown duration, redelivery count and retry age. Also test forced termination after the grace period. A graceful path is valuable, but the system must still recover when graceful shutdown fails.
Kubernetes can orchestrate container termination, but it cannot guarantee business-level exactly-once processing. Reliable queue workers require cooperation between infrastructure, application lifecycle management and idempotent business operations.























