Skip to content

WIP Adds whereabouts IPAM CNI and route-override usage descriptions #20605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 90 additions & 1 deletion modules/nw-multus-ipam-object.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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[]


Expand Down