Adds whereabouts IPAM CNI and route-override usage descriptions

Author: dougbtv

modules/nw-multus-ipam-object.adoc

@@ -23,6 +23,8 @@ endif::[]
 
 The IP address management (IPAM) Container Network Interface (CNI) plug-in manages IP address assignment for other CNI plug-ins. You can configure ipam for either static IP address assignment or dynamic IP address assignment by using DHCP. The DHCP server you specify must be reachable from the additional network.
 
+Alternatively for dynamic IP addressment without an available DHCP server, you may use the Whereabouts IPAM CNI plugin.
+
 ifdef::json[]
 The following JSON configuration object describes the parameters that you can set.
 endif::json[]
@@ -110,7 +112,7 @@ You can configure ipam for static IP address assignment:
 ----
 
 [id="nw-multus-dynamic-example_{context}"]
-== Dynamic IP address assignment configuration example
+== Dynamic IP address assignment configuration example using DHCP
 
 You can configure ipam for DHCP:
 
@@ -141,6 +143,40 @@ cannot specify any additional parameters if you specify a value of `DHCP`.
 <2> If you set the `type` parameter to `static`, then provide the
 `staticIPAMConfig` parameter.
 
+[id="nw-multus-dynamic-whereabouts-example_{context}"]
+== Dynamic IP address assignment configuration example using Whereabouts
+
+Whereabouts is an IPAM CNI plugin that can be used for dynamic IP address assignment
+without having to rely on a DHCP server.
+
+You can configure ipam for Whereabouts:
+
+.Whereabouts ipam configuration JSON
+[source,json]
+----
+{
+  "ipam": {
+    "type": "whereabouts", <1>
+    "range": "192.0.2.192/27", <2>
+    "exclude": [ <3>
+       "192.0.2.192/30",
+       "192.0.2.196/32"
+    ],
+  }
+}
+----
+
+<1> Specify `type` with a value of `whereabouts` to use Whereabouts for IPAM.
+<2> The `range` parameter is an IP address and range in CIDR notation, IP addresses will be
+assigned from within this range of addresses.
+<3> The `exclude` parameter is a list of IP addresses and ranges in CIDR notation,
+IP address ranges listed in `exclude` will not be assigned. Optional.
+
+[NOTE]
+=====
+Whereabouts can be used for both IPv4 and IPv6 addresses.
+=====
+
 [id="nw-multus-static-config_{context}"]
 == Static ipam configuration YAML
 
@@ -238,6 +274,59 @@ The following example shows an ipam configuration for DHCP:
 ipamConfig:
   type: DHCP
 ----
+
+[id="nw-multus-route-override-example_{context}"]
+== Specifying routes using the route-override CNI plugin
+
+In addition to assigning IP addresses to pods, you can also override any routing on a given pod.
+
+The "route-override" CNI plugin is used to accomplish this, and is used as a "chained plugin". To chain
+CNI plugins, you specify a list of CNI configurations. Only some plugins (such as route-override) can
+be utilized in this fashion, and are typically used to add capabilities or alter properties of additional
+network interfaces.
+
+
+.Route-Override CNI chained CNI plug-in JSON configuration object
+[source,json]
+----
+{
+    "cniVersion": "0.3.0",
+    "name" : "exampleconfiguration",
+    "plugins": [ <1>
+    {
+        "type": "...", <2>
+        "ipam": {
+            "type": "..."
+        }
+    },
+    {
+        "type" : "route-override", <3>
+        "flushroutes" : true, <4>
+        "addroutes": [ <5>
+        {
+            "dst": "192.168.10.0/24", <6>
+            "gw": "10.1.254.254" <7>
+        }],
+        "delroutes": [ <8>
+        {
+            "dst": "192.168.0.0/24"
+        }],
+        "flushgateway": false, <9>
+    }
+    ]
+}
+----
+
+<1> When using chained plugins the `plugins` key should be a list of JSON objects
+<2> The first JSON object in the list will be the primary CNI plugin for the additional network.
+<3> The second JSON object should be set to `"type" : "route-override"` in order to alter routing. Required.
+<4> The `flushroutes` key, when set to true, will remove all existing routes from pods referencing this configuration. Optional.
+<5> The `addroutes` key is a list of JSON objects describing route destinations and gateways to be added. Optional.
+<6> The `dst` field in each `addroutes` object is the destination IP address and subnet mask in CIDR format.
+<7> The `gw` field is the gateway to set for each of the destination CIDR ranges. Optional.
+<8> The `delroutes` key is a list of JSON objects describing which destination routes to delete.
+<9> The `flushgateway` key when set to true, will remove the default gateway. Optional.
+
 endif::yaml[]