From 7777e217c924ba13b7f2746ceb2857702591357d Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Wed, 30 Apr 2025 16:59:58 +0100 Subject: [PATCH] OSDOCS-8677-OVNK: Applied revised changes to the K8S NMstate docs --- modules/node-network-configuration-policy-file.adoc | 10 +++++----- modules/virt-creating-interface-on-nodes.adoc | 9 +++++++-- modules/virt-example-nmstate-IP-management.adoc | 7 ------- .../virt-nmstate-example-policy-configurations.adoc | 6 ++++-- .../k8s-nmstate-updating-node-network-config.adoc | 3 +++ 5 files changed, 19 insertions(+), 16 deletions(-) diff --git a/modules/node-network-configuration-policy-file.adoc b/modules/node-network-configuration-policy-file.adoc index abfa1d894b4a..16adaf256fbf 100644 --- a/modules/node-network-configuration-policy-file.adoc +++ b/modules/node-network-configuration-policy-file.adoc @@ -8,7 +8,7 @@ A `NodeNetworkConfigurationPolicy` (NNCP) manifest file defines policies that the Kubernetes NMState Operator uses to configure networking for nodes that exist in an {product-title} cluster. -After you apply a node network policy to a node, the Kubernetes NMState Operator creates an interface on the node. A node network policy includes your requested network configuration and the status of execution for the policy on the cluster as a whole. +After you apply a node network policy to a node, the Kubernetes NMState Operator configures the networking configuration for nodes according to the node network policy details. You can create an NNCP by using either the {oc-first} or the {product-title} web console. As a postinstallation task you can create an NNCP or edit an existing NNCP. @@ -17,13 +17,13 @@ You can create an NNCP by using either the {oc-first} or the {product-title} web Before you create an NNCP, ensure that you read the "Example policy configurations for different interfaces" document. ==== -If you want to delete an NNCP, you can use the `oc delete nncp` command to complete this action. However, this command does not delete any created objects, such as a bridge interface. +If you want to delete an NNCP, you can use the `oc delete nncp` command to complete this action. However, this command does not delete any objects, such as a bridge interface. -Deleting the node network policy that added an interface to a node does not change the configuration of the policy on the node. Similarly, removing an interface does not delete the policy, because the Kubernetes NMState Operator recreates the removed interface whenever a pod or a node is restarted. +Deleting the node network policy that added an interface to a node does not change the configuration of the policy on the node. Similarly, removing an interface does not delete the policy, because the Kubernetes NMState Operator re-adds the removed interface whenever a pod or a node is restarted. -To effectively delete the NNCP, the node network policy, and any created interfaces would typically require the following actions: +To effectively delete the NNCP, the node network policy, and any interfaces would typically require the following actions: . Edit the NNCP and remove interface details from the file. Ensure that you do not remove `name`, `state`, and `type` parameters from the file. . Add `state: absent` under the `interfaces.state` section of the NNCP. -. Run `oc apply -f `. After the Kubernetes NMState Operator applies the node network policy to each node in your cluster, the interface that was previously created on each node is now marked _absent_. +. Run `oc apply -f `. After the Kubernetes NMState Operator applies the node network policy to each node in your cluster, any interface that exists on each node is now marked as _absent_. . Run `oc delete nncp` to delete the NNCP. diff --git a/modules/virt-creating-interface-on-nodes.adoc b/modules/virt-creating-interface-on-nodes.adoc index 12b58c001034..94bd242dc0b3 100644 --- a/modules/virt-creating-interface-on-nodes.adoc +++ b/modules/virt-creating-interface-on-nodes.adoc @@ -6,11 +6,16 @@ [id="virt-creating-interface-on-nodes_{context}"] = Creating an interface on nodes -Create an interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster. The manifest details the requested configuration for the interface. +Create an interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` (NNCP) manifest to the cluster. The manifest details the requested configuration for the interface. By default, the manifest applies to all nodes in the cluster. To add the interface to specific nodes, add the `spec: nodeSelector` parameter and the appropriate `:` for your node selector. -You can configure multiple nmstate-enabled nodes concurrently. The configuration applies to 50% of the nodes in parallel. This strategy prevents the entire cluster from being unavailable if the network connection fails. To apply the policy configuration in parallel to a specific portion of the cluster, use the `maxUnavailable` field. +You can configure multiple nmstate-enabled nodes concurrently. The configuration applies to 50% of the nodes in parallel. This strategy prevents the entire cluster from being unavailable if the network connection fails. To apply the policy configuration in parallel to a specific portion of the cluster, use the `maxUnavailable` parameter in the `NodeNetworkConfigurationPolicy` manifest configuration file. + +[NOTE] +==== +If you have two nodes and you apply an NNCP manifest with the `maxUnavailable` parameter set to `50%` to these nodes, one node at a time receives the NNCP configuration. If you then introduce an additional NNCP manifest file with the `maxUnavailable` parameter set to `50%`, this NCCP is independent of the initial NNCP; this means that if both NNCP manifests apply a bad configuration to nodes, you can no longer guarantee that half of your cluster is functional. +==== .Procedure diff --git a/modules/virt-example-nmstate-IP-management.adoc b/modules/virt-example-nmstate-IP-management.adoc index 90a521dee3ea..deaad6a49f05 100644 --- a/modules/virt-example-nmstate-IP-management.adoc +++ b/modules/virt-example-nmstate-IP-management.adoc @@ -106,13 +106,6 @@ Setting a DNS configuration is comparable to modifying the `/etc/resolv.conf` fi To define a DNS configuration for a network interface, you must initially specify the `dns-resolver` section in the network interface's YAML configuration file. To apply an NNCP configuration to your network interface, you need to run the `oc apply -f ` command. -[IMPORTANT] -==== -You cannot use the `br-ex` bridge, an OVN-Kubernetes-managed Open vSwitch bridge, as the interface when configuring DNS resolvers unless you manually configured a customized `br-ex` bridge. - -For more information, see "Creating a manifest object that includes a customized br-ex bridge" in the _Deploying installer-provisioned clusters on bare metal_ document or the _Installing a user-provisioned cluster on bare metal_ document. -==== - The following example shows a default situation that stores DNS values globally: * Configure a static DNS without a network interface. Note that when updating the `/etc/resolv.conf` file on a host node, you do not need to specify an interface, IPv4 or IPv6, in the `NodeNetworkConfigurationPolicy` (NNCP) manifest. diff --git a/modules/virt-nmstate-example-policy-configurations.adoc b/modules/virt-nmstate-example-policy-configurations.adoc index 8556d8bbcf73..d3ad3619bbfa 100644 --- a/modules/virt-nmstate-example-policy-configurations.adoc +++ b/modules/virt-nmstate-example-policy-configurations.adoc @@ -8,10 +8,12 @@ Before you read the different example `NodeNetworkConfigurationPolicy` (NNCP) manifest configurations, consider the following factors when you apply a policy to nodes so that your cluster runs under its best performance conditions: -* When you need to apply a policy to more than one node, create a `NodeNetworkConfigurationPolicy` manifest for each target node. The Kubernetes NMState Operator applies the policy to each node with a defined NNCP in an unspecified order. Scoping a policy with this approach reduces the length of time for policy application but risks a cluster-wide outage if an error exists in the cluster's configuration. To avoid this type of error, initially apply an NNCP to some nodes, confirm the NNCP is configured correctly for these nodes, and then proceed with applying the policy to the remaining nodes. +* When you need to apply a policy to more than one node, create a `NodeNetworkConfigurationPolicy` manifest for each target node. The Kubernetes NMState Operator applies the policy to each node with a defined NNCP in an unspecified order. Scoping a policy with this approach reduces the length of time for policy application but risks a cluster-wide outage if an error exists in the configuration of the cluster. To avoid this type of error, initially apply an NNCP to some nodes, confirm the NNCP is configured correctly for these nodes, and then proceed with applying the policy to the remaining nodes. * When you need to apply a policy to many nodes but you only want to create a single NNCP for all the nodes, the Kubernetes NMState Operator applies the policy to each node in sequence. You can set the speed and coverage of policy application for target nodes with the `maxUnavailable` parameter in the cluster's configuration file. By setting a lower percentage value for the parameter, you can reduce the risk of a cluster-wide outage if the outage impacts the small percentage of nodes that are receiving the policy application. -* Consider specifying all related network configurations in a single policy. +* If you set the `maxUnavailable` parameter to `50%` in two NNCP manifests, the policy configuration coverage applies to 100% of the nodes in your cluster. * When a node restarts, the Kubernetes NMState Operator cannot control the order to which it applies policies to nodes. The Kubernetes NMState Operator might apply interdependent policies in a sequence that results in a degraded network object. + +* Consider specifying all related network configurations in a single policy. diff --git a/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc b/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc index 4182292ad58b..59a807aad28f 100644 --- a/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc +++ b/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc @@ -7,7 +7,9 @@ include::_attributes/common-attributes.adoc[] toc::[] +For more information about how to install the NMState Operator, see xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator#k8s-nmstate-about-the-k8s-nmstate-operator[Kubernetes NMState Operator]. +// Viewing the network state of a node by using the CLI include::modules/virt-viewing-network-state-of-node.adoc[leveloffset=+1] // The `NodeNetworkConfigurationPolicy` manifest file @@ -50,6 +52,7 @@ include::modules/virt-removing-interface-from-nodes.adoc[leveloffset=+1] // Example policy configurations for different interfaces include::modules/virt-nmstate-example-policy-configurations.adoc[leveloffset=+1] +// Example: Linux bridge interface node network configuration policy include::modules/virt-example-bridge-nncp.adoc[leveloffset=+2] include::modules/virt-example-vlan-nncp.adoc[leveloffset=+2]