OSDOCS-16250 [NETOBSERV] API spec updates 1.10

Author: gwynnemonahan

modules/network-observability-flowcollector-api-specifications.adoc

@@ -118,7 +118,7 @@ Kafka can provide better scalability, resiliency, and high availability (for mor
 
 | `networkPolicy`
 | `object`
-| `networkPolicy` defines ingress network policy settings for Network Observability components isolation.
+| `networkPolicy` defines network policy settings for Network Observability components isolation.
 
 | `processor`
 | `object`
@@ -180,7 +180,7 @@ Type::
 | `object`
 | `advanced` allows setting some aspects of the internal configuration of the eBPF agent.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk. You can also
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk. You can also
 override the default Linux capabilities from there.
 
 | `cacheActiveTimeout`
@@ -258,10 +258,8 @@ Otherwise it is matched as a case-sensitive string.
 
 | `privileged`
 | `boolean`
-| Privileged mode for the eBPF Agent container. When ignored or set to `false`, the operator sets
-granular capabilities (BPF, PERFMON, NET_ADMIN) to the container.
-If for some reason these capabilities cannot be set, such as if an old kernel version not knowing CAP_BPF
-is in use, then you can turn on this mode for more global privileges.
+| Privileged mode for the eBPF Agent container. When set to `true`, the agent is able to capture more traffic, including from secondary interfaces.
+When ignored or set to `false`, the operator sets granular capabilities (BPF, PERFMON, NET_ADMIN) to the container.
 Some agent features require the privileged mode, such as packet drops tracking (see `features`) and SR-IOV support.
 
 | `resources`
@@ -271,7 +269,7 @@ For more information, see https://kubernetes.io/docs/concepts/configuration/mana
 
 | `sampling`
 | `integer`
-| Sampling ratio of the eBPF probe. 100 means one packet on 100 is sent. 0 or 1 means all packets are sampled.
+| Sampling interval of the eBPF probe. 100 means one packet on 100 is sent. 0 or 1 means all packets are sampled.
 
 |===
 == .spec.agent.ebpf.advanced
@@ -280,7 +278,7 @@ Description::
 --
 `advanced` allows setting some aspects of the internal configuration of the eBPF agent.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk. You can also
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk. You can also
 override the default Linux capabilities from there.
 --
 
@@ -456,7 +454,7 @@ To change the default, you can define a rule that accepts everything: `{ action:
 
 | `sampling`
 | `integer`
-| `sampling` is the sampling ratio for the matched packets, overriding the global sampling defined at `spec.agent.ebpf.sampling`.
+| `sampling` is the sampling interval for the matched packets, overriding the global sampling defined at `spec.agent.ebpf.sampling`.
 
 | `sourcePorts`
 | `integer-or-string`
@@ -558,7 +556,7 @@ To filter two ports, use a "port1,port2" in string format. For example, `ports:
 
 | `sampling`
 | `integer`
-| `sampling` is the sampling ratio for the matched packets, overriding the global sampling defined at `spec.agent.ebpf.sampling`.
+| `sampling` is the sampling interval for the matched packets, overriding the global sampling defined at `spec.agent.ebpf.sampling`.
 
 | `sourcePorts`
 | `integer-or-string`
@@ -800,7 +798,7 @@ Type::
 | `object`
 | `advanced` allows setting some aspects of the internal configuration of the console plugin.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk.
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk.
 
 | `autoscaler`
 | `object`
@@ -842,7 +840,7 @@ Description::
 --
 `advanced` allows setting some aspects of the internal configuration of the console plugin.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk.
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk.
 --
 
 Type::
@@ -2014,6 +2012,10 @@ Type::
 |===
 | Property | Type | Description
 
+| `excludeLabels`
+| `array (string)`
+| `excludeLabels` is a list of fields to be excluded from the list of Loki labels. [Unsupported (*)].
+
 | `staticLabels`
 | `object (string)`
 | `staticLabels` is a map of common labels to set on each flow in Loki storage.
@@ -2649,7 +2651,7 @@ If the namespace is different, the config map or the secret is copied so that it
 Description::
 +
 --
-`networkPolicy` defines ingress network policy settings for Network Observability components isolation.
+`networkPolicy` defines network policy settings for Network Observability components isolation.
 --
 
 Type::
@@ -2672,7 +2674,7 @@ configuration, you can disable it and install your own instead.
 | `boolean`
 | Set `enable` to `true` to deploy network policies on the namespaces used by Network Observability (main and privileged). It is disabled by default.
 These network policies better isolate the Network Observability components to prevent undesired connections to them.
-To increase the security of connections, enable this option or create your own network policy.
+This option is enabled by default, disable it to manually manage network policies
 
 |===
 == .spec.processor
@@ -2702,7 +2704,7 @@ This feature requires the "topology.kubernetes.io/zone" label to be set on nodes
 | `object`
 | `advanced` allows setting some aspects of the internal configuration of the flow processor.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk.
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk.
 
 | `clusterName`
 | `string`
@@ -2782,7 +2784,7 @@ Description::
 --
 `advanced` allows setting some aspects of the internal configuration of the flow processor.
 This section is aimed mostly for debugging and fine-grained performance optimizations,
-such as `GOGC` and `GOMAXPROCS` environment vars. Set these values at your own risk.
+such as `GOGC` and `GOMAXPROCS` environment variables. Set these values at your own risk.
 --
 
 Type::
@@ -2988,7 +2990,7 @@ Type::
 
 | `sampling`
 | `integer`
-| `sampling` is the sampling ratio when deduper `mode` is `Sample`. For example, a value of `50` means that 1 flow in 50 is sampled.
+| `sampling` is the sampling interval when deduper `mode` is `Sample`. For example, a value of `50` means that 1 flow in 50 is sampled.
 
 |===
 == .spec.processor.filters
@@ -3033,7 +3035,7 @@ Type::
 
 | `sampling`
 | `integer`
-| `sampling` is an optional sampling ratio to apply to this filter. For example, a value of `50` means that 1 matching flow in 50 is sampled.
+| `sampling` is an optional sampling interval to apply to this filter. For example, a value of `50` means that 1 matching flow in 50 is sampled.
 
 |===
 == .spec.processor.kafkaConsumerAutoscaler
@@ -3067,15 +3069,18 @@ Type::
 |===
 | Property | Type | Description
 
+| `alerts`
+| `array`
+| `alerts` is a list of alerts to be created for Prometheus AlertManager, organized by templates and variants [Unsupported (*)].
+This is currently an experimental feature behind a feature gate. To enable, edit `spec.processor.advanced.env` by adding `EXPERIMENTAL_ALERTS_HEALTH` set to `true`.
+More information on alerts: https://github.com/netobserv/network-observability-operator/blob/main/docs/Alerts.md
+
 | `disableAlerts`
 | `array (string)`
-| `disableAlerts` is a list of alerts that should be disabled.
-Possible values are: +
-
-`NetObservNoFlows`, which is triggered when no flows are being observed for a certain period. +
-
-`NetObservLokiError`, which is triggered when flows are being dropped due to Loki errors. +
-
+| `disableAlerts` is a list of alert groups that should be disabled from the default set of alerts.
+Possible values are: `NetObservNoFlows`, `NetObservLokiError`, `PacketDropsByKernel`, `PacketDropsByDevice`, `IPsecErrors`, `NetpolDenied`,
+`LatencyHighTrend`, `DNSErrors`, `ExternalEgressHighTrend`, `ExternalIngressHighTrend`, `CrossAZ`.
+More information on alerts: https://github.com/netobserv/network-observability-operator/blob/main/docs/Alerts.md
 
 | `includeList`
 | `array (string)`
@@ -3094,6 +3099,140 @@ More information, with full list of available metrics: https://github.com/netobs
 | `object`
 | Metrics server endpoint configuration for Prometheus scraper
 
+|===
+== .spec.processor.metrics.alerts
+Description::
++
+--
+`alerts` is a list of alerts to be created for Prometheus AlertManager, organized by templates and variants [Unsupported (*)].
+This is currently an experimental feature behind a feature gate. To enable, edit `spec.processor.advanced.env` by adding `EXPERIMENTAL_ALERTS_HEALTH` set to `true`.
+More information on alerts: https://github.com/netobserv/network-observability-operator/blob/main/docs/Alerts.md
+--
+
+Type::
+  `array`
+
+
+
+
+== .spec.processor.metrics.alerts[]
+Description::
++
+--
+
+--
+
+Type::
+  `object`
+
+Required::
+  - `template`
+  - `variants`
+
+
+
+[cols="1,1,1",options="header"]
+|===
+| Property | Type | Description
+
+| `template`
+| `string`
+| Alert template name.
+Possible values are: `PacketDropsByKernel`, `PacketDropsByDevice`, `IPsecErrors`, `NetpolDenied`,
+`LatencyHighTrend`, `DNSErrors`, `ExternalEgressHighTrend`, `ExternalIngressHighTrend`, `CrossAZ`.
+More information on alerts: https://github.com/netobserv/network-observability-operator/blob/main/docs/Alerts.md
+
+| `variants`
+| `array`
+| A list of variants for this template
+
+|===
+== .spec.processor.metrics.alerts[].variants
+Description::
++
+--
+A list of variants for this template
+--
+
+Type::
+  `array`
+
+
+
+
+== .spec.processor.metrics.alerts[].variants[]
+Description::
++
+--
+
+--
+
+Type::
+  `object`
+
+Required::
+  - `thresholds`
+
+
+
+[cols="1,1,1",options="header"]
+|===
+| Property | Type | Description
+
+| `groupBy`
+| `string`
+| Optional grouping criteria, possible values are: `Node`, `Namespace`, `Workload`.
+
+| `lowVolumeThreshold`
+| `string`
+| The low volume threshold allows to ignore metrics with a too low volume of traffic, in order to improve signal-to-noise.
+It is provided as an absolute rate (bytes per second or packets per second, depending on the context).
+When provided, it must be parsable as a float.
+
+| `thresholds`
+| `object`
+| Thresholds of the alert per severity.
+They are expressed as a percentage of errors above which the alert is triggered. They must be parsable as floats.
+
+| `trendDuration`
+| `string`
+| For trending alerts, the duration interval for baseline comparison. For example, "2h" means comparing against a 2-hours average. Defaults to 2h.
+
+| `trendOffset`
+| `string`
+| For trending alerts, the time offset for baseline comparison. For example, "1d" means comparing against yesterday. Defaults to 1d.
+
+|===
+== .spec.processor.metrics.alerts[].variants[].thresholds
+Description::
++
+--
+Thresholds of the alert per severity.
+They are expressed as a percentage of errors above which the alert is triggered. They must be parsable as floats.
+--
+
+Type::
+  `object`
+
+
+
+
+[cols="1,1,1",options="header"]
+|===
+| Property | Type | Description
+
+| `critical`
+| `string`
+| Threshold for severity `critical`. Leave empty to not generate a Critical alert.
+
+| `info`
+| `string`
+| Threshold for severity `info`. Leave empty to not generate an Info alert.
+
+| `warning`
+| `string`
+| Threshold for severity `warning`. Leave empty to not generate a Warning alert.
+
 |===
 == .spec.processor.metrics.server
 Description::

modules/network-observability-flowmetric-api-specifications.adoc

@@ -74,7 +74,6 @@ Type::
   `object`
 
 Required::
-  - `metricName`
   - `type`
 
 
@@ -104,7 +103,7 @@ When set to `Egress`, it is equivalent to adding the regular expression filter o
 | `filters`
 | `array`
 | `filters` is a list of fields and values used to restrict which flows are taken into account.
-Refer to the documentation for the list of available fields: https://docs.openshift.com/container-platform/latest/observability/network_observability/json-flows-format-reference.html.
+Refer to the documentation for the list of available fields: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/json-flows-format-reference.
 
 | `flatten`
 | `array (string)`
@@ -113,16 +112,16 @@ For instance, when flattening `Interfaces` on a bytes counter, a flow having Int
 
 | `labels`
 | `array (string)`
-| `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions.
+| `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions (for example: `SrcK8S_Namespace`).
 From choosing labels results the level of granularity of this metric, and the available aggregations at query time.
 It must be done carefully as it impacts the metric cardinality (cf https://rhobs-handbook.netlify.app/products/openshiftmonitoring/telemetry.md/#what-is-the-cardinality-of-a-metric).
 In general, avoid setting very high cardinality labels such as IP or MAC addresses.
 "SrcK8S_OwnerName" or "DstK8S_OwnerName" should be preferred over "SrcK8S_Name" or "DstK8S_Name" as much as possible.
-Refer to the documentation for the list of available fields: https://docs.openshift.com/container-platform/latest/observability/network_observability/json-flows-format-reference.html.
+Refer to the documentation for the list of available fields: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/json-flows-format-reference.
 
 | `metricName`
 | `string`
-| Name of the metric. In Prometheus, it is automatically prefixed with "netobserv_".
+| Name of the metric. In Prometheus, it is automatically prefixed with "netobserv_". Leave empty to generate the name based on the `FlowMetric` resource name.
 
 | `remap`
 | `object (string)`
@@ -137,9 +136,9 @@ Use "Gauge" for other values that don't necessitate accuracy over time (gauges a
 
 | `valueField`
 | `string`
-| `valueField` is the flow field that must be used as a value for this metric. This field must hold numeric values.
+| `valueField` is the flow field that must be used as a value for this metric (for example: `Bytes`). This field must hold numeric values.
 Leave empty to count flows rather than a specific value per flow.
-Refer to the documentation for the list of available fields: https://docs.openshift.com/container-platform/latest/observability/network_observability/json-flows-format-reference.html.
+Refer to the documentation for the list of available fields: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/json-flows-format-reference.
 
 |===
 == .spec.charts
@@ -262,7 +261,7 @@ Description::
 +
 --
 `filters` is a list of fields and values used to restrict which flows are taken into account.
-Refer to the documentation for the list of available fields: https://docs.openshift.com/container-platform/latest/observability/network_observability/json-flows-format-reference.html.
+Refer to the documentation for the list of available fields: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/json-flows-format-reference.
 --
 
 Type::
@@ -293,7 +292,7 @@ Required::
 
 | `field`
 | `string`
-| Name of the field to filter on
+| Name of the field to filter on (for example: `SrcK8S_Namespace`).
 
 | `matchType`
 | `string`
@@ -303,4 +302,4 @@ Required::
 | `string`
 | Value to filter on. When `matchType` is `Equal` or `NotEqual`, you can use field injection with `$(SomeField)` to refer to any other field of the flow.
 
-|===
+|===