Chapter 2. Primary networks

1. Enhanced network isolation for security

   • Tenant isolation: Namespaces can have their own isolated primary network, similar to how tenants are isolated in Red Hat OpenStack Platform (RHOSP). This improves security by reducing the risk of cross-tenant traffic.

2. Network flexibility

   • Layer 2 and layer 3 support: Cluster administrators can configure primary networks as layer 2 or layer 3 network types.

3. Simplified network management

   • Reduced network configuration complexity: With user-defined networks, the need for complex network policies are eliminated because isolation can be achieved by grouping workloads in different networks.

4. Advanced capabilities

   • Consistent and selectable IP addressing: Users can specify and reuse IP subnets across different namespaces and clusters, providing a consistent networking environment.
   • Support for multiple networks: The user-defined networking feature allows administrators to connect multiple namespaces to a single network, or to create distinct networks for different sets of namespaces.

5. Simplification of application migration from Red Hat OpenStack Platform (RHOSP)

   • Network parity: With user-defined networking, the migration of applications from OpenStack to OpenShift Container Platform is simplified by providing similar network isolation and configuration options.

1. An administrator creates a namespace for a user-defined network with the k8s.ovn.org/primary-user-defined-network label.
2. The UserDefinedNetwork CR is created by either the cluster administrator or the user.
3. The user creates pods in the namespace.

Procedure

1. Optional: For a UserDefinedNetwork CR that uses a primary network, create a namespace with the k8s.ovn.org/primary-user-defined-network label by entering the following command:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Namespace
   metadata:
     name: <udn_namespace_name>
     labels:
       k8s.ovn.org/primary-user-defined-network: ""
   EOF

   Copy to Clipboard Toggle word wrap

2. Create a request for either a Layer2 or Layer3 topology type user-defined network:

   1. Create a YAML file, such as my-layer-two-udn.yaml, to define your request for a Layer2 topology as in the following example:

      apiVersion: k8s.ovn.org/v1
      kind: UserDefinedNetwork
      metadata:
        name: udn-1 

      1

      
        namespace: <some_custom_namespace>
      spec:
        topology: Layer2 

      2

      
        layer2: 

      3

      
          role: Primary 

      4

      
          subnets:
            - "10.0.0.0/24"
            - "2001:db8::/60" 

      5

      Copy to Clipboard Toggle word wrap

      1

      Name of your UserDefinedNetwork resource. This should not be default or duplicate any global namespaces created by the Cluster Network Operator (CNO).

      2

      The topology field describes the network configuration; accepted values are Layer2 and Layer3. Specifying a Layer2 topology type creates one logical switch that is shared by all nodes.

      3

      This field specifies the topology configuration. It can be layer2 or layer3.

      4

      Specifies a Primary or Secondary role.

      5

      For Layer2 topology types the following specifies config details for the subnet field:

      • The subnets field is optional.
      • The subnets field is of type string and accepts standard CIDR formats for both IPv4 and IPv6.
      • The subnets field accepts one or two items. For two items, they must be of a different family. For example, subnets values of 10.100.0.0/16 and 2001:db8::/64.
      • Layer2 subnets can be omitted. If omitted, users must configure IP addresses for the pods. As a consequence, port security only prevents MAC spoofing.
      • The Layer2 subnets field is mandatory when the ipamLifecycle field is specified.

   2. Create a YAML file, such as my-layer-three-udn.yaml, to define your request for a Layer3 topology as in the following example:

      apiVersion: k8s.ovn.org/v1
      kind: UserDefinedNetwork
      metadata:
        name: udn-2-primary 

      1

      
        namespace: <some_custom_namespace>
      spec:
        topology: Layer3 

      2

      
        layer3: 

      3

      
          role: Primary 

      4

      
          subnets: 

      5

      
            - cidr: 10.150.0.0/16
              hostSubnet: 24
            - cidr: 2001:db8::/60
              hostSubnet: 64
      # ...

      Copy to Clipboard Toggle word wrap

      1

      Name of your UserDefinedNetwork resource. This should not be default or duplicate any global namespaces created by the Cluster Network Operator (CNO).

      2

      The topology field describes the network configuration; accepted values are Layer2 and Layer3. Specifying a Layer3 topology type creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets.

      3

      This field specifies the topology configuration. Valid values are layer2 or layer3.

      4

      Specifies a Primary or Secondary role.

      5

      For Layer3 topology types the following specifies config details for the subnet field:

      • The subnets field is mandatory.

      • The type for the subnets field is cidr and hostSubnet:

        • cidr is equivalent to the clusterNetwork configuration settings of a cluster. The IP addresses in the CIDR are distributed to pods in the user defined network. This parameter accepts a string value.
        • hostSubnet defines the per-node subnet prefix.
        • For IPv6, only a /64 length is supported for hostSubnet.

3. Apply your request by running the following command:

   $ oc apply -f <my_layer_two_udn.yaml>

   Copy to Clipboard Toggle word wrap

   Where <my_layer_two_udn.yaml> is the name of your Layer2 or Layer3 configuration file.

4. Verify that your request is successful by running the following command:

   $ oc get userdefinednetworks udn-1 -n <some_custom_namespace> -o yaml

   Copy to Clipboard Toggle word wrap

   Where some_custom_namespace is the namespace you created for your user-defined network.

   Example output

   apiVersion: k8s.ovn.org/v1
   kind: UserDefinedNetwork
   metadata:
     creationTimestamp: "2024-08-28T17:18:47Z"
     finalizers:
     - k8s.ovn.org/user-defined-network-protection
     generation: 1
     name: udn-1
     namespace: some-custom-namespace
     resourceVersion: "53313"
     uid: f483626d-6846-48a1-b88e-6bbeb8bcde8c
   spec:
     layer2:
       role: Primary
       subnets:
       - 10.0.0.0/24
       - 2001:db8::/60
     topology: Layer2
   status:
     conditions:
     - lastTransitionTime: "2024-08-28T17:18:47Z"
       message: NetworkAttachmentDefinition has been created
       reason: NetworkAttachmentDefinitionReady
       status: "True"
       type: NetworkReady

   Copy to Clipboard Toggle word wrap

Procedure

1. Optional: Create the namespace for the primary networks:

   $ oc create namespace <namespace_name>

   Copy to Clipboard Toggle word wrap

2. To edit the CNO configuration, enter the following command:

   $ oc edit networks.operator.openshift.io cluster

   Copy to Clipboard Toggle word wrap

3. Modify the CR that you are creating by adding the configuration for the primary network that you are creating, as in the following example CR.

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
     # ...
     additionalNetworks:
     - name: tertiary-net
       namespace: namespace2
       type: Raw
       rawCNIConfig: |-
         {
           "cniVersion": "0.3.1",
           "name": "tertiary-net",
           "type": "ipvlan",
           "master": "eth1",
           "mode": "l2",
           "ipam": {
             "type": "static",
             "addresses": [
               {
                 "address": "192.168.1.23/24"
               }
             ]
           }
         }

   Copy to Clipboard Toggle word wrap
4. Save your changes and quit the text editor to commit your changes.

Procedure

1. Create a YAML file with your primary network configuration, such as in the following example:

   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: next-net
   spec:
     config: |-
       {
         "cniVersion": "0.3.1",
         "name": "work-network",
         "namespace": "namespace2", 

   1

   
         "type": "host-device",
         "device": "eth1",
         "ipam": {
           "type": "dhcp"
         }
       }

   Copy to Clipboard Toggle word wrap

   1

   Optional: You can specify a namespace to which the NAD is applied. If you are working in the namespace where the NAD is to be deployed, this spec is not necessary.

2. To create the primary network, enter the following command:

   $ oc apply -f <file>.yaml

   Copy to Clipboard Toggle word wrap

   where:

   <file>

   Specifies the name of the file contained the YAML manifest.