Skip to content

Add Whereabouts CNI plug-in documentation #23057

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jun 26, 2020
Merged

Add Whereabouts CNI plug-in documentation #23057

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 6 additions & 4 deletions _topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -458,12 +458,14 @@ Topics:
File: removing-pod
- Name: Configuring a bridge network
File: configuring-bridge
- Name: Configuring a macvlan network
File: configuring-macvlan
- Name: Configuring an ipvlan network
File: configuring-ipvlan
- Name: Configuring a host-device network
File: configuring-host-device
- Name: Configuring an ipvlan network
File: configuring-ipvlan
- Name: Configuring a macvlan network with basic customizations
File: configuring-macvlan-basic
- Name: Configuring a macvlan network
File: configuring-macvlan
- Name: Editing an additional network
File: edit-additional-network
- Name: Removing an additional network
Expand Down
57 changes: 48 additions & 9 deletions modules/nw-multus-create-network.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,17 @@
// Configuring Multus plug-ins using the Cluster Network Operator
// is nearly identical in each case.

ifeval::["{context}" == "configuring-macvlan"]
ifeval::["{context}" == "configuring-macvlan-basic"]
:plugin: macvlan
:macvlan:
:yaml:
endif::[]
// This is necessary for Whereabouts CNI which is JSON-only
ifeval::["{context}" == "configuring-macvlan"]
:plugin: macvlan
:macvlan:
:json:
endif::[]
ifeval::["{context}" == "configuring-ipvlan"]
:plugin: ipvlan
:json:
Expand All @@ -30,7 +37,7 @@ endif::[]

The Cluster Network Operator (CNO) manages additional network definitions. When
you specify an additional network to create, the CNO creates the
NetworkAttachmentDefinition Custom Resource (CR) automatically.
NetworkAttachmentDefinition custom resource (CR) automatically.

[IMPORTANT]
====
Expand Down Expand Up @@ -76,7 +83,7 @@ spec:
type: static
staticIPAMConfig:
addresses:
- address: 10.1.1.0/24
- address: 10.1.1.7
----
endif::yaml[]
ifdef::json[]
Expand Down Expand Up @@ -104,7 +111,7 @@ spec:
"type": "static",
"addresses": [
{
"address": "191.168.1.1/24"
"address": "191.168.1.23"
}
]
}
Expand Down Expand Up @@ -153,7 +160,35 @@ spec:
"type": "static",
"addresses": [
{
"address": "191.168.1.1/24"
"address": "191.168.1.23"
}
]
}
}'
----
endif::[]
ifdef::macvlan+json[]
[source,yaml,subs="attributes+"]
----
apiVersion: operator.openshift.io/v1
kind: Network
metadata:
name: cluster
spec:
additionalNetworks: <1>
- name: test-network-1
namespace: test-1
type: Raw
rawCNIConfig: '{
"cniVersion": "0.3.1",
"name": "test-network-1",
"type": "{plugin}",
"master": "eth1",
"ipam": {
"type": "static",
"addresses": [
{
"address": "191.168.1.23"
}
]
}
Expand All @@ -164,20 +199,24 @@ endif::[]

. Save your changes and quit the text editor to commit your changes.

. Optional: Confirm that the CNO created the NetworkAttachmentDefinition CR by
running the following command. There might be a delay before the CNO creates the
CR.
. Confirm that the CNO created the NetworkAttachmentDefinition CR by running the following command. Replace `<namespace>` with the namespace that you specified when configuring the network attachment. There might be a delay before the CNO creates the CR.
+
----
$ oc get network-attachment-definitions -n <namespace>
NAME AGE
test-network-1 14m
----

ifeval::["{context}" == "configuring-macvlan"]
ifeval::["{context}" == "configuring-macvlan-basic"]
:!macvlan:
:!plugin:
:!yaml:
endif::[]
ifeval::["{context}" == "configuring-macvlan"]
:!macvlan:
:!plugin:
:!json:
endif::[]
ifeval::["{context}" == "configuring-ipvlan"]
:!plugin:
:!json:
Expand Down
147 changes: 107 additions & 40 deletions modules/nw-multus-ipam-object.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,85 +11,134 @@
// for the Macvlan CNI plug-in only. In the future other Multus plug-ins
// might be managed the same way by the CNO.

ifeval::["{context}" == "configuring-macvlan"]
ifeval::["{context}" == "configuring-macvlan-basic"]
:yaml:
endif::[]
ifeval::["{context}" != "configuring-macvlan"]
ifeval::["{context}" != "configuring-macvlan-basic"]
:json:
endif::[]

[id="nw-multus-ipam-object_{context}"]
= Configuration for ipam CNI plug-in

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.
The ipam Container Network Interface (CNI) plug-in provides IP address management (IPAM) for other CNI plug-ins.

ifdef::json[]
The following JSON configuration object describes the parameters that you can set.
You can use the following methods for IP address assignment:

- Static assignment.
- Dynamic assignment through a DHCP server. The DHCP server you specify must be reachable from the additional network.
- Dynamic assignment through the Whereabouts IPAM CNI plug-in.
endif::json[]

ifdef::yaml[]
The following YAML configuration describes the parameters that you can set.
endif::yaml[]

////
IMPORTANT: If you set the `type` parameter to the `DHCP` value, you cannot set
any other parameters.
////

ifdef::json[]
.ipam CNI plug-in JSON configuration object
[id="nw-multus-static_{context}"]
== Static IP address assignment configuration

The following JSON describes the configuration for static IP address assignment:

.Static assignment configuration
[source,json]
----
{
"ipam": {
"type": "<type>", <1>
"addresses": [ <2>
"type": "static",
"addresses": [ <1>
{
"address": "<address>", <3>
"gateway": "<gateway>" <4>
"address": "<address>", <2>
"gateway": "<gateway>" <3>
}
],
"routes": [ <5>
"routes": [ <4>
{
"dst": "<dst>" <6>
"gw": "<gw>" <7>
"dst": "<dst>" <5>
"gw": "<gw>" <6>
}
],
"dns": { <8>
"nameservers": ["<nameserver>"], <9>
"domain": "<domain>", <10>
"search": ["<search_domain>"] <11>
"dns": { <7>
"nameservers": ["<nameserver>"], <8>
"domain": "<domain>", <9>
"search": ["<search_domain>"] <10>
}
}
}
----
<1> Specify `static` to configure the plug-in to manage IP address assignment.
Specify `DHCP` to allow a DHCP server to manage IP address assignment. You
cannot specify any additional parameters if you specify a value of `DHCP`.

<2> An array describing IP addresses to assign to the virtual interface. Both
<1> An array describing IP addresses to assign to the virtual interface. Both
IPv4 and IPv6 IP addresses are supported.

<3> A block of IP addresses that you specify in CIDR format to assign
to Pods on a worker node, such as `10.1.1.0/24`.
<2> An IP address that you specify.

<4> The default gateway to route egress network traffic to.
<3> The default gateway to route egress network traffic to.

<5> An array describing routes to configure inside the Pod.
<4> An array describing routes to configure inside the Pod.

<6> The IP address range in CIDR format.
<5> The IP address range in CIDR format.

<7> The gateway where network traffic is routed.
<6> The gateway where network traffic is routed.

<8> Optional: DNS configuration.
<7> Optional: DNS configuration.

<9> An of array of one or more IP addresses for to send DNS queries to.
<8> An of array of one or more IP addresses for to send DNS queries to.

<10> The default domain to append to a host name. For example, if the
<9> The default domain to append to a host name. For example, if the
domain is set to `example.com`, a DNS lookup query for `example-host` is
rewritten as `example-host.example.com`.

<11> An array of domain names to append to an unqualified host name,
<10> An array of domain names to append to an unqualified host name,
such as `example-host`, during a DNS lookup query.

[id="nw-multus-dhcp_{context}"]
== Dynamic IP address assignment configuration

The following JSON describes the configuration for dynamic IP address address assignment with DHCP:

.DHCP assignment configuration
[source,json]
----
{
"ipam": {
"type": "dhcp"
}
}
----

[id="nw-multus-whereabouts_{context}"]
== Dynamic IP address assignment configuration with Whereabouts

The Whereabouts CNI plug-in allows the dynamic assignment of an IP address to an additional network without the use of a DHCP server.

The following JSON describes the configuration for dynamic IP address assignment with Whereabouts:

.Whereabouts assignment configuration
[source,json]
----
{
"ipam": {
"type": "whereabouts",
"range": "<range>", <1>
"exclude": ["<exclude_part>, ..."], <2>
}
}
----
<1> Specify an IP address and range in CIDR notation. IP addresses are assigned from within this range of addresses.
<2> Optional: Specify a list of IP addresses and ranges in CIDR notation. IP addresses within an excluded address range are not assigned.

////
[NOTE]
=====
Whereabouts can be used for both IPv4 and IPv6 addresses.
=====
////

[id="nw-multus-static-example_{context}"]
== Static IP address assignment configuration example

Expand All @@ -109,22 +158,42 @@ You can configure ipam for static IP address assignment:
}
----

[id="nw-multus-dynamic-example_{context}"]
== Dynamic IP address assignment configuration example
[id="nw-multus-dhcp-example_{context}"]
== Dynamic IP address assignment configuration example using DHCP

You can configure ipam for DHCP:

[source,json]
----
{
"ipam": {
"type": "DHCP"
"type": "dhcp"
}
}
----

[id="nw-multus-whereabouts-example_{context}"]
== Dynamic IP address assignment configuration example using Whereabouts

You can configure ipam to use Whereabouts:

[source,json]
----
{
"ipam": {
"type": "whereabouts",
"range": "192.0.2.192/27",
"exclude": [
"192.0.2.192/30",
"192.0.2.196/32"
]
}
}
----
endif::json[]

// YAML uses collection and mapping to describe arrays and objects
// YAML configuration is only relevant to `simpleMacvlanConfig`
// This is limited by the fields that the CNO accepts

ifdef::yaml[]
.ipam CNI plug-in YAML configuration object
Expand Down Expand Up @@ -168,8 +237,7 @@ ipamConfig:
<1> A collection of mappings that define IP addresses to assign to the virtual
interface. Both IPv4 and IPv6 IP addresses are supported.

<2> A block of IP addresses that you specify in CIDR format to assign
to Pods on a worker node, such as `10.1.1.0/24`.
<2> An IP address that you specify.

<3> The default gateway to route egress network traffic to.

Expand Down Expand Up @@ -240,10 +308,9 @@ ipamConfig:
----
endif::yaml[]


ifeval::["{context}" == "configuring-macvlan"]
ifeval::["{context}" == "configuring-macvlan-basic"]
:!yaml:
endif::[]
ifeval::["{context}" != "configuring-macvlan"]
ifeval::["{context}" != "configuring-macvlan-basic"]
:!json:
endif::[]
Loading