mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
Merge pull request #88688 from openshift-cherrypick-robot/cherry-pick-85165-to-enterprise-4.18
[enterprise-4.18] Adds cudn docs
This commit is contained in:
Steven Smith
84
modules/cudn-status-conditions.adoc
Normal file
84
modules/cudn-status-conditions.adoc
Normal file
@@ -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 "<namespace_name>": "<primary_network_name>"`
|
||||
|
||||
|`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: [<namespace>/<nad_name>]`
|
||||
|===
|
||||
|
||||
.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: [<node_name>], check UDN events for more info.`
|
||||
|
||||
|===
|
||||
31
modules/nw-cudn-best-practices.adoc
Normal file
31
modules/nw-cudn-best-practices.adoc
Normal file
@@ -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.
|
||||
169
modules/nw-cudn-cr.adoc
Normal file
169
modules/nw-cudn-cr.adoc
Normal file
@@ -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: <cudn_namespace_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: <cudn_name> # <1>
|
||||
spec:
|
||||
namespaceSelector: # <2>
|
||||
matchLabels: # <3>
|
||||
- "<example_namespace_one>":"" # <4>
|
||||
- "<example_namespace_two>":"" # <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 `<example_namespace_one>` _and_ `<example_namespace_two>`.
|
||||
<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: <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: 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 `<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 {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 <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
|
||||
----
|
||||
@@ -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}"]
|
||||
|
||||
@@ -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}"]
|
||||
|
||||
@@ -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 <my_layer_two_udn.yaml>
|
||||
$ oc apply -f <my_layer_two_udn>.yaml
|
||||
----
|
||||
+
|
||||
Where `<my_layer_two_udn.yaml>` is the name of your `Layer2` or `Layer3` configuration file.
|
||||
Where `<my_layer_two_udn>.yaml` is the name of your `Layer2` or `Layer3` configuration file.
|
||||
|
||||
. Verify that your request is successful by running the following command:
|
||||
+
|
||||
|
||||
@@ -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}"]
|
||||
|
||||
@@ -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}"]
|
||||
|
||||
@@ -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]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user