diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 9a3edd6a4b43..baa5ca324a59 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/modules/network-observability-automatic-installation-overview.adoc b/modules/network-observability-automatic-installation-overview.adoc new file mode 100644 index 000000000000..6ccc671589f9 --- /dev/null +++ b/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 +//// diff --git a/modules/network-observability-automatic-installation-process.adoc b/modules/network-observability-automatic-installation-process.adoc new file mode 100644 index 000000000000..96029243d6fb --- /dev/null +++ b/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. +==== diff --git a/modules/network-observability-automatic-installation-upgrades.adoc b/modules/network-observability-automatic-installation-upgrades.adoc new file mode 100644 index 000000000000..99a9512cb4e3 --- /dev/null +++ b/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". \ No newline at end of file diff --git a/modules/network-observability-automatic-installation-verification.adoc b/modules/network-observability-automatic-installation-verification.adoc new file mode 100644 index 000000000000..fb0f0f07600d --- /dev/null +++ b/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*. diff --git a/modules/network-observability-prevent-automatic-installation-during-upgrade.adoc b/modules/network-observability-prevent-automatic-installation-during-upgrade.adoc new file mode 100644 index 000000000000..02a39e131230 --- /dev/null +++ b/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. diff --git a/modules/network-observability-prevent-automatic-installation.adoc b/modules/network-observability-prevent-automatic-installation.adoc new file mode 100644 index 000000000000..51d01df64124 --- /dev/null +++ b/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 +---- diff --git a/modules/nw-operator-cr.adoc b/modules/nw-operator-cr.adoc index 96d6143669bc..d8f9858cb96f 100644 --- a/modules/nw-operator-cr.adoc +++ b/modules/nw-operator-cr.adoc @@ -127,6 +127,27 @@ spec: - FRR ---- +|`spec.networkObservability` +|`object` +|Optional: Configures the Network Observability Operator installation during cluster creation. + +ifndef::operator[] +You can configure this field in the `install-config.yaml` file before creating the cluster to control whether network observability is enabled by default. + +[NOTE] +==== +Network observability Day 0 configuration is a Technology Preview feature. You must enable the `NetworkObservabilityInstall` feature gate before you can use the `networkObservability` field. For more information, see _Enabling the network observability feature gate_. +==== +endif::operator[] +ifdef::operator[] +This value is inherited from the `install-config.yaml` file during cluster installation and cannot be changed after installation. + +[NOTE] +==== +This field is only available when the `NetworkObservabilityInstall` feature gate is enabled. This is a Technology Preview feature. +==== +endif::operator[] + |==== [IMPORTANT] @@ -398,6 +419,49 @@ a|Specifies the behavior of the IPsec implementation. Must be one of the followi |==== +[id="nw-operator-cr-networkobservability_{context}"] +.`networkObservability` object +[cols=".^3,.^2,.^5a",options="header"] +|==== +|Field|Type|Description + +|`installationPolicy` +|`string` +|Controls whether the Network Observability Operator is installed during cluster creation. Valid values are: + +-- +- `InstallAndEnable`: Install the Network Observability Operator and create a default FlowCollector configuration during cluster creation. +- `DoNotInstall`: Do not install the Network Observability Operator during cluster creation. +-- + +The default value is `InstallAndEnable` for standard multi-node clusters and Hosted Control Plane clusters. {sno} clusters default to `DoNotInstall` due to resource constraints. + +ifndef::operator[] +[source,yaml] +---- +apiVersion: operator.openshift.io/v1 +kind: Network +metadata: + name: cluster +spec: + networkObservability: + installationPolicy: InstallAndEnable +---- + +[NOTE] +==== +This field is only available when the `NetworkObservabilityInstall` feature gate is enabled. This is a Technology Preview feature. +==== +endif::operator[] +ifdef::operator[] +[NOTE] +==== +This field is inherited from the `install-config.yaml` file during cluster installation and is only available when the `NetworkObservabilityInstall` feature gate is enabled. This is a Technology Preview feature. +==== +endif::operator[] + +|==== + ifdef::operator[] [NOTE] ==== diff --git a/observability/network_observability/network-observability-automatic-installation.adoc b/observability/network_observability/network-observability-automatic-installation.adoc new file mode 100644 index 000000000000..67a55f920e83 --- /dev/null +++ b/observability/network_observability/network-observability-automatic-installation.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: ASSEMBLY +[id="network-observability-automatic-installation"] += Install network observability during cluster creation +include::_attributes/common-attributes.adoc[] +:context: network-observability-automatic-installation + +toc::[] + +[role="_abstract"] +Monitor network traffic immediately after cluster creation by automatically installing network observability during the installation process. This Technology Preview feature requires enabling the `NetworkObservabilityInstall` feature gate. + +:FeatureName: Network observability automatic installation +include::snippets/technology-preview.adoc[] +:!FeatureName: + +include::modules/network-observability-automatic-installation-overview.adoc[leveloffset=+1] + +include::modules/network-observability-automatic-installation-process.adoc[leveloffset=+1] + +include::modules/network-observability-prevent-automatic-installation.adoc[leveloffset=+1] + +include::modules/network-observability-automatic-installation-verification.adoc[leveloffset=+1] + +include::modules/network-observability-automatic-installation-upgrades.adoc[leveloffset=+1] + +include::modules/network-observability-prevent-automatic-installation-during-upgrade.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_network-observability-automatic-installation_{context}"] +== Additional resources + +* xref:../network_observability/installing-operators.adoc#installing-network-observability-operators[Installing the Network Observability Operator] +* xref:../network_observability/configuring-operator.adoc#network-observability-flowcollector-view_network_observability[Configuring the FlowCollector custom resource] +* xref:../../networking/networking_operators/cluster-network-operator.adoc#cluster-network-operator[Cluster Network Operator] +* xref:../network_observability/installing-operators.adoc#network-observability-operator-uninstall_network_observability[Uninstalling Network Observability Operator]