Docker Swarm Unless-Stopped Policy Auditor

The Incident (What Does the Error Mean?)

When you migrate a standalone docker-compose.yml to a Swarm stack, Docker silently drops unsupported restart policy values. You will not get a hard error. The service deploys, appears healthy, and then behaves incorrectly under failure conditions.

Raw symptom output from docker service inspect:

"RestartPolicy": {
    "Condition": "any",
    "Delay": 0,
    "MaxAttempts": 0
}

Swarm has silently coerced your policy — or in some versions, simply defaulted to any with no cap — because unless-stopped is a Docker Engine concept tied to a local daemon tracking explicit docker stop calls. Swarm has no daemon-local state per container. There is no "stopped by the user" signal at the orchestration layer. The concept is architecturally meaningless in a distributed scheduler.

Immediate consequence: Services you intended to leave stopped after a manual halt will restart automatically. Maintenance windows, deliberate scale-to-zero operations, or controlled drains get undermined silently.

The Attack Vector / Blast Radius

This is not a CVE, but the operational blast radius is significant:

1. Runaway restart loops during incidents. You manually stop a misbehaving service replica during a production incident. Swarm immediately restarts it. You are now fighting the orchestrator during an outage.

2. Cascading dependency failures. A service dependent on an external resource (DB migration lock, external API rate limit) keeps restarting and hammering the dependency. Without MaxAttempts set, this is unbounded.

3. Invisible policy drift from Compose migrations. Teams assume Swarm honored their Compose file. Audits show the running policy is not what the source-controlled file declares. Your Git repo lies about your production state.

4. Silent coercion means no alert fires. No docker stack deploy error, no warning in docker service ps, no event in docker events. Engineers discover the mismatch only during post-mortems.

Prevention in CI/CD

This class of silent misconfiguration is entirely preventable with static analysis in your pipeline.

1. Checkov — Swarm Policy Validation

# .checkov.yml
checks:
  - CKV_DOCKER_*
# Add custom check for unless-stopped in deploy blocks

Checkov's CKV_DOCKER_9 flags restart policy issues. Add a custom policy for Swarm-specific constraints:

# checkov/custom/SwarmRestartPolicy.py
from checkov.common.models.enums import CheckResult
from checkov.yaml_runner.checks.base_yaml_check import BaseYamlCheck

INVALID_SWARM_CONDITIONS = {"unless-stopped", "always"}

class SwarmRestartPolicyCheck(BaseYamlCheck):
    def __init__(self):
        super().__init__(
            name="Ensure Swarm restart_policy condition is valid",
            check_id="CKV_CUSTOM_SWARM_1",
            supported_entities=["services"],
            block_type="services"
        )

    def scan_resource_conf(self, conf):
        for svc in conf.values():
            condition = svc.get("deploy", {}).get("restart_policy", {}).get("condition", "")
            if condition in INVALID_SWARM_CONDITIONS:
                return CheckResult.FAILED
        return CheckResult.PASSED

2. OPA / Conftest Gate

# policy/swarm_restart.rego
package swarm

DENY_CONDITIONS := {"unless-stopped", "always"}

deny[msg] {
  svc := input.services[name]
  condition := svc.deploy.restart_policy.condition
  DENY_CONDITIONS[condition]
  msg := sprintf("Service '%v': restart_policy condition '%v' is not valid in Swarm mode. Use 'any', 'on-failure', or 'none'.", [name, condition])
}

# In your CI pipeline
conftest test docker-compose.yml --policy policy/

3. Pre-Deploy Hook (Shell)

#!/bin/bash
# pre-deploy-check.sh — fails the pipeline on invalid Swarm restart policies
if grep -rE 'condition:\s*unless-stopped' docker-compose*.yml; then
  echo "ERROR: 'unless-stopped' is not a valid Swarm restart policy condition."
  echo "Replace with 'any' or 'on-failure'. See runbook: wiki/swarm-restart-policies"
  exit 1
fi

Add this as a required CI step before any docker stack deploy command. Zero dependencies, runs in 200ms.