Configuring a macvlan network

As a cluster administrator, you can configure an additional network for your cluster using the macvlan Container Network Interface (CNI) plug-in with advanced customization. When a pod is attached to the network, the plug-in creates a sub-interface from the parent interface on the host. A unique hardware mac address is generated for each sub-device.

You specify a configuration with a CNI object. This approach allows you to specify additional configuration options that are not available when using a YAML configuration.

Creating an additional network attachment with the macvlan 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.

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:

1. Edit the CNO CR by running the following command:

   $ oc edit networks.operator.openshift.io cluster

2. 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 macvlan 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": "macvlan",
         "master": "eth1",
         "ipam": {
           "type": "static",
           "addresses": [
             {
               "address": "192.168.1.23/24"
             }
           ]
         }
       }'

   1	Specify the configuration for the additional network attachment definition.

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

4. 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

Configuration for macvlan CNI plug-in

The configuration for an additional network attachment that uses the macvlan 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

The following object describes the configuration parameters for the macvlan CNI plug-in:

macvlan CNI plug-in JSON configuration object

{
  "cniVersion": "0.3.1",
  "name": "<name>", (1)
  "type": "macvlan",
  "mode": "<mode>", (2)
  "master": "<master>", (3)
  "mtu": <mtu>, (4)
  "ipam": { (5)
    ...
  }
}

macvlan configuration example

The following example configures an additional network named macvlan-net:

name: macvlan-net
namespace: work-network
type: Raw
rawCNIConfig: |-
  {
    "cniVersion": "0.3.1",
    "name": "macvlan-net",
    "type": "macvlan",
    "master": "eth1",
    "mode": "bridge",
    "ipam": {
      "type": "dhcp"
      }
  }

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.

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)
    }
  }
}

Dynamic IP address assignment configuration

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

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"
  }
}

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)
  }
}

Static IP address assignment configuration example

You can configure ipam for static IP address assignment:

{
  "ipam": {
    "type": "static",
      "addresses": [
        {
          "address": "191.168.1.7"
        }
      ]
  }
}

Dynamic IP address assignment configuration example using DHCP

You can configure ipam for DHCP:

{
  "ipam": {
    "type": "dhcp"
  }
}

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"
    ]
  }
}

Next steps

• Attach a pod to an additional network.