From ec0698d048c6c6543ac0b9128fb92d0393ad8d45 Mon Sep 17 00:00:00 2001 From: Steven Smith Date: Tue, 19 Nov 2024 14:27:46 -0500 Subject: [PATCH] Adds cudn docs two --- modules/cudn-status-conditions.adoc | 84 +++++++++ modules/nw-cudn-best-practices.adoc | 31 ++++ modules/nw-cudn-cr.adoc | 169 ++++++++++++++++++ modules/nw-udn-additional-config-details.adoc | 2 +- modules/nw-udn-best-practices.adoc | 2 +- modules/nw-udn-cr.adoc | 8 +- modules/nw-udn-examples.adoc | 2 +- modules/nw-udn-limitations.adoc | 2 +- .../about-user-defined-networks.adoc | 13 ++ 9 files changed, 305 insertions(+), 8 deletions(-) create mode 100644 modules/cudn-status-conditions.adoc create mode 100644 modules/nw-cudn-best-practices.adoc create mode 100644 modules/nw-cudn-cr.adoc diff --git a/modules/cudn-status-conditions.adoc b/modules/cudn-status-conditions.adoc new file mode 100644 index 0000000000..e059b8769b --- /dev/null +++ b/modules/cudn-status-conditions.adoc @@ -0,0 +1,84 @@ +//module included in the following assembly: +// +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc + +:_mod-docs-content-type: REFERENCE +[id="cudn-status-conditions_{context}"] += ClusterUserDefinedNetwork status condition types + +The following tables explain the status condition types returned for `ClusterUserDefinedNetwork` CRs when describing the resource. These conditions can be used to troubleshoot your deployment. + +//The following table is subject to change and will be updated accordingly. + +.NetworkCreated condition types +[cols="2a,2a,3a,6a",options="header"] +|=== + +|Condition type +|Status +2+|Reason and Message + +.3+|`NetworkCreated` +.3+| `True` +2+|When `True`, the following reason and message is returned: +h|Reason +h|Message + +|`NetworkAttachmentDefinitionCreated` +|'NetworkAttachmentDefinition has been created in following namespaces: [example-namespace-1, example-namespace-2, example-namespace-3]'` + +.9+|`NetworkCreated` +.9+| `False` +2+|When `False`, one of the following messages is returned: +h|Reason +h|Message + +|`SyncError` +|`failed to generate NetworkAttachmentDefinition` + +|`SyncError` +|`failed to update NetworkAttachmentDefinition` + +|`SyncError` +|`primary network already exist in namespace "": ""` + +|`SyncError` +|`failed to create NetworkAttachmentDefinition: create NAD error` + +|`SyncError` +|`foreign NetworkAttachmentDefinition with the desired name already exist` + +|`SyncError` +|`failed to add finalizer to UserDefinedNetwork` + +|`NetworkAttachmentDefinitionDeleted` +|`NetworkAttachmentDefinition is being deleted: [/]` +|=== + +.NetworkAllocationSucceeded condition types +[cols="2a,2a,3a,6a",options="header"] +|=== + +|Condition type +|Status +2+|Reason and Message + +.3+|`NetworkAllocationSucceeded` +.3+| `True` +2+|When `True`, the following reason and message is returned: +h|Reason +h|Message + +|`NetworkAllocationSucceeded` +|`Network allocation succeeded for all synced nodes.` + +.3+|`NetworkAllocationSucceeded` +.3+| `False` +2+|When `False`, the following message is returned: +h|Reason +h|Message + +|`InternalError` +|`Network allocation failed for at least one node: [], check UDN events for more info.` + +|=== diff --git a/modules/nw-cudn-best-practices.adoc b/modules/nw-cudn-best-practices.adoc new file mode 100644 index 0000000000..b9bb5f9b2c --- /dev/null +++ b/modules/nw-cudn-best-practices.adoc @@ -0,0 +1,31 @@ +//module included in the following assembly: +// +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc + +:_mod-docs-content-type: CONCEPT +[id="considerations-for-cudn_{context}"] += Best practices for ClusterUserDefinedNetwork CRs + +Before setting up a `ClusterUserDefinedNetwork` custom resource (CR), users should consider the following information: + +* A `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. + +* `ClusterUserDefinedNetwork` CRs should not be created in the default namespace. This can result in no isolation and, as a result, could introduce security risks to the cluster. + +* `ClusterUserDefinedNetwork` CRs should not target `openshift-*` namespaces. + +* {product-title} administrators should be aware that all namespaces of a cluster are selected when one of the following conditions are met: + +** The `matchLabels` selector is left empty. +** The `matchExpressions` selector is left empty. +** The `namespaceSelector` is initialized, but does not specify `matchExpressions` or `matchLabel`. For example: `namespaceSelector: {}`. + +* For primary networks, the namespace used for the `ClusterUserDefinedNetwork` CR must include the `k8s.ovn.org/primary-user-defined-network` label. This label cannot be updated, and can only be added when the namespace is created. The following conditions apply with the `k8s.ovn.org/primary-user-defined-network` namespace label: + +** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a pod is created, the pod attaches itself to the default network. + +** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `ClusterUserDefinedNetwork` CR is created that matches the namespace, the CUDN reports an error status and the network is not created. + +** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `CluserUserDefinedNetwork` CR already exists, a pod in the namespace is created and attached to the default network. + +** If the namespace _has_ the label, and a primary `ClusterUserDefinedNetwork` CR does not exist, a pod in the namespace is not created until the `ClusterUserDefinedNetwork` CR is created. \ No newline at end of file diff --git a/modules/nw-cudn-cr.adoc b/modules/nw-cudn-cr.adoc new file mode 100644 index 0000000000..fdad6c0fd9 --- /dev/null +++ b/modules/nw-cudn-cr.adoc @@ -0,0 +1,169 @@ +//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 custom resource + +The following procedure creates a `ClusterUserDefinedNetwork` custom resource definition (CRD). Based upon your use case, create your request 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` CRD 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` topology. +==== + +.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: + labels: + k8s.ovn.org/primary-user-defined-network: "" +EOF +---- + +. Create a request for either a `Layer2` or `Layer3` topology type cluster-wide user-defined network: + +.. 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: # <1> +spec: + namespaceSelector: # <2> + matchLabels: # <3> + - "":"" # <4> + - "":"" # <4> + network: # <5> + topology: Layer2 # <6> + layer2: # <7> + role: Primary # <8> + subnets: + - "2001:db8::/64" + - "10.100.0.0/16" # <9> +---- +<1> Name of your `ClusterUserDefinedNetwork` custom resource. +<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 `matchLabels` selector type, where terms are evaluated with an `AND` relationship. +<4> Because the `matchLabels` selector type is used, provisions namespaces matching both `` _and_ ``. +<5> Describes the network configuration. +<6> 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. +<7> This field specifies the topology configuration. It can be `layer2` or `layer3`. +<8> Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}. +<9> 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". ++ +.. 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: # <1> +spec: + namespaceSelector: # <2> + matchExpressions: # <3> + - key: kubernetes.io/metadata.name # <4> + operator: In # <5> + values: [", "] # <6> + network: # <7> + topology: Layer3 # <8> + layer3: # <9> + role: Primary # <10> + subnets: # <11> + - cidr: 10.100.0.0/16 + hostSubnet: 64 +---- +<1> Name of your `ClusterUserDefinedNetwork` custom resource. +<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 `` or ``. +<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 {product-version}. +<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`. ++ +. Apply your request by running the following command: ++ +[source,terminal] +---- +$ oc create --validate=true -f .yaml +---- ++ +Where `.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 -o yaml +---- ++ +Where `` 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 +---- diff --git a/modules/nw-udn-additional-config-details.adoc b/modules/nw-udn-additional-config-details.adoc index 7b8926ee2f..5dff9c355b 100644 --- a/modules/nw-udn-additional-config-details.adoc +++ b/modules/nw-udn-additional-config-details.adoc @@ -1,6 +1,6 @@ //module included in the following assembly: // -// *networking/multiple_networks/understanding-user-defined-networks.adoc +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc :_mod-docs-content-type: REFERENCE [id="nw-udn-additional-config-details_{context}"] diff --git a/modules/nw-udn-best-practices.adoc b/modules/nw-udn-best-practices.adoc index 024f9e7890..eebd3ef619 100644 --- a/modules/nw-udn-best-practices.adoc +++ b/modules/nw-udn-best-practices.adoc @@ -1,6 +1,6 @@ //module included in the following assembly: // -// *networkking/multiple_networks/understanding-user-defined-networks.adoc +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc :_mod-docs-content-type: CONCEPT [id="considerations-for-udn_{context}"] diff --git a/modules/nw-udn-cr.adoc b/modules/nw-udn-cr.adoc index d11d7366a8..37b85d11ac 100644 --- a/modules/nw-udn-cr.adoc +++ b/modules/nw-udn-cr.adoc @@ -1,6 +1,6 @@ //module included in the following assembly: // -// *networking/multiple_networks/understanding-user-defined-networks.adoc +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc :_mod-docs-content-type: PROCEDURE [id="nw-udn-cr_{context}"] @@ -11,7 +11,7 @@ The following procedure creates a user-defined network that is namespace scoped. //We won't have these pieces till GA in 4.18. //[NOTE] //==== -//If any cluster default networked pods exist before the user-defined network is created, any further pods created in this namespace will return an error message: `What_is_this`. +//If any cluster default networked pods exist before the user-defined network is created, any further pods created in this namespace will return an error message: `What_is_this`? //==== .Procedure @@ -96,10 +96,10 @@ spec: + [source,terminal] ---- -$ oc apply -f +$ oc apply -f .yaml ---- + -Where `` is the name of your `Layer2` or `Layer3` configuration file. +Where `.yaml` is the name of your `Layer2` or `Layer3` configuration file. . Verify that your request is successful by running the following command: + diff --git a/modules/nw-udn-examples.adoc b/modules/nw-udn-examples.adoc index 3c6bebff33..5e9409ed69 100644 --- a/modules/nw-udn-examples.adoc +++ b/modules/nw-udn-examples.adoc @@ -1,6 +1,6 @@ //module included in the following assembly: // -// *networking/multiple_networks/understanding-user-defined-networks.adoc +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc :_mod-docs-content-type: REFERENCE [id="nw-udn-examples_{context}"] diff --git a/modules/nw-udn-limitations.adoc b/modules/nw-udn-limitations.adoc index ee8ff2fcc9..17d4408f07 100644 --- a/modules/nw-udn-limitations.adoc +++ b/modules/nw-udn-limitations.adoc @@ -1,6 +1,6 @@ //module included in the following assembly: // -// *networkking/multiple_networks/understanding-user-defined-networks.adoc +// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc :_mod-docs-content-type: CONCEPT [id="limitations-for-udn_{context}"] diff --git a/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc b/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc index bcad31b023..7f3ca646bf 100644 --- a/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc +++ b/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc @@ -43,6 +43,19 @@ include::modules/nw-udn-benefits.adoc[leveloffset=+1] //Limitations that users should consider for UDN. include::modules/nw-udn-limitations.adoc[leveloffset=+1] +//Best practices for using CUDN. +include::modules/nw-cudn-best-practices.adoc[leveloffset=+1] + +//How to implement the CUDN API on a cluster. +include::modules/nw-cudn-cr.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc#configuring-pods-static-ip_configuring-additional-network-ovnk[Configuring pods with a static IP address] + +//CUDN status conditions +include::modules/cudn-status-conditions.adoc[leveloffset=+2] + //Best practices for using UDN. include::modules/nw-udn-best-practices.adoc[leveloffset=+1]