diff --git a/content/plugins/current/main/host-device.md b/content/plugins/current/main/host-device.md index f759491..d9854d7 100644 --- a/content/plugins/current/main/host-device.md +++ b/content/plugins/current/main/host-device.md @@ -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` @@ -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" } + ] + } +} +```