feat(deployments): inject auth-proxy sidecar for docker; document auth fallback

Addresses PR feedback.

- Docker backend now injects the auth-proxy sidecar too (build_docker_plan),
  reusing build_auth_proxy_container. The sidecar shares the primary container's
  network namespace, so the agent reaches it on localhost:8090 — the same
  loopback address used in k8s. Previously the sidecar was injected only in the
  k8s compiler, so auth-on docker agent deployments got no identity and would
  401.
- The docker sidecar's upstream (NMP_BASE_URL) is rewritten to a
  docker-reachable host via determine_loopback_override() (e.g.
  host.docker.internal on macOS) when the platform base URL is a loopback,
  mirroring the agent-side rewrite from #899. K8s uses the Service DNS verbatim.
- Documented platform_auth_enabled()'s fail-to-False behavior: the realistic
  failure is ImportError (package used outside the platform image); other
  failures are effectively unreachable in the controller (missing config ->
  defaults; malformed config would have crashed startup; the read is cached).
- Tests: docker auth-proxy injection, auth-off no-op, and loopback upstream
  rewrite.

Signed-off-by: Ben McCown <bmccown@nvidia.com>

Author: benmccown

packages/nemo_platform_plugin/src/nemo_platform_plugin/auth.py

@@ -18,7 +18,22 @@
 
 
 def platform_auth_enabled() -> bool:
-    """Return whether platform authentication is enabled."""
+    """Return whether platform authentication is enabled.
+
+    Returns ``False`` on any failure to resolve the auth config. The realistic
+    failure is ``ImportError``: ``nmp_common`` ships only in the platform process
+    image, so when this package is used standalone (outside the platform) there
+    is no auth config and "disabled" is the correct answer.
+
+    Other failures are effectively unreachable in the context that matters here
+    (the deployment controller, which runs *inside* the platform image): a
+    missing config file resolves to defaults (``enabled=False``) rather than
+    raising, and a malformed/invalid config file would have already crashed the
+    platform service at startup before any deployment is reconciled. The config
+    read is cached from that successful startup load. We therefore accept the
+    narrow, largely theoretical fail-open window rather than propagate and block
+    deployments on a transient/unexpected error.
+    """
     try:
         from nmp.common.config import get_auth_config
 

plugins/nemo-deployments/src/nemo_deployments_plugin/auth_proxy.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 import logging
+from urllib.parse import urlsplit
 
 from nemo_deployments_plugin.config import DeploymentsConfig
 from nemo_deployments_plugin.entities import (
@@ -26,7 +27,7 @@
     RestartPolicy,
 )
 from nemo_platform_plugin.auth import platform_auth_enabled
-from nemo_platform_plugin.config import get_nemo_config
+from nemo_platform_plugin.config import LOOPBACK_ADDRESSES, get_nemo_config
 from nemo_platform_plugin.jobs.image import get_qualified_image
 
 logger = logging.getLogger(__name__)
@@ -44,18 +45,36 @@ def auth_proxy_port() -> int:
     return get_nemo_config(DeploymentsConfig).auth_proxy_port
 
 
-def _upstream_base_url() -> str:
-    from nemo_platform_plugin.config import get_platform_config
+def _upstream_base_url(*, docker: bool) -> str:
+    """Return the platform base URL the sidecar forwards to, reachable from its container.
 
-    return get_platform_config().base_url.rstrip("/")
-
-
-def build_auth_proxy_container(config: DeploymentConfig) -> Container | None:
+    In docker mode the platform base URL is often a host loopback the container
+    cannot reach; substitute the docker-reachable host (e.g. host.docker.internal)
+    the same way jobs do. In k8s the base URL is the in-cluster Service DNS and is
+    used verbatim.
+    """
+    from nemo_platform_plugin.config import determine_loopback_override, get_platform_config
+
+    base_url = get_platform_config().base_url.rstrip("/")
+    if not docker:
+        return base_url
+    override = determine_loopback_override()
+    if not override:
+        return base_url
+    parts = urlsplit(base_url)
+    if (parts.hostname or "").lower() not in LOOPBACK_ADDRESSES:
+        return base_url
+    netloc = override if parts.port is None else f"{override}:{parts.port}"
+    return parts._replace(netloc=netloc).geturl()
+
+
+def build_auth_proxy_container(config: DeploymentConfig, *, docker: bool = False) -> Container | None:
     """Return the auth-proxy sidecar Container for *config*, or None.
 
     Returns None when the config does not request the sidecar, or when platform
     auth is disabled (the sidecar would be pointless — internal calls are already
-    trusted).
+    trusted). Pass ``docker=True`` so the sidecar's upstream is rewritten to a
+    docker-reachable host.
     """
     if not config.auth_proxy_sidecar:
         return None
@@ -73,7 +92,7 @@ def build_auth_proxy_container(config: DeploymentConfig) -> Container | None:
         image=image,
         command=["nemo", "services", "run", "--sidecars", "auth-proxy"],
         env=[
-            EnvVar(name="NMP_BASE_URL", value=_upstream_base_url()),
+            EnvVar(name="NMP_BASE_URL", value=_upstream_base_url(docker=docker)),
             EnvVar(name=_AUTH_PROXY_PRINCIPAL_ENVVAR, value=identity),
             EnvVar(name=_AUTH_PROXY_HOST_ENVVAR, value="127.0.0.1"),
             EnvVar(name=_AUTH_PROXY_PORT_ENVVAR, value=str(port)),

plugins/nemo-deployments/src/nemo_deployments_plugin/backends/docker/containers.py

@@ -8,6 +8,7 @@
 from dataclasses import dataclass, field
 from typing import Any
 
+from nemo_deployments_plugin.auth_proxy import build_auth_proxy_container
 from nemo_deployments_plugin.backends.labels import docker_volume_name
 from nemo_deployments_plugin.entities import Container, DeploymentConfig, DockerDeploymentConfig, VolumeMount
 from nemo_deployments_plugin.types import RestartPolicy
@@ -58,6 +59,13 @@ def build_docker_plan(config: DeploymentConfig) -> DockerDeploymentPlan:
     primary = config.containers[0]
     sidecars = list(config.containers[1:])
 
+    # Auth-proxy sidecar (no-op unless requested and platform auth is enabled).
+    # It shares the primary's netns, so the primary reaches it on localhost —
+    # the same loopback address the workload targets in k8s. Declares no ports.
+    auth_proxy = build_auth_proxy_container(config, docker=True)
+    if auth_proxy is not None:
+        sidecars.append(auth_proxy)
+
     # Sidecars share the primary's netns, so they cannot publish their own host
     # ports. (The primary owns the published ports for the whole group.)
     for sidecar in sidecars:

plugins/nemo-deployments/tests/unit/backends/docker/test_containers.py

@@ -5,6 +5,8 @@
 
 from __future__ import annotations
 
+from unittest.mock import patch
+
 import pytest
 from backends.docker.docker_helpers import lora_config, sample_config
 from nemo_deployments_plugin.backends.docker.containers import (
@@ -14,6 +16,8 @@
 )
 from nemo_deployments_plugin.entities import Container, ContainerPort, DeploymentConfig
 
+_AUTH_PROXY_MOD = "nemo_deployments_plugin.auth_proxy"
+
 
 def test_single_container_plan_has_no_init_or_sidecars() -> None:
     plan = build_docker_plan(sample_config())
@@ -23,6 +27,47 @@ def test_single_container_plan_has_no_init_or_sidecars() -> None:
     assert plan.is_multi_container is False
 
 
+def test_auth_proxy_injected_as_docker_sidecar_when_auth_on() -> None:
+    config = sample_config()
+    config = config.model_copy(update={"auth_proxy_sidecar": True, "auth_proxy_sidecar_identity": "agents"})
+    with (
+        patch(f"{_AUTH_PROXY_MOD}.platform_auth_enabled", return_value=True),
+        patch(f"{_AUTH_PROXY_MOD}.get_qualified_image", return_value="my-registry/nmp-api:local"),
+        patch(f"{_AUTH_PROXY_MOD}._upstream_base_url", return_value="http://host.docker.internal:8080"),
+    ):
+        plan = build_docker_plan(config)
+    # Injected as a sidecar (shares primary netns), not the primary.
+    assert plan.primary.name == "main"
+    proxy = next(c for c in plan.sidecars if c.name == "auth-proxy")
+    env = {e.name: e.value for e in proxy.env}
+    assert env["NMP_AUTH_PROXY_PRINCIPAL"] == "agents"
+    assert env["NMP_BASE_URL"] == "http://host.docker.internal:8080"
+    # Sidecar must not declare ports (shares netns).
+    assert proxy.ports == []
+
+
+def test_auth_proxy_not_injected_when_auth_off() -> None:
+    config = sample_config().model_copy(update={"auth_proxy_sidecar": True, "auth_proxy_sidecar_identity": "agents"})
+    with patch(f"{_AUTH_PROXY_MOD}.platform_auth_enabled", return_value=False):
+        plan = build_docker_plan(config)
+    assert plan.sidecars == []
+
+
+def test_auth_proxy_docker_upstream_rewrites_loopback() -> None:
+    # docker=True + loopback base_url -> host.docker.internal substitution.
+    # _upstream_base_url imports these lazily from nemo_platform_plugin.config.
+    from nemo_deployments_plugin.auth_proxy import _upstream_base_url
+
+    with (
+        patch("nemo_platform_plugin.config.determine_loopback_override", return_value="host.docker.internal"),
+        patch("nemo_platform_plugin.config.get_platform_config") as get_cfg,
+    ):
+        get_cfg.return_value.base_url = "http://localhost:8080"
+        assert _upstream_base_url(docker=True) == "http://host.docker.internal:8080"
+        # k8s path leaves it verbatim.
+        assert _upstream_base_url(docker=False) == "http://localhost:8080"
+
+
 def test_lora_plan_splits_init_primary_and_sidecar() -> None:
     plan = build_docker_plan(lora_config())
     assert plan.primary.name == "server"