add CheckDuplicate docs and logics in network

Signed-off-by: allencloud <allen.sun@daocloud.io>

api/server/router/network/network_routes.go

@@ -181,6 +181,16 @@ func (n *networkRouter) postNetworkCreate(ctx context.Context, w http.ResponseWr
 
 	nw, err := n.backend.CreateNetwork(create)
 	if err != nil {
+		var warning string
+		if _, ok := err.(libnetwork.NetworkNameError); ok {
+			// check if user defined CheckDuplicate, if set true, return err
+			// otherwise prepare a warning message
+			if create.CheckDuplicate {
+				return libnetwork.NetworkNameError(create.Name)
+			}
+			warning = libnetwork.NetworkNameError(create.Name).Error()
+		}
+
 		if _, ok := err.(libnetwork.ManagerRedirectError); !ok {
 			return err
 		}
@@ -188,7 +198,10 @@ func (n *networkRouter) postNetworkCreate(ctx context.Context, w http.ResponseWr
 		if err != nil {
 			return err
 		}
-		nw = &types.NetworkCreateResponse{ID: id}
+		nw = &types.NetworkCreateResponse{
+			ID:      id,
+			Warning: warning,
+		}
 	}
 
 	return httputils.WriteJSON(w, http.StatusCreated, nw)

api/swagger.yaml

@@ -6218,7 +6218,7 @@ paths:
                 description: "The network's name."
                 type: "string"
               CheckDuplicate:
-                description: "Check for networks with duplicate names."
+                description: "Check for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions."
                 type: "boolean"
               Driver:
                 description: "Name of the network driver plugin to use."

api/types/types.go

@@ -416,6 +416,13 @@ type EndpointResource struct {
 
 // NetworkCreate is the expected body of the "create network" http request message
 type NetworkCreate struct {
+	// Check for networks with duplicate names.
+	// Network is primarily keyed based on a random ID and not on the name.
+	// Network name is strictly a user-friendly alias to the network
+	// which is uniquely identified using ID.
+	// And there is no guaranteed way to check for duplicates.
+	// Option CheckDuplicate is there to provide a best effort checking of any networks
+	// which has the same name but it is not guaranteed to catch all name collisions.
 	CheckDuplicate bool
 	Driver         string
 	EnableIPv6     bool

daemon/network.go

@@ -248,6 +248,8 @@ func (daemon *Daemon) createNetwork(create types.NetworkCreateRequest, id string
 		}
 	}
 	if nw != nil {
+		// check if user defined CheckDuplicate, if set true, return err
+		// otherwise prepare a warning message
 		if create.CheckDuplicate {
 			return nil, libnetwork.NetworkNameError(create.Name)
 		}

docs/api/v1.21.md

@@ -2836,7 +2836,12 @@ Content-Type: application/json
 **JSON parameters**:
 
 - **Name** - The new network's name. this is a mandatory field
-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`
+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
+    Since Network is primarily keyed based on a random ID and not on the name, 
+    and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, 
+    there is no guaranteed way to check for duplicates across a cluster of docker hosts. 
+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 
+    which has the same name but it is not guaranteed to catch all name collisions.
 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
 - **IPAM** - Optional custom IP scheme for the network
   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver

docs/api/v1.22.md

@@ -3165,7 +3165,12 @@ Content-Type: application/json
 **JSON parameters**:
 
 - **Name** - The new network's name. this is a mandatory field
-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`
+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
+    Since Network is primarily keyed based on a random ID and not on the name, 
+    and network name is strictly a user-friendly alias to the network 
+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 
+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 
+    which has the same name but it is not guaranteed to catch all name collisions.
 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
 - **IPAM** - Optional custom IP scheme for the network
   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver

docs/api/v1.23.md

@@ -3279,7 +3279,12 @@ Content-Type: application/json
 **JSON parameters**:
 
 - **Name** - The new network's name. this is a mandatory field
-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`
+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
+    Since Network is primarily keyed based on a random ID and not on the name, 
+    and network name is strictly a user-friendly alias to the network 
+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 
+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 
+    which has the same name but it is not guaranteed to catch all name collisions.
 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
 - **Internal** - Restrict external access to the network
 - **IPAM** - Optional custom IP scheme for the network

docs/api/v1.24.md

@@ -3344,7 +3344,12 @@ Content-Type: application/json
 **JSON parameters**:
 
 - **Name** - The new network's name. this is a mandatory field
-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`
+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
+    Since Network is primarily keyed based on a random ID and not on the name, 
+    and network name is strictly a user-friendly alias to the network 
+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 
+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 
+    which has the same name but it is not guaranteed to catch all name collisions.
 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
 - **Internal** - Restrict external access to the network
 - **IPAM** - Optional custom IP scheme for the network