OSDOCS-19153 [NETOBSERV] 1.12 Technology Preview Network Observability Operator Day 0

_topic_maps/_topic_map.yml

@@ -3329,6 +3329,8 @@ Topics:
       File: network-observability-operator-release-notes-archive
   - Name: Network observability overview
     File: network-observability-overview
+  - Name: Network Observability Operator automatic installation
+    File: network-observability-automatic-installation
   - Name: Installing the Network Observability Operator
     File: installing-operators
   - Name: Scaling network flow collection with Kafka

modules/network-observability-automatic-installation-overview.adoc

@@ -0,0 +1,96 @@
+// Module included in the following assemblies:
+//
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="network-observability-automatic-installation-overview_{context}"]
+= Understand automatic network observability installation
+
+[role="_abstract"]
+Technology Preview clusters with the `NetworkObservabilityInstall` feature gate enabled automatically install the Network Observability Operator during cluster creation.
+
+[IMPORTANT]
+====
+This Technology Preview feature is intended for testing and development environments with {product-title} 4.22. The feature gate requirement is temporary until this feature reaches General Availability (GA).
+
+Clusters created with the Technology Preview feature gate cannot be upgraded when the feature becomes GA. You must create a new cluster to use the GA version.
+
+For production deployments, Red Hat recommends using the standard postinstallation method to install the Network Observability Operator.
+====
+
+On {product-title} 4.22 clusters with the `NetworkObservabilityInstall` feature gate enabled, the Network Observability Operator and its dependencies are automatically installed and configured during cluster creation. This provides immediate access to network traffic monitoring capabilities through the {product-title} web console.
+
+Network observability helps you:
+
+* Monitor network traffic flows between pods, services, and external endpoints.
+* Identify network performance issues such as packet loss and latency.
+* Troubleshoot connectivity problems between applications.
+* Analyze network usage patterns for capacity planning.
+* Detect security anomalies in network behavior.
+
+
+[id="prerequisites-for-network-observability-automatic-installation_{context}"]
+== Prerequisites for automatic network observability installation (Technology Preview)
+
+Network Observability automatic installation is a Technology Preview feature that requires the `NetworkObservabilityInstall` feature gate. To use this feature during cluster installation, you must:
+
+* Enable the `NetworkObservabilityInstall` feature gate by creating a manifest file during cluster installation.
+* Accept that enabling the `CustomNoUpgrade` feature set prevents minor version updates.
+* Understand that clusters installed with this Technology Preview feature cannot be upgraded when the feature reaches general availability (GA). You must create a new cluster using the GA version.
+
+[id="when-network-observability-is-enabled_{context}"]
+== When network observability is enabled
+
+When the `NetworkObservabilityInstall` feature gate is enabled, the following cluster types enable network observability by default during cluster installation:
+
+* Standard multi-node clusters
+* Hosted Control Plane clusters
+
+The following cluster types do not enable network observability by default:
+
+* {sno-caps} clusters, due to resource constraints.
+* Clusters where you disabled network observability in the installation configuration.
+
+[id="accessing-network-observability-features_{context}"]
+== Accessing network observability features
+
+After cluster installation completes, you can access network observability features immediately without additional configuration:
+
+Network traffic overview:: View cluster-wide network traffic metrics and identify top talkers from *Observe* -> *Network Traffic* in the web console.
+
+Network topology visualization:: Explore visual representations of network traffic flows between namespaces, workloads, and nodes.
+
+Metrics and dashboards:: Access Prometheus metrics and Grafana dashboards that track network performance indicators including throughput, packet drops, and connection counts.
+
+[id="resource-impact_{context}"]
+== Resource impact
+
+The default network observability configuration balances monitoring capabilities with cluster resource usage. On typical clusters, network observability consumes approximately 3-5% of CPU and memory resources per node.
+
+If you need to reduce resource consumption, you can customize the `FlowCollector` resource configuration to adjust sampling rates, filter traffic, or disable specific features.
+
+[id="deployment-lifecycle_{context}"]
+== Deployment lifecycle
+
+The automatic network observability installation occurs during cluster creation and upgrade. The Cluster Network Operator (CNO) installs the Network Observability Operator and creates a default `FlowCollector` custom resource (CR), then sets the `NetworkObservabilityDeployed` condition in the Network CR status.
+
+After successful deployment with the default policy, the CNO does not monitor or manage the Network Observability Operator. If you delete the Network Observability Operator or the `FlowCollector` resource, they are not automatically reinstalled.
+
+If you set `installationPolicy` to `InstallAndEnable` in your `install-config.yaml` file, the CNO continues to monitor the installation and reinstalls the Network Observability Operator if you remove it. The CNO does not manage the `FlowCollector` resource because it is managed by the Network Observability Operator.
+
+To remove network observability, see "Uninstalling Network Observability Operator".
+
+[NOTE]
+====
+To prevent automatic installation during an upgrade to {product-title} 4.22 or later, set `installationPolicy` to `NoAction` in the Network CR before upgrading.
+====
+
+////
+This content might be better suited for GA
+[id="next-steps_{context}"]
+== Next steps
+* Configure flow collection settings to focus on specific namespaces or traffic types
+* Set up alerts for network anomalies and performance degradation
+* Export flow data to external systems for long-term analysis
+* Customize dashboards to monitor application-specific network metrics
+////

modules/network-observability-automatic-installation-process.adoc

@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+//
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="network-observability-automatic-installation-process_{context}"]
+= Network observability automatic installation process
+
+[role="_abstract"]
+The cluster installation process automatically deploys network observability capabilities when you run the `openshift-install` program with the `NetworkObservabilityInstall` feature gate enabled. You do not need to add network observability configuration to your `install-config.yaml` file unless you want to override the default behavior.
+
+[id="installation-flow_{context}"]
+== Installation flow
+
+If the `NetworkObservabilityInstall` feature gate is not enabled, automatic network observability installation does not occur during cluster creation.
+
+When the feature gate is enabled, you can choose one of the following outcomes:
+
+Default (enabled on supported cluster types)::
+Standard multi-node and {hcp} clusters enable network observability by default. You do not need to add or change the `networkObservability` section in your `install-config.yaml` file.
++
+With this default configuration:
++
+* The Cluster Network Operator (CNO) automatically installs network observability on standard multi-node clusters and {hcp} clusters.
+* {sno-caps} clusters do not install network observability by default due to resource constraints.
+
+Do not install::
+Add the following configuration to your `install-config.yaml` file to prevent installation on all cluster types:
++
+[source,yaml]
+----
+networking:
+  networkObservability:
+    installationPolicy: NoAction
+----
+
+Always install and enable::
+Add the following configuration to your `install-config.yaml` file to install network observability on all cluster types, including {sno} clusters:
++
+[source,yaml]
+----
+networking:
+  networkObservability:
+    installationPolicy: InstallAndEnable
+----
++
+With this policy, the CNO monitors the installation and reinstalls the Network Observability Operator if you remove it.
+
+During cluster installation, the following sequence occurs:
+
+. You optionally configure the `networking.networkObservability.installationPolicy` field in the `install-config.yaml` file to override the default behavior.
+
+. The `openshift-install` program generates the Network CR using the network observability configuration in the `install-config.yaml` file.
+
+. The Cluster Network Operator (CNO) reads the `installationPolicy` field in the Network custom resource (CR) if it exists. Based on the `installationPolicy` value and your cluster type, the CNO applies the default, `NoAction`, or `InstallAndEnable` outcome.
+
+. If the policy enables installation on your cluster type, the CNO:
+   * Installs the Network Observability Operator
+   * Creates a default `FlowCollector` configuration that starts collecting network flow data
+
+. If the effective policy is `NoAction`, the CNO skips network observability installation.
+
+[NOTE]
+====
+The automatic installation process deploys network observability in the `openshift-network-observability` namespace, which is treated as infrastructure traffic. Standard Operator installation uses the `netobserv` namespace.
+====
+
+[id="configuration-copying_{context}"]
+== Configuration copying
+
+When you override the default behavior, the `install-config.yaml` file contains the network observability configuration. The following example sets `installationPolicy` to `InstallAndEnable`:
+
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: example.com
+networking:
+  networkObservability:
+    installationPolicy: InstallAndEnable
+----
+
+The Network custom resource (CR) copies this configuration during cluster creation:
+
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  networkObservability:
+    installationPolicy: InstallAndEnable
+----
+
+After cluster creation, the CNO sets the `NetworkObservabilityDeployed` condition when the Operator deploys successfully.
+
+If you omit `installationPolicy`, which then installs Network Observability Operator, the CNO will not reinstall the operator if you remove it later.
+
+If you set `installationPolicy` to `InstallAndEnable` in the Network CR (even after initial installation), the CNO monitors the installation and reinstalls the Network Observability Operator if you remove it. The CNO supports only two installation policies: `InstallAndEnable` and `NoAction`. The CNO never removes network observability components.
+
+[NOTE]
+====
+To prevent automatic installation during an upgrade to {product-title} 4.22 or later, set `installationPolicy` to `NoAction` in the Network CR before upgrading.
+====

modules/network-observability-automatic-installation-upgrades.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="network-observability-automatic-installation-upgrades_{context}"]
+= Network observability and cluster upgrades
+
+[role="_abstract"]
+Understand how upgrading to {product-title} 4.22 or later affects automatic network observability installation when the `NetworkObservabilityInstall` feature gate is enabled.
+
+When you upgrade an existing cluster to {product-title} 4.22 or later with the `NetworkObservabilityInstall` feature gate enabled, the CNO evaluates the `installationPolicy` field in the Network custom resource (CR) to determine whether to install network observability.
+
+If the `NetworkObservabilityInstall` feature gate is not enabled, automatic network observability installation does not occur during the upgrade.
+
+[id="upgrade-default-behavior_{context}"]
+== Default upgrade behavior
+
+When the feature gate is enabled and you upgrade to {product-title} 4.22 or later, the following behaviors apply by default:
+
+* If the Network CR does not have the `networkObservability.installationPolicy` field configured, the CNO automatically installs network observability on multi-node and Hosted Control Plane clusters.
+* {sno-caps} clusters do not automatically install network observability due to resource constraints.
+* If network observability is already installed by using the standard Operator installation method, no changes occur. The automatic installation process detects the existing installation and takes no action.
+
+To prevent automatic installation during the upgrade, see "Prevent automatic network observability installation during upgrades".

modules/network-observability-automatic-installation-verification.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="network-observability-automatic-installation-verification_{context}"]
+= Verify automatic network observability installation
+
+[role="_abstract"]
+Verify that the Network Observability Operator and FlowCollector are running after automatic installation during cluster creation.
+
+.Prerequisites
+
+* You created the cluster with the `NetworkObservabilityInstall` feature gate enabled.
+* You have access to the cluster as a user with the `cluster-admin` role.
+* The OpenShift CLI (`oc`) is installed.
+
+[NOTE]
+====
+Automatic installation deploys network observability in the `openshift-network-observability` namespace. Standard Operator installation uses the `netobserv` namespace. Namespaces that begin with `openshift-` are treated as infrastructure traffic.
+====
+
+.Procedure
+
+. Verify that the Network Observability Operator is installed and running by running the following command:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-netobserv-operator
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                                READY   STATUS    RESTARTS   AGE
+netobserv-controller-manager-6d4b8d9f8c-xk7lm      2/2     Running   0          5m
+----
+
+. Verify that the cluster has a `FlowCollector` resource by running the following command:
++
+[source,terminal]
+----
+$ oc get flowcollector cluster -n openshift-network-observability
+----
++
+.Example output
+[source,terminal]
+----
+NAME      AGENT   SAMPLING   DEPLOYMENT MODEL   STATUS
+cluster   eBPF    400        Service            Ready
+----
+
+. Verify that network traffic data is available in the web console by navigating to *Observe* -> *Network Traffic*.

modules/network-observability-prevent-automatic-installation-during-upgrade.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="network-observability-prevent-automatic-installation-during-upgrade_{context}"]
+= Prevent automatic network observability installation during upgrades
+
+[role="_abstract"]
+You can configure the Network custom resource (CR) to prevent the Cluster Network Operator (CNO) from automatically installing network observability during a cluster upgrade.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* The OpenShift CLI (`oc`) is installed.
+* For Technology Preview, the `NetworkObservabilityInstall` feature gate is enabled for automatic installation to occur during the upgrade.
+
+.Procedure
+
+. Before upgrading your cluster, edit the Network CR by running the following command:
++
+[source,terminal]
+----
+$ oc edit network.config.openshift.io cluster
+----
+
+. Add the `NoAction` installation policy to the `spec` section:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  networkObservability:
+    installationPolicy: NoAction
+# ...
+----
+
+. Save and close the file to apply the changes.
+
+. Proceed with the cluster upgrade. The CNO skips the network observability installation during and after the upgrade process.

modules/network-observability-prevent-automatic-installation.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// * observability/network_observability/network-observability-automatic-installation.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="network-observability-prevent-automatic-installation_{context}"]
+= Prevent automatic network observability installation
+
+[role="_abstract"]
+Disable automatic installation of the Network Observability Operator during cluster creation by setting `installationPolicy` to `NoAction` in your `install-config.yaml` file.
+
+By default, {product-title} installs the Network Observability Operator on new clusters when the `NetworkObservabilityInstall` feature gate is enabled. You can disable this behavior by configuring the `install-config.yaml` file before creating the cluster. Disabling network observability prevents the operator installation and reduces the cluster's base resource footprint.
+
+.Prerequisites
+
+* For Technology Preview only, the `NetworkObservabilityInstall` feature gate is enabled.
+* You have access to the `install-config.yaml` file before creating installation manifests.
+
+.Procedure
+
+. Edit the `install-config.yaml` file before creating installation manifests.
+
+. Add the `networkObservability` field to the `networking` section:
++
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: my-cluster
+networking:
+  networkObservability:
+    installationPolicy: NoAction
+# ...
+----
++
+where:
++
+`networking.networkObservability.installationPolicy`:: Controls whether the Network Observability Operator is installed during cluster creation. Set to `NoAction` to prevent installation on all cluster types. Set to `InstallAndEnable` to force installation. Omit this field to use the default behavior: automatic installation on multi-node and Hosted Control Plane clusters, but not on {sno} clusters. Valid values are `InstallAndEnable`, `NoAction`, or omitted (empty string default).
+
+. Configure the `FeatureGate` manifest in your installation directory to include the `NetworkObservabilityInstall` feature gate under the designated feature set.
+
+. Complete the cluster installation using your platform's standard deployment method.
+
+.Verification
+
+. Verify that the Network Observability Operator is not installed by running the following command:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-netobserv-operator
+----
++
+The output should indicate that the namespace does not exist:
++
+.Example output
+[source,terminal]
+----
+Error from server (NotFound): namespaces "openshift-netobserv-operator" not found
+----