From eb2ff7fe57c80c85b37fb4158bfa3f4ce9c29734 Mon Sep 17 00:00:00 2001 From: Gabe Rosenhouse Date: Wed, 15 Feb 2017 15:18:25 -0800 Subject: [PATCH] docs: consolidate host-local documentation - remove the README.md in the plugins/ipam/host-local (no other plugin has this) - merge that info into the main Documentation/host-local.md --- Documentation/host-local.md | 50 ++++++++++++++++-- plugins/ipam/host-local/README.md | 88 ------------------------------- 2 files changed, 45 insertions(+), 93 deletions(-) delete mode 100644 plugins/ipam/host-local/README.md diff --git a/Documentation/host-local.md b/Documentation/host-local.md index 00c1e84c..073e369a 100644 --- a/Documentation/host-local.md +++ b/Documentation/host-local.md @@ -1,12 +1,17 @@ -# host-local plugin +# host-local IP address management plugin + +host-local IPAM allocates IPv4 and IPv6 addresses out of a specified address range. Optionally, +it can include a DNS configuration from a `resolv.conf` file on the host. ## 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 -``` +## Example configurations + +IPv4: +```json { "ipam": { "type": "host-local", @@ -17,11 +22,44 @@ It stores the state locally on the host filesystem, therefore ensuring uniquenes "routes": [ { "dst": "0.0.0.0/0" }, { "dst": "192.168.0.0/16", "gw": "10.10.5.1" } - ] + ], + "dataDir": "/var/my-orchestrator/container-ipam-state" } } ``` +IPv6: +```json +{ + "ipam": { + "type": "host-local", + "subnet": "3ffe:ffff:0:01ff::/64", + "rangeStart": "3ffe:ffff:0:01ff::0010", + "rangeEnd": "3ffe:ffff:0:01ff::0020", + "routes": [ + { "dst": "3ffe:ffff:0:01ff::1/64" } + ], + "resolvConf": "/etc/resolv.conf" + } +} +``` + +We can test it out on the command-line: + +```bash +$ export CNI_COMMAND=ADD +$ export CNI_CONTAINERID=f81d4fae-7dec-11d0-a765-00a0c91e6bf6 +$ echo '{ "name": "default", "ipam": { "type": "host-local", "subnet": "203.0.113.0/24" } }' | ./host-local +``` + +```json +{ + "ip4": { + "ip": "203.0.113.1/24" + } +} +``` + ## Network configuration reference * `type` (string, required): "host-local". @@ -31,6 +69,8 @@ It stores the state locally on the host filesystem, therefore ensuring uniquenes * `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. * `resolvConf` (string, optional): Path to a `resolv.conf` on the host to parse and return as the DNS configuration +* `dataDir` (string, optional): Path to a directory to use for maintaining state, e.g. which IPs have been allocated to which containers + ## Supported arguments The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: @@ -39,4 +79,4 @@ The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/ ## Files -Allocated IP addresses are stored as files in /var/lib/cni/networks/$NETWORK_NAME. +Allocated IP addresses are stored as files in `/var/lib/cni/networks/$NETWORK_NAME`. The prefix can be customized with the `dataDir` option listed above. diff --git a/plugins/ipam/host-local/README.md b/plugins/ipam/host-local/README.md deleted file mode 100644 index 128bc6d8..00000000 --- a/plugins/ipam/host-local/README.md +++ /dev/null @@ -1,88 +0,0 @@ -# host-local IP address manager - -host-local IPAM allocates IPv4 and IPv6 addresses out of a specified address range. Optionally, -it can include a DNS configuration from a `resolv.conf` file on the host. - -## Usage - -### Obtain an IP - -Given the following network configuration: - -``` -{ - "name": "default", - "ipam": { - "type": "host-local", - "subnet": "203.0.113.0/24" - } -} -``` - -#### Using the command line interface - -``` -$ export CNI_COMMAND=ADD -$ export CNI_CONTAINERID=f81d4fae-7dec-11d0-a765-00a0c91e6bf6 -$ ./host-local < $conf -``` - -``` -{ - "ip4": { - "ip": "203.0.113.1/24" - } -} -``` - -## Backends - -By default ipmanager stores IP allocations on the local filesystem using the IP address as the file name and the ID as contents. For example: - -``` -$ ls /var/lib/cni/networks/default -``` -``` -203.0.113.1 203.0.113.2 -``` - -``` -$ cat /var/lib/cni/networks/default/203.0.113.1 -``` -``` -f81d4fae-7dec-11d0-a765-00a0c91e6bf6 -``` - -## Configuration Files - - -``` -{ - "name": "ipv6", - "ipam": { - "type": "host-local", - "subnet": "3ffe:ffff:0:01ff::/64", - "rangeStart": "3ffe:ffff:0:01ff::0010", - "rangeEnd": "3ffe:ffff:0:01ff::0020", - "routes": [ - { "dst": "3ffe:ffff:0:01ff::1/64" } - ], - "resolvConf": "/etc/resolv.conf" - } -} -``` - -``` -{ - "name": "ipv4", - "ipam": { - "type": "host-local", - "subnet": "203.0.113.1/24", - "rangeStart": "203.0.113.10", - "rangeEnd": "203.0.113.20", - "routes": [ - { "dst": "203.0.113.0/24" } - ] - } -} -```