From ebb8569b5f208d9c34d681ca7a17498bf33921a6 Mon Sep 17 00:00:00 2001
From: salty <salty@saltbox.dev>
Date: Tue, 7 Oct 2025 18:26:25 +0200
Subject: [PATCH] docker_container: add driver_opts and gw_priority (#1143)

closes #1142
---
 ...2-docker-container-network-driver-opts.yml |  4 +++
 .../module_utils/_module_container/base.py    |  2 ++
 .../_module_container/docker_api.py           | 28 +++++++++++++++++++
 plugins/modules/docker_container.py           | 15 ++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 changelogs/fragments/1142-docker-container-network-driver-opts.yml

diff --git a/changelogs/fragments/1142-docker-container-network-driver-opts.yml b/changelogs/fragments/1142-docker-container-network-driver-opts.yml
new file mode 100644
index 00000000..06892643
--- /dev/null
+++ b/changelogs/fragments/1142-docker-container-network-driver-opts.yml
@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - "docker_container - add ``driver_opts`` option in ``networks`` (https://github.com/ansible-collections/community.docker/issues/1142, https://github.com/ansible-collections/community.docker/pull/1143)."
+  - "docker_container - add ``gw_priority`` option in ``networks`` (https://github.com/ansible-collections/community.docker/issues/1142, https://github.com/ansible-collections/community.docker/pull/1143)."
diff --git a/plugins/module_utils/_module_container/base.py b/plugins/module_utils/_module_container/base.py
index f3d9751d..001a1af7 100644
--- a/plugins/module_utils/_module_container/base.py
+++ b/plugins/module_utils/_module_container/base.py
@@ -1144,6 +1144,8 @@ OPTION_NETWORK = (
             aliases=dict(type="list", elements="str"),
             links=dict(type="list", elements="str"),
             mac_address=dict(type="str"),
+            driver_opts=dict(type="dict"),
+            gw_priority=dict(type="int"),
         ),
     )
 )
diff --git a/plugins/module_utils/_module_container/docker_api.py b/plugins/module_utils/_module_container/docker_api.py
index 459a04bd..00c3acfb 100644
--- a/plugins/module_utils/_module_container/docker_api.py
+++ b/plugins/module_utils/_module_container/docker_api.py
@@ -255,11 +255,25 @@ class DockerAPIEngineDriver(EngineDriver):
             "links": "Links",
             "aliases": "Aliases",
             "mac_address": "MacAddress",
+            "driver_opts": "DriverOpts",
         }.items():
             value = parameters.pop(para, None)
             if value:
                 if para == "links":
                     value = normalize_links(value)
+                elif para == "driver_opts":
+                    # Ensure driver_opts values are strings
+                    for key, val in value.items():
+                        if not isinstance(val, str):
+                            raise Exception(
+                                f"driver_opts values must be strings, got {type(val).__name__} for key '{key}'"
+                            )
+                params[dest_para] = value
+        for para, dest_para in {
+            "gw_priority": "GwPriority",
+        }.items():
+            value = parameters.pop(para, None)
+            if value is not None:
                 params[dest_para] = value
         if parameters:
             ups = ", ".join([f'"{p}"' for p in sorted(parameters)])
@@ -1785,6 +1799,20 @@ OPTION_NETWORK.add_engine(
                     for net_info in (c.module.params["networks"] or [])
                 ),
             },
+            "networks.driver_opts": {
+                "docker_api_version": "1.32",
+                "detect_usage": lambda c: any(
+                    net_info.get("driver_opts") is not None
+                    for net_info in (c.module.params["networks"] or [])
+                ),
+            },
+            "networks.gw_priority": {
+                "docker_api_version": "1.48",
+                "detect_usage": lambda c: any(
+                    net_info.get("gw_priority") is not None
+                    for net_info in (c.module.params["networks"] or [])
+                ),
+            },
         },
     ),
 )
diff --git a/plugins/modules/docker_container.py b/plugins/modules/docker_container.py
index 3ff02226..21fd5659 100644
--- a/plugins/modules/docker_container.py
+++ b/plugins/modules/docker_container.py
@@ -751,6 +751,21 @@ options:
             Daemon at least in some cases. When passed on creation, this seems to work better.
         type: str
         version_added: 3.6.0
+      driver_opts:
+        description:
+          - Dictionary of driver options for this network endpoint.
+          - Allows setting endpoint-specific driver options like C(com.docker.network.endpoint.ifname) to set a custom network interface name.
+          - Requires Docker API version 1.32 or newer.
+        type: dict
+        version_added: 5.0.0
+      gw_priority:
+        description:
+          - Gateway priority for this network endpoint.
+          - When a container is connected to multiple networks, this controls which network's gateway is used as the default gateway.
+          - Higher values indicate higher priority.
+          - Requires Docker API version 1.48 or newer.
+        type: int
+        version_added: 5.0.0
   networks_cli_compatible:
     description:
       - If O(networks_cli_compatible=true) (default), this module will behave as C(docker run --network) and will B(not) add