Merge pull request #818 from rmb938/patch-1

allow custom ipam options when creating networks

Author: aanand

docker/api/network.py

@@ -19,14 +19,15 @@ def networks(self, names=None, ids=None):
         return self._result(res, json=True)
 
     @minimum_version('1.21')
-    def create_network(self, name, driver=None, options=None):
+    def create_network(self, name, driver=None, options=None, ipam=None):
         if options is not None and not isinstance(options, dict):
             raise TypeError('options must be a dictionary')
 
         data = {
             'name': name,
             'driver': driver,
-            'options': options
+            'options': options,
+            'ipam': ipam,
         }
         url = self._url("/networks/create")
         res = self._post_json(url, data=data)

docker/utils/__init__.py

@@ -4,7 +4,8 @@
     kwargs_from_env, convert_filters, datetime_to_timestamp, create_host_config,
     create_container_config, parse_bytes, ping_registry, parse_env_file,
     version_lt, version_gte, decode_json_header, split_command,
-)  # flake8: noqa
+    create_ipam_config, create_ipam_pool
+) # flake8: noqa
 
 from .types import Ulimit, LogConfig # flake8: noqa
 from .decorators import check_resource, minimum_version  # flake8: noqa

docker/utils/utils.py

@@ -44,6 +44,23 @@
 }
 
 
+def create_ipam_pool(subnet=None, iprange=None, gateway=None,
+                     aux_addresses=None):
+    return {
+        'subnet': subnet,
+        'iprange': iprange,
+        'gateway': gateway,
+        'auxaddresses': aux_addresses
+    }
+
+
+def create_ipam_config(driver='default', pool_configs=None):
+    return {
+        'driver': driver,
+        'config': pool_configs or []
+    }
+
+
 def mkbuildcontext(dockerfile):
     f = tempfile.NamedTemporaryFile()
     t = tarfile.open(mode='w', fileobj=f)

docs/networks.md

@@ -0,0 +1,20 @@
+# Using Networks
+
+With the release of Docker 1.9 you can now manage custom networks.
+
+
+Here you can see how to create a network named ```network1``` using the ```bridge``` driver
+
+```python
+docker_client.create_network("network1", driver="bridge")
+```
+
+You can also create more advanced networks with custom IPAM configurations. For example, 
+setting the subnet to ```192.168.52.0/24``` and gateway to ```192.168.52.254```
+
+```python
+
+ipam_config = docker.utils.create_ipam_config(subnet='192.168.52.0/24', gateway='192.168.52.254')
+
+docker_client.create_network("network1", driver="bridge", ipam=ipam_config)
+```

mkdocs.yml

@@ -12,6 +12,7 @@ pages:
 - Using TLS: tls.md
 - Host devices: host-devices.md
 - Host configuration: hostconfig.md
+- Network configuration: networks.md
 - Using with boot2docker: boot2docker.md
 - Change Log: change_log.md
 - Contributing: contributing.md

tests/unit/network_test.py

@@ -4,6 +4,7 @@
 
 from .. import base
 from .api_test import DockerClientTest, url_prefix, response
+from docker.utils import create_ipam_config, create_ipam_pool
 
 try:
     from unittest import mock
@@ -80,6 +81,29 @@ def test_create_network(self):
                 json.loads(post.call_args[1]['data']),
                 {"name": "foo", "driver": "bridge", "options": opts})
 
+            ipam_pool_config = create_ipam_pool(subnet="192.168.52.0/24",
+                                                gateway="192.168.52.254")
+            ipam_config = create_ipam_config(pool_configs=[ipam_pool_config])
+
+            self.client.create_network("bar", driver="bridge",
+                                       ipam=ipam_config)
+
+            self.assertEqual(
+                json.loads(post.call_args[1]['data']),
+                {
+                    "name": "bar",
+                    "driver": "bridge",
+                    "ipam": {
+                        "driver": "default",
+                        "config": [{
+                            "iprange": None,
+                            "gateway": "192.168.52.254",
+                            "subnet": "192.168.52.0/24",
+                            "auxaddresses": None
+                        }]
+                    }
+                })
+
     @base.requires_api_version('1.21')
     def test_remove_network(self):
         network_id = 'abc12345'

tests/unit/utils_test.py

@@ -18,7 +18,7 @@
     parse_repository_tag, parse_host, convert_filters, kwargs_from_env,
     create_host_config, Ulimit, LogConfig, parse_bytes, parse_env_file,
     exclude_paths, convert_volume_binds, decode_json_header, tar,
-    split_command,
+    split_command, create_ipam_config, create_ipam_pool
 )
 from docker.utils.ports import build_port_bindings, split_port
 
@@ -428,6 +428,21 @@ def test_decode_json_header(self):
         decoded_data = decode_json_header(data)
         self.assertEqual(obj, decoded_data)
 
+    def test_create_ipam_config(self):
+        ipam_pool = create_ipam_pool(subnet='192.168.52.0/24',
+                                     gateway='192.168.52.254')
+
+        ipam_config = create_ipam_config(pool_configs=[ipam_pool])
+        self.assertEqual(ipam_config, {
+            'driver': 'default',
+            'config': [{
+                'subnet': '192.168.52.0/24',
+                'gateway': '192.168.52.254',
+                'auxaddresses': None,
+                'iprange': None
+            }]
+        })
+
 
 class SplitCommandTest(base.BaseTestCase):