From 507805f8c49f8e052e0fbfc0552a7457e8af6295 Mon Sep 17 00:00:00 2001 From: Eugene Yakubovich Date: Fri, 10 Jul 2015 12:48:36 -0700 Subject: [PATCH] Document the plugins Adds a .md file to the Documentation/ folder for each plugin. Fixes #16 --- bridge.md | 37 +++++++++++++++++++++++++++++++++++++ dhcp.md | 35 +++++++++++++++++++++++++++++++++++ host-local.md | 36 ++++++++++++++++++++++++++++++++++++ ipvlan.md | 40 ++++++++++++++++++++++++++++++++++++++++ macvlan.md | 34 ++++++++++++++++++++++++++++++++++ 5 files changed, 182 insertions(+) create mode 100644 bridge.md create mode 100644 dhcp.md create mode 100644 host-local.md create mode 100644 ipvlan.md create mode 100644 macvlan.md diff --git a/bridge.md b/bridge.md new file mode 100644 index 00000000..bda5ac5c --- /dev/null +++ b/bridge.md @@ -0,0 +1,37 @@ +# bridge plugin + +## Overview + +With bridge plugin, all containers (on the same host) are plugged into a bridge (virtual switch) that resides in the host network namespace. +The containers receive one end of the veth pair with the other end connected to the bridge. +An IP address is only assigned to one end of the veth pair -- one residing in the container. +The bridge itself can also be assigned an IP address, turning it into a gateway for the containers. +Alternatively, the bridge can function purely in L2 mode and would need to be bridged to the host network interface (if other than container-to-container communication on the same host is desired). + +The network configuration specifies the name of the bridge to be used. +If the bridge is missing, the plugin will create one on first use and, if gateway mode is used, assign it an IP that was returned by IPAM plugin via the gateway field. + +## Example configuration +``` +{ + "name": "mynet", + "type": "bridge", + "bridge": "mynet0", + "isGateway": true, + "ipMasq": true, + "ipam": { + "type": "host-local", + "subnet": "10.10.0.0/16" + } +} +``` + +## Network configuration reference + +* `name` (string, required): the name of the network. +* `type` (string, required): "bridge". +* `bridge` (string, optional): name of the bridge to use/create. Defaults to "cni0". +* `isGateway` (boolean, optional): assign an IP address to the bridge. Defaults to false. +* `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from this network and destined outside of it. Defaults to false. +* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. +* `ipam` (dictionary, required): IPAM configuration to be used for this network. diff --git a/dhcp.md b/dhcp.md new file mode 100644 index 00000000..298e96e0 --- /dev/null +++ b/dhcp.md @@ -0,0 +1,35 @@ +# dhcp plugin + +## Overview + +With dhcp plugin the containers can get an IP allocated by a DHCP server already running on your network. +This can be especially useful with plugin types such as [macvlan](https://github.com/appc/cni/blob/master/Documentation/macvlan.md). +Because a DHCP lease must be periodically renewed for the duration of container lifetime, a separate daemon is required to be running. +The same plugin binary can also be run in the daemon mode. + +## Operation +To use the dhcp IPAM plugin, first launch the dhcp daemon: + +``` +# Make sure the unix socket has been removed +$ rm -f /run/cni/dhcp.sock +$ ./dhcp daemon +``` + +Alternatively, you can use systemd socket activation protocol. +Be sure that the .socket file uses /run/cni/dhcp.sock as the socket path. + +With the daemon running, containers using the dhcp plugin can be launched. + +## Example configuration + +``` +{ + "ipam": { + "type": "dhcp", + } +} + +## Network configuration reference + +* `type` (string, required): "dhcp" diff --git a/host-local.md b/host-local.md new file mode 100644 index 00000000..ff6ee775 --- /dev/null +++ b/host-local.md @@ -0,0 +1,36 @@ +# host-local plugin + +## Overview + +host-local IPAM plugin allocates IPv4 addresses out of a specified address range. +It stores the state locally on the host filesystem, therefore ensuring uniqueness of IP addresses on a single host. + +## Example configuration +``` +{ + "ipam": { + "type": "host-local", + "subnet": "10.10.0.0/16", + "rangeStart": "10.10.1.20", + "rangeEnd": "10.10.3.50", + "gateway": "10.10.0.254", + "routes": [ + { "dst": "0.0.0.0/0" }, + { "dst": "192.168.0.0/16", "gw": "10.10.5.1" } + ] + } +} +``` + +## Network configuration reference + +* `type` (string, required): "host-local". +* `subnet` (string, required): CIDR block to allocate out of. +* `rangeStart` (string, optional): IP inside of "subnet" from which to start allocating addresses. Defaults to ".2" IP inside of the "subnet" block. +* `rangeEnd` (string, optional): IP inside of "subnet" with which to end allocating addresses. Defaults to ".254" IP inside of the "subnet" block. +* `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. Defaults to ".1" IP inside of the "subnet" block. +* `routes` (string, optional): list of routes to add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used. + +## Files + +Allocated IP addresses are stored as files in /var/lib/cni/networks/$NETWORK_NAME. diff --git a/ipvlan.md b/ipvlan.md new file mode 100644 index 00000000..f86a0159 --- /dev/null +++ b/ipvlan.md @@ -0,0 +1,40 @@ +# ipvlan plugin + +## Overview + +ipvlan is a new [addition](https://lwn.net/Articles/620087/) to the Linux kernel. +Like its cousin macvlan, it virtualizes the host interface. +However unlike macvlan which generates a new MAC address for each interface, ipvlan devices all share the same MAC. +The kernel driver inspects the IP address of each packet when making a decision about which virtual interface should process the packet. + +Because all ipvlan interfaces share the MAC address with the host interface, DHCP can only be used in conjunction with ClientID (currently not supported by DHCP plugin). + +## Example configuration + +``` +{ + "name": "mynet", + "type": "ipvlan", + "master": "eth0", + "ipam": { + "type": "host-local", + "subnet": "10.1.2.0/24", + } +} +``` + +## Network configuration reference + +* `name` (string, required): the name of the network. +* `type` (string, required): "ipvlan". +* `master` (string, required): name of the host interface to enslave. +* `mode` (string, optional): one of "l2", "l3". Defaults to "l2". +* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. +* `ipam` (dictionary, required): IPAM configuration to be used for this network. + +## Notes + +* `ipvlan` does not allow virtual interfaces to communicate with the master interface. +Therefore the container will not be able to reach the host via `ipvlan` interface. +Be sure to also have container join a network that provides connectivity to the host (e.g. `ptp`). +* A single master interface can not be enslaved by both `macvlan` and `ipvlan`. diff --git a/macvlan.md b/macvlan.md new file mode 100644 index 00000000..9e9f981d --- /dev/null +++ b/macvlan.md @@ -0,0 +1,34 @@ +# macvlan plugin + +## Overview + +[macvlan](http://backreference.org/2014/03/20/some-notes-on-macvlanmacvtap/) functions like a switch that is already connected to the host interface. +A host interface gets "enslaved" with the virtual interfaces sharing the physical device but having distinct MAC addresses. +Since each macvlan interface has its own MAC address, it makes it easy to use with exising DHCP servers already present on the network. + +## Example configuration + +``` +{ + "name": "mynet", + "type": "macvlan", + "master": "eth0", + "ipam": { + "type": "dhcp" + } +} +``` + +## Network configuration reference + +* `name` (string, required): the name of the network +* `type` (string, required): "macvlan" +* `master` (string, required): name of the host interface to enslave +* `mode` (string, optional): one of "bridge", "private", "vepa", "passthrough". Defaults to "bridge". +* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. +* `ipam` (dictionary, required): IPAM configuration to be used for this network. + +## Notes + +* If are testing on a laptop, please remember that most wireless cards do not support being enslaved by macvlan. +* A single master interface can not be enslaved by both `macvlan` and `ipvlan`.