10.5. Configuring a host-device network
As a cluster administrator, you can configure an additional network for your cluster by using the host-device Container Network Interface (CNI) plug-in. The plug-in moves the specified network device from the network namespace of the host into the network namespace of the pod.
10.5.1. Creating an additional network attachment with the host-device CNI plug-in
The Cluster Network Operator (CNO) manages additional network definitions. When you specify an additional network to create, the CNO creates the NetworkAttachmentDefinition
object automatically.
Do not edit the NetworkAttachmentDefinition
objects that the Cluster Network Operator manages. Doing so might disrupt network traffic on your additional network.
Prerequisites
-
Install the OpenShift CLI (
oc
). -
Log in as a user with
cluster-admin
privileges.
Procedure
To create an additional network for your cluster, complete the following steps:
Edit the CNO CR by running the following command:
$ oc edit networks.operator.openshift.io cluster
Modify the CR that you are creating by adding the configuration for the additional network you are creating, as in the following example CR.
The following YAML configures the host-device CNI plug-in:
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": "host-device", "device": "eth1", "ipam": { "type": "static", "addresses": [ { "address": "192.168.1.23/24" } ] } }'
- 1
- Specify the configuration for the additional network attachment definition.
- Save your changes and quit the text editor to commit your changes.
Confirm that the CNO created the NetworkAttachmentDefinition object 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 object.$ oc get network-attachment-definitions -n <namespace>
Example output
NAME AGE test-network-1 14m
10.5.1.1. Configuration for host-device
The configuration for an additional network attachment that uses the host-device Container Network Interface (CNI) plug-in is provided in two parts:
- Cluster Network Operator (CNO) configuration
- CNI plug-in configuration
The CNO configuration specifies the name for the additional network attachment and the namespace to create the attachment in. The plug-in is configured by a JSON object specified by the rawCNIConfig
parameter in the CNO configuration.
The following YAML describes the configuration parameters for the CNO:
Cluster Network Operator YAML configuration
name: <name> 1 namespace: <namespace> 2 rawCNIConfig: '{ 3 ... }' type: Raw
- 1
- Specify a name for the additional network attachment that you are creating. The name must be unique within the specified
namespace
. - 2
- Specify the namespace to create the network attachment in. If you do not specify a value, the
default
namespace is used. - 3
- Specify the CNI plug-in configuration in JSON format, which is based on the following template.
Specify your network device by setting only one of the following parameters: device
, hwaddr
, kernelpath
, or pciBusID
.
The following object describes the configuration parameters for the host-device CNI plug-in:
host-device CNI plug-in JSON configuration object
{ "cniVersion": "0.3.1", "name": "<name>", 1 "type": "host-device", "device": "<device>", 2 "hwaddr": "<hwaddr>", 3 "kernelpath": "<kernelpath>", 4 "pciBusID": "<pciBusID>", 5 "ipam": { 6 ... } }
- 1
- Specify the value for the
name
parameter you provided previously for the CNO configuration. - 2
- Specify the name of the device, such as
eth0
. - 3
- Specify the device hardware MAC address.
- 4
- Specify the Linux kernel device path, such as
/sys/devices/pci0000:00/0000:00:1f.6
. - 5
- Specify the PCI address of the network device, such as
0000:00:1f.6
. - 6
- Specify a configuration object for the ipam CNI plug-in. The plug-in manages IP address assignment for the attachment definition.
10.5.1.1.1. host-device configuration example
The following example configures an additional network named hostdev-net
:
name: hostdev-net
namespace: work-network
type: Raw
rawCNIConfig: '{ 1
"cniVersion": "0.3.1",
"name": "work-network",
"type": "host-device",
"device": "eth1",
"ipam": {
"type": "dhcp"
}
}'
- 1
- The CNI configuration object is specified as a YAML string.
10.5.1.2. Configuration for ipam CNI plug-in
The ipam Container Network Interface (CNI) plug-in provides IP address management (IPAM) for other CNI plug-ins.
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.
10.5.1.2.1. Static IP address assignment configuration
The following JSON describes the configuration for static IP address assignment:
Static assignment configuration
{ "ipam": { "type": "static", "addresses": [ 1 { "address": "<address>", 2 "gateway": "<gateway>" 3 } ], "routes": [ 4 { "dst": "<dst>", 5 "gw": "<gw>" 6 } ], "dns": { 7 "nameservers": ["<nameserver>"], 8 "domain": "<domain>", 9 "search": ["<search_domain>"] 10 } } }
- 1
- An array describing IP addresses to assign to the virtual interface. Both IPv4 and IPv6 IP addresses are supported.
- 2
- An IP address and network prefix that you specify. For example, if you specify
10.10.21.10/24
, then the additional network is assigned an IP address of10.10.21.10
and the netmask is255.255.255.0
. - 3
- The default gateway to route egress network traffic to.
- 4
- An array describing routes to configure inside the pod.
- 5
- The IP address range in CIDR format, such as
192.168.17.0/24
, or0.0.0.0/0
for the default route. - 6
- The gateway where network traffic is routed.
- 7
- Optional: DNS configuration.
- 8
- An of array of one or more IP addresses for to send DNS queries to.
- 9
- The default domain to append to a host name. For example, if the domain is set to
example.com
, a DNS lookup query forexample-host
is rewritten asexample-host.example.com
. - 10
- An array of domain names to append to an unqualified host name, such as
example-host
, during a DNS lookup query.
10.5.1.2.2. Dynamic IP address assignment configuration
The following JSON describes the configuration for dynamic IP address address assignment with DHCP.
A pod obtains its original DHCP lease when it is created. The lease must be periodically renewed by a minimal DHCP server deployment running on the cluster.
To trigger the deployment of the DHCP server, you must create a shim network attachment by editing the Cluster Network Operator configuration, as in the following example:
Example shim network attachment definition
apiVersion: operator.openshift.io/v1 kind: Network metadata: name: cluster spec: ... additionalNetworks: - name: dhcp-shim namespace: default type: Raw rawCNIConfig: |- { "name": "dhcp-shim", "cniVersion": "0.3.1", "type": "bridge", "ipam": { "type": "dhcp" } }
DHCP assignment configuration
{ "ipam": { "type": "dhcp" } }
10.5.1.2.3. 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
{ "ipam": { "type": "whereabouts", "range": "<range>", 1 "exclude": ["<exclude_part>, ..."], 2 } }
10.5.1.2.4. Static IP address assignment configuration example
You can configure ipam for static IP address assignment:
{ "ipam": { "type": "static", "addresses": [ { "address": "191.168.1.7" } ] } }
10.5.1.2.5. Dynamic IP address assignment configuration example using DHCP
You can configure ipam for DHCP:
{ "ipam": { "type": "dhcp" } }
10.5.1.2.6. Dynamic IP address assignment configuration example using Whereabouts
You can configure ipam to use Whereabouts:
{ "ipam": { "type": "whereabouts", "range": "192.0.2.192/27", "exclude": [ "192.0.2.192/30", "192.0.2.196/32" ] } }