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

diff --git a/Documentation/host-local.md b/Documentation/host-local.md
index 00c1e84..073e369 100644 (file)
--- 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 (file)
index 128bc6d..0000000
--- 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" }
-               ]
-       }
-}
-```