Advanced Kube-OVN Features: Multi‑Network IPAM and Usage Guide

Kube-OVN can provide cluster‑wide IPAM capabilities to other CNI plugins such as macvlan, vlan, and host‑device, and it also supports address management when multiple network interfaces are all of the Kube-OVN type.

Working Principle

By using Multus CNI, a Pod can have multiple network interfaces, but native Kubernetes lacks cluster‑wide IP management for those networks. Kube-OVN introduces Subnet and IP custom resources (CRDs) that enable advanced IP management features such as subnet allocation, IP reservation, random allocation, and fixed allocation. Extending subnets allows other CNI plugins to reuse Kube-OVN’s IPAM functions.

Workflow

The diagram shows how Kube-OVN manages IP addresses for other network plugins. The container’s eth0 connects to the OVN network, while net1 connects to another CNI network defined by a NetworkAttachmentDefinition resource in Multus.

When a Pod is created, the kube-ovn-controller watches the Pod add event, reads the Pod annotation to locate the corresponding Subnet, allocates an IP from that Subnet, and writes the allocated address back to the Pod annotation.

On the node, the CNI configuration specifies kube-ovn-cni as the IPAM plugin. The plugin reads the Pod annotation and returns the address in the standard CNI result format to the underlying CNI plugin.

Usage

Install Kube-OVN and Multus

Refer to the Kube-OVN one‑step installation guide and the Multus "how to use" documentation for installation steps.

Provide IPAM for Other CNI Plugins

Example: use macvlan as a secondary network and set its IPAM type to kube-ovn :

apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: macvlan
  namespace: default
spec:
  config: '{
      "cniVersion": "0.3.0",
      "type": "macvlan",
      "master": "eth0",
      "mode": "bridge",
      "ipam": {
        "type": "kube-ovn",
        "server_socket": "/run/openvswitch/kube-ovn-daemon.sock",
        "provider": "macvlan.default"
      }
    }'

Key fields:

spec.config.ipam.type : must be kube-ovn to invoke the Kube‑OVN IPAM plugin.

server_socket : the socket file used by Kube‑OVN (default /run/openvswitch/kube-ovn-daemon.sock ).

provider : formatted as <name>.<namespace> ; Kube‑OVN uses this to locate the matching Subnet resource.

Create a Kube‑OVN Subnet

Define a Subnet that matches the secondary network, setting cidrBlock , excludeIps , and provider to the corresponding NetworkAttachmentDefinition :

apiVersion: kubeovn.io/v1
kind: Subnet
metadata:
  name: macvlan
spec:
  protocol: IPv4
  provider: macvlan.default
  cidrBlock: 172.17.0.0/16
  gateway: 172.17.0.1
  excludeIps:
  - 172.17.0.0..172.17.0.10

Fields gateway , private , and nat only apply to Subnets whose provider ends with .ovn and are not used for attachment networks.

Create a Multi‑Network Pod

For a Pod that receives a randomly allocated IP from the secondary network, add the annotation k8s.v1.cni.cncf.io/networks with the NetworkAttachmentDefinition name:

apiVersion: v1
kind: Pod
metadata:
  name: samplepod
  namespace: default
  annotations:
    k8s.v1.cni.cncf.io/networks: default/macvlan
spec:
  containers:
  - name: samplepod
    command: ["/bin/ash", "-c", "trap : TERM INT; sleep infinity & wait"]
    image: alpine

Create a Pod with a Fixed IP

To assign a static IP, add the appropriate IP address annotations for the chosen network:

apiVersion: v1
kind: Pod
metadata:
  name: static-ip
  namespace: default
  annotations:
    k8s.v1.cni.cncf.io/networks: default/macvlan
    ovn.kubernetes.io/ip_address: 10.16.0.15
    ovn.kubernetes.io/mac_address: 00:00:00:53:6B:B6
    macvlan.default.kubernetes.io/ip_address: 172.17.0.100
    macvlan.default.kubernetes.io/mac_address: 00:00:00:53:6B:BB
spec:
  containers:
  - name: static-ip
    image: nginx:alpine

Create a Workload with Fixed IP Pool

For a Deployment that should draw IPs from a predefined pool, add the ip_pool annotation to the Pod template:

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: default
  name: static-workload
  labels:
    app: static-workload
spec:
  replicas: 2
  selector:
    matchLabels:
      app: static-workload
  template:
    metadata:
      labels:
        app: static-workload
      annotations:
        k8s.v1.cni.cncf.io/networks: default/macvlan
        ovn.kubernetes.io/ip_pool: 10.16.0.15,10.16.0.16,10.16.0.17
        macvlan.default.kubernetes.io/ip_pool: 172.17.0.200,172.17.0.201,172.17.0.202
    spec:
      containers:
      - name: static-workload
        image: nginx:alpine

For more details, refer to the official Kube‑OVN documentation at https://kubeovn.github.io/docs/v1.10.x/ .