Skip to content

Commit 8e5519f

Browse files
stevsmitstevsmit
authored
Merge pull request #85165 from stevsmit/12599-osdocs-cudn-proc
Adds cudn docs
2 parents 4659b74 + 51a5969 commit 8e5519f

9 files changed

+305
-8
lines changed

‎modules/cudn-status-conditions.adoc

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
//module included in the following assembly:
2+
//
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="cudn-status-conditions_{context}"]
7+
= ClusterUserDefinedNetwork status condition types
8+
9+
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.
10+
11+
//The following table is subject to change and will be updated accordingly.
12+
13+
.NetworkCreated condition types
14+
[cols="2a,2a,3a,6a",options="header"]
15+
|===
16+
17+
|Condition type
18+
|Status
19+
2+|Reason and Message
20+
21+
.3+|`NetworkCreated`
22+
.3+| `True`
23+
2+|When `True`, the following reason and message is returned:
24+
h|Reason
25+
h|Message
26+
27+
|`NetworkAttachmentDefinitionCreated`
28+
|'NetworkAttachmentDefinition has been created in following namespaces: [example-namespace-1, example-namespace-2, example-namespace-3]'`
29+
30+
.9+|`NetworkCreated`
31+
.9+| `False`
32+
2+|When `False`, one of the following messages is returned:
33+
h|Reason
34+
h|Message
35+
36+
|`SyncError`
37+
|`failed to generate NetworkAttachmentDefinition`
38+
39+
|`SyncError`
40+
|`failed to update NetworkAttachmentDefinition`
41+
42+
|`SyncError`
43+
|`primary network already exist in namespace "<namespace_name>": "<primary_network_name>"`
44+
45+
|`SyncError`
46+
|`failed to create NetworkAttachmentDefinition: create NAD error`
47+
48+
|`SyncError`
49+
|`foreign NetworkAttachmentDefinition with the desired name already exist`
50+
51+
|`SyncError`
52+
|`failed to add finalizer to UserDefinedNetwork`
53+
54+
|`NetworkAttachmentDefinitionDeleted`
55+
|`NetworkAttachmentDefinition is being deleted: [<namespace>/<nad_name>]`
56+
|===
57+
58+
.NetworkAllocationSucceeded condition types
59+
[cols="2a,2a,3a,6a",options="header"]
60+
|===
61+
62+
|Condition type
63+
|Status
64+
2+|Reason and Message
65+
66+
.3+|`NetworkAllocationSucceeded`
67+
.3+| `True`
68+
2+|When `True`, the following reason and message is returned:
69+
h|Reason
70+
h|Message
71+
72+
|`NetworkAllocationSucceeded`
73+
|`Network allocation succeeded for all synced nodes.`
74+
75+
.3+|`NetworkAllocationSucceeded`
76+
.3+| `False`
77+
2+|When `False`, the following message is returned:
78+
h|Reason
79+
h|Message
80+
81+
|`InternalError`
82+
|`Network allocation failed for at least one node: [<node_name>], check UDN events for more info.`
83+
84+
|===

‎modules/nw-cudn-best-practices.adoc

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
//module included in the following assembly:
2+
//
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="considerations-for-cudn_{context}"]
7+
= Best practices for ClusterUserDefinedNetwork CRs
8+
9+
Before setting up a `ClusterUserDefinedNetwork` custom resource (CR), users should consider the following information:
10+
11+
* 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.
12+
13+
* `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.
14+
15+
* `ClusterUserDefinedNetwork` CRs should not target `openshift-*` namespaces.
16+
17+
* {product-title} administrators should be aware that all namespaces of a cluster are selected when one of the following conditions are met:
18+
19+
** The `matchLabels` selector is left empty.
20+
** The `matchExpressions` selector is left empty.
21+
** The `namespaceSelector` is initialized, but does not specify `matchExpressions` or `matchLabel`. For example: `namespaceSelector: {}`.
22+
23+
* 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:
24+
25+
** 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.
26+
27+
** 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.
28+
29+
** 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.
30+
31+
** 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.

‎modules/nw-cudn-cr.adoc

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
//module included in the following assembly:
2+
//
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nw-cudn-cr_{context}"]
7+
= Creating a ClusterUserDefinedNetwork custom resource
8+
9+
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.
10+
11+
[IMPORTANT]
12+
====
13+
* 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.
14+
* {VirtProductName} only supports the `Layer2` topology.
15+
====
16+
17+
.Prerequisites
18+
19+
* You have logged in as a user with `cluster-admin` privileges.
20+
21+
.Procedure
22+
23+
. 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:
24+
+
25+
[source,yaml]
26+
----
27+
$ cat << EOF | oc apply -f -
28+
apiVersion: v1
29+
kind: Namespace
30+
metadata:
31+
name: <cudn_namespace_name>
32+
labels:
33+
k8s.ovn.org/primary-user-defined-network: ""
34+
EOF
35+
----
36+
37+
. Create a request for either a `Layer2` or `Layer3` topology type cluster-wide user-defined network:
38+
39+
.. Create a YAML file, such as `cluster-layer-two-udn.yaml`, to define your request for a `Layer2` topology as in the following example:
40+
+
41+
[source, yaml]
42+
----
43+
apiVersion: k8s.ovn.org/v1
44+
kind: ClusterUserDefinedNetwork
45+
metadata:
46+
name: <cudn_name> # <1>
47+
spec:
48+
namespaceSelector: # <2>
49+
matchLabels: # <3>
50+
- "<example_namespace_one>":"" # <4>
51+
- "<example_namespace_two>":"" # <4>
52+
network: # <5>
53+
topology: Layer2 # <6>
54+
layer2: # <7>
55+
role: Primary # <8>
56+
subnets:
57+
- "2001:db8::/64"
58+
- "10.100.0.0/16" # <9>
59+
----
60+
<1> Name of your `ClusterUserDefinedNetwork` custom resource.
61+
<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.
62+
<3> Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship.
63+
<4> Because the `matchLabels` selector type is used, provisions namespaces matching both `<example_namespace_one>` _and_ `<example_namespace_two>`.
64+
<5> Describes the network configuration.
65+
<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.
66+
<7> This field specifies the topology configuration. It can be `layer2` or `layer3`.
67+
<8> Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}.
68+
<9> For `Layer2` topology types the following specifies config details for the `subnet` field:
69+
+
70+
* The subnets field is optional.
71+
* The subnets field is of type `string` and accepts standard CIDR formats for both IPv4 and IPv6.
72+
* 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`.
73+
* `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".
74+
+
75+
.. Create a YAML file, such as `cluster-layer-three-udn.yaml`, to define your request for a `Layer3` topology as in the following example:
76+
+
77+
[source, yaml]
78+
----
79+
apiVersion: k8s.ovn.org/v1
80+
kind: ClusterUserDefinedNetwork
81+
metadata:
82+
name: <cudn_name> # <1>
83+
spec:
84+
namespaceSelector: # <2>
85+
matchExpressions: # <3>
86+
- key: kubernetes.io/metadata.name # <4>
87+
operator: In # <5>
88+
values: ["<example_namespace_one>, <example_namespace_two>"] # <6>
89+
network: # <7>
90+
topology: Layer3 # <8>
91+
layer3: # <9>
92+
role: Primary # <10>
93+
subnets: # <11>
94+
- cidr: 10.100.0.0/16
95+
hostSubnet: 64
96+
----
97+
<1> Name of your `ClusterUserDefinedNetwork` custom resource.
98+
<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.
99+
<3> Uses the `matchExpressions` selector type, where terms are evaluated with an _*OR*_ relationship.
100+
<4> Specifies the label key to match.
101+
<5> Specifies the operator. Valid values include: `In`, `NotIn`, `Exists`, and `DoesNotExist`.
102+
<6> Because the `matchExpressions` type is used, provisions namespaces matching either `<example_namespace_one>` or `<example_namespace_two>`.
103+
<7> Describes the network configuration.
104+
<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.
105+
<9> This field specifies the topology configuration. Valid values are `layer2` or `layer3`.
106+
<10> Specifies a `Primary` or `Secondary` role. `Primary` is the only `role` specification supported in {product-version}.
107+
<11> For `Layer3` topology types the following specifies config details for the `subnet` field:
108+
+
109+
* The `subnets` field is mandatory.
110+
* The type for the `subnets` field is `cidr` and `hostSubnet`:
111+
** `cidr` is the cluster subnet and accepts a string value.
112+
** `hostSubnet` specifies the nodes subnet prefix that the cluster subnet is split to.
113+
** For IPv6, only a `/64` length is supported for `hostSubnet`.
114+
+
115+
. Apply your request by running the following command:
116+
+
117+
[source,terminal]
118+
----
119+
$ oc create --validate=true -f <example_cluster_udn>.yaml
120+
----
121+
+
122+
Where `<example_cluster_udn>.yaml` is the name of your `Layer2` or `Layer3` configuration file.
123+
124+
. Verify that your request is successful by running the following command:
125+
+
126+
[source,terminal]
127+
----
128+
$ oc get clusteruserdefinednetwork <cudn_name> -o yaml
129+
----
130+
+
131+
Where `<cudn_name>` is the name you created of your cluster-wide user-defined network.
132+
+
133+
.Example output
134+
[source,yaml]
135+
----
136+
apiVersion: k8s.ovn.org/v1
137+
kind: ClusterUserDefinedNetwork
138+
metadata:
139+
creationTimestamp: "2024-12-05T15:53:00Z"
140+
finalizers:
141+
- k8s.ovn.org/user-defined-network-protection
142+
generation: 1
143+
name: my-cudn
144+
resourceVersion: "47985"
145+
uid: 16ee0fcf-74d1-4826-a6b7-25c737c1a634
146+
spec:
147+
namespaceSelector:
148+
matchExpressions:
149+
- key: custom.network.selector
150+
operator: In
151+
values:
152+
- example-namespace-1
153+
- example-namespace-2
154+
- example-namespace-3
155+
network:
156+
layer3:
157+
role: Primary
158+
subnets:
159+
- cidr: 10.100.0.0/16
160+
topology: Layer3
161+
status:
162+
conditions:
163+
- lastTransitionTime: "2024-11-19T16:46:34Z"
164+
message: 'NetworkAttachmentDefinition has been created in following namespaces:
165+
[example-namespace-1, example-namespace-2, example-namespace-3]'
166+
reason: NetworkAttachmentDefinitionReady
167+
status: "True"
168+
type: NetworkCreated
169+
----

‎modules/nw-udn-additional-config-details.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//module included in the following assembly:
22
//
3-
// *networking/multiple_networks/understanding-user-defined-networks.adoc
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
44

55
:_mod-docs-content-type: REFERENCE
66
[id="nw-udn-additional-config-details_{context}"]

‎modules/nw-udn-best-practices.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//module included in the following assembly:
22
//
3-
// *networkking/multiple_networks/understanding-user-defined-networks.adoc
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="considerations-for-udn_{context}"]

‎modules/nw-udn-cr.adoc

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//module included in the following assembly:
22
//
3-
// *networking/multiple_networks/understanding-user-defined-networks.adoc
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="nw-udn-cr_{context}"]
@@ -11,7 +11,7 @@ The following procedure creates a user-defined network that is namespace scoped.
1111
//We won't have these pieces till GA in 4.18.
1212
//[NOTE]
1313
//====
14-
//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`.
14+
//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`?
1515
//====
1616

1717
.Procedure
@@ -96,10 +96,10 @@ spec:
9696
+
9797
[source,terminal]
9898
----
99-
$ oc apply -f <my_layer_two_udn.yaml>
99+
$ oc apply -f <my_layer_two_udn>.yaml
100100
----
101101
+
102-
Where `<my_layer_two_udn.yaml>` is the name of your `Layer2` or `Layer3` configuration file.
102+
Where `<my_layer_two_udn>.yaml` is the name of your `Layer2` or `Layer3` configuration file.
103103

104104
. Verify that your request is successful by running the following command:
105105
+

‎modules/nw-udn-examples.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//module included in the following assembly:
22
//
3-
// *networking/multiple_networks/understanding-user-defined-networks.adoc
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
44

55
:_mod-docs-content-type: REFERENCE
66
[id="nw-udn-examples_{context}"]

‎modules/nw-udn-limitations.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//module included in the following assembly:
22
//
3-
// *networkking/multiple_networks/understanding-user-defined-networks.adoc
3+
// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="limitations-for-udn_{context}"]

‎networking/multiple_networks/primary_networks/about-user-defined-networks.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,19 @@ include::modules/nw-udn-benefits.adoc[leveloffset=+1]
4343
//Limitations that users should consider for UDN.
4444
include::modules/nw-udn-limitations.adoc[leveloffset=+1]
4545

46+
//Best practices for using CUDN.
47+
include::modules/nw-cudn-best-practices.adoc[leveloffset=+1]
48+
49+
//How to implement the CUDN API on a cluster.
50+
include::modules/nw-cudn-cr.adoc[leveloffset=+1]
51+
52+
[role="_additional-resources"]
53+
.Additional resources
54+
* 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]
55+
56+
//CUDN status conditions
57+
include::modules/cudn-status-conditions.adoc[leveloffset=+2]
58+
4659
//Best practices for using UDN.
4760
include::modules/nw-udn-best-practices.adoc[leveloffset=+1]
4861

0 commit comments

Comments
 (0)