diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index ad441ca0e7..2d43005930 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2912,9 +2912,22 @@ Topics: File: metrics-alerts-dashboards - Name: Monitoring the Network Observability Operator File: network-observability-operator-monitoring - - Name: API reference + - Name: Scheduling resources + File: network-observability-scheduling-resources + - Name: Network Observability CLI + Dir: netobserv_cli + Topics: + - Name: Installing the Network Observability CLI + File: netobserv-cli-install + - Name: Using the Network Observability CLI + File: netobserv-cli-using + - Name: Network Observability CLI reference + File: netobserv-cli-reference + - Name: FlowCollector API reference File: flowcollector-api - - Name: JSON flows format reference + - Name: FlowMetric API reference + File: flowmetric-api + - Name: Flows format reference File: json-flows-format-reference - Name: Troubleshooting Network Observability File: troubleshooting-network-observability diff --git a/modules/network-observability-RTT-overview.adoc b/modules/network-observability-RTT-overview.adoc index 6c42599c31..8810843517 100644 --- a/modules/network-observability-RTT-overview.adoc +++ b/modules/network-observability-RTT-overview.adoc @@ -5,24 +5,24 @@ :_mod-docs-content-type: CONCEPT [id="network-observability-RTT-overview_{context}"] = Round-Trip Time -You can use TCP handshake Round-Trip Time (RTT) to analyze network flows. You can use RTT captured from the `fentry/tcp_rcv_established` eBPF hookpoint to read SRTT from the TCP socket to help with the following: +You can use TCP smoothed Round-Trip Time (sRTT) to analyze network flow latencies. You can use RTT captured from the `fentry/tcp_rcv_established` eBPF hookpoint to read sRTT from the TCP socket to help with the following: -* Network Monitoring: Gain insights into TCP handshakes, helping +* Network Monitoring: Gain insights into TCP latencies, helping network administrators identify unusual patterns, potential bottlenecks, or performance issues. * Troubleshooting: Debug TCP-related issues by tracking latency and identifying misconfigurations. -By default, when RTT is enabled, you can see the following TCP handshake RTT metrics represented in the *Overview*: +By default, when RTT is enabled, you can see the following TCP RTT metrics represented in the *Overview*: -* Top X 90th percentile TCP handshake Round Trip Time with overall -* Top X average TCP handshake Round Trip Time with overall -* Bottom X minimum TCP handshake Round Trip Time with overall +* Top X 90th percentile TCP Round Trip Time with overall +* Top X average TCP Round Trip Time with overall +* Bottom X minimum TCP Round Trip Time with overall Other RTT panels can be added in *Manage panels*: -* Top X maximum TCP handshake Round Trip Time with overall -* Top X 99th percentile TCP handshake Round Trip Time with overall +* Top X maximum TCP Round Trip Time with overall +* Top X 99th percentile TCP Round Trip Time with overall See the _Additional Resources_ in this section for more information about enabling and working with this view. \ No newline at end of file diff --git a/modules/network-observability-RTT.adoc b/modules/network-observability-RTT.adoc index f56205ba0e..a7d1c98bda 100644 --- a/modules/network-observability-RTT.adoc +++ b/modules/network-observability-RTT.adoc @@ -23,7 +23,6 @@ metadata: name: cluster spec: namespace: netobserv - deploymentModel: Direct agent: type: eBPF ebpf: diff --git a/modules/network-observability-cli-capturing-flows.adoc b/modules/network-observability-cli-capturing-flows.adoc new file mode 100644 index 0000000000..6f101c6106 --- /dev/null +++ b/modules/network-observability-cli-capturing-flows.adoc @@ -0,0 +1,88 @@ +//Module included in the following assemblies: +// +// observability/network_observability/netobserv_cli/netobserv-cli-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-cli-capturing-flows_{context}"] += Capturing flows + +You can capture flows and filter on any resource or zone in the data to solve use cases, such as displaying Round-Trip Time (RTT) between two zones. Table visualization in the CLI provides viewing and flow search capabilities. + +.Prerequisites +* Install the {oc-first}. +* Install the Network Observability CLI (`oc netobserv`) plugin. + +.Procedure +. Capture flows with filters enabled by running the following command: ++ +[source,terminal] +---- +$ oc netobserv flows --enable_filter=true --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051 +---- +. Add filters to the `live table filter` prompt in the terminal to further refine the incoming flows. For example: ++ +[source,terminal] +---- +live table filter: [SrcK8S_Zone:us-west-1b] press enter to match multiple regular expressions at once +---- +. To stop capturing, press kbd:[Ctrl+C]. The data that was captured is written to two separate files in an `./output` directory located in the same path used to install the CLI. +. View the captured data in the `./output/flow/.json` JSON file, which contains JSON arrays of the captured data. ++ +.Example JSON file +[source,json] +---- +{ + "AgentIP": "10.0.1.76", + "Bytes": 561, + "DnsErrno": 0, + "Dscp": 20, + "DstAddr": "f904:ece9:ba63:6ac7:8018:1e5:7130:0", + "DstMac": "0A:58:0A:80:00:37", + "DstPort": 9999, + "Duplicate": false, + "Etype": 2048, + "Flags": 16, + "FlowDirection": 0, + "IfDirection": 0, + "Interface": "ens5", + "K8S_FlowLayer": "infra", + "Packets": 1, + "Proto": 6, + "SrcAddr": "3e06:6c10:6440:2:a80:37:b756:270f", + "SrcMac": "0A:58:0A:80:00:01", + "SrcPort": 46934, + "TimeFlowEndMs": 1709741962111, + "TimeFlowRttNs": 121000, + "TimeFlowStartMs": 1709741962111, + "TimeReceived": 1709741964 +} +---- +. You can use SQLite to inspect the `./output/flow/.db` database file. For example: +.. Open the file by running the following command: ++ +[source,terminal] +---- +$ sqlite3 ./output/flow/.db +---- + +.. Query the data by running a SQLite `SELECT` statement, for example: ++ +[source,terminal] +---- +sqlite> SELECT DnsLatencyMs, DnsFlagsResponseCode, DnsId, DstAddr, DstPort, Interface, Proto, SrcAddr, SrcPort, Bytes, Packets FROM flow WHERE DnsLatencyMs >10 LIMIT 10; +---- ++ +.Example output +[source,terminal] +---- +12|NoError|58747|10.128.0.63|57856||17|172.30.0.10|53|284|1 +11|NoError|20486|10.128.0.52|56575||17|169.254.169.254|53|225|1 +11|NoError|59544|10.128.0.103|51089||17|172.30.0.10|53|307|1 +13|NoError|32519|10.128.0.52|55241||17|169.254.169.254|53|254|1 +12|NoError|32519|10.0.0.3|55241||17|169.254.169.254|53|254|1 +15|NoError|57673|10.128.0.19|59051||17|172.30.0.10|53|313|1 +13|NoError|35652|10.0.0.3|46532||17|169.254.169.254|53|183|1 +32|NoError|37326|10.0.0.3|52718||17|169.254.169.254|53|169|1 +14|NoError|14530|10.0.0.3|58203||17|169.254.169.254|53|246|1 +15|NoError|40548|10.0.0.3|45933||17|169.254.169.254|53|174|1 +---- diff --git a/modules/network-observability-cli-capturing-packets.adoc b/modules/network-observability-cli-capturing-packets.adoc new file mode 100644 index 0000000000..748c964172 --- /dev/null +++ b/modules/network-observability-cli-capturing-packets.adoc @@ -0,0 +1,29 @@ +//Module included in the following assemblies: +// +// observability/network_observability/netobserv_cli/netobserv-cli-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-cli-capturing-packets_{context}"] += Capturing packets +You can capture packets using the Network Observability CLI. + +.Prerequisites +* Install the {oc-first}. +* Install the Network Observability CLI (`oc netobserv`) plugin. + +.Procedure +. Run the packet capture with filters enabled: ++ +[source,terminal] +---- +$ oc netobserv packets --filter=tcp,80 +---- +. Add filters to the `live table filter` prompt in the terminal to refine the incoming packets. An example filter is as follows: ++ +[source,terminal] +---- +live table filter: [SrcK8S_Zone:us-west-1b] press enter to match multiple regular expressions at once +---- +. To stop capturing, press kbd:[Ctrl+C]. +. View the captured data, which is written to a single file in an `./output/pcap` directory located in the same path that was used to install the CLI: +.. The `./output/pcap/.pcap` file can be opened with Wireshark. \ No newline at end of file diff --git a/modules/network-observability-configuring-custom-metrics.adoc b/modules/network-observability-configuring-custom-metrics.adoc new file mode 100644 index 0000000000..c73bb10549 --- /dev/null +++ b/modules/network-observability-configuring-custom-metrics.adoc @@ -0,0 +1,85 @@ +// Module included in the following assemblies: +// +// network_observability/metrics-alerts-dashboards.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-configuring-custom-metrics_{context}"] += Configuring custom metrics by using FlowMetric API +You can configure the `FlowMetric` API to create custom metrics by using flowlogs data fields as Prometheus labels. You can add multiple `FlowMetric` resources to a project to see multiple dashboard views. + +.Procedure + +. In the web console, navigate to *Operators* -> *Installed Operators*. +. In the *Provided APIs* heading for the *NetObserv Operator*, select *FlowMetric*. +. In the *Project:* dropdown list, select the project of the Network Observability Operator instance. +. Click *Create FlowMetric*. +. Configure the `FlowMetric` resource, similar to the following sample configurations: ++ +.Generate a metric that tracks ingress bytes received from cluster external sources +[%collapsible] +==== +[source,yaml] +---- +apiVersion: flows.netobserv.io/v1alpha1 +kind: FlowMetric +metadata: + name: flowmetric-cluster-external-ingress-traffic + namespace: netobserv <1> +spec: + metricName: cluster_external_ingress_bytes_total <2> + type: Counter <3> + valueField: Bytes + direction: Ingress <4> + labels: [DstK8S_HostName,DstK8S_Namespace,DstK8S_OwnerName,DstK8S_OwnerType] <5> + filters: <6> + - field: SrcSubnetLabel + matchType: Absence +---- +<1> The `FlowMetric` resources need to be created in the namespace defined in the `FlowCollector` `spec.namespace`, which is `netobserv` by default. +<2> The name of the Prometheus metric, which in the web console appears with the prefix `netobserv-`. +<3> The `type` specifies the type of metric. The `Counter` `type` is useful for counting bytes or packets. +<4> The direction of traffic to capture. If not specified, both ingress and egress are captured, which can lead to duplicated counts. +<5> Labels define what the metrics look like and the relationship between the different entities and also define the metrics cardinality. For example, `SrcK8S_Name` is a high cardinality metric. +<6> Refines results based on the listed criteria. In this example, selecting only the cluster external traffic is done by matching only flows where `SrcSubnetLabel` is absent. This assumes the subnet labels feature is enabled (via `spec.processor.subnetLabels`), which is done by default. + +.Verification +. Once the pods refresh, navigate to *Observe* -> *Metrics*. +. In the *Expression* field, type the metric name to view the corresponding result. You can also enter an expression, such as `topk(5, sum(rate(netobserv_cluster_external_ingress_bytes_total{DstK8S_Namespace="my-namespace"}[2m])) by (DstK8S_HostName, DstK8S_OwnerName, DstK8S_OwnerType))` +==== ++ +.Show RTT latency for cluster external ingress traffic +[%collapsible] +==== +[source,yaml] +---- +apiVersion: flows.netobserv.io/v1alpha1 +kind: FlowMetric +metadata: + name: flowmetric-cluster-external-ingress-rtt + namespace: netobserv <1> +spec: + metricName: cluster_external_ingress_rtt_seconds + type: Histogram <2> + valueField: TimeFlowRttNs + direction: Ingress + labels: [DstK8S_HostName,DstK8S_Namespace,DstK8S_OwnerName,DstK8S_OwnerType] + filters: + - field: SrcSubnetLabel + matchType: Absence + - field: TimeFlowRttNs + matchType: Presence + divider: "1000000000" <3> + buckets: [".001", ".005", ".01", ".02", ".03", ".04", ".05", ".075", ".1", ".25", "1"] <4> +---- +<1> The `FlowMetric` resources need to be created in the namespace defined in the `FlowCollector` `spec.namespace`, which is `netobserv` by default. +<2> The `type` specifies the type of metric. The `Histogram` `type` is useful for a latency value (`TimeFlowRttNs`). +<3> Since the Round-trip time (RTT) is provided as nanos in flows, use a divider of 1 billion to convert into seconds, which is standard in Prometheus guidelines. +<4> The custom buckets specify precision on RTT, with optimal precision ranging between 5ms and 250ms. + +.Verification +. Once the pods refresh, navigate to *Observe* -> *Metrics*. +. In the *Expression* field, you can type the metric name to view the corresponding result. +==== + + + diff --git a/modules/network-observability-custom-metrics.adoc b/modules/network-observability-custom-metrics.adoc new file mode 100644 index 0000000000..eeb505747c --- /dev/null +++ b/modules/network-observability-custom-metrics.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// network_observability/metrics-alerts-dashboards.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-observability-custom-metrics_{context}"] += Custom metrics +You can create custom metrics out of the flowlogs data using the `FlowMetric` API. In every flowlogs data that is collected, there are a number of fields labeled per log, such as source name and destination name. These fields can be leveraged as Prometheus labels to enable the customization of cluster information on your dashboard. \ No newline at end of file diff --git a/modules/network-observability-dns-tracking.adoc b/modules/network-observability-dns-tracking.adoc index 134cb6c09b..1bebed820f 100644 --- a/modules/network-observability-dns-tracking.adoc +++ b/modules/network-observability-dns-tracking.adoc @@ -27,7 +27,6 @@ metadata: name: cluster spec: namespace: netobserv - deploymentModel: Direct agent: type: eBPF ebpf: @@ -36,7 +35,7 @@ spec: sampling: 1 <2> ---- <1> You can set the `spec.agent.ebpf.features` parameter list to enable DNS tracking of each network flow in the web console. -<2> You can set `sampling` to a value of `1` for more accurate metrics. +<2> You can set `sampling` to a value of `1` for more accurate metrics and to capture *DNS latency*. For a `sampling` value greater than 1, you can observe flows with *DNS Response Code* and *DNS Id*, and it is unlikely that *DNS Latency* can be observed. . When you refresh the *Network Traffic* page, there are new DNS representations you can choose to view in the *Overview* and *Traffic Flow* views and new filters you can apply. .. Select new DNS choices in *Manage panels* to display graphical visualizations and DNS metrics in the *Overview*. diff --git a/modules/network-observability-ebpf-agent-alert.adoc b/modules/network-observability-ebpf-agent-alert.adoc new file mode 100644 index 0000000000..f9201d46aa --- /dev/null +++ b/modules/network-observability-ebpf-agent-alert.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// * network_observability/network-observability-operator-monitoring.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-netobserv-dashboard-ebpf-agent-alerts_{context}"] += Using the eBPF agent alert + +An alert, `NetObservAgentFlowsDropped`, is triggered when the Network Observability eBPF agent hashmap table is full or when the capacity limiter is triggered. If you see this alert, consider increasing the `cacheMaxFlows` in the `FlowCollector`, as shown in the following example. + +[NOTE] +==== +Increasing the `cacheMaxFlows` might increase the memory usage of the eBPF agent. +==== + +.Procedure + +. In the web console, navigate to *Operators* -> *Installed Operators*. + +. Under the *Provided APIs* heading for the *Network Observability Operator*, select *Flow Collector*. + +. Select *cluster*, and then select the *YAML* tab. + +. Increase the `spec.agent.ebpf.cacheMaxFlows` value, as shown in the following YAML sample: +[source,yaml] +---- +apiVersion: flows.netobserv.io/v1beta2 +kind: FlowCollector +metadata: + name: cluster +spec: + namespace: netobserv + deploymentModel: Direct + agent: + type: eBPF + ebpf: + cacheMaxFlows: 200000 <1> +---- +<1> Increase the `cacheMaxFlows` value from its value at the time of the `NetObservAgentFlowsDropped` alert. diff --git a/modules/network-observability-ebpf-rule-flow-filter.adoc b/modules/network-observability-ebpf-rule-flow-filter.adoc new file mode 100644 index 0000000000..b20c6a8035 --- /dev/null +++ b/modules/network-observability-ebpf-rule-flow-filter.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// network_observability/observing-network-traffic.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-observability-ebpf-flow-rule-filter_{context}"] += eBPF flow rule filter +You can use rule-based filtering to control the volume of packets cached in the eBPF flow table. For example, a filter can specify that only packets coming from port 100 should be recorded. Then only the packets that match the filter are cached and the rest are not cached. + +[id="ingress-and-egress-traffic-filtering_{context}"] +== Ingress and egress traffic filtering +CIDR notation efficiently represents IP address ranges by combining the base IP address with a prefix length. For both ingress and egress traffic, the source IP address is first used to match filter rules configured with CIDR notation. If there is a match, then the filtering proceeds. If there is no match, then the destination IP is used to match filter rules configured with CIDR notation. + +After matching either the source IP or the destination IP CIDR, you can pinpoint specific endpoints using the `peerIP` to differentiate the destination IP address of the packet. Based on the provisioned action, the flow data is either cached in the eBPF flow table or not cached. + +[id="dashboard-and-metrics-integrations_{context}"] +== Dashboard and metrics integrations +When this option is enabled, the *Netobserv/Health* dashboard for *eBPF agent statistics* now has the *Filtered flows rate* view. Additionally, in *Observe* -> *Metrics* you can query `netobserv_agent_filtered_flows_total` to observe metrics with the reason in *FlowFilterAcceptCounter*, *FlowFilterNoMatchCounter* or *FlowFilterRecjectCounter*. \ No newline at end of file diff --git a/modules/network-observability-filtering-ebpf-rule.adoc b/modules/network-observability-filtering-ebpf-rule.adoc new file mode 100644 index 0000000000..85e41e34b2 --- /dev/null +++ b/modules/network-observability-filtering-ebpf-rule.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// network_observability/observing-network-traffic.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-filtering-ebpf-rule_{context}"] += Filtering eBPF flow data using a global rule +You can configure the `FlowCollector` to filter eBPF flows using a global rule to control the flow of packets cached in the eBPF flow table. + +.Procedure +. In the web console, navigate to *Operators* -> *Installed Operators*. +. Under the *Provided APIs* heading for *Network Observability*, select *Flow Collector*. +. Select *cluster*, then select the *YAML* tab. +. Configure the `FlowCollector` custom resource, similar to the following sample configurations: ++ + +[%collapsible] +.Filter Kubernetes service traffic to a specific Pod IP endpoint +==== +[source, yaml] +---- +apiVersion: flows.netobserv.io/v1beta2 +kind: FlowCollector +metadata: + name: cluster +spec: + namespace: netobserv + deploymentModel: Direct + agent: + type: eBPF + ebpf: + flowFilter: + action: Accept <1> + cidr: 172.210.150.1/24 <2> + protocol: SCTP + direction: Ingress + destPortRange: 80-100 + peerIP: 10.10.10.10 + enable: true <3> +---- +<1> The required `action` parameter describes the action that is taken for the flow filter rule. Possible values are `Accept` or `Reject`. +<2> The required `cidr` parameter provides the IP address and CIDR mask for the flow filter rule and supports IPv4 and IPv6 address formats. If you want to match against any IP address, you can use `0.0.0.0/0` for IPv4 or `::/0` for IPv6. +<3> You must set `spec.agent.ebpf.flowFilter.enable` to `true` to enable this feature. +==== ++ +[%collapsible] +.See flows to any addresses outside the cluster +==== +[source, yaml] +---- +apiVersion: flows.netobserv.io/v1beta2 +kind: FlowCollector +metadata: + name: cluster +spec: + namespace: netobserv + deploymentModel: Direct + agent: + type: eBPF + ebpf: + flowFilter: + action: Accept <1> + cidr: 0.0.0.0/0 <2> + protocol: TCP + direction: Egress + sourcePort: 100 + peerIP: 192.168.127.12 <3> + enable: true <4> +---- +<1> You can `Accept` flows based on the criteria in the `flowFilter` specification. +<2> The `cidr` value of `0.0.0.0/0` matches against any IP address. +<3> See flows after `peerIP` is configured with `192.168.127.12`. +<4> You must set `spec.agent.ebpf.flowFilter.enable` to `true` to enable the feature. +==== \ No newline at end of file diff --git a/modules/network-observability-flow-filter-parameters.adoc b/modules/network-observability-flow-filter-parameters.adoc new file mode 100644 index 0000000000..51e10d254c --- /dev/null +++ b/modules/network-observability-flow-filter-parameters.adoc @@ -0,0 +1,59 @@ +:_mod-docs-content-type: REFERENCE +// Module included in the following assemblies: +// +// network_observability/observing-network-traffic.adoc + +[id="network-observability-flowcollector-flowfilter-parameters_{context}"] += Flow filter configuration parameters +The flow filter rules consist of required and optional parameters. + +.Required configuration parameters +[cols="3a,8a",options="header"] +|=== +|Parameter |Description + +|`enable` +| Set `enable` to `true` to enable the eBPF flow filtering feature. + +|`cidr` +| Provides the IP address and CIDR mask for the flow filter rule. Supports both IPv4 and IPv6 address format. If you want to match against any IP, you can use `0.0.0.0/0` for IPv4 or `::/0` for IPv6. + +|`action` +| Describes the action that is taken for the flow filter rule. The possible values are `Accept` or `Reject`. + +* For the `Accept` action matching rule, the flow data is cached in the eBPF table and updated with the global metric, `FlowFilterAcceptCounter`. +* For the `Reject` action matching rule, the flow data is dropped and not cached in the eBPF table. The flow data is updated with the global metric, `FlowFilterRejectCounter`. +* If the rule is not matched, the flow is cached in the eBPF table and updated with the global metric, `FlowFilterNoMatchCounter`. +|=== + + +.Optional configuration parameters +[cols="3a,8a",options="header"] +|=== +|Parameter |Description + +|`direction` +| Defines the direction of the flow filter rule. Possible values are `Ingress` or `Egress`. + +|`protocol` +| Defines the protocol of the flow filter rule. Possible values are `TCP`, `UDP`, `SCTP`, `ICMP`, and `ICMPv6`. + +| `ports` +| Defines the ports to use for filtering flows. It can be used for either source or destination ports. To filter a single port, set a single port as an integer value. For example `ports: 80`. To filter a range of ports, use a "start-end" range in string format. For example `ports: "80-100"` + +|`sourcePorts` +| Defines the source port to use for filtering flows. To filter a single port, set a single port as an integer value, for example `sourcePorts: 80`. To filter a range of ports, use a "start-end" range, string format, for example `sourcePorts: "80-100"`. + + +| `destPorts` +| DestPorts defines the destination ports to use for filtering flows. To filter a single port, set a single port as an integer value, for example `destPorts: 80`. To filter a range of ports, use a "start-end" range in string format, for example `destPorts: "80-100"`. + +| `icmpType` +| Defines the ICMP type to use for filtering flows. + +| `icmpCode` +| Defines the ICMP code to use for filtering flows. + +| `peerIP` +| Defines the IP address to use for filtering flows, for example: `10.10.10.10`. +|=== \ No newline at end of file diff --git a/modules/network-observability-flowcollector-api-specifications.adoc b/modules/network-observability-flowcollector-api-specifications.adoc index 3f60dc67b5..b1f5bde9a9 100644 --- a/modules/network-observability-flowcollector-api-specifications.adoc +++ b/modules/network-observability-flowcollector-api-specifications.adoc @@ -35,9 +35,14 @@ Type:: | `spec` | `object` -| Defines the desired state of the FlowCollector resource. + +| Defines the desired state of the FlowCollector resource. + - *: the mention of "unsupported", or "deprecated" for a feature throughout this document means that this feature is not officially supported by Red Hat. It might have been, for example, contributed by the community and accepted without a formal agreement for maintenance. The product maintainers might provide some support for these features as a best effort only. + + + +*: the mention of "unsupported" or "deprecated" for a feature throughout this document means that this feature +is not officially supported by Red Hat. It might have been, for example, contributed by the community +and accepted without a formal agreement for maintenance. The product maintainers might provide some support +for these features as a best effort only. |=== == .metadata @@ -57,9 +62,14 @@ Type:: Description:: + -- -Defines the desired state of the FlowCollector resource. + +Defines the desired state of the FlowCollector resource. + - *: the mention of "unsupported", or "deprecated" for a feature throughout this document means that this feature is not officially supported by Red Hat. It might have been, for example, contributed by the community and accepted without a formal agreement for maintenance. The product maintainers might provide some support for these features as a best effort only. + + + +*: the mention of "unsupported" or "deprecated" for a feature throughout this document means that this feature +is not officially supported by Red Hat. It might have been, for example, contributed by the community +and accepted without a formal agreement for maintenance. The product maintainers might provide some support +for these features as a best effort only. -- Type:: @@ -83,9 +93,12 @@ Type:: | `deploymentModel` | `string` | `deploymentModel` defines the desired type of deployment for flow processing. Possible values are: + - - `Direct` (default) to make the flow processor listening directly from the agents. + - - `Kafka` to make flows sent to a Kafka pipeline before consumption by the processor. + - Kafka can provide better scalability, resiliency, and high availability (for more details, see https://www.redhat.com/en/topics/integration/what-is-apache-kafka). + +- `Direct` (default) to make the flow processor listen directly from the agents. + + +- `Kafka` to make flows sent to a Kafka pipeline before consumption by the processor. + + +Kafka can provide better scalability, resiliency, and high availability (for more details, see https://www.redhat.com/en/topics/integration/what-is-apache-kafka). | `exporters` | `array` @@ -105,7 +118,12 @@ Type:: | `processor` | `object` -| `processor` defines the settings of the component that receives the flows from the agent, enriches them, generates metrics, and forwards them to the Loki persistence layer and/or any available exporter. +| `processor` defines the settings of the component that receives the flows from the agent, +enriches them, generates metrics, and forwards them to the Loki persistence layer and/or any available exporter. + +| `prometheus` +| `object` +| `prometheus` defines Prometheus settings, such as querier configuration used to fetch metrics from the Console plugin. |=== == .spec.agent @@ -127,25 +145,21 @@ Type:: | `ebpf` | `object` -| `ebpf` describes the settings related to the eBPF-based flow reporter when `spec.agent.type` is set to `eBPF`. - -| `ipfix` -| `object` -| `ipfix` [deprecated (*)] - describes the settings related to the IPFIX-based flow reporter when `spec.agent.type` is set to `IPFIX`. +| `ebpf` describes the settings related to the eBPF-based flow reporter when `spec.agent.type` +is set to `eBPF`. | `type` | `string` -| `type` selects the flows tracing agent. Possible values are: + - - `eBPF` (default) to use Network Observability eBPF agent. + - - `IPFIX` [deprecated (*)] - to use the legacy IPFIX collector. + - `eBPF` is recommended as it offers better performances and should work regardless of the CNI installed on the cluster. `IPFIX` works with OVN-Kubernetes CNI (other CNIs could work if they support exporting IPFIX, but they would require manual configuration). +| `type` [deprecated (*)] selects the flows tracing agent. Previously, this field allowed to select between `eBPF` or `IPFIX`. +Only `eBPF` is allowed now, so this field is deprecated and is planned for removal in a future version of the API. |=== == .spec.agent.ebpf Description:: + -- -`ebpf` describes the settings related to the eBPF-based flow reporter when `spec.agent.type` is set to `eBPF`. +`ebpf` describes the settings related to the eBPF-based flow reporter when `spec.agent.type` +is set to `eBPF`. -- Type:: @@ -160,27 +174,44 @@ Type:: | `advanced` | `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` env vars. Set these values at your own risk. +| `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` env vars. Set these values at your own risk. | `cacheActiveTimeout` | `string` -| `cacheActiveTimeout` is the max period during which the reporter aggregates flows before sending. Increasing `cacheMaxFlows` and `cacheActiveTimeout` can decrease the network traffic overhead and the CPU load, however you can expect higher memory consumption and an increased latency in the flow collection. +| `cacheActiveTimeout` is the max period during which the reporter aggregates flows before sending. +Increasing `cacheMaxFlows` and `cacheActiveTimeout` can decrease the network traffic overhead and the CPU load, +however you can expect higher memory consumption and an increased latency in the flow collection. | `cacheMaxFlows` | `integer` -| `cacheMaxFlows` is the max number of flows in an aggregate; when reached, the reporter sends the flows. Increasing `cacheMaxFlows` and `cacheActiveTimeout` can decrease the network traffic overhead and the CPU load, however you can expect higher memory consumption and an increased latency in the flow collection. +| `cacheMaxFlows` is the max number of flows in an aggregate; when reached, the reporter sends the flows. +Increasing `cacheMaxFlows` and `cacheActiveTimeout` can decrease the network traffic overhead and the CPU load, +however you can expect higher memory consumption and an increased latency in the flow collection. | `excludeInterfaces` | `array (string)` -| `excludeInterfaces` contains the interface names that are excluded from flow tracing. An entry enclosed by slashes, such as `/br-/`, is matched as a regular expression. Otherwise it is matched as a case-sensitive string. +| `excludeInterfaces` contains the interface names that are excluded from flow tracing. +An entry enclosed by slashes, such as `/br-/`, is matched as a regular expression. +Otherwise it is matched as a case-sensitive string. | `features` | `array (string)` | List of additional features to enable. They are all disabled by default. Enabling additional features might have performance impacts. Possible values are: + - - `PacketDrop`: enable the packets drop flows logging feature. This feature requires mounting the kernel debug filesystem, so the eBPF pod has to run as privileged. If the `spec.agent.ebpf.privileged` parameter is not set, an error is reported. + - - `DNSTracking`: enable the DNS tracking feature. + - - `FlowRTT`: enable flow latency (RTT) calculations in the eBPF agent during TCP handshakes. This feature better works with `sampling` set to 1. + +- `PacketDrop`: enable the packets drop flows logging feature. This feature requires mounting +the kernel debug filesystem, so the eBPF pod has to run as privileged. +If the `spec.agent.ebpf.privileged` parameter is not set, an error is reported. + + +- `DNSTracking`: enable the DNS tracking feature. + + +- `FlowRTT`: enable flow latency (sRTT) extraction in the eBPF agent from TCP traffic. + + + +| `flowFilter` +| `object` +| `flowFilter` defines the eBPF agent configuration regarding flow filtering. | `imagePullPolicy` | `string` @@ -188,23 +219,35 @@ Type:: | `interfaces` | `array (string)` -| `interfaces` contains the interface names from where flows are collected. If empty, the agent fetches all the interfaces in the system, excepting the ones listed in ExcludeInterfaces. An entry enclosed by slashes, such as `/br-/`, is matched as a regular expression. Otherwise it is matched as a case-sensitive string. +| `interfaces` contains the interface names from where flows are collected. If empty, the agent +fetches all the interfaces in the system, excepting the ones listed in `excludeInterfaces`. +An entry enclosed by slashes, such as `/br-/`, is matched as a regular expression. +Otherwise it is matched as a case-sensitive string. | `kafkaBatchSize` | `integer` -| `kafkaBatchSize` limits the maximum size of a request in bytes before being sent to a partition. Ignored when not using Kafka. Default: 10MB. +| `kafkaBatchSize` limits the maximum size of a request in bytes before being sent to a partition. Ignored when not using Kafka. Default: 1MB. | `logLevel` | `string` | `logLevel` defines the log level for the Network Observability eBPF Agent +| `metrics` +| `object` +| `metrics` defines the eBPF agent configuration regarding metrics. + | `privileged` | `boolean` -| Privileged mode for the eBPF Agent container. When ignored or set to `false`, the operator sets granular capabilities (BPF, PERFMON, NET_ADMIN, SYS_RESOURCE) 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. Some agent features require the privileged mode, such as packet drops tracking (see `features`) and SR-IOV support. +| Privileged mode for the eBPF Agent container. When ignored or set to `false`, the operator sets +granular capabilities (BPF, PERFMON, NET_ADMIN, SYS_RESOURCE) 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. +Some agent features require the privileged mode, such as packet drops tracking (see `features`) and SR-IOV support. | `resources` | `object` -| `resources` are the compute resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| `resources` are the compute resources required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | `sampling` | `integer` @@ -215,7 +258,9 @@ Type:: 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` env vars. Set these values at your own risk. +`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` env vars. Set these values at your own risk. -- Type:: @@ -230,14 +275,329 @@ Type:: | `env` | `object (string)` -| `env` allows passing custom environment variables to underlying components. Useful for passing some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be publicly exposed as part of the FlowCollector descriptor, as they are only useful in edge debug or support scenarios. +| `env` allows passing custom environment variables to underlying components. Useful for passing +some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be +publicly exposed as part of the FlowCollector descriptor, as they are only useful +in edge debug or support scenarios. + +| `scheduling` +| `object` +| scheduling controls how the pods are scheduled on nodes. + +|=== +== .spec.agent.ebpf.advanced.scheduling +Description:: ++ +-- +scheduling controls how the pods are scheduled on nodes. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `affinity` +| `object` +| If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +| `nodeSelector` +| `object (string)` +| `nodeSelector` allows scheduling of pods only onto nodes that have each of the specified labels. +For documentation, refer to https://kubernetes.io/docs/concepts/configuration/assign-pod-node/. + +| `priorityClassName` +| `string` +| If specified, indicates the pod's priority. For documentation, refer to https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#how-to-use-priority-and-preemption. +If not specified, default priority is used, or zero if there is no default. + +| `tolerations` +| `array` +| `tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +|=== +== .spec.agent.ebpf.advanced.scheduling.affinity +Description:: ++ +-- +If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `object` + + + + +== .spec.agent.ebpf.advanced.scheduling.tolerations +Description:: ++ +-- +`tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `array` + + + + +== .spec.agent.ebpf.flowFilter +Description:: ++ +-- +`flowFilter` defines the eBPF agent configuration regarding flow filtering. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `action` +| `string` +| `action` defines the action to perform on the flows that match the filter. + +| `cidr` +| `string` +| `cidr` defines the IP CIDR to filter flows by. +Examples: `10.10.10.0/24` or `100:100:100:100::/64` + +| `destPorts` +| `integer-or-string` +| `destPorts` defines the destination ports to filter flows by. +To filter a single port, set a single port as an integer value. For example: `destPorts: 80`. +To filter a range of ports, use a "start-end" range in string format. For example: `destPorts: "80-100"`. + +| `direction` +| `string` +| `direction` defines the direction to filter flows by. + +| `enable` +| `boolean` +| Set `enable` to `true` to enable the eBPF flow filtering feature. + +| `icmpCode` +| `integer` +| `icmpCode`, for Internet Control Message Protocol (ICMP) traffic, defines the ICMP code to filter flows by. + +| `icmpType` +| `integer` +| `icmpType`, for ICMP traffic, defines the ICMP type to filter flows by. + +| `peerIP` +| `string` +| `peerIP` defines the IP address to filter flows by. +Example: `10.10.10.10`. + +| `ports` +| `integer-or-string` +| `ports` defines the ports to filter flows by. It is used both for source and destination ports. +To filter a single port, set a single port as an integer value. For example: `ports: 80`. +To filter a range of ports, use a "start-end" range in string format. For example: `ports: "80-100"`. + +| `protocol` +| `string` +| `protocol` defines the protocol to filter flows by. + +| `sourcePorts` +| `integer-or-string` +| `sourcePorts` defines the source ports to filter flows by. +To filter a single port, set a single port as an integer value. For example: `sourcePorts: 80`. +To filter a range of ports, use a "start-end" range in string format. For example: `sourcePorts: "80-100"`. + +|=== +== .spec.agent.ebpf.metrics +Description:: ++ +-- +`metrics` defines the eBPF agent configuration regarding metrics. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `disableAlerts` +| `array (string)` +| `disableAlerts` is a list of alerts that should be disabled. +Possible values are: + + +`NetObservDroppedFlows`, which is triggered when the eBPF agent is dropping flows, such as when the BPF hashmap is full or the capacity limiter is being triggered. + + + +| `enable` +| `boolean` +| Set `enable` to `false` to disable eBPF agent metrics collection. It is enabled by default. + +| `server` +| `object` +| Metrics server endpoint configuration for the Prometheus scraper. + +|=== +== .spec.agent.ebpf.metrics.server +Description:: ++ +-- +Metrics server endpoint configuration for the Prometheus scraper. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `port` +| `integer` +| The metrics server HTTP port. + +| `tls` +| `object` +| TLS configuration. + +|=== +== .spec.agent.ebpf.metrics.server.tls +Description:: ++ +-- +TLS configuration. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `insecureSkipVerify` +| `boolean` +| `insecureSkipVerify` allows skipping client-side verification of the provided certificate. +If set to `true`, the `providedCaFile` field is ignored. + +| `provided` +| `object` +| TLS configuration when `type` is set to `Provided`. + +| `providedCaFile` +| `object` +| Reference to the CA file when `type` is set to `Provided`. + +| `type` +| `string` +| Select the type of TLS configuration: + + +- `Disabled` (default) to not configure TLS for the endpoint. +- `Provided` to manually provide cert file and a key file. [Unsupported (*)]. +- `Auto` to use {product-title} auto generated certificate using annotations. + +|=== +== .spec.agent.ebpf.metrics.server.tls.provided +Description:: ++ +-- +TLS configuration when `type` is set to `Provided`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `certFile` +| `string` +| `certFile` defines the path to the certificate file name within the config map or secret. + +| `certKey` +| `string` +| `certKey` defines the path to the certificate private key file name within the config map or secret. Omit when the key is not necessary. + +| `name` +| `string` +| Name of the config map or secret containing certificates. + +| `namespace` +| `string` +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. + +| `type` +| `string` +| Type for the certificate reference: `configmap` or `secret`. + +|=== +== .spec.agent.ebpf.metrics.server.tls.providedCaFile +Description:: ++ +-- +Reference to the CA file when `type` is set to `Provided`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `file` +| `string` +| File name within the config map or secret. + +| `name` +| `string` +| Name of the config map or secret containing the file. + +| `namespace` +| `string` +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. + +| `type` +| `string` +| Type for the file reference: "configmap" or "secret". |=== == .spec.agent.ebpf.resources Description:: + -- -`resources` are the compute resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +`resources` are the compute resources required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ -- Type:: @@ -252,105 +612,15 @@ Type:: | `limits` | `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| Limits describes the maximum amount of compute resources allowed. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | `requests` | `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ - -|=== -== .spec.agent.ipfix -Description:: -+ --- -`ipfix` [deprecated (*)] - describes the settings related to the IPFIX-based flow reporter when `spec.agent.type` is set to `IPFIX`. --- - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cacheActiveTimeout` -| `string` -| `cacheActiveTimeout` is the max period during which the reporter aggregates flows before sending. - -| `cacheMaxFlows` -| `integer` -| `cacheMaxFlows` is the max number of flows in an aggregate; when reached, the reporter sends the flows. - -| `clusterNetworkOperator` -| `object` -| `clusterNetworkOperator` defines the settings related to the {product-title} Cluster Network Operator, when available. - -| `forceSampleAll` -| `boolean` -| `forceSampleAll` allows disabling sampling in the IPFIX-based flow reporter. It is not recommended to sample all the traffic with IPFIX, as it might generate cluster instability. If you REALLY want to do that, set this flag to `true`. Use at your own risk. When it is set to `true`, the value of `sampling` is ignored. - -| `ovnKubernetes` -| `object` -| `ovnKubernetes` defines the settings of the OVN-Kubernetes CNI, when available. This configuration is used when using OVN's IPFIX exports, without {product-title}. When using {product-title}, refer to the `clusterNetworkOperator` property instead. - -| `sampling` -| `integer` -| `sampling` is the sampling rate on the reporter. 100 means one flow on 100 is sent. To ensure cluster stability, it is not possible to set a value below 2. If you really want to sample every packet, which might impact the cluster stability, refer to `forceSampleAll`. Alternatively, you can use the eBPF Agent instead of IPFIX. - -|=== -== .spec.agent.ipfix.clusterNetworkOperator -Description:: -+ --- -`clusterNetworkOperator` defines the settings related to the {product-title} Cluster Network Operator, when available. --- - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespace` -| `string` -| Namespace where the config map is going to be deployed. - -|=== -== .spec.agent.ipfix.ovnKubernetes -Description:: -+ --- -`ovnKubernetes` defines the settings of the OVN-Kubernetes CNI, when available. This configuration is used when using OVN's IPFIX exports, without {product-title}. When using {product-title}, refer to the `clusterNetworkOperator` property instead. --- - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| `containerName` defines the name of the container to configure for IPFIX. - -| `daemonSetName` -| `string` -| `daemonSetName` defines the name of the DaemonSet controlling the OVN-Kubernetes pods. - -| `namespace` -| `string` -| Namespace where OVN-Kubernetes pods are deployed. +| Requests describes the minimum amount of compute resources required. +If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, +otherwise to an implementation-defined value. Requests cannot exceed Limits. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |=== == .spec.consolePlugin @@ -372,7 +642,9 @@ Type:: | `advanced` | `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` env vars. Set these values at your own risk. +| `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` env vars. Set these values at your own risk. | `autoscaler` | `object` @@ -380,7 +652,7 @@ Type:: | `enable` | `boolean` -| Enables the console plugin deployment. `spec.loki.enable` must also be `true` +| Enables the console plugin deployment. | `imagePullPolicy` | `string` @@ -404,14 +676,17 @@ Type:: | `resources` | `object` -| `resources`, in terms of compute resources, required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| `resources`, in terms of compute resources, required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |=== == .spec.consolePlugin.advanced 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` env vars. Set these values at your own risk. +`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` env vars. Set these values at your own risk. -- Type:: @@ -426,11 +701,17 @@ Type:: | `args` | `array (string)` -| `args` allows passing custom arguments to underlying components. Useful for overriding some parameters, such as an url or a configuration path, that should not be publicly exposed as part of the FlowCollector descriptor, as they are only useful in edge debug or support scenarios. +| `args` allows passing custom arguments to underlying components. Useful for overriding +some parameters, such as a URL or a configuration path, that should not be +publicly exposed as part of the FlowCollector descriptor, as they are only useful +in edge debug or support scenarios. | `env` | `object (string)` -| `env` allows passing custom environment variables to underlying components. Useful for passing some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be publicly exposed as part of the FlowCollector descriptor, as they are only useful in edge debug or support scenarios. +| `env` allows passing custom environment variables to underlying components. Useful for passing +some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be +publicly exposed as part of the FlowCollector descriptor, as they are only useful +in edge debug or support scenarios. | `port` | `integer` @@ -438,9 +719,79 @@ Type:: | `register` | `boolean` -| `register` allows, when set to `true`, to automatically register the provided console plugin with the {product-title} Console operator. When set to `false`, you can still register it manually by editing console.operator.openshift.io/cluster with the following command: `oc patch console.operator.openshift.io cluster --type='json' -p '[{"op": "add", "path": "/spec/plugins/-", "value": "netobserv-plugin"}]'` +| `register` allows, when set to `true`, to automatically register the provided console plugin with the {product-title} Console operator. +When set to `false`, you can still register it manually by editing console.operator.openshift.io/cluster with the following command: +`oc patch console.operator.openshift.io cluster --type='json' -p '[{"op": "add", "path": "/spec/plugins/-", "value": "netobserv-plugin"}]'` + +| `scheduling` +| `object` +| `scheduling` controls how the pods are scheduled on nodes. |=== +== .spec.consolePlugin.advanced.scheduling +Description:: ++ +-- +`scheduling` controls how the pods are scheduled on nodes. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `affinity` +| `object` +| If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +| `nodeSelector` +| `object (string)` +| `nodeSelector` allows scheduling of pods only onto nodes that have each of the specified labels. +For documentation, refer to https://kubernetes.io/docs/concepts/configuration/assign-pod-node/. + +| `priorityClassName` +| `string` +| If specified, indicates the pod's priority. For documentation, refer to https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#how-to-use-priority-and-preemption. +If not specified, default priority is used, or zero if there is no default. + +| `tolerations` +| `array` +| `tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +|=== +== .spec.consolePlugin.advanced.scheduling.affinity +Description:: ++ +-- +If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `object` + + + + +== .spec.consolePlugin.advanced.scheduling.tolerations +Description:: ++ +-- +`tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `array` + + + + == .spec.consolePlugin.autoscaler Description:: + @@ -477,7 +828,8 @@ Type:: | `portNames` | `object (string)` -| `portNames` defines additional port names to use in the console, for example, `portNames: {"3100": "loki"}`. +| `portNames` defines additional port names to use in the console, +for example, `portNames: {"3100": "loki"}`. |=== == .spec.consolePlugin.quickFilters @@ -519,7 +871,8 @@ Required:: | `filter` | `object (string)` -| `filter` is a set of keys and values to be set when this filter is selected. Each key can relate to a list of values using a coma-separated string, for example, `filter: {"src_namespace": "namespace1,namespace2"}`. +| `filter` is a set of keys and values to be set when this filter is selected. Each key can relate to a list of values using a coma-separated string, +for example, `filter: {"src_namespace": "namespace1,namespace2"}`. | `name` | `string` @@ -530,7 +883,8 @@ Required:: Description:: + -- -`resources`, in terms of compute resources, required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +`resources`, in terms of compute resources, required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ -- Type:: @@ -545,11 +899,15 @@ Type:: | `limits` | `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| Limits describes the maximum amount of compute resources allowed. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | `requests` | `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| Requests describes the minimum amount of compute resources required. +If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, +otherwise to an implementation-defined value. Requests cannot exceed Limits. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |=== == .spec.exporters @@ -716,19 +1074,20 @@ Type:: | `file` | `string` -| File name within the config map or secret +| File name within the config map or secret. | `name` | `string` -| Name of the config map or secret containing the file +| Name of the config map or secret containing the file. | `namespace` | `string` -| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the file reference: "configmap" or "secret" +| Type for the file reference: "configmap" or "secret". |=== == .spec.exporters[].kafka.sasl.clientSecretReference @@ -750,19 +1109,20 @@ Type:: | `file` | `string` -| File name within the config map or secret +| File name within the config map or secret. | `name` | `string` -| Name of the config map or secret containing the file +| Name of the config map or secret containing the file. | `namespace` | `string` -| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the file reference: "configmap" or "secret" +| Type for the file reference: "configmap" or "secret". |=== == .spec.exporters[].kafka.tls @@ -792,7 +1152,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -818,7 +1179,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -826,15 +1187,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.exporters[].kafka.tls.userCert @@ -856,7 +1218,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -864,15 +1226,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.kafka @@ -961,19 +1324,20 @@ Type:: | `file` | `string` -| File name within the config map or secret +| File name within the config map or secret. | `name` | `string` -| Name of the config map or secret containing the file +| Name of the config map or secret containing the file. | `namespace` | `string` -| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the file reference: "configmap" or "secret" +| Type for the file reference: "configmap" or "secret". |=== == .spec.kafka.sasl.clientSecretReference @@ -995,19 +1359,20 @@ Type:: | `file` | `string` -| File name within the config map or secret +| File name within the config map or secret. | `name` | `string` -| Name of the config map or secret containing the file +| Name of the config map or secret containing the file. | `namespace` | `string` -| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the file reference: "configmap" or "secret" +| Type for the file reference: "configmap" or "secret". |=== == .spec.kafka.tls @@ -1037,7 +1402,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -1063,7 +1429,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1071,15 +1437,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.kafka.tls.userCert @@ -1101,7 +1468,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1109,15 +1476,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki @@ -1139,40 +1507,57 @@ Type:: | `advanced` | `object` -| `advanced` allows setting some aspects of the internal configuration of the Loki clients. This section is aimed mostly for debugging and fine-grained performance optimizations. +| `advanced` allows setting some aspects of the internal configuration of the Loki clients. +This section is aimed mostly for debugging and fine-grained performance optimizations. | `enable` | `boolean` -| Set `enable` to `true` to store flows in Loki. It is required for the {product-title} Console plugin installation. +| Set `enable` to `true` to store flows in Loki. +The Console plugin can use either Loki or Prometheus as a data source for metrics (see also `spec.prometheus.querier`), or both. +Not all queries are transposable from Loki to Prometheus. Hence, if Loki is disabled, some features of the plugin are disabled as well, +such as getting per-pod information or viewing raw flows. +If both Prometheus and Loki are enabled, Prometheus takes precedence and Loki is used as a fallback for queries that Prometheus cannot handle. +If they are both disabled, the Console plugin is not deployed. | `lokiStack` | `object` -| Loki configuration for `LokiStack` mode. This is useful for an easy loki-operator configuration. It is ignored for other modes. +| Loki configuration for `LokiStack` mode. This is useful for an easy Loki Operator configuration. +It is ignored for other modes. | `manual` | `object` -| Loki configuration for `Manual` mode. This is the most flexible configuration. It is ignored for other modes. +| Loki configuration for `Manual` mode. This is the most flexible configuration. +It is ignored for other modes. | `microservices` | `object` -| Loki configuration for `Microservices` mode. Use this option when Loki is installed using the microservices deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#microservices-mode). It is ignored for other modes. +| Loki configuration for `Microservices` mode. +Use this option when Loki is installed using the microservices deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#microservices-mode). +It is ignored for other modes. | `mode` | `string` | `mode` must be set according to the installation mode of Loki: + - - Use `LokiStack` when Loki is managed using the Loki Operator + - - Use `Monolithic` when Loki is installed as a monolithic workload + - - Use `Microservices` when Loki is installed as microservices, but without Loki Operator + - - Use `Manual` if none of the options above match your setup + + +- Use `LokiStack` when Loki is managed using the Loki Operator + + +- Use `Monolithic` when Loki is installed as a monolithic workload + + +- Use `Microservices` when Loki is installed as microservices, but without Loki Operator + + +- Use `Manual` if none of the options above match your setup + | `monolithic` | `object` -| Loki configuration for `Monolithic` mode. Use this option when Loki is installed using the monolithic deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#monolithic-mode). It is ignored for other modes. +| Loki configuration for `Monolithic` mode. +Use this option when Loki is installed using the monolithic deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#monolithic-mode). +It is ignored for other modes. | `readTimeout` | `string` -| `readTimeout` is the maximum console plugin loki query total time limit. A timeout of zero means no timeout. +| `readTimeout` is the maximum console plugin loki query total time limit. +A timeout of zero means no timeout. | `writeBatchSize` | `integer` @@ -1184,14 +1569,16 @@ Type:: | `writeTimeout` | `string` -| `writeTimeout` is the maximum Loki time connection / request limit. A timeout of zero means no timeout. +| `writeTimeout` is the maximum Loki time connection / request limit. +A timeout of zero means no timeout. |=== == .spec.loki.advanced Description:: + -- -`advanced` allows setting some aspects of the internal configuration of the Loki clients. This section is aimed mostly for debugging and fine-grained performance optimizations. +`advanced` allows setting some aspects of the internal configuration of the Loki clients. +This section is aimed mostly for debugging and fine-grained performance optimizations. -- Type:: @@ -1225,7 +1612,8 @@ Type:: Description:: + -- -Loki configuration for `LokiStack` mode. This is useful for an easy loki-operator configuration. It is ignored for other modes. +Loki configuration for `LokiStack` mode. This is useful for an easy Loki Operator configuration. +It is ignored for other modes. -- Type:: @@ -1251,7 +1639,8 @@ Type:: Description:: + -- -Loki configuration for `Manual` mode. This is the most flexible configuration. It is ignored for other modes. +Loki configuration for `Manual` mode. This is the most flexible configuration. +It is ignored for other modes. -- Type:: @@ -1267,18 +1656,26 @@ Type:: | `authToken` | `string` | `authToken` describes the way to get a token to authenticate to Loki. + - - `Disabled` does not send any token with the request. + - - `Forward` forwards the user token for authorization. + - - `Host` [deprecated (*)] - uses the local pod service account to authenticate to Loki. + - When using the Loki Operator, this must be set to `Forward`. + +- `Disabled` does not send any token with the request. + + +- `Forward` forwards the user token for authorization. + + +- `Host` [deprecated (*)] - uses the local pod service account to authenticate to Loki. + + +When using the Loki Operator, this must be set to `Forward`. | `ingesterUrl` | `string` -| `ingesterUrl` is the address of an existing Loki ingester service to push the flows to. When using the Loki Operator, set it to the Loki gateway service with the `network` tenant set in path, for example https://loki-gateway-http.netobserv.svc:8080/api/logs/v1/network. +| `ingesterUrl` is the address of an existing Loki ingester service to push the flows to. When using the Loki Operator, +set it to the Loki gateway service with the `network` tenant set in path, for example +https://loki-gateway-http.netobserv.svc:8080/api/logs/v1/network. | `querierUrl` | `string` -| `querierUrl` specifies the address of the Loki querier service. When using the Loki Operator, set it to the Loki gateway service with the `network` tenant set in path, for example https://loki-gateway-http.netobserv.svc:8080/api/logs/v1/network. +| `querierUrl` specifies the address of the Loki querier service. +When using the Loki Operator, set it to the Loki gateway service with the `network` tenant set in path, for example +https://loki-gateway-http.netobserv.svc:8080/api/logs/v1/network. | `statusTls` | `object` @@ -1286,11 +1683,17 @@ Type:: | `statusUrl` | `string` -| `statusUrl` specifies the address of the Loki `/ready`, `/metrics` and `/config` endpoints, in case it is different from the Loki querier URL. If empty, the `querierUrl` value is used. This is useful to show error messages and some context in the frontend. When using the Loki Operator, set it to the Loki HTTP query frontend service, for example https://loki-query-frontend-http.netobserv.svc:3100/. `statusTLS` configuration is used when `statusUrl` is set. +| `statusUrl` specifies the address of the Loki `/ready`, `/metrics` and `/config` endpoints, in case it is different from the +Loki querier URL. If empty, the `querierUrl` value is used. +This is useful to show error messages and some context in the frontend. +When using the Loki Operator, set it to the Loki HTTP query frontend service, for example +https://loki-query-frontend-http.netobserv.svc:3100/. +`statusTLS` configuration is used when `statusUrl` is set. | `tenantID` | `string` -| `tenantID` is the Loki `X-Scope-OrgID` that identifies the tenant for each request. When using the Loki Operator, set it to `network`, which corresponds to a special tenant mode. +| `tenantID` is the Loki `X-Scope-OrgID` that identifies the tenant for each request. +When using the Loki Operator, set it to `network`, which corresponds to a special tenant mode. | `tls` | `object` @@ -1324,7 +1727,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -1350,7 +1754,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1358,15 +1762,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.manual.statusTls.userCert @@ -1388,7 +1793,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1396,15 +1801,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.manual.tls @@ -1434,7 +1840,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -1460,7 +1867,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1468,15 +1875,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.manual.tls.userCert @@ -1498,7 +1906,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1506,22 +1914,25 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.microservices Description:: + -- -Loki configuration for `Microservices` mode. Use this option when Loki is installed using the microservices deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#microservices-mode). It is ignored for other modes. +Loki configuration for `Microservices` mode. +Use this option when Loki is installed using the microservices deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#microservices-mode). +It is ignored for other modes. -- Type:: @@ -1578,7 +1989,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -1604,7 +2016,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1612,15 +2024,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.microservices.tls.userCert @@ -1642,7 +2055,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1650,22 +2063,25 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.monolithic Description:: + -- -Loki configuration for `Monolithic` mode. Use this option when Loki is installed using the monolithic deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#monolithic-mode). It is ignored for other modes. +Loki configuration for `Monolithic` mode. +Use this option when Loki is installed using the monolithic deployment mode (https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/#monolithic-mode). +It is ignored for other modes. -- Type:: @@ -1718,7 +2134,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the server certificate. If set to `true`, the `caCert` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. | `userCert` | `object` @@ -1744,7 +2161,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1752,15 +2169,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.loki.monolithic.tls.userCert @@ -1782,7 +2200,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -1790,22 +2208,24 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.processor Description:: + -- -`processor` defines the settings of the component that receives the flows from the agent, enriches them, generates metrics, and forwards them to the Loki persistence layer and/or any available exporter. +`processor` defines the settings of the component that receives the flows from the agent, +enriches them, generates metrics, and forwards them to the Loki persistence layer and/or any available exporter. -- Type:: @@ -1820,11 +2240,14 @@ Type:: | `addZone` | `boolean` -| `addZone` allows availability zone awareness by labelling flows with their source and destination zones. This feature requires the "topology.kubernetes.io/zone" label to be set on nodes. +| `addZone` allows availability zone awareness by labelling flows with their source and destination zones. +This feature requires the "topology.kubernetes.io/zone" label to be set on nodes. | `advanced` | `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` env vars. Set these values at your own risk. +| `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` env vars. Set these values at your own risk. | `clusterName` | `string` @@ -1836,7 +2259,8 @@ Type:: | `kafkaConsumerAutoscaler` | `object` -| `kafkaConsumerAutoscaler` is the spec of a horizontal pod autoscaler to set up for `flowlogs-pipeline-transformer`, which consumes Kafka messages. This setting is ignored when Kafka is disabled. Refer to HorizontalPodAutoscaler documentation (autoscaling/v2). +| `kafkaConsumerAutoscaler` is the spec of a horizontal pod autoscaler to set up for `flowlogs-pipeline-transformer`, which consumes Kafka messages. +This setting is ignored when Kafka is disabled. Refer to HorizontalPodAutoscaler documentation (autoscaling/v2). | `kafkaConsumerBatchSize` | `integer` @@ -1848,7 +2272,8 @@ Type:: | `kafkaConsumerReplicas` | `integer` -| `kafkaConsumerReplicas` defines the number of replicas (pods) to start for `flowlogs-pipeline-transformer`, which consumes Kafka messages. This setting is ignored when Kafka is disabled. +| `kafkaConsumerReplicas` defines the number of replicas (pods) to start for `flowlogs-pipeline-transformer`, which consumes Kafka messages. +This setting is ignored when Kafka is disabled. | `logLevel` | `string` @@ -1857,10 +2282,14 @@ Type:: | `logTypes` | `string` | `logTypes` defines the desired record types to generate. Possible values are: + - - `Flows` (default) to export regular network flows + - - `Conversations` to generate events for started conversations, ended conversations as well as periodic "tick" updates + - - `EndedConversations` to generate only ended conversations events + - - `All` to generate both network flows and all conversations events + + +- `Flows` (default) to export regular network flows + + +- `Conversations` to generate events for started conversations, ended conversations as well as periodic "tick" updates + + +- `EndedConversations` to generate only ended conversations events + + +- `All` to generate both network flows and all conversations events + | `metrics` @@ -1873,14 +2302,22 @@ Type:: | `resources` | `object` -| `resources` are the compute resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| `resources` are the compute resources required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +| `subnetLabels` +| `object` +| `subnetLabels` allows to define custom labels on subnets and IPs or to enable automatic labelling of recognized subnets in {product-title}, which is used to identify cluster external traffic. +When a subnet matches the source or destination IP of a flow, a corresponding field is added: `SrcSubnetLabel` or `DstSubnetLabel`. |=== == .spec.processor.advanced 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` env vars. Set these values at your own risk. +`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` env vars. Set these values at your own risk. -- Type:: @@ -1895,7 +2332,8 @@ Type:: | `conversationEndTimeout` | `string` -| `conversationEndTimeout` is the time to wait after a network flow is received, to consider the conversation ended. This delay is ignored when a FIN packet is collected for TCP flows (see `conversationTerminatingTimeout` instead). +| `conversationEndTimeout` is the time to wait after a network flow is received, to consider the conversation ended. +This delay is ignored when a FIN packet is collected for TCP flows (see `conversationTerminatingTimeout` instead). | `conversationHeartbeatInterval` | `string` @@ -1907,7 +2345,7 @@ Type:: | `dropUnusedFields` | `boolean` -| `dropUnusedFields` allows, when set to `true`, to drop fields that are known to be unused by OVS, to save storage space. +| `dropUnusedFields` [deprecated (*)] this setting is not used anymore. | `enableKubeProbes` | `boolean` @@ -1915,7 +2353,10 @@ Type:: | `env` | `object (string)` -| `env` allows passing custom environment variables to underlying components. Useful for passing some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be publicly exposed as part of the FlowCollector descriptor, as they are only useful in edge debug or support scenarios. +| `env` allows passing custom environment variables to underlying components. Useful for passing +some very concrete performance-tuning options, such as `GOGC` and `GOMAXPROCS`, that should not be +publicly exposed as part of the FlowCollector descriptor, as they are only useful +in edge debug or support scenarios. | `healthPort` | `integer` @@ -1923,18 +2364,89 @@ Type:: | `port` | `integer` -| Port of the flow collector (host port). By convention, some values are forbidden. It must be greater than 1024 and different from 4500, 4789 and 6081. +| Port of the flow collector (host port). +By convention, some values are forbidden. It must be greater than 1024 and different from +4500, 4789 and 6081. | `profilePort` | `integer` | `profilePort` allows setting up a Go pprof profiler listening to this port +| `scheduling` +| `object` +| scheduling controls how the pods are scheduled on nodes. + |=== +== .spec.processor.advanced.scheduling +Description:: ++ +-- +scheduling controls how the pods are scheduled on nodes. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `affinity` +| `object` +| If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +| `nodeSelector` +| `object (string)` +| `nodeSelector` allows scheduling of pods only onto nodes that have each of the specified labels. +For documentation, refer to https://kubernetes.io/docs/concepts/configuration/assign-pod-node/. + +| `priorityClassName` +| `string` +| If specified, indicates the pod's priority. For documentation, refer to https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#how-to-use-priority-and-preemption. +If not specified, default priority is used, or zero if there is no default. + +| `tolerations` +| `array` +| `tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. + +|=== +== .spec.processor.advanced.scheduling.affinity +Description:: ++ +-- +If specified, the pod's scheduling constraints. For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `object` + + + + +== .spec.processor.advanced.scheduling.tolerations +Description:: ++ +-- +`tolerations` is a list of tolerations that allow the pod to schedule onto nodes with matching taints. +For documentation, refer to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling. +-- + +Type:: + `array` + + + + == .spec.processor.kafkaConsumerAutoscaler Description:: + -- -`kafkaConsumerAutoscaler` is the spec of a horizontal pod autoscaler to set up for `flowlogs-pipeline-transformer`, which consumes Kafka messages. This setting is ignored when Kafka is disabled. Refer to HorizontalPodAutoscaler documentation (autoscaling/v2). +`kafkaConsumerAutoscaler` is the spec of a horizontal pod autoscaler to set up for `flowlogs-pipeline-transformer`, which consumes Kafka messages. +This setting is ignored when Kafka is disabled. Refer to HorizontalPodAutoscaler documentation (autoscaling/v2). -- Type:: @@ -1962,14 +2474,24 @@ Type:: | `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 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. + | `includeList` | `array (string)` -| `includeList` is a list of metric names to specify which ones to generate. The names correspond to the names in Prometheus without the prefix. For example, `namespace_egress_packets_total` shows up as `netobserv_namespace_egress_packets_total` in Prometheus. Note that the more metrics you add, the bigger is the impact on Prometheus workload resources. Metrics enabled by default are: `namespace_flows_total`, `node_ingress_bytes_total`, `workload_ingress_bytes_total`, `namespace_drop_packets_total` (when `PacketDrop` feature is enabled), `namespace_rtt_seconds` (when `FlowRTT` feature is enabled), `namespace_dns_latency_seconds` (when `DNSTracking` feature is enabled). More information, with full list of available metrics: https://github.com/netobserv/network-observability-operator/blob/main/docs/Metrics.md +| `includeList` is a list of metric names to specify which ones to generate. +The names correspond to the names in Prometheus without the prefix. For example, +`namespace_egress_packets_total` shows up as `netobserv_namespace_egress_packets_total` in Prometheus. +Note that the more metrics you add, the bigger is the impact on Prometheus workload resources. +Metrics enabled by default are: +`namespace_flows_total`, `node_ingress_bytes_total`, `workload_ingress_bytes_total`, `namespace_drop_packets_total` (when `PacketDrop` feature is enabled), +`namespace_rtt_seconds` (when `FlowRTT` feature is enabled), `namespace_dns_latency_seconds` (when `DNSTracking` feature is enabled). +More information, with full list of available metrics: https://github.com/netobserv/network-observability-operator/blob/main/docs/Metrics.md | `server` | `object` @@ -1995,7 +2517,7 @@ Type:: | `port` | `integer` -| The prometheus HTTP port +| The metrics server HTTP port. | `tls` | `object` @@ -2021,7 +2543,8 @@ Type:: | `insecureSkipVerify` | `boolean` -| `insecureSkipVerify` allows skipping client-side verification of the provided certificate. If set to `true`, the `providedCaFile` field is ignored. +| `insecureSkipVerify` allows skipping client-side verification of the provided certificate. +If set to `true`, the `providedCaFile` field is ignored. | `provided` | `object` @@ -2034,7 +2557,10 @@ Type:: | `type` | `string` | Select the type of TLS configuration: + - - `Disabled` (default) to not configure TLS for the endpoint. - `Provided` to manually provide cert file and a key file. - `Auto` to use {product-title} auto generated certificate using annotations. + +- `Disabled` (default) to not configure TLS for the endpoint. +- `Provided` to manually provide cert file and a key file. [Unsupported (*)]. +- `Auto` to use {product-title} auto generated certificate using annotations. |=== == .spec.processor.metrics.server.tls.provided @@ -2056,7 +2582,7 @@ Type:: | `certFile` | `string` -| `certFile` defines the path to the certificate file name within the config map or secret +| `certFile` defines the path to the certificate file name within the config map or secret. | `certKey` | `string` @@ -2064,15 +2590,16 @@ Type:: | `name` | `string` -| Name of the config map or secret containing certificates +| Name of the config map or secret containing certificates. | `namespace` | `string` -| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the certificate reference: `configmap` or `secret` +| Type for the certificate reference: `configmap` or `secret`. |=== == .spec.processor.metrics.server.tls.providedCaFile @@ -2094,26 +2621,28 @@ Type:: | `file` | `string` -| File name within the config map or secret +| File name within the config map or secret. | `name` | `string` -| Name of the config map or secret containing the file +| Name of the config map or secret containing the file. | `namespace` | `string` -| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. If the namespace is different, the config map or the secret is copied so that it can be mounted as required. +| Namespace of the config map or secret containing the file. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. | `type` | `string` -| Type for the file reference: "configmap" or "secret" +| Type for the file reference: "configmap" or "secret". |=== == .spec.processor.resources Description:: + -- -`resources` are the compute resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +`resources` are the compute resources required by this container. +For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ -- Type:: @@ -2128,10 +2657,295 @@ Type:: | `limits` | `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| Limits describes the maximum amount of compute resources allowed. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | `requests` | `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +| Requests describes the minimum amount of compute resources required. +If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, +otherwise to an implementation-defined value. Requests cannot exceed Limits. +More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +|=== +== .spec.processor.subnetLabels +Description:: ++ +-- +`subnetLabels` allows to define custom labels on subnets and IPs or to enable automatic labelling of recognized subnets in {product-title}, which is used to identify cluster external traffic. +When a subnet matches the source or destination IP of a flow, a corresponding field is added: `SrcSubnetLabel` or `DstSubnetLabel`. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `customLabels` +| `array` +| `customLabels` allows to customize subnets and IPs labelling, such as to identify cluster-external workloads or web services. +If you enable `openShiftAutoDetect`, `customLabels` can override the detected subnets in case they overlap. + +| `openShiftAutoDetect` +| `boolean` +| `openShiftAutoDetect` allows, when set to `true`, to detect automatically the machines, pods and services subnets based on the +{product-title} install configuration and the Cluster Network Operator configuration. Indirectly, this is a way to accurately detect +external traffic: flows that are not labeled for those subnets are external to the cluster. Enabled by default on {product-title}. + +|=== +== .spec.processor.subnetLabels.customLabels +Description:: ++ +-- +`customLabels` allows to customize subnets and IPs labelling, such as to identify cluster-external workloads or web services. +If you enable `openShiftAutoDetect`, `customLabels` can override the detected subnets in case they overlap. +-- + +Type:: + `array` + + + + +== .spec.processor.subnetLabels.customLabels[] +Description:: ++ +-- +SubnetLabel allows to label subnets and IPs, such as to identify cluster-external workloads or web services. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `cidrs` +| `array (string)` +| List of CIDRs, such as `["1.2.3.4/32"]`. + +| `name` +| `string` +| Label name, used to flag matching flows. + +|=== +== .spec.prometheus +Description:: ++ +-- +`prometheus` defines Prometheus settings, such as querier configuration used to fetch metrics from the Console plugin. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `querier` +| `object` +| Prometheus querying configuration, such as client settings, used in the Console plugin. + +|=== +== .spec.prometheus.querier +Description:: ++ +-- +Prometheus querying configuration, such as client settings, used in the Console plugin. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `enable` +| `boolean` +| When `enable` is `true`, the Console plugin queries flow metrics from Prometheus instead of Loki whenever possible. +It is enbaled by default: set it to `false` to disable this feature. +The Console plugin can use either Loki or Prometheus as a data source for metrics (see also `spec.loki`), or both. +Not all queries are transposable from Loki to Prometheus. Hence, if Loki is disabled, some features of the plugin are disabled as well, +such as getting per-pod information or viewing raw flows. +If both Prometheus and Loki are enabled, Prometheus takes precedence and Loki is used as a fallback for queries that Prometheus cannot handle. +If they are both disabled, the Console plugin is not deployed. + +| `manual` +| `object` +| Prometheus configuration for `Manual` mode. + +| `mode` +| `string` +| `mode` must be set according to the type of Prometheus installation that stores Network Observability metrics: + + +- Use `Auto` to try configuring automatically. In {product-title}, it uses the Thanos querier from {product-title} Cluster Monitoring + + +- Use `Manual` for a manual setup + + + +| `timeout` +| `string` +| `timeout` is the read timeout for console plugin queries to Prometheus. +A timeout of zero means no timeout. + +|=== +== .spec.prometheus.querier.manual +Description:: ++ +-- +Prometheus configuration for `Manual` mode. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `forwardUserToken` +| `boolean` +| Set `true` to forward logged in user token in queries to Prometheus + +| `tls` +| `object` +| TLS client configuration for Prometheus URL. + +| `url` +| `string` +| `url` is the address of an existing Prometheus service to use for querying metrics. + +|=== +== .spec.prometheus.querier.manual.tls +Description:: ++ +-- +TLS client configuration for Prometheus URL. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `caCert` +| `object` +| `caCert` defines the reference of the certificate for the Certificate Authority + +| `enable` +| `boolean` +| Enable TLS + +| `insecureSkipVerify` +| `boolean` +| `insecureSkipVerify` allows skipping client-side verification of the server certificate. +If set to `true`, the `caCert` field is ignored. + +| `userCert` +| `object` +| `userCert` defines the user certificate reference and is used for mTLS (you can ignore it when using one-way TLS) + +|=== +== .spec.prometheus.querier.manual.tls.caCert +Description:: ++ +-- +`caCert` defines the reference of the certificate for the Certificate Authority +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `certFile` +| `string` +| `certFile` defines the path to the certificate file name within the config map or secret. + +| `certKey` +| `string` +| `certKey` defines the path to the certificate private key file name within the config map or secret. Omit when the key is not necessary. + +| `name` +| `string` +| Name of the config map or secret containing certificates. + +| `namespace` +| `string` +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. + +| `type` +| `string` +| Type for the certificate reference: `configmap` or `secret`. + +|=== +== .spec.prometheus.querier.manual.tls.userCert +Description:: ++ +-- +`userCert` defines the user certificate reference and is used for mTLS (you can ignore it when using one-way TLS) +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `certFile` +| `string` +| `certFile` defines the path to the certificate file name within the config map or secret. + +| `certKey` +| `string` +| `certKey` defines the path to the certificate private key file name within the config map or secret. Omit when the key is not necessary. + +| `name` +| `string` +| Name of the config map or secret containing certificates. + +| `namespace` +| `string` +| Namespace of the config map or secret containing certificates. If omitted, the default is to use the same namespace as where Network Observability is deployed. +If the namespace is different, the config map or the secret is copied so that it can be mounted as required. + +| `type` +| `string` +| Type for the certificate reference: `configmap` or `secret`. |=== \ No newline at end of file diff --git a/modules/network-observability-flowmetric-api-specifications.adoc b/modules/network-observability-flowmetric-api-specifications.adoc new file mode 100644 index 0000000000..3bcc0f41db --- /dev/null +++ b/modules/network-observability-flowmetric-api-specifications.adoc @@ -0,0 +1,298 @@ +// Automatically generated by 'openshift-apidocs-gen'. Do not edit. +:_mod-docs-content-type: REFERENCE +[id="flowmetric-flows-netobserv-io-v1alpha1"] += FlowMetric [flows.netobserv.io/v1alpha1] + + + +Description:: ++ +-- +FlowMetric is the API allowing to create custom metrics from the collected flow logs. +-- + +Type:: + `object` + + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `apiVersion` +| `string` +| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and might reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +| `kind` +| `string` +| Kind is a string value representing the REST resource this object represents. Servers might infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +| `metadata` +| `object` +| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +| `spec` +| `object` +| FlowMetricSpec defines the desired state of FlowMetric +The provided API allows you to customize these metrics according to your needs. + + +When adding new metrics or modifying existing labels, you must carefully monitor the memory +usage of Prometheus workloads as this could potentially have a high impact. Cf https://rhobs-handbook.netlify.app/products/openshiftmonitoring/telemetry.md/#what-is-the-cardinality-of-a-metric + + +To check the cardinality of all Network Observability metrics, run as `promql`: `count({__name__=~"netobserv.*"}) by (__name__)`. + +|=== +== .metadata +Description:: ++ +-- +Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +-- + +Type:: + `object` + + + + +== .spec +Description:: ++ +-- +FlowMetricSpec defines the desired state of FlowMetric +The provided API allows you to customize these metrics according to your needs. + + +When adding new metrics or modifying existing labels, you must carefully monitor the memory +usage of Prometheus workloads as this could potentially have a high impact. Cf https://rhobs-handbook.netlify.app/products/openshiftmonitoring/telemetry.md/#what-is-the-cardinality-of-a-metric + + +To check the cardinality of all Network Observability metrics, run as `promql`: `count({__name__=~"netobserv.*"}) by (__name__)`. +-- + +Type:: + `object` + +Required:: + - `metricName` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `buckets` +| `array (string)` +| A list of buckets to use when `type` is "Histogram". The list must be parsable as floats. When not set, Prometheus default buckets are used. + +| `charts` +| `array` +| Charts configuration, for the {product-title} Console in the administrator view, Dashboards menu. + +| `direction` +| `string` +| Filter for ingress, egress or any direction flows. +When set to `Ingress`, it is equivalent to adding the regular expression filter on `FlowDirection`: `0\|2`. +When set to `Egress`, it is equivalent to adding the regular expression filter on `FlowDirection`: `1\|2`. + +| `divider` +| `string` +| When nonzero, scale factor (divider) of the value. Metric value = Flow value / Divider. + +| `filters` +| `array` +| `filters` is a list of fields and values used to restrict which flows are taken into account. Oftentimes, these filters must +be used to eliminate duplicates: `Duplicate != "true"` and `FlowDirection = "0"`. +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. + +| `labels` +| `array (string)` +| `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions. +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. + +| `metricName` +| `string` +| Name of the metric. In Prometheus, it is automatically prefixed with "netobserv_". + +| `type` +| `string` +| Metric type: "Counter" or "Histogram". +Use "Counter" for any value that increases over time and on which you can compute a rate, such as Bytes or Packets. +Use "Histogram" for any value that must be sampled independently, such as latencies. + +| `valueField` +| `string` +| `valueField` is the flow field that must be used as a value for this metric. 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. + +|=== +== .spec.charts +Description:: ++ +-- +Charts configuration, for the {product-title} Console in the administrator view, Dashboards menu. +-- + +Type:: + `array` + + + + +== .spec.charts[] +Description:: ++ +-- +Configures charts / dashboard generation associated to a metric +-- + +Type:: + `object` + +Required:: + - `dashboardName` + - `queries` + - `title` + - `type` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `dashboardName` +| `string` +| Name of the containing dashboard. If this name does not refer to an existing dashboard, a new dashboard is created. + +| `queries` +| `array` +| List of queries to be displayed on this chart. If `type` is `SingleStat` and multiple queries are provided, +this chart is automatically expanded in several panels (one per query). + +| `sectionName` +| `string` +| Name of the containing dashboard section. If this name does not refer to an existing section, a new section is created. +If `sectionName` is omitted or empty, the chart is placed in the global top section. + +| `title` +| `string` +| Title of the chart. + +| `type` +| `string` +| Type of the chart. + +| `unit` +| `string` +| Unit of this chart. Only a few units are currently supported. Leave empty to use generic number. + +|=== +== .spec.charts[].queries +Description:: ++ +-- +List of queries to be displayed on this chart. If `type` is `SingleStat` and multiple queries are provided, +this chart is automatically expanded in several panels (one per query). +-- + +Type:: + `array` + + + + +== .spec.charts[].queries[] +Description:: ++ +-- +Configures PromQL queries +-- + +Type:: + `object` + +Required:: + - `legend` + - `promQL` + - `top` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `legend` +| `string` +| The query legend that applies to each timeseries represented in this chart. When multiple timeseries are displayed, you should set a legend +that distinguishes each of them. It can be done with the following format: `{{ Label }}`. For example, if the `promQL` groups timeseries per +label such as: `sum(rate($METRIC[2m])) by (Label1, Label2)`, you might write as the legend: `Label1={{ Label1 }}, Label2={{ Label2 }}`. + +| `promQL` +| `string` +| The `promQL` query to be run against Prometheus. If the chart `type` is `SingleStat`, this query should only return +a single timeseries. For other types, a top 7 is displayed. +You can use `$METRIC` to refer to the metric defined in this resource. For example: `sum(rate($METRIC[2m]))`. +To learn more about `promQL`, refer to the Prometheus documentation: https://prometheus.io/docs/prometheus/latest/querying/basics/ + +| `top` +| `integer` +| Top N series to display per timestamp. Does not apply to `SingleStat` chart type. + +|=== +== .spec.filters +Description:: ++ +-- +`filters` is a list of fields and values used to restrict which flows are taken into account. Oftentimes, these filters must +be used to eliminate duplicates: `Duplicate != "true"` and `FlowDirection = "0"`. +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. +-- + +Type:: + `array` + + + + +== .spec.filters[] +Description:: ++ +-- + +-- + +Type:: + `object` + +Required:: + - `field` + - `matchType` + + + +[cols="1,1,1",options="header"] +|=== +| Property | Type | Description + +| `field` +| `string` +| Name of the field to filter on + +| `matchType` +| `string` +| Type of matching to apply + +| `value` +| `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. + +|=== \ No newline at end of file diff --git a/modules/network-observability-flowmetrics-charts.adoc b/modules/network-observability-flowmetrics-charts.adoc new file mode 100644 index 0000000000..ff0aef792c --- /dev/null +++ b/modules/network-observability-flowmetrics-charts.adoc @@ -0,0 +1,112 @@ +// Module included in the following assemblies: +// +// network_observability/metrics-alerts-dashboards.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-custom-charts-flowmetrics_{context}"] += Configuring custom charts using FlowMetric API +You can generate charts for dashboards in the {product-title} web console, which you can view as an administrator in the *Dashboard* menu by defining the `charts` section of the `FlowMetric` resource. + +.Procedure +. In the web console, navigate to *Operators* -> *Installed Operators*. +. In the *Provided APIs* heading for the *NetObserv Operator*, select *FlowMetric*. +. In the *Project:* dropdown list, select the project of the Network Observability Operator instance. +. Click *Create FlowMetric*. +. Configure the `FlowMetric` resource, similar to the following sample configurations: + +.Chart for tracking ingress bytes received from cluster external sources +[%collapsible] +==== +[source,yaml] +---- +apiVersion: flows.netobserv.io/v1alpha1 +kind: FlowMetric +metadata: + name: flowmetric-cluster-external-ingress-traffic + namespace: netobserv <1> +# ... + charts: + - dashboardName: Main <2> + title: External ingress traffic + unit: Bps + type: SingleStat + queries: + - promQL: "sum(rate($METRIC[2m]))" + legend: "" + - dashboardName: Main <2> + sectionName: External + title: Top external ingress traffic per workload + unit: Bps + type: StackArea + queries: + - promQL: "sum(rate($METRIC{DstK8S_Namespace!=\"\"}[2m])) by (DstK8S_Namespace, DstK8S_OwnerName)" + legend: "{{DstK8S_Namespace}} / {{DstK8S_OwnerName}}" +# ... +---- +<1> The `FlowMetric` resources need to be created in the namespace defined in the `FlowCollector` `spec.namespace`, which is `netobserv` by default. + +.Verification +. Once the pods refresh, navigate to *Observe* -> *Dashboards*. +. Search for the *NetObserv / Main* dashboard. View two panels under the *NetObserv / Main* dashboard, or optionally a dashboard name that you create: + +* A textual single statistic showing the global external ingress rate summed across all dimensions +* A timeseries graph showing the same metric per destination workload + +For more information about the query language, refer to the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus documentation]. +==== + +.Chart for RTT latency for cluster external ingress traffic +[%collapsible] +==== +[source,yaml] +---- +apiVersion: flows.netobserv.io/v1alpha1 +kind: FlowMetric +metadata: + name: flowmetric-cluster-external-ingress-traffic + namespace: netobserv <1> +# ... + charts: + - dashboardName: Main <2> + title: External ingress TCP latency + unit: seconds + type: SingleStat + queries: + - promQL: "histogram_quantile(0.99, sum(rate($METRIC_bucket[2m])) by (le)) > 0" + legend: "p99" + - dashboardName: Main <2> + sectionName: External + title: "Top external ingress sRTT per workload, p50 (ms)" + unit: seconds + type: Line + queries: + - promQL: "histogram_quantile(0.5, sum(rate($METRIC_bucket{DstK8S_Namespace!=\"\"}[2m])) by (le,DstK8S_Namespace,DstK8S_OwnerName))*1000 > 0" + legend: "{{DstK8S_Namespace}} / {{DstK8S_OwnerName}}" + - dashboardName: Main <2> + sectionName: External + title: "Top external ingress sRTT per workload, p99 (ms)" + unit: seconds + type: Line + queries: + - promQL: "histogram_quantile(0.99, sum(rate($METRIC_bucket{DstK8S_Namespace!=\"\"}[2m])) by (le,DstK8S_Namespace,DstK8S_OwnerName))*1000 > 0" + legend: "{{DstK8S_Namespace}} / {{DstK8S_OwnerName}}" +# ... +---- +<1> The `FlowMetric` resources need to be created in the namespace defined in the `FlowCollector` `spec.namespace`, which is `netobserv` by default. +<2> Using a different `dashboardName` creates a new dashboard that is prefixed with `Netobserv`. For example, *Netobserv / *. + +This example uses the `histogram_quantile` function to show `p50` and `p99`. + +You can show averages of histograms by dividing the metric, `$METRIC_sum`, by the metric ,`$METRIC_count`, which are automatically generated when you create a histogram. With the preceding example, the Prometheus query to do this is as follows: + +[source,yaml] +---- +promQL: "(sum(rate($METRIC_sum{DstK8S_Namespace!=\"\"}[2m])) by (DstK8S_Namespace,DstK8S_OwnerName) / sum(rate($METRIC_count{DstK8S_Namespace!=\"\"}[2m])) by (DstK8S_Namespace,DstK8S_OwnerName))*1000" +---- + +.Verification +. Once the pods refresh, navigate to *Observe* -> *Dashboards*. +. Search for the *NetObserv / Main* dashboard. View the new panel under the *NetObserv / Main* dashboard, or optionally a dashboard name that you create. + +For more information about the query language, refer to the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus documentation]. +==== diff --git a/modules/network-observability-flows-format.adoc b/modules/network-observability-flows-format.adoc index 47367884ea..72241cf6ab 100644 --- a/modules/network-observability-flows-format.adoc +++ b/modules/network-observability-flows-format.adoc @@ -9,105 +9,131 @@ The "Filter ID" column shows which related name to use when defining Quick Filte The "Loki label" column is useful when querying Loki directly: label fields need to be selected using link:https://grafana.com/docs/loki/latest/logql/log_queries/#log-stream-selector[stream selectors]. +The "Cardinality" column gives information about the implied metric cardinality if this field was to be used as a Prometheus label with the `FlowMetric` API. For more information, see the "FlowMetric API reference". -[cols="1,1,3,1,1",options="header"] +[cols="1,1,3,1,1,1",options="header"] |=== -| Name | Type | Description | Filter ID | Loki label +| Name | Type | Description | Filter ID | Loki label | Cardinality | `Bytes` | number | Number of bytes | n/a | no +| avoid | `DnsErrno` | number | Error number returned from DNS tracker ebpf hook function | `dns_errno` | no +| fine | `DnsFlags` | number | DNS flags for DNS record | n/a | no +| fine | `DnsFlagsResponseCode` | string | Parsed DNS header RCODEs name | `dns_flag_response_code` | no +| fine | `DnsId` | number | DNS record id | `dns_id` | no +| avoid | `DnsLatencyMs` | number | Time between a DNS request and response, in milliseconds | `dns_latency` | no +| avoid | `Dscp` | number | Differentiated Services Code Point (DSCP) value | `dscp` | no +| fine | `DstAddr` | string | Destination IP address (ipv4 or ipv6) | `dst_address` | no +| avoid | `DstK8S_HostIP` | string | Destination node IP | `dst_host_address` | no +| fine | `DstK8S_HostName` | string | Destination node name | `dst_host_name` | no +| fine | `DstK8S_Name` | string | Name of the destination Kubernetes object, such as Pod name, Service name or Node name. | `dst_name` | no +| careful | `DstK8S_Namespace` | string | Destination namespace | `dst_namespace` | yes +| fine | `DstK8S_OwnerName` | string | Name of the destination owner, such as Deployment name, StatefulSet name, etc. | `dst_owner_name` | yes +| fine | `DstK8S_OwnerType` | string | Kind of the destination owner, such as Deployment, StatefulSet, etc. | `dst_kind` | no +| fine | `DstK8S_Type` | string | Kind of the destination Kubernetes object, such as Pod, Service or Node. | `dst_kind` | yes +| fine | `DstK8S_Zone` | string | Destination availability zone | `dst_zone` | yes +| fine | `DstMac` | string | Destination MAC address | `dst_mac` | no +| avoid | `DstPort` | number | Destination port | `dst_port` | no +| careful +| `DstSubnetLabel` +| string +| Destination subnet label +| `dst_subnet_label` +| no +| fine | `Duplicate` | boolean | Indicates if this flow was also captured from another interface on the same host | n/a | yes +| fine | `Flags` | number | Logical OR combination of unique TCP flags comprised in the flow, as per RFC-9293, with additional custom flags to represent the following per-packet combinations: + @@ -116,164 +142,202 @@ The "Loki label" column is useful when querying Loki directly: label fields need - RST+ACK (0x400) | n/a | no +| fine | `FlowDirection` | number -| Flow direction from the node observation point. Can be one of: + +| Flow interpreted direction from the node observation point. Can be one of: + - 0: Ingress (incoming traffic, from the node observation point) + - 1: Egress (outgoing traffic, from the node observation point) + - 2: Inner (with the same source and destination node) -| `direction` +| `node_direction` | yes +| fine | `IcmpCode` | number | ICMP code | `icmp_code` | no +| fine | `IcmpType` | number | ICMP type | `icmp_type` | no -| `IfDirection` +| fine +| `IfDirections` | number -| Flow direction from the network interface observation point. Can be one of: + +| Flow directions from the network interface observation point. Can be one of: + - 0: Ingress (interface incoming traffic) + - 1: Egress (interface outgoing traffic) -| n/a +| `ifdirections` | no -| `Interface` +| fine +| `Interfaces` | string -| Network interface -| `interface` +| Network interfaces +| `interfaces` | no +| careful | `K8S_ClusterName` | string | Cluster name or identifier | `cluster_name` | yes +| fine | `K8S_FlowLayer` | string | Flow layer: 'app' or 'infra' | `flow_layer` | no +| fine | `Packets` | number | Number of packets | n/a | no +| avoid | `PktDropBytes` | number | Number of bytes dropped by the kernel | n/a | no +| avoid | `PktDropLatestDropCause` | string | Latest drop cause | `pkt_drop_cause` | no +| fine | `PktDropLatestFlags` | number | TCP flags on last dropped packet | n/a | no +| fine | `PktDropLatestState` | string | TCP state on last dropped packet | `pkt_drop_state` | no +| fine | `PktDropPackets` | number | Number of packets dropped by the kernel | n/a | no +| avoid | `Proto` | number | L4 protocol | `protocol` | no +| fine | `SrcAddr` | string | Source IP address (ipv4 or ipv6) | `src_address` | no +| avoid | `SrcK8S_HostIP` | string | Source node IP | `src_host_address` | no +| fine | `SrcK8S_HostName` | string | Source node name | `src_host_name` | no +| fine | `SrcK8S_Name` | string | Name of the source Kubernetes object, such as Pod name, Service name or Node name. | `src_name` | no +| careful | `SrcK8S_Namespace` | string | Source namespace | `src_namespace` | yes +| fine | `SrcK8S_OwnerName` | string | Name of the source owner, such as Deployment name, StatefulSet name, etc. | `src_owner_name` | yes +| fine | `SrcK8S_OwnerType` | string | Kind of the source owner, such as Deployment, StatefulSet, etc. | `src_kind` | no +| fine | `SrcK8S_Type` | string | Kind of the source Kubernetes object, such as Pod, Service or Node. | `src_kind` | yes +| fine | `SrcK8S_Zone` | string | Source availability zone | `src_zone` | yes +| fine | `SrcMac` | string | Source MAC address | `src_mac` | no +| avoid | `SrcPort` | number | Source port | `src_port` | no +| careful +| `SrcSubnetLabel` +| string +| Source subnet label +| `src_subnet_label` +| no +| fine | `TimeFlowEndMs` | number | End timestamp of this flow, in milliseconds | n/a | no +| avoid | `TimeFlowRttNs` | number | TCP Smoothed Round Trip Time (SRTT), in nanoseconds | `time_flow_rtt` | no +| avoid | `TimeFlowStartMs` | number | Start timestamp of this flow, in milliseconds | n/a | no +| avoid | `TimeReceived` | number | Timestamp when this flow was received and processed by the flow collector, in seconds | n/a | no +| avoid | `_HashId` | string | In conversation tracking, the conversation identifier | `id` | no +| avoid | `_RecordType` | string | Type of record: 'flowLog' for regular flow logs, or 'newConnection', 'heartbeat', 'endConnection' for conversation tracking | `type` | yes +| fine |=== \ No newline at end of file diff --git a/modules/network-observability-health-alerts-overview.adoc b/modules/network-observability-health-alerts-overview.adoc new file mode 100644 index 0000000000..ee06e061fd --- /dev/null +++ b/modules/network-observability-health-alerts-overview.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * network_observability/network-observability-operator-monitoring.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-observability-health-alert-overview_{context}"] += Health alerts + +A health alert banner that directs you to the dashboard can appear on the *Network Traffic* and *Home* pages if an alert is triggered. Alerts are generated in the following cases: + +* The `NetObservLokiError` alert occurs if the `flowlogs-pipeline` workload is dropping flows because of Loki errors, such as if the Loki ingestion rate limit has been reached. +* The `NetObservNoFlows` alert occurs if no flows are ingested for a certain amount of time. +* The `NetObservFlowsDropped` alert occurs if the Network Observability eBPF agent hashmap table is full, and the eBPF agent processes flows with degraded performance, or when the capacity limiter is triggered. \ No newline at end of file diff --git a/modules/network-observability-health-dashboard-overview.adoc b/modules/network-observability-health-dashboard-overview.adoc new file mode 100644 index 0000000000..78729968d4 --- /dev/null +++ b/modules/network-observability-health-dashboard-overview.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * network_observability/network-observability-operator-monitoring.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-observability-health-dashboard-overview_{context}"] += Health dashboards + +Metrics about health and resource usage of the Network Observability Operator are located in the *Observe* -> *Dashboards* page in the web console. You can view metrics about the health of the Operator in the following categories: + +* *Flows per second* +* *Sampling* +* *Errors last minute* +* *Dropped flows per second* +* *Flowlogs-pipeline statistics* +* *Flowlogs-pipleine statistics views* +* *eBPF agent statistics views* +* *Operator statistics* +* *Resource usage* \ No newline at end of file diff --git a/modules/network-observability-metrics.adoc b/modules/network-observability-metrics-names.adoc similarity index 77% rename from modules/network-observability-metrics.adoc rename to modules/network-observability-metrics-names.adoc index 9ecab20728..c2555fe716 100644 --- a/modules/network-observability-metrics.adoc +++ b/modules/network-observability-metrics-names.adoc @@ -5,13 +5,11 @@ :_mod-docs-content-type: REFERENCE [id="network-observability-metrics_{context}"] = Network Observability metrics -Metrics generated by the `flowlogs-pipeline` are configurable in the `spec.processor.metrics.includeList` of the `FlowCollector` custom resource to add or remove metrics. - You can also create alerts by using the `includeList` metrics in Prometheus rules, as shown in the example "Creating alerts". -When looking for these metrics in Prometheus, such as in the Console through Observe -> Metrics, or when defining alerts, all the metrics names are prefixed with `netobserv_. For example, `netobserv_namespace_flows_total. Available metrics names are as follows. +When looking for these metrics in Prometheus, such as in the Console through *Observe* -> *Metrics*, or when defining alerts, all the metrics names are prefixed with `netobserv_`. For example, `netobserv_namespace_flows_total`. Available metrics names are as follows: -== includeList metrics names +includeList metrics names:: Names followed by an asterisk `*` are enabled by default. * `namespace_egress_bytes_total` @@ -30,7 +28,7 @@ Names followed by an asterisk `*` are enabled by default. * `workload_ingress_packets_total` * `workload_flows_total` -=== PacketDrop metrics names +PacketDrop metrics names:: When the `PacketDrop` feature is enabled in `spec.agent.ebpf.features` (with `privileged` mode), the following additional metrics are available: * `namespace_drop_bytes_total` @@ -40,14 +38,14 @@ When the `PacketDrop` feature is enabled in `spec.agent.ebpf.features` (with `pr * `workload_drop_bytes_total` * `workload_drop_packets_total` -=== DNS metrics names +DNS metrics names:: When the `DNSTracking` feature is enabled in `spec.agent.ebpf.features`, the following additional metrics are available: * `namespace_dns_latency_seconds` * * `node_dns_latency_seconds` * `workload_dns_latency_seconds` -=== FlowRTT metrics names +FlowRTT metrics names:: When the `FlowRTT` feature is enabled in `spec.agent.ebpf.features`, the following additional metrics are available: * `namespace_rtt_seconds` * diff --git a/modules/network-observability-netobserv-cli-about.adoc b/modules/network-observability-netobserv-cli-about.adoc new file mode 100644 index 0000000000..e0005e75dc --- /dev/null +++ b/modules/network-observability-netobserv-cli-about.adoc @@ -0,0 +1,14 @@ +//Module included in the following assemblies: +// +// observability/network_observability/network-observability-cli/netobserv-cli-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-observability-netoberv-cli-about_{context}"] += About the Network Observability CLI + +You can quickly debug and troubleshoot networking issues by using the Network Observability CLI (`oc netobserv`). The Network Observability CLI is a flow and packet visualization tool that relies on eBPF agents to stream collected data to an ephemeral collector pod. It requires no persistent storage during the capture. After the run, the output is transferred to your local machine. This enables quick, live insight into packets and flow data without installing the Network Observability Operator. + +[IMPORTANT] +==== +CLI capture is meant to run only for short durations, such as 8-10 minutes. If it runs for too long, it can be difficult to delete the running process. +==== \ No newline at end of file diff --git a/modules/network-observability-netobserv-cli-cleaning.adoc b/modules/network-observability-netobserv-cli-cleaning.adoc new file mode 100644 index 0000000000..600d037571 --- /dev/null +++ b/modules/network-observability-netobserv-cli-cleaning.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: + +// * observability/network_observability/netobserv_cli/netobserv-cli-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-cli-uninstall_{context}"] += Cleaning the Network Observability CLI + +You can manually clean the CLI workload by running `oc netobserv cleanup`. This command removes all the CLI components from your cluster. + +When you end a capture, this command is run automatically by the client. You might be required to manually run it if you experience connectivity issues. + +.Procedure +* Run the following command: ++ +[source,terminal] +---- +$ oc netobserv cleanup +---- \ No newline at end of file diff --git a/modules/network-observability-netobserv-cli-install.adoc b/modules/network-observability-netobserv-cli-install.adoc new file mode 100644 index 0000000000..f7e720fdf8 --- /dev/null +++ b/modules/network-observability-netobserv-cli-install.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: + +// * observability/network_observability/netobserv_cli/netobserv-cli-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="network-observability-cli-install_{context}"] += Installing the Network Observability CLI +Installing the Network Observability CLI (`oc netobserv`) is a separate procedure from the Network Observability Operator installation. This means that, even if you have the Operator installed from OperatorHub, you need to install the CLI separately. + +[NOTE] +==== +You can optionally use Krew to install the `netobserv` CLI plugin. For more information, see "Installing a CLI plugin with Krew". +==== + +.Prerequisites +* You must install the {oc-first}. +* You must have a macOS or Linux operating system. + +.Procedure + +. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/netobserv/latest/[`oc netobserv` CLI tar file]. +. Unpack the archive: ++ +[source,terminal] +---- +$ tar xvf netobserv-cli.tar.gz +---- +. Make the file executable: ++ +[source,terminal] +---- +$ chmod +x ./build/oc-netobserv +---- +. Move the extracted `netobserv-cli` binary to a directory that is on your `PATH`, such as `/usr/local/bin/`: ++ +[source,terminal] +---- +$ sudo mv ./build/oc-netobserv /usr/local/bin/ +---- + +.Verification + +* Verify that `oc netobserv` is available: ++ +[source,terminal] +---- +$ oc netobserv version +---- ++ +.Example output +[source,terminal] +---- +Netobserv CLI version +---- diff --git a/modules/network-observability-netobserv-cli-reference.adoc b/modules/network-observability-netobserv-cli-reference.adoc new file mode 100644 index 0000000000..abb2d7f606 --- /dev/null +++ b/modules/network-observability-netobserv-cli-reference.adoc @@ -0,0 +1,195 @@ +// Module included in the following assemblies: +// * observability/network_observability/netobserv-cli-reference.adoc + +:_mod-docs-content-type: REFERENCE +[id="network-observability-netobserv-cli-reference_{context}"] += oc netobserv CLI reference +The Network Observability CLI (`oc netobserv`) is a CLI tool for capturing flow data and packet data for further analysis. + +.`oc netobserv` syntax +[source,terminal] +---- +$ oc netobserv [] [] [] <1> +---- +<1> Feature options can only be used with the `oc netobserv flows` command. They cannot be used with the `oc netobserv packets` command. + +[cols="3a,8a",options="header"] +.Basic commands +|=== +|Command| Description + +| `flows` +| Capture flows information. For subcommands, see the "Flow capture subcommands" table. + +| `packets` +| Capture packets from a specific protocol or port pair, such as `netobserv packets --filter=tcp,80`. For more information about packet capture, see the "Packet capture subcommand" table. + +| `cleanup` +| Remove the Network Observability CLI components. + +| `version` +| Print the software version. + +| `help` +| Show help. +|=== + +[id="network-observability-cli-enrichment_{context}"] +== Network Observability enrichment +The Network Observability enrichment to display zone, node, owner and resource names including optional features about packet drops, DNS latencies and Round-trip time can only be enabled when capturing flows. These do not appear in packet capture pcap output file. + +.Network Observability enrichment syntax +[source,terminal] +---- +$ oc netobserv flows [] [] +---- + +.Network Observability enrichment options +|=== +|Option| Description| Possible values| Default + +| `--enable_pktdrop` +| Enable packet drop. +| `true`, `false` +| `false` + +| `--enable_rtt` +| Enable round trip time. +| `true`, `false` +| `false` + +| `--enable_dns` +| Enable DNS tracking. +| `true`, `false` +| `false` + +| `--help` +| Show help. +| - +| - + +| `--interfaces` +| Interfaces to match on the flow. For example, `"eth0,eth1"`. +| `""` +| - +|=== + +[id="cli-reference-flow-capture-options_{context}"] +== Flow capture options +Flow capture has mandatory commands as well as additional options, such as enabling extra features about packet drops, DNS latencies, Round-trip time, and filtering. + +.`oc netobserv flows` syntax +[source,terminal] +---- +$ oc netobserv flows [] [] +---- + +.Flow capture filter options +|=== +|Option| Description| Possible values| Mandatory| Default + +| `--enable_filter` +| Enable flow filter. +| `true`, `false` +| Yes +| `false` + +| `--action` +| Action to apply on the flow. +| `Accept`, `Reject` +| Yes +| `Accept` + +| `--cidr` +| CIDR to match on the flow. +| `1.1.1.0/24`, `1::100/64`, or `0.0.0.0/0` +| Yes +| `0.0.0.0/0` + +| `--protocol` +| Protocol to match on the flow +| `TCP`, `UDP`, `SCTP`, `ICMP`, or `ICMPv6` +| No +| - + +| `--direction` +| Direction to match on the flow +| `Ingress`, `Egress` +| No +| - + +| `--dport` +| Destination port to match on the flow. +| `80`, `443`, or `49051` +| no +| - + +| `--sport` +| Source port to match on the flow. +| `80`, `443`, or `49051` +| No +| - + +| `--port` +| Port to match on the flow. +| `80`, `443`, or `49051` +| No +| - + +| `--sport_range` +| Source port range to match on the flow. +| `80-100` or `443-445` +| No +| - + +| `--dport_range` +| Destination port range to match on the flow. +| `80-100` +| No +| - + +| `--port_range` +| Port range to match on the flow. +| `80-100` or `443-445` +| No +| - + +| `--icmp_type` +| ICMP type to match on the flow. +| `8` or `13` +| No +| - + +| `--icmp_code` +| ICMP code to match on the flow. +| `0` or `1` +| No +| - + +| `--peer_ip` +| Peer IP to match on the flow. +| `1.1.1.1` or `1::1` +| No +| - +|=== + +[id="cli-reference-packet-capture-options_{context}"] +== Packet capture options +You can filter on port and protocol for packet capture data. + +.`oc netobserv packets` syntax +[source,terminal] +---- +$ oc netobserv packets [