Chapter 2. Primary networks

Procedure

1. Optional: For a ClusterUserDefinedNetwork 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: <cudn_namespace_name>
     labels:
       k8s.ovn.org/primary-user-defined-network: ""
   EOF

   Copy to Clipboard Toggle word wrap

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

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

      apiVersion: k8s.ovn.org/v1
      kind: ClusterUserDefinedNetwork
      metadata:
        name: <cudn_name> 

      1

      
      spec:
        namespaceSelector: 

      2

      
          matchLabels: 

      3

      
            "<label_1_key>": "<label_1_value>" 

      4

      
            "<label_2_key>": "<label_2_value>" 

      5

      
        network: 

      6

      
          topology: Layer2 

      7

      
          layer2: 

      8

      
            role: Primary 

      9

      
            subnets:
              - "2001:db8::/64"
              - "10.100.0.0/16" 

      10

      Copy to Clipboard Toggle word wrap

      1

      Name of your ClusterUserDefinedNetwork CR.

      2

      A label query over the set of namespaces that the CUDN CR applies to. Uses the standard Kubernetes MatchLabel selector. Must not point to default or openshift-* namespaces.

      3

      Uses the matchLabels selector type, where terms are evaluated with an AND relationship.

      4 5

      In this example, the CUDN CR is deployed to namespaces that contain both <label_1_key>=<label_1_value> and <label_2_key>=<label_2_value> labels.

      6

      Describes the network configuration.

      7

      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.

      8

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

      9

      Specifies Primary or Secondary. Primary is the only role specification supported in 4.18.

      10

      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 static IP addresses for the pods. As a consequence, port security only prevents MAC spoofing. For more information, see "Configuring pods with a static IP address".

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

      apiVersion: k8s.ovn.org/v1
      kind: ClusterUserDefinedNetwork
      metadata:
        name: <cudn_name> 

      1

      
      spec:
        namespaceSelector: 

      2

      
          matchExpressions: 

      3

      
          - key: kubernetes.io/metadata.name 

      4

      
            operator: In 

      5

      
            values: ["<example_namespace_one>", "<example_namespace_two>"] 

      6

      
        network: 

      7

      
          topology: Layer3 

      8

      
          layer3: 

      9

      
            role: Primary 

      10

      
            subnets: 

      11

      
              - cidr: 10.100.0.0/16
                hostSubnet: 24

      Copy to Clipboard Toggle word wrap

      1

      Name of your ClusterUserDefinedNetwork CR.

      2

      A label query over the set of namespaces that the cluster UDN applies to. Uses the standard Kubernetes MatchLabel selector. Must not point to default or openshift-* namespaces.

      3

      Uses the matchExpressions selector type, where terms are evaluated with an OR relationship.

      4

      Specifies the label key to match.

      5

      Specifies the operator. Valid values include: In, NotIn, Exists, and DoesNotExist.

      6

      Because the matchExpressions type is used, provisions namespaces matching either <example_namespace_one> or <example_namespace_two>.

      7

      Describes the network configuration.

      8

      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.

      9

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

      10

      Specifies a Primary or Secondary role. Primary is the only role specification supported in 4.18.

      11

      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 the cluster subnet and accepts a string value.
        • hostSubnet specifies the nodes subnet prefix that the cluster subnet is split to.
        • For IPv6, only a /64 length is supported for hostSubnet.

3. Apply your request by running the following command:

   $ oc create --validate=true -f <example_cluster_udn>.yaml

   Copy to Clipboard Toggle word wrap

   Where <example_cluster_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 clusteruserdefinednetwork <cudn_name> -o yaml

   Copy to Clipboard Toggle word wrap

   Where <cudn_name> is the name you created of your cluster-wide user-defined network.

   Example output

   apiVersion: k8s.ovn.org/v1
   kind: ClusterUserDefinedNetwork
   metadata:
     creationTimestamp: "2024-12-05T15:53:00Z"
     finalizers:
     - k8s.ovn.org/user-defined-network-protection
     generation: 1
     name: my-cudn
     resourceVersion: "47985"
     uid: 16ee0fcf-74d1-4826-a6b7-25c737c1a634
   spec:
     namespaceSelector:
       matchExpressions:
       - key: custom.network.selector
         operator: In
         values:
         - example-namespace-1
         - example-namespace-2
         - example-namespace-3
     network:
       layer3:
         role: Primary
         subnets:
         - cidr: 10.100.0.0/16
       topology: Layer3
   status:
     conditions:
     - lastTransitionTime: "2024-11-19T16:46:34Z"
       message: 'NetworkAttachmentDefinition has been created in following namespaces:
         [example-namespace-1, example-namespace-2, example-namespace-3]'
       reason: NetworkAttachmentDefinitionReady
       status: "True"
       type: NetworkCreated

   Copy to Clipboard Toggle word wrap

Procedure

1. From the Administrator perspective, click Networking UserDefinedNetworks.
2. Click ClusterUserDefinedNetwork.
3. In the Name field, specify a name for the cluster-scoped UDN.
4. Specify a value in the Subnet field.
5. In the Project(s) Match Labels field, add the appropriate labels to select namespaces that the cluster UDN applies to.
6. Click Create. The cluster-scoped UDN serves as the default primary network for pods located in namespaces that contain the labels that you specified in step 5.

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 user-defined network for either a Layer2 or Layer3 topology type:

   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: NetworkCreated

   Copy to Clipboard Toggle word wrap

Procedure

1. From the Administrator perspective, click Networking UserDefinedNetworks.
2. Click Create UserDefinedNetwork.
3. From the Project name list, select the namespace that you previously created.
4. Specify a value in the Subnet field.
5. Click Create. The user-defined network serves as the default primary network for pods that you create in this namespace.