DOCKER-723: support `docker network create`


Issue Type:Bug
Priority:3 - Elevated
Created at:2016-03-03T22:31:29.000Z
Updated at:2018-06-26T06:49:27.183Z


Created by:Former user
Reported by:Former user
Assigned to:Todd Whiteman

Related Issues


docker network create provides a facility to define networks both within a docker host ('bridge') and between docker hosts ('overlay').

SDC's fabric implementation can reasonably provide this as well.


Comment by Former user
Created at 2016-03-18T21:45:51.000Z
Updated at 2016-03-18T21:51:40.000Z

Hi @accountid:62561a9d4f1d57006a24d3ff - I think we may want to stick to just the 'overlay' driver option since Triton's networking is always across all Triton-eligible hosts in the DC. There won't be a scenario for creating a single-host network, as what the 'bridge' option is for.

The docker remote API network create endpoint currently requires only the network name. All other attributes are set to certain default values. In our case, we may want to mandate the passing of the 'subnet' value. Other than that, the attributes Triton networking requires can be set to default values as well. I think this may be what we need:

Attribute Required? Default Validation
name required none netname validation as defined in joyent schemas
subnet required none subnet validation as defined in joyent schemas
driver optional overlay ignored, always set to 'overlay'
gateway optional none v4 address as defined in joyent schemas, but will need to accept v6 in the future
ip-range optional entire range allowed for subnet same as napi provision start/end ip validation
internal optional none when present, maps to internet_nat=true in napi
ipam-driver optional default ignored, i.e. always set to 'default'
ipam-opt optional none ignored
opt optional none may consider using this for passing resolvers and routes

You mentioned some additional options/attributes required for overlay network but I believe those are meant for the docker host (passed when bringing up the docker daemon) instead of the containers. If that's correct, we can totally ignore those.

Let me know if the above makes sense. Thanks.


Comment by Former user
Created at 2016-03-18T21:56:53.000Z

Regarding the DNS integration - since we have chosen to do service discovery in a different way in CNS, I think we can disregard the DNS portion of docker networking in our implementation.

We can also disregard the 'links' functionality as it predates docker networking, and is considered a legacy feature. (

Comment by Todd Whiteman
Created at 2017-09-25T22:13:16.000Z

For docker network create, there are some differences (in what docker allows v's what NAPI allows) that should be discussed:

1) the subnet field is optional in docker/docker - docker uses a free /24 subnet (i.e. to when not specified. I think we should follow suit here, and modify NAPI.CreateFabricNetwork (or create a new endpoint) to allow the creation of a fabric network that finds/uses a free subnet, and errors when none are available.

2) NAPI has the additional concept of a vlan_id (required in the CreateFabricNetwork call). For sdc-docker, that means a call to NAPI.CreateFabricVLAN. But first, one needs a vlan_id to do the creation, so similar to CreateFabricNetwork above, we should modify NAPI to find/use a free vlan_id (there are 4095 possible vlan_id's) when one is not supplied. Note that the alternative (we made vlan_id a required parameter), it would need to be passed through as a network option, e.g.:

docker network create  --subnet  --label  MyDockerNetwork

Comment by Todd Whiteman
Created at 2017-09-25T22:19:26.000Z

FYI, this sdc-docker branch holds the 'docker network create' functionality:
with the limitation that the subnet must be provided (required) and that a free vlan_id is found by querying all existing vlan_id's and then finding a free one from that set.

Note that the behaviour of the vlan_id handling (finding a free default vlan_id) will also affect 'docker network rm', in that deleting a docker network should also free up (delete) it's associated fabric vlan when it's no longer referenced.

Comment by Former user
Created at 2017-11-01T04:53:56.000Z

So, the NAPI stuff is almost good to go. There is one small question, however. While the `subnet` param is now optional, the `provision_ip_start` and `provision_ip_end` params are required. NAPI currently validates these 3 params such that the start-IP and end-IP are both within the `subnet`. The questions is this: do we want to make start-IP and end-IP optional as well (and we fill them in if we find a subnet), or do we want to choose a subnet that contains both start-IP and end-IP (we would have to make use both IPs are private IPs)?

I have a bias in favor of the former, but would like to hear why the latter might be a better idea.

cc: @accountid:624ba422247a4b0069202447

Comment by Former user
Created at 2017-11-01T17:03:24.000Z

The "NAPI stuff" is NAPI-434 right?

Comment by Former user
Created at 2017-11-01T17:44:15.000Z

@accountid:62561aa44f1d57006a24d40c: Yep.

Comment by Former user
Created at 2017-11-01T18:45:37.000Z

@accountid:624a8dd1fd5e4500704673c4 Yes, if sdc-docker is going to call NAPI CreateFabricNetwork and have NAPI select a free subnet, then it is also going to require NAPI to select reasonable provision_start_ip and provision_end_ip.

I assume, but I'm not sure, that NAPI will want to make start_ip the second IP -- reserving the first (.1) for a gateway?
Likewise, I assume NAPI will make end_ip, second last IP -- reserving .255 for broadcast.

@accountid:70121:a36ea101-b8c9-4f3d-825e-334bc077ca5e, @accountid:624a8dd1fd5e4500704673c4 When selecting a subnet, are we settling on NAPI picking a /24 range (e.g. 192.168.N.0/24)?

I'm happy to be overruled by Cody.

Comment by Former user
Created at 2017-11-01T20:08:45.000Z

@accountid:62561aa44f1d57006a24d40c: So, just discussed this over lunch. Basically we settled on (a) selecting a sane range if the subnet is to be auto-allocated, and (b) creating a second set of HTTP params that explicitly tell NAPI that auto-allocation is desired, and that doesn't overload the meaning of the 'subnet' param (which is what the code currently does, and shouldn't). Part of one new params mentioned in (b) is the prefix-length --- so that sdc-docker can specify the /24 range (and so that other consumers can do whatever they want).

Comment by Former user
Created at 2017-11-02T20:15:16.000Z

Sounds good, thanks.