×

As a cluster administrator, you can configure an additional network for your cluster by using the ipvlan Container Network Interface (CNI) plug-in. The virtual network created by this plug-in is associated with a physical interface that you specify.

Creating an additional network attachment with the ipvlan 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 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 ipvlan 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": "ipvlan",
          "master": "eth1",
          "mode": "l2",
          "ipam": {
            "type": "static",
            "addresses": [
              {
                "address": "191.168.1.7"
              }
            ]
          }
        }'
    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 -n <namespace>
    Example output
    NAME                 AGE
    test-network-1       14m

Configuration for ipvlan

The configuration for an additional network attachment that uses the ipvlan 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
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 you do not specify a value, then the default namespace is used.
3 Specify the CNI plug-in configuration in JSON format, which is based on the following template.

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

ipvlan CNI plug-in JSON configuration object
{
  "cniVersion": "0.3.1",
  "name": "<name>", (1)
  "type": "ipvlan",
  "mode": "<mode>", (2)
  "master": "<master>", (3)
  "mtu": <mtu>, (4)
  "ipam": { (5)
    ...
  }
}
1 Specify the value for the name parameter you provided previously for the CNO configuration.
2 Specify the operating mode for the virtual network. The value must be l2, l3, or l3s. The default value is l2.
3 Specify the ethernet interface to associate with the network attachment. If a master is not specified, the interface for the default network route is used.
4 Set the maximum transmission unit (MTU) to the specified value. The default value is automatically set by the kernel.
5 Specify a configuration object for the ipam CNI plug-in. The plug-in manages IP address assignment for the attachment definition.

ipvlan configuration example

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

name: ipvlan-net
namespace: work-network
type: Raw
rawCNIConfig: '{ (1)
  "cniVersion": "0.3.1",
  "name": "work-network",
  "type": "ipvlan",
  "master": "eth1",
  "mode": "l3",
  "ipam": {
    "type": "dhcp"
    }
}'
1 The CNI configuration object is specified as a YAML string.

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

The following JSON configuration object describes the parameters that you can set.

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)
    }
  }
}
1 An array describing IP addresses to assign to the virtual interface. Both IPv4 and IPv6 IP addresses are supported.
2 An IP address that you specify.
3 The default gateway to route egress network traffic to.
4 An array describing routes to configure inside the Pod.
5 The IP address range in CIDR format.
6 The gateway where network traffic is routed.
7 Optional: DNS configuration.
8 An of array 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 is 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 IP address assignment configuration

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

Renewal of DHCP leases

A Pod obtains its original DHCP lease when it is created. The lease must be periodically renewed by a minimal DHCP server deployment running on the cluster.

To trigger the deployment of the DHCP server, you must create a shim network attachment by editing the Cluster Network Operator configuration, as in the following example:

Example shim network attachment definition
apiVersion: operator.openshift.io/v1
kind: Network
metadata:
  name: cluster
spec:
  ...
  additionalNetworks:
  - name: dhcp-shim
    namespace: default
    rawCNIConfig: |-
    {
      "name": "dhcp-shim",
      "cniVersion": "0.3.1",
      "type": "bridge",
      "master": "ens5",
      "ipam": {
        "type": "dhcp"
      }
    }
DHCP assignment configuration
{
  "ipam": {
    "type": "dhcp"
  }
}

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