Merge pull request #656 from liubin/add-docs-for-net

add docs for using CNI plugins with nerdctl

Author: AkihiroSuda

README.md

@@ -27,7 +27,7 @@ nerdctl is a **non-core** sub-project of containerd.
 
 ### Basic usage
 
-To run a container with the default CNI network (10.4.0.0/24):
+To run a container with the default `bridge` CNI network (10.4.0.0/24):
 ```console
 # nerdctl run -it --rm alpine
 ```
@@ -1298,6 +1298,7 @@ Configuration guide:
 Basic features:
 - [`./docs/compose.md`](./docs/compose.md):   Compose
 - [`./docs/rootless.md`](./docs/rootless.md): Rootless mode
+- [`./docs/cni.md`](./docs/cni.md): CNI for containers network
 
 Advanced features:
 - [`./docs/stargz.md`](./docs/stargz.md):     Lazy-pulling using Stargz Snapshotter

cmd/nerdctl/run.go

@@ -115,11 +115,11 @@ func setCreateFlags(cmd *cobra.Command) {
 
 	// #region network flags
 	// network (net) is defined as StringSlice, not StringArray, to allow specifying "--network=cni1,cni2"
-	cmd.Flags().StringSlice("network", []string{netutil.DefaultNetworkName}, `Connect a container to a network ("bridge"|"host"|"none")`)
+	cmd.Flags().StringSlice("network", []string{netutil.DefaultNetworkName}, `Connect a container to a network ("bridge"|"host"|"none"|<CNI>)`)
 	cmd.RegisterFlagCompletionFunc("network", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return shellCompleteNetworkNames(cmd, []string{})
 	})
-	cmd.Flags().StringSlice("net", []string{netutil.DefaultNetworkName}, `Connect a container to a network ("bridge"|"host"|"none")`)
+	cmd.Flags().StringSlice("net", []string{netutil.DefaultNetworkName}, `Connect a container to a network ("bridge"|"host"|"none"|<CNI>)`)
 	cmd.RegisterFlagCompletionFunc("net", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return shellCompleteNetworkNames(cmd, []string{})
 	})

docs/cni.md

@@ -0,0 +1,61 @@
+# Using CNI with nerdctl
+
+nerdctl uses CNI plugins for its container network, you can set network by
+either `--network` or `--net` option.
+
+## Basic networks
+
+nerdctl support some basic types of CNI plugins without any configuration
+needed(you should have CNI plugin be installed), for Linux systems the basic
+CNI plugin types are `bridge`, `portmap`, `firewall`, `tuning`, for Windows
+system, the supported CNI plugin types are `nat` only.
+
+The default network `bridge` for Linux and `nat` for Windows if you
+don't set any network options.
+
+## Custom networks
+
+You can also customize your CNI network by providing configuration files.
+For example you have one configuration file(`/etc/cni/net.d/10-mynet.conf`)
+for `bridge` network:
+
+```json
+{
+  "cniVersion": "0.4.0",
+  "name": "mynet",
+  "type": "bridge",
+  "bridge": "cni0",
+  "isGateway": true,
+  "ipMasq": true,
+  "ipam": {
+    "type": "host-local",
+    "subnet": "172.19.0.0/24",
+    "routes": [
+      { "dst": "0.0.0.0/0" }
+    ]
+  }
+}
+```
+
+This will configure a new CNI network with the name `mynet`, and you can use
+this network to create a container:
+
+```console
+# nerdctl run -it --net mynet --rm alpine ip addr show
+1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+    inet6 ::1/128 scope host
+       valid_lft forever preferred_lft forever
+3: eth0@if6120: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
+    link/ether 5e:5b:3f:0c:36:56 brd ff:ff:ff:ff:ff:ff
+    inet 172.19.0.51/24 brd 172.19.0.255 scope global eth0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::5c5b:3fff:fe0c:3656/64 scope link tentative
+       valid_lft forever preferred_lft forever
+```
+
+## Bridge Isolation Plugin
+
+If you have the [CNI isolation plugin](https://github.com/AkihiroSuda/cni-isolation) installed, the `isolation` plugin will be used automatically.

pkg/netutil/netutil.go

@@ -55,7 +55,7 @@ type ConfigListTemplateOpts struct {
 	ID           int
 	Name         string // e.g. "nerdctl"
 	Labels       string // e.g. `{"version":"1.1.0"}`
-	Subnet       string // e.g. "10.4.0.0/16"
+	Subnet       string // e.g. "10.4.0.0/24"
 	Gateway      string // e.g. "10.4.0.1"
 	ExtraPlugins string // e.g. `,{"type":"isolation"}`
 }