openshift-docs/modules/nw-cudn-cr.adoc

//module included in the following assembly:
//
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-cudn-cr_{context}"]
= Creating a ClusterUserDefinedNetwork CR by using the CLI

[role="_abstract"]
To implement cluster-wide network segmentation and isolation across multiple namespaces, supporting either layer 2 or layer 3 in {product-title}, create a `ClusterUserDefinedNetwork` CR by using the CLI. Defining this resource ensures that network traffic is securely partitioned across the cluster.

Based upon your use case, create your request by using either the `cluster-layer-two-udn.yaml` example for a `Layer2` topology type or the `cluster-layer-three-udn.yaml` example for a `Layer3` topology type.

[IMPORTANT]
====
* The `ClusterUserDefinedNetwork` CR is intended for use by cluster administrators and should not be used by non-administrators. If used incorrectly, it might result in security issues with your deployment, cause disruptions, or break the cluster network.
* {VirtProductName} only supports the `Layer2` and `Localnet` topologies.
====

.Prerequisites

* You have logged in as a user with `cluster-admin` privileges.

.Procedure

. 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:
+
[source,yaml]
----
$ cat << EOF | oc apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: <cudn_namespace_name>
  labels:
    k8s.ovn.org/primary-user-defined-network: ""
EOF
----

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

.. Create a YAML file, such as `cluster-layer-two-udn.yaml`, to define your request for a `Layer2` topology as in the following example:
+
[source, yaml]
----
apiVersion: k8s.ovn.org/v1
kind: ClusterUserDefinedNetwork
metadata:
  name: <cudn_name>
spec:
  namespaceSelector:
    matchLabels:
      "<label_1_key>": "<label_1_value>"
      "<label_2_key>": "<label_2_value>"
  network:
    topology: Layer2
    layer2:
      role: Primary
      subnets:
        - "2001:db8::/64"
        - "10.100.0.0/16"
----
+
where:

`Name`:: Specifies the name of your `ClusterUserDefinedNetwork` CR.
`namespaceSelector`:: Specifies 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.
`matchLabels`:: Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship. 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.
`network`:: Describes the network configuration.
`topology`:: This 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.
This field specifies the topology configuration. It can be `layer2` or `layer3`.
`role`:: Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}.
`subnets`:: For `Layer2` topology types the following specifies config details for the 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".
+
.. Create a YAML file, such as `cluster-layer-three-udn.yaml`, to define your request for a `Layer3` topology as in the following example:
+
[source, yaml]
----
apiVersion: k8s.ovn.org/v1
kind: ClusterUserDefinedNetwork
metadata:
  name: <cudn_name>
spec:
  namespaceSelector:
    matchExpressions:
    - key: kubernetes.io/metadata.name
      operator: In
      values: ["<example_namespace_one>", "<example_namespace_two>"]
  network:
    topology: Layer3
    layer3:
      role: Primary
      subnets:
        - cidr: 10.100.0.0/16
          hostSubnet: 24
----
+
where:

`Name`:: Specifies the name of your `ClusterUserDefinedNetwork` CR.
`namespaceSelector`:: Specifies 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. Uses the `matchExpressions` selector type, where terms are evaluated with an `OR` relationship.
`Key`:: Specifies the label key to match. Takes an operator value; valid values include: `In`, `NotIn`, `Exists`, and `DoesNotExist`. Because the `matchExpressions` type is used, provisions namespaces matching either `<example_namespace_one>` or `<example_namespace_two>`.
`network`:: Describes the network configuration.
`topology`:: 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.
`role`:: Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}.
`subnets`:: 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`.
+
. Apply your request by running the following command:
+
[source,terminal]
----
$ oc create --validate=true -f <example_cluster_udn>.yaml
----
+
Where `<example_cluster_udn>.yaml` is the name of your `Layer2` or `Layer3` configuration file.

. Verify that your request is successful by running the following command:
+
[source,terminal]
----
$ oc get clusteruserdefinednetwork <cudn_name> -o yaml
----
+
Where `<cudn_name>` is the name you created of your cluster-wide user-defined network.
+
.Example output
[source,yaml]
----
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
----