Skip to content

docs: document host-device useInterfaceNetwork option #156

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

Open
SchSeba wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document host-device useInterfaceNetwork option #156

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
35 changes: 34 additions & 1 deletion content/plugins/current/main/host-device.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,17 @@ runtimeConfig `deviceID` parameter then IPAM configuration will be ignored.

## Network configuration reference

The device can be specified with any one of four properties:
The device can be specified with any one of five properties:
* `device`: The device name, e.g. `eth0`, `can0`
* `hwaddr`: A MAC address
* `kernelpath`: The kernel device kobj, e.g. `/sys/devices/pci0000:00/0000:00:1f.6`
* `pciBusID`: A PCI address of network device, e.g `0000:00:1f.6`
* `useInterfaceNetwork` (boolean, default `false`): When set to `true`, the plugin captures the host interface's IP addresses and routes before moving the device into the container namespace, and then applies them inside the container. This is useful in cloud and virtual environments (e.g. AWS, GCP, IBM Cloud) where L3 configuration (IP addresses, routes) is provisioned directly on the host network device by the cloud provider and there is no traditional IPAM source. Only permanently configured addresses are captured; dynamic addresses (SLAAC, DHCPv6) and RA-learned routes are excluded. Can be combined with IPAM to add extra addresses or routes on top of the host-provided ones. Not supported for DPDK-bound devices.

For this plugin, `CNI_IFNAME` will be ignored. Upon DEL, the device will be moved back.

**Note:** When using `useInterfaceNetwork`, the interface configuration on the host node must be persistent. When the device is moved back to the host (via DEL), the system's network management service (e.g. NetworkManager, systemd-networkd, cloud-init, or cloud-specific agents) is expected to re-apply the IP addresses and routes. The plugin does not re-configure the host interface on DEL.

The plugin also supports the following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md):
* `deviceID`: A PCI address of the network device, e.g `0000:00:1f.6`

Expand Down Expand Up @@ -73,3 +76,33 @@ A sample configuration utilizing `deviceID` runtime configuration looks like:
}
}
```

A sample configuration using `useInterfaceNetwork` to carry the host interface's
L3 configuration into the container:

```json
{
"cniVersion": "1.0.0",
"type": "host-device",
"device": "enp0s1",
"useInterfaceNetwork": true
}
```

A sample configuration combining `useInterfaceNetwork` with IPAM to add
additional addresses on top of the cloud-provisioned ones:

```json
{
"cniVersion": "1.0.0",
"type": "host-device",
"device": "enp0s1",
"useInterfaceNetwork": true,
"ipam": {
"type": "static",
"addresses": [
{ "address": "10.10.0.100/24" }
]
}
}
```