As a cluster administrator, you can configure an additional network for your cluster using the macvlan CNI plug-in. 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.

The unique MAC addresses this plug-in generates for sub-interfaces might not be compatible with the security polices of your cloud provider.

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 Custom Resource (CR) automatically.

Do not edit the NetworkAttachmentDefinition CRs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your additional network.

Prerequisites
  • Install the OpenShift Command-line Interface (CLI), commonly known as 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: example-addn-network
        type: SimpleMacvlan
        simpleMacvlanConfig:
          ipamConfig:
            type: static
            staticIPAMConfig:
              addresses:
              - address: 10.1.1.0/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. Optional: Confirm that the CNO created the NetworkAttachmentDefinition CR by running the following command. There might be a delay before the CNO creates the CR.

    $ oc get network-attachment-definitions
    NAME                 AGE
    example-network      14m
    example-macvlan      21m

Configuration for macvlan CNI plug-in

The following YAML describes the configuration parameters for the macvlan Container Network Interface (CNI) plug-in:

macvlan YAML configuration
name: <name> (1)
namespace: <namespace> (2)
type: SimpleMacvlan
simpleMacvlanConfig:
  master: <master> (3)
  mode: <mode> (4)
  mtu: <mtu> (5)
  ipamConfig: (6)
    ...
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 a value is not specified, the default namespace is used.
3 The ethernet interface to associate with the virtual interface. If a value for master is not specified, then the host system’s primary ethernet interface is used.
4 Configures traffic visibility on the virtual network. Must be either bridge, passthru, private, or vepa. If a value for mode is not provided, the default value is bridge.
5 Set the maximum transmission unit (MTU) to the specified value. The default value is automatically set by the kernel.
6 Specify a configuration object for the ipam CNI plug-in. The plug-in manages IP address assignment for the attachment definition.

macvlan configuration example

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

name: macvlan-net
type: SimpleMacvlan
simpleMacvlanConfig:
  ipamConfig:
    type: DHCP

Configuration for ipam CNI plug-in

The IP address management (IPAM) CNI plug-in manages IP address assignment for other CNI plug-ins. You can configure ipam for either static IP address assignment or dynamic IP address assignment by using DHCP. The DHCP server you specify must be reachable from the additional network.

In OpenShift Container Platform 4.2.0, if you attach a Pod to an additional network that uses DHCP for IP address management, the Pod will fail to start. This will be fixed in a future release. For more information, see BZ#1754686.

The following YAML configuration describes the parameters that you can set.

If you set the type parameter to the DHCP value, you cannot set any other parameters.
ipam CNI plug-in YAML configuration object
ipamConfig:
  type: <type> (1)
  ... (2)
1 Specify static to configure the plug-in to manage IP address assignment. Specify DHCP to allow a DHCP server to manage IP address assignment. You cannot specify any additional parameters if you specify a value of DHCP.
2 If you set the type parameter to static, then provide the staticIPAMConfig parameter.

Static ipam configuration YAML

The following YAML describes a configuration for static IP address assignment:

Static ipam configuration YAML
ipamConfig:
  type: static
  staticIPAMConfig:
    addresses: (1)
    - address: <address> (2)
      gateway: <gateway> (3)
    routes: (4)
    - destination: <destination> (5)
      gateway: <gateway> (6)
    dns: (7)
      nameservers: (8)
      - <nameserver>
      domain: <domain> (9)
      search: (10)
      - <search_domain>
1 A collection of mappings that define IP addresses to assign to the virtual interface. Both IPv4 and IPv6 IP addresses are supported.
2 A block of IP addresses that you specify in CIDR format to assign to Pods on a worker node, such as 10.1.1.0/24.
3 The default gateway to route egress network traffic to.
4 A collection of mappings describing routes to configure inside the Pod.
5 The IP address range in CIDR format.
6 The gateway to use to route network traffic to.
7 The DNS configuration. Optional.
8 A collection 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 for example-host will be rewritten as example-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.

Dynamic ipam configuration YAML

The following YAML describes a configuration for static IP address assignment:

Dynamic ipam configuration YAML
ipamConfig:
  type: DHCP

Static IP address assignment configuration example

The following example shows an ipam configuration for static IP addresses:

ipamConfig:
  type: static
  staticIPAMConfig:
    addresses:
    - address: 198.51.100.11/24
      gateway: 198.51.100.10
    routes:
    - destination: 0.0.0.0/0
      gateway: 198.51.100.1
    dns:
      nameservers:
      - 198.51.100.1
      - 198.51.100.2
      domain: testDNS.example
      search:
      - testdomain1.example
      - testdomain2.example

Dynamic IP address assignment configuration example

The following example shows an ipam configuration for DHCP:

ipamConfig:
  type: DHCP