Merge pull request #2333 from hannseman/network-attachment-config

Add NetworkAttachmentConfig for service create/update

docker/api/service.py

@@ -135,8 +135,9 @@ class ServiceApiMixin(object):
                 of the service. Default: ``None``
             rollback_config (RollbackConfig): Specification for the rollback
                 strategy of the service. Default: ``None``
-            networks (:py:class:`list`): List of network names or IDs to attach
+            networks (:py:class:`list`): List of network names or IDs or
-                the service to. Default: ``None``.
+                :py:class:`~docker.types.NetworkAttachmentConfig` to attach the
+                service to. Default: ``None``.
             endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
@@ -383,8 +384,9 @@ class ServiceApiMixin(object):
                 of the service. Default: ``None``.
             rollback_config (RollbackConfig): Specification for the rollback
                 strategy of the service. Default: ``None``
-            networks (:py:class:`list`): List of network names or IDs to attach
+            networks (:py:class:`list`): List of network names or IDs or
-                the service to. Default: ``None``.
+                :py:class:`~docker.types.NetworkAttachmentConfig` to attach the
+                service to. Default: ``None``.
             endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
             fetch_current_spec (boolean): Use the undefined settings from the

docker/models/services.py

@@ -178,11 +178,12 @@ class ServiceCollection(Collection):
                 ``source:target:options``, where options is either
                 ``ro`` or ``rw``.
             name (str): Name to give to the service.
-            networks (list of str): List of network names or IDs to attach
+            networks (:py:class:`list`): List of network names or IDs or
-                the service to. Default: ``None``.
+                :py:class:`~docker.types.NetworkAttachmentConfig` to attach the
+                service to. Default: ``None``.
             resources (Resources): Resource limits and reservations.
             restart_policy (RestartPolicy): Restart policy for containers.
-            secrets (list of :py:class:`docker.types.SecretReference`): List
+            secrets (list of :py:class:`~docker.types.SecretReference`): List
                 of secrets accessible to containers for this service.
             stop_grace_period (int): Amount of time to wait for
                 containers to terminate before forcefully killing them.
@@ -205,8 +206,9 @@ class ServiceCollection(Collection):
                 the container's `hosts` file.
             dns_config (DNSConfig): Specification for DNS
                 related configurations in resolver configuration file.
-            configs (:py:class:`list`): List of :py:class:`ConfigReference`
+            configs (:py:class:`list`): List of
-                that will be exposed to the service.
+                :py:class:`~docker.types.ConfigReference` that will be exposed
+                to the service.
             privileges (Privileges): Security options for the service's
                 containers.
 

docker/types/__init__.py

@@ -7,6 +7,6 @@ from .services import (
     ConfigReference, ContainerSpec, DNSConfig, DriverConfig, EndpointSpec,
     Mount, Placement, PlacementPreference, Privileges, Resources,
     RestartPolicy, RollbackConfig, SecretReference, ServiceMode, TaskTemplate,
-    UpdateConfig
+    UpdateConfig, NetworkAttachmentConfig
 )
 from .swarm import SwarmSpec, SwarmExternalCA

docker/types/services.py

@@ -26,8 +26,8 @@ class TaskTemplate(dict):
         placement (Placement): Placement instructions for the scheduler.
             If a list is passed instead, it is assumed to be a list of
             constraints as part of a :py:class:`Placement` object.
-        networks (:py:class:`list`): List of network names or IDs to attach
+        networks (:py:class:`list`): List of network names or IDs or
-            the containers to.
+            :py:class:`NetworkAttachmentConfig` to attach the service to.
         force_update (int): A counter that triggers an update even if no
             relevant parameters have been changed.
     """
@@ -770,3 +770,21 @@ class Privileges(dict):
 
         if len(selinux_context) > 0:
             self['SELinuxContext'] = selinux_context
+
+
+class NetworkAttachmentConfig(dict):
+    """
+        Network attachment options for a service.
+
+        Args:
+            target (str): The target network for attachment.
+                Can be a network name or ID.
+            aliases (:py:class:`list`): A list of discoverable alternate names
+                for the service.
+            options (:py:class:`dict`): Driver attachment options for the
+                network target.
+    """
+    def __init__(self, target, aliases=None, options=None):
+        self['Target'] = target
+        self['Aliases'] = aliases
+        self['DriverOpts'] = options

docs/api.rst

@@ -142,6 +142,7 @@ Configuration types
 .. autoclass:: IPAMPool
 .. autoclass:: LogConfig
 .. autoclass:: Mount
+.. autoclass:: NetworkAttachmentConfig
 .. autoclass:: Placement
 .. autoclass:: PlacementPreference
 .. autoclass:: Privileges

tests/integration/api_service_test.py

@@ -371,6 +371,35 @@ class ServiceTest(BaseAPIIntegrationTest):
             {'Target': net1['Id']}, {'Target': net2['Id']}
         ]
 
+    def test_create_service_with_network_attachment_config(self):
+        network = self.client.create_network(
+            'dockerpytest_1', driver='overlay', ipam={'Driver': 'default'}
+        )
+        self.tmp_networks.append(network['Id'])
+        container_spec = docker.types.ContainerSpec(BUSYBOX, ['true'])
+        network_config = docker.types.NetworkAttachmentConfig(
+            target='dockerpytest_1',
+            aliases=['dockerpytest_1_alias'],
+            options={
+                'foo': 'bar'
+            }
+        )
+        task_tmpl = docker.types.TaskTemplate(
+            container_spec,
+            networks=[network_config]
+        )
+        name = self.get_service_name()
+        svc_id = self.client.create_service(
+            task_tmpl, name=name
+        )
+        svc_info = self.client.inspect_service(svc_id)
+        assert 'Networks' in svc_info['Spec']['TaskTemplate']
+        service_networks_info = svc_info['Spec']['TaskTemplate']['Networks']
+        assert len(service_networks_info) == 1
+        assert service_networks_info[0]['Target'] == network['Id']
+        assert service_networks_info[0]['Aliases'] == ['dockerpytest_1_alias']
+        assert service_networks_info[0]['DriverOpts'] == {'foo': 'bar'}
+
     def test_create_service_with_placement(self):
         node_id = self.client.nodes()[0]['ID']
         container_spec = docker.types.ContainerSpec(TEST_IMG, ['true'])