Support prefer-local mode for swarm

Author: mesudip

README.md

@@ -85,7 +85,7 @@ Control the default behavior of `nginx-proxy`:
 | `NGINX_WORKER_CONNECTIONS` | `65535` | Max connections per worker. |
 | `CERT_RENEW_THRESHOLD_DAYS` | `30` | By default certificates are renewed when they have <=30 days remaining. |
 | `ENABLE_IPV6` | `false` | Enable IPv6 support on nginx. |
-| `DOCKER_SWARM` | `ignore` | Controls Docker Swarm discovery. Supported values are `ignore`, `exclude`, `enable`, and `strict`; see [Docker Swarm Support](#docker-swarm-support-preview). |
+| `DOCKER_SWARM` | `ignore` | Controls Docker Swarm discovery. Supported values are `ignore`, `exclude`, `enable`, `prefer-local`, and `strict`; see [Docker Swarm Support](#docker-swarm-support-preview). |
 | `SWARM_DOCKER_HOST` | - | URL of the Swarm manager socket (e.g., `tcp://manager:2375`). |
 | `CERTAPI_URL` | - | External Certificate API URL. |
 | `CERTAPI_BATCH_DOMAINS` | `true` | When using `CERTAPI_URL`, request safe domain batching (`batch_domains=true`) to avoid recursive domain-order errors. |
@@ -150,6 +150,7 @@ Docker Swarm discovery is controlled by the `DOCKER_SWARM` environment variable
 | `ignore` | Included | Not discovered | Default Docker-only behavior. Swarm task containers are treated like standalone containers if they are visible on the local Docker socket. |
 | `exclude` | Included | Not discovered | Docker-only discovery while explicitly ignoring containers that belong to Swarm services. |
 | `enable` | Included | Included | Mixed mode. Use this when `nginx-proxy` should route both standalone containers and Swarm services. |
+| `prefer-local` | Included | Included | Mixed Swarm mode that prefers healthy local task containers and keeps the service VIP as a fallback. |
 | `strict` | Excluded | Included | Swarm-only mode. Use this when `nginx-proxy` should route only Swarm services. |
 
 `ignore` is the default and does not require the Docker node to be in Swarm mode. In this mode, `nginx-proxy` only reads the normal Docker container API. If a Swarm task container is visible on the local Docker socket, it can be registered as if it were a regular container.
@@ -158,9 +159,11 @@ Docker Swarm discovery is controlled by the `DOCKER_SWARM` environment variable
 
 `enable` reads both local containers and Swarm services. Standalone containers are discovered from the local Docker socket. Swarm services are discovered from the Swarm manager API, and task containers are skipped so each service is registered once.
 
+`prefer-local` reads both local containers and Swarm services, but local Swarm task containers are also discovered from the local Docker socket. When a route has local containers and the Swarm service VIP, nginx sends normal traffic to the local containers and marks the service VIP as a `backup` upstream server. If no local container is available, the service VIP is used normally. Existing container healthcheck and `BACKEND_START_GRACE_SECONDS` behavior still applies before local containers are registered.
+
 `strict` reads only Swarm services. Local standalone containers are ignored, and Swarm task containers are also ignored. This is the mode to use when this proxy instance is dedicated to Swarm routing.
 
-For `enable` and `strict`, the Swarm API client must be connected to a manager node because Docker only allows managers to list services. If `nginx-proxy` is running on a worker node, set `SWARM_DOCKER_HOST` to a reachable manager Docker API endpoint:
+For `enable`, `prefer-local`, and `strict`, the Swarm API client must be connected to a manager node because Docker only allows managers to list services. If `nginx-proxy` is running on a worker node, set `SWARM_DOCKER_HOST` to a reachable manager Docker API endpoint:
 
 ```bash
 -e DOCKER_SWARM=enable \

dev-requirements.txt

@@ -1,4 +1,4 @@
-pytest==8.2.2
+pytest==9.0.3
 pytest-cov
 websocket-client
 python-dotenv

nginx/Nginx.py

@@ -107,19 +107,19 @@ def _parse_error_line(self, error_msg):
         # Try to find the specific error line for the config file we are managing
         config_filename = os.path.basename(self.config_file_path)
         escaped_filename = re.escape(config_filename)
-        
+
         # Search for: filename:line_number
         match = re.search(f"{escaped_filename}:(\\d+)", error_msg)
         if match:
             return int(match.group(1))
-            
+
         # Fallback: Search for any line number pattern usually at end of line in Nginx errors
         lines = error_msg.splitlines()
         for line in lines:
             if "emerg" in line or "error" in line:
-                 match = re.search(r':(\d+)(?:\s|$)', line)
-                 if match:
-                     return int(match.group(1))
+                match = re.search(r":(\d+)(?:\s|$)", line)
+                if match:
+                    return int(match.group(1))
         return None
 
     def _print_error_context(self, config_str, line_no):
@@ -130,10 +130,10 @@ def _print_error_context(self, config_str, line_no):
             return False
 
         print(f"Error Location in Config (Line {line_no}):", file=sys.stderr)
-        
-        start_idx = max(0, line_no - 6) 
+
+        start_idx = max(0, line_no - 6)
         end_idx = min(total_lines, line_no + 5)
-        
+
         for i in range(start_idx, end_idx):
             current_line = i + 1
             marker = ">>" if current_line == line_no else "  "

nginx_proxy/BackendTarget.py

@@ -17,6 +17,7 @@ def __init__(
         network_settings: dict = None,
         ports: dict = None,
         backend_type: str = "container",
+        backup: bool = False,
     ):
         self.name = name
         self.id = id
@@ -30,6 +31,7 @@ def __init__(
         self.network_settings = network_settings if network_settings else {}
         self.ports = ports if ports else {}
         self.type = backend_type
+        self.backup = backup
 
     @staticmethod
     def from_container(container: DockerContainer):

nginx_proxy/DockerEventListener.py

@@ -37,7 +37,7 @@ def run(self):
                 t1.start()
                 threads.append(t1)
 
-            if swarm_mode in ("enable", "strict") and self.swarm_client is not None:
+            if swarm_mode in ("enable", "prefer-local", "strict") and self.swarm_client is not None:
                 t2 = threading.Thread(target=self._listen, args=(self.swarm_client,), daemon=True)
                 t2.start()
                 threads.append(t2)
@@ -53,7 +53,7 @@ def _listen(self, client):
         types = []
         events = ["health_status"]  # common events
 
-        if client == self.swarm_client and swarm_mode in ("enable", "strict"):
+        if client == self.swarm_client and swarm_mode in ("enable", "prefer-local", "strict"):
             types.append("service")
             events.extend(["create", "update", "remove"])
 
@@ -114,9 +114,9 @@ def _process_service_event(self, action, event):
     def _process_container_event(self, action, event):
         container_id = event.get("Actor", {}).get("ID") or event.get("id")
         attributes = event.get("Actor", {}).get("Attributes", {})
-        
+
         swarm_mode = self.web_server.config.get("docker_swarm", "ignore")
-        if swarm_mode != "ignore" and "com.docker.swarm.service.id" in attributes:
+        if swarm_mode not in ("ignore", "prefer-local") and "com.docker.swarm.service.id" in attributes:
             # print(f"Skipping event {action} for service task container {container_id}")
             return
 
@@ -135,7 +135,7 @@ def _process_container_health_event(self, action, event):
         attributes = event.get("Actor", {}).get("Attributes", {})
 
         swarm_mode = self.web_server.config.get("docker_swarm", "ignore")
-        if swarm_mode != "ignore" and "com.docker.swarm.service.id" in attributes:
+        if swarm_mode not in ("ignore", "prefer-local") and "com.docker.swarm.service.id" in attributes:
             return
 
         health_status = (action or "").strip().lower().removeprefix("health_status:").strip()
@@ -153,7 +153,9 @@ def _handle_container_start(self, container_id: str, attributes=None):
                     self._activate_backend_if_running(container_id, container=container)
                 else:
                     self._waiting_for_healthy.add(container_id)
-                    self._log_container_event("Container waiting   ", container_id, container=container, detail="for healthy")
+                    self._log_container_event(
+                        "Container waiting   ", container_id, container=container, detail="for healthy"
+                    )
                 return
 
             grace_seconds = float(self.web_server.config.get("backend_start_grace_seconds", 0) or 0)
@@ -220,7 +222,9 @@ def _container_is_running(container) -> bool:
         state_status = container.attrs.get("State", {}).get("Status")
         return state_status == "running" or getattr(container, "status", None) == "running"
 
-    def _log_container_event(self, label: str, container_id: str, container=None, attributes=None, detail: str | None = None):
+    def _log_container_event(
+        self, label: str, container_id: str, container=None, attributes=None, detail: str | None = None
+    ):
         container_name = self._container_name(container=container, container_id=container_id, attributes=attributes)
         parts = [label, "Id:" + container_id[:12]]
         if container_name:
@@ -296,7 +300,7 @@ def _should_forward_network_connect(self, container_id: str) -> bool:
 
         swarm_mode = self.web_server.config.get("docker_swarm", "ignore")
         labels = container.attrs.get("Config", {}).get("Labels", {})
-        if swarm_mode != "ignore" and "com.docker.swarm.service.id" in labels:
+        if swarm_mode not in ("ignore", "prefer-local") and "com.docker.swarm.service.id" in labels:
             return False
         return True
 
@@ -305,7 +309,9 @@ def _is_pending_startup(self, container_id: str) -> bool:
 
     def _load_started_container_ids(self) -> set[str]:
         try:
-            return {container.id for container in self.client.containers.list() if self._container_is_running(container)}
+            return {
+                container.id for container in self.client.containers.list() if self._container_is_running(container)
+            }
         except (KeyboardInterrupt, SystemExit):
             raise
         except Exception:

nginx_proxy/NginxProxyApp.py

@@ -72,13 +72,8 @@ def _loadconfig(self) -> NginxProxyAppConfig:
             port = parsed.port
             if port is None:
                 port = 443 if parsed.scheme == "https" else 80
-            
-            certapi = {
-                "url": certapi_url,
-                "host": parsed.hostname,
-                "scheme": parsed.scheme,
-                "port": port
-            }
+
+            certapi = {"url": certapi_url, "host": parsed.hostname, "scheme": parsed.scheme, "port": port}
 
         wellknown_path = os.getenv("WELLKNOWN_PATH", "/.well-known/acme-challenge/").strip()
         # Ensure wellknown_path starts with / and ends with /
@@ -163,7 +158,7 @@ def _init_docker_client(self) -> None:
 
         # Validate Swarm mode if enabled
         swarm_mode = self.config["docker_swarm"]
-        if swarm_mode in ("enable", "strict"):
+        if swarm_mode in ("enable", "prefer-local", "strict"):
             try:
                 info = self.swarm_client.info()
                 swarm_info = info.get("Swarm", {})
@@ -186,7 +181,9 @@ def _init_docker_client(self) -> None:
 
     def start(self):
         self.server = WebServer(self.docker_client, self.config, swarm_client=self.swarm_client)
-        self.docker_event_listener = DockerEventListener(self.server, self.docker_client, swarm_client=self.swarm_client)
+        self.docker_event_listener = DockerEventListener(
+            self.server, self.docker_client, swarm_client=self.swarm_client
+        )
 
     def stop(self):
         print("Stopping NginxProxyApp...")

nginx_proxy/WebServer.py

@@ -69,7 +69,7 @@ def __init__(
         )
         self.basic_auth_processor = post_processors.BasicAuthProcessor(self.config["conf_dir"] + "/basic_auth")
         self.redirect_processor = post_processors.RedirectProcessor()
-        self.sticky_session_processor = post_processors.StickySessionProcessor()
+        self.upstream_processor = post_processors.UpstreamProcessor()
 
         # Render default config for Nginx setup
         default_nginx_config = self.template.render(config=self.config)
@@ -137,7 +137,9 @@ def _do_reload(self, forced=False) -> bool:
                 location.container = list(location.backends)[0]
             hosts.append(host)
 
-        upstreams = self.sticky_session_processor.process(hosts)
+        upstreams = self.upstream_processor.process(
+            hosts, prefer_local=self.config.get("docker_swarm") == "prefer-local"
+        )
         self.basic_auth_processor.process_basic_auth(hosts)
         self.ssl_processor.process_ssl_certificates(hosts)
         hosts = self._ensure_https_redirects(hosts)
@@ -210,7 +212,7 @@ def register_backend(self, backend: BackendTarget):
     # removes container from the maintained list.
     # this is called when a caontainer dies or leaves a known network
     def remove_backend(self, container_id: str):
-        deleted, deleted_domain = self.config_data.remove_backend(container_id)
+        deleted, deleted_domain = self._remove_backend_without_reload(container_id)
         if deleted:
             print(
                 "Container removed   ",
@@ -220,6 +222,9 @@ def remove_backend(self, container_id: str):
             )
             self.reload()
 
+    def _remove_backend_without_reload(self, container_id: str):
+        return self.config_data.remove_backend(container_id)
+
     def reload(self, immediate=False, force=False) -> bool:
         """
         Schedules or performs a reload of the Nginx configuration.
@@ -269,9 +274,15 @@ def connect(self, network, container, scope):
                 container_obj = self.client.containers.get(container)
                 if container_obj.status != "running":
                     return
-                if self._container_has_healthcheck(container_obj) and self._container_health_status(container_obj) != "healthy":
+                if (
+                    self._container_has_healthcheck(container_obj)
+                    and self._container_health_status(container_obj) != "healthy"
+                ):
                     return
-                if swarm_mode != "ignore" and "com.docker.swarm.service.id" in container_obj.attrs["Config"].get("Labels", {}):
+                if swarm_mode not in (
+                    "ignore",
+                    "prefer-local",
+                ) and "com.docker.swarm.service.id" in container_obj.attrs["Config"].get("Labels", {}):
                     # print(f"Skipping network connect for service task container {container}")
                     return
                 backend = BackendTarget.from_container(container_obj)
@@ -290,30 +301,41 @@ def update_backend(self, backend: BackendTarget):
         :return: true if state change affected the nginx configuration else false
         """
         try:
-            if not self.config_data.has_backend(backend.id):
-                if self.register_backend(backend):
-                    self.reload()
-                    return True
+            existing_backend = self.config_data.has_backend(backend.id)
+            if existing_backend and backend.type != "service":
+                return False
+
+            removed = None
+            if existing_backend:
+                removed, _ = self._remove_backend_without_reload(backend.id)
+
+            registered = self.register_backend(backend)
+            if registered or removed:
+                self.reload()
+                return True
         except requests.exceptions.HTTPError as e:
             pass
         return False
 
     def rescan_all_container(self, bypass_start_grace=False):
         """
-        Rescan all the containers and services to detect changes. 
+        Rescan all the containers and services to detect changes.
         Previously this only did containers, but now it's a full rescan for consistency.
         """
         swarm_mode = self.config.get("docker_swarm", "ignore")
         with self._lock:
             # Clear previous state to ensure we don't leak dead containers/services
             self.config_data.clear()
-            
+
             # 1. Register local containers (unless in strict swarm mode)
             if swarm_mode != "strict" and self.client is not None:
                 try:
                     containers = self.client.containers.list()
                     for container in containers:
-                        if swarm_mode != "ignore" and "com.docker.swarm.service.id" in container.attrs["Config"].get("Labels", {}):
+                        if swarm_mode not in (
+                            "ignore",
+                            "prefer-local",
+                        ) and "com.docker.swarm.service.id" in container.attrs["Config"].get("Labels", {}):
                             continue
                         if not self._should_register_container_now(container, bypass_start_grace=bypass_start_grace):
                             continue
@@ -324,8 +346,8 @@ def rescan_all_container(self, bypass_start_grace=False):
                 except Exception as e:
                     print(f"Error scanning containers: {e}", file=sys.stderr)
 
-            # 2. Register swarm services (if enable or strict)
-            if swarm_mode in ("enable", "strict"):
+            # 2. Register swarm services (if enable, prefer-local, or strict)
+            if swarm_mode in ("enable", "prefer-local", "strict"):
                 try:
                     info = self.swarm_client.info()
                     swarm_info = info.get("Swarm", {})

nginx_proxy/post_processors/__init__.py

@@ -1,4 +1,4 @@
 from .basic_auth_processor import BasicAuthProcessor
 from .redirect_processor import RedirectProcessor
 from .ssl_certificate_processor import SslCertificateProcessor
-from .sticky_session_processor import StickySessionProcessor
+from .upstream_processor import UpstreamProcessor