Merge pull request #107644 from gwynnemonahan/OSDOCS-14480

OSDOCS-14480 [NETOBSERV] Update callouts for DITA

Author: skopacz1

modules/network-observability-SRIOV-configuration.adoc

@@ -34,6 +34,7 @@ spec:
   agent:
     type: eBPF
     ebpf:
-      privileged: true   <1>
+      privileged: true
 ----
-<1> The `spec.agent.ebpf.privileged` field value must be set to `true` to enable SR-IOV monitoring.
++
+** The `spec.agent.ebpf.privileged` field value must be set to `true` to enable SR-IOV monitoring.

modules/network-observability-dns-tracking.adoc

@@ -36,11 +36,12 @@ spec:
     type: eBPF
     ebpf:
       features:
-       - DNSTracking           <1>
-      sampling: 1              <2>
+       - DNSTracking
+      sampling: 1
 ----
-<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 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.
++
+* You can set the `spec.agent.ebpf.features` parameter list to enable DNS tracking of each network flow in the web console.
+* 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*.

modules/network-observability-flowcollector-example.adoc

@@ -20,61 +20,38 @@ metadata:
 spec:
   namespace: netobserv
   deploymentModel: Service
+  networkPolicy:
+    enable: true
   agent:
-    type: eBPF                                <1>
+    type: eBPF
     ebpf:
-      sampling: 50                            <2>
-      logLevel: info
+      sampling: 50
       privileged: false
-      resources:
-        requests:
-          memory: 50Mi
-          cpu: 100m
-        limits:
-          memory: 800Mi
-  processor:               <3>
-    logLevel: info
-    resources:
-      requests:
-        memory: 100Mi
-        cpu: 100m
-      limits:
-        memory: 800Mi
-    logTypes: Flows
-    advanced:
-      conversationEndTimeout: 10s
-      conversationHeartbeatInterval: 30s
-  loki:                     <4>
-    mode: LokiStack         <5>
+      features: []
+  processor:
+    addZone: false
+    subnetLabels:
+      openShiftAutoDetect: true
+      customLabels: []
+    consumerReplicas: 3
+  loki:
+    enable: true
+    mode: LokiStack
+    lokiStack:
+      name: loki
+      namespace: netobserv-loki
   consolePlugin:
-    register: true
-    logLevel: info
-    portNaming:
-      enable: true
-      portNames:
-        "3100": loki
-    quickFilters:            <6>
-    - name: Applications
-      filter:
-        src_namespace!: 'openshift-,netobserv'
-        dst_namespace!: 'openshift-,netobserv'
-      default: true
-    - name: Infrastructure
-      filter:
-        src_namespace: 'openshift-,netobserv'
-        dst_namespace: 'openshift-,netobserv'
-    - name: Pods network
-      filter:
-        src_kind: 'Pod'
-        dst_kind: 'Pod'
-      default: true
-    - name: Services network
-      filter:
-        dst_kind: 'Service'
+    enable: true
+  exporters: []
 ----
-<1> The Agent specification, `spec.agent.type`, must be `EBPF`. eBPF is the only {product-title} supported option.
-<2> You can set the Sampling specification, `spec.agent.ebpf.sampling`, to manage resources. By default, eBPF sampling is set to `50`, so a flow has a 1 in 50 chance of being sampled. A lower sampling interval value requires more computational, memory, and storage resources. A value of `0` or `1` means all flows are sampled. It is recommended to start with the default value and refine it empirically to determine the optimal setting for your cluster.
-<3> The Processor specification `spec.processor.` can be set to enable conversation tracking. When enabled, conversation events are queryable in the web console. The `spec.processor.logTypes` value is `Flows`. The `spec.processor.advanced` values are `Conversations`, `EndedConversations`, or `ALL`. Storage requirements are highest for `All` and lowest for `EndedConversations`.
-<4> The Loki specification, `spec.loki`, specifies the Loki client. The default values match the Loki install paths mentioned in the Installing the Loki Operator section. If you used another installation method for Loki, specify the appropriate client information for your install.
-<5> The `LokiStack` mode automatically sets a few configurations: `querierUrl`, `ingesterUrl` and `statusUrl`, `tenantID`, and corresponding TLS configuration. Cluster roles and a cluster role binding are created for reading and writing logs to Loki. And `authToken` is set to `Forward`. You can set these manually using the `Manual` mode.
-<6> The `spec.quickFilters` specification defines filters that show up in the web console. The `Application` filter keys,`src_namespace` and `dst_namespace`, are negated (`!`), so the `Application` filter shows all traffic that _does not_ originate from, or have a destination to, any `openshift-` or `netobserv` namespaces. For more information, see Configuring quick filters below.
+
+where:
+
+`spec.agent.type`:: Must be `eBPF` as eBPF is the only {product-title} supported option.
+`spec.agent.ebpf.sampling`:: Specifies the sampling interval. By default, eBPF sampling is set to `50`, so a packet has a 1 in 50 chance of being sampled. A lower sampling interval value requires more computational, memory, and storage resources. A value of `0` or `1` means all packets are sampled. It is recommended to start with the default value and refine it empirically to determine the optimal setting for your cluster.
+`spec.agent.ebpf.privileged`:: Specifies if the eBPF agent pods should run as privileged. Running as privileged is required for several features, such as monitoring non-default networks and tracking packet drops. For security, in accordance with the principle of least privilege, it should only be enabled when some of those features are desired. A warning will be displayed if you enabled a feature requiring privileged mode without setting it to true explicitly.
+`spec.processor.addZone`:: Used to inject cloud availability zones in network flows.
+`spec.processor.subnetLabels`:: Specifies a list of customized labels to inject in network flows, based on CIDR matching.
+`spec.processor.consumerReplicas`:: Specifies the number of replicas for the processor pods (flowlogs-pipeline). Refer to the Resource management and performance considerations section for recommendations based on the cluster size.
+`spec.loki.mode`:: Specifies how to configure the connection to Loki, depending on its installation mode. If you use the install paths described in "Installing the Loki Operator", the mode must be set to `LokiStack`, and `spec.loki.lokiStack` should refer to the installed `LokiStack` resource name and namespace.
+`spec.loki.lokistack.namespace`:: Specifies the namespace for the `LokiStack` resource. This value must match the `metadata.namespace` defined in the `LokiStack` custom resource. While this example uses `netobserv-loki`, you can use a different namespace for different components.

modules/network-observability-flowcollector-kafka-config.adoc

@@ -9,10 +9,10 @@
 [role="_abstract"]
 Configure the `FlowCollector` resource to use Kafka for high-throughput and low-latency data feeds.
 
-A Kafka instance needs to be running, and a Kafka topic dedicated to {product-title} Network Observability must be created in that instance. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.7/html/using_amq_streams_on_openshift/using-the-topic-operator-str[Kafka documentation with AMQ Streams].
+You must have a running Kafka instance and create a Kafka topic in that instance dedicated to {product-title} Network Observability. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.7/html/using_amq_streams_on_openshift/using-the-topic-operator-str[Kafka documentation with AMQ Streams].
 
 .Prerequisites
-* Kafka is installed. Red Hat supports Kafka with AMQ Streams Operator.
+* You have installed Kafka. Red{nbsp}Hat supports Kafka with AMQ Streams Operator.
 
 .Procedure
 . In the web console, navigate to *Ecosystem* -> *Installed Operators*.
@@ -21,7 +21,7 @@ A Kafka instance needs to be running, and a Kafka topic dedicated to {product-ti
 
 . Select the cluster and then click the *YAML* tab.
 
-. Modify the `FlowCollector` resource for {product-title} Network Observability Operator to use Kafka, as shown in the following sample YAML:
+. Change the `FlowCollector` resource for {product-title} Network Observability Operator to use Kafka, as shown in the following sample YAML:
 +
 .Sample Kafka configuration in `FlowCollector` resource
 [source, yaml]
@@ -31,14 +31,18 @@ kind: FlowCollector
 metadata:
   name: cluster
 spec:
-  deploymentModel: Kafka                                    <1>
+  deploymentModel: Kafka
   kafka:
-    address: "kafka-cluster-kafka-bootstrap.netobserv"      <2>
-    topic: network-flows                                    <3>
+    address: "kafka-cluster-kafka-bootstrap.netobserv"
+    topic: network-flows
     tls:
-      enable: false                                         <4>
+      enable: false
 ----
-<1> Set `spec.deploymentModel` to `Kafka` instead of `Direct` to enable the Kafka deployment model.
-<2> `spec.kafka.address` refers to the Kafka bootstrap server address. You can specify a port if needed, for instance `kafka-cluster-kafka-bootstrap.netobserv:9093` for using TLS on port 9093.
-<3> `spec.kafka.topic` should match the name of a topic created in Kafka.
-<4> `spec.kafka.tls` can be used to encrypt all communications to and from Kafka with TLS or mTLS. When enabled, the Kafka CA certificate must be available as a ConfigMap or a Secret, both in the namespace where the `flowlogs-pipeline` processor component is deployed (default: `netobserv`) and where the eBPF agents are deployed (default: `netobserv-privileged`). It must be referenced with `spec.kafka.tls.caCert`. When using mTLS, client secrets must be available in these namespaces as well (they can be generated for instance using the AMQ Streams User Operator) and referenced with `spec.kafka.tls.userCert`.
++
+where:
+
+`spec.deploymentModel`:: Specifies the deployment model. Set to `Kafka` instead of `Service`
+to enable the Kafka deployment model.
+`spec.kafka.address`:: Specifies the Kafka bootstrap server address. You can specify a port if needed, for instance `kafka-cluster-kafka-bootstrap.netobserv:9093` for using TLS on port 9093.
+`spec.kafka.topic`:: Specifies the name of the topic created in Kafka. It should match the name of a topic created in Kafka.
+`spec.kafka.tls`:: Specifies communication encryption. Use this setting to encrypt all communications to and from Kafka with TLS or mTLS. When enabled, the Kafka CA certificate must be available as a ConfigMap or a Secret in both namespaces: the namespace where you deploy the `flowlogs-pipeline` processor component (default: `netobserv`) and the namespace where you deploy the eBPF agents (default: `netobserv-privileged`). Reference the certificate by using `spec.kafka.tls.caCert`. When you use mTLS, make the client secrets available in these namespaces as well. You can generate the secrets by using the Red Hat AMQ Streams User Operator. Reference the secrets by using `spec.kafka.tls.userCert`.

modules/network-observability-includelist-example.adoc

@@ -34,11 +34,12 @@ spec:
         message: |-
           {{ $labels.job }}: incoming traffic exceeding 10 MBps for 30s on {{ $labels.DstK8S_OwnerType }} {{ $labels.DstK8S_OwnerName }} ({{ $labels.DstK8S_Namespace }}).
         summary: "High incoming traffic."
-      expr: sum(rate(netobserv_workload_ingress_bytes_total     {SrcK8S_Namespace="openshift-ingress"}[1m])) by (job, DstK8S_Namespace, DstK8S_OwnerName, DstK8S_OwnerType) > 10000000      <1>
+      expr: sum(rate(netobserv_workload_ingress_bytes_total     {SrcK8S_Namespace="openshift-ingress"}[1m])) by (job, DstK8S_Namespace, DstK8S_OwnerName, DstK8S_OwnerType) > 10000000
       for: 30s
       labels:
         severity: warning
 ----
-<1> The `netobserv_workload_ingress_bytes_total` metric is enabled by default in `spec.processor.metrics.includeList`.
++
+** The `netobserv_workload_ingress_bytes_total` metric is enabled by default in `spec.processor.metrics.includeList`.
 
 . Click *Create* to apply the configuration file to the cluster.

modules/network-observability-loki-secret.adoc

@@ -25,15 +25,23 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: loki-s3
-  namespace: netobserv   <1>
+  namespace: netobserv-loki
 stringData:
   access_key_id: QUtJQUlPU0ZPRE5ON0VYQU1QTEUK
   access_key_secret: d0phbHJYVXRuRkVNSS9LN01ERU5HL2JQeFJmaUNZRVhBTVBMRUtFWQo=
   bucketnames: s3-bucket-name
   endpoint: https://s3.eu-central-1.amazonaws.com
   region: eu-central-1
 ----
-<1> The installation examples in this documentation use the same namespace, `netobserv`, across all components. You can optionally use a different namespace for the different components
++
+where:
+
+`metadata.namespace`:: Specifies the namespace for the Loki S3 secret. While this example uses `netobserv-loki`, you can use a different namespace for different components.
+`stringData.access_key_id`:: Specifies the access key ID for the S3 bucket.
+`stringData.access_key_secret`:: Specifies the secret access key for the S3 bucket.
+`stringData.bucketnames`:: Specifies the name of the S3 bucket.
+`stringData.endpoint`:: Specifies the endpoint URL for the S3 service.
+`stringData.region`:: Specifies the AWS region where the bucket is located.
 
 .Verification
 * After you create the secret, you view the secret listed under *Workloads* -> *Secrets* in the web console.

modules/network-observability-lokistack-create.adoc

@@ -18,40 +18,41 @@ You can deploy a `LokiStack` custom resource (CR) to create a namespace or new p
 . Click *Create LokiStack*.
 . Ensure the following fields are specified in either *Form View* or *YAML view*:
 +
---
 [source,yaml]
 ----
 apiVersion: loki.grafana.com/v1
 kind: LokiStack
 metadata:
   name: loki
-  namespace: netobserv # <1>
+  namespace: netobserv-loki
 spec:
-  size: 1x.small # <2>
+  size: 1x.small
   storage:
     schemas:
     - version: v13
       effectiveDate: '2022-06-01'
     secret:
       name: loki-s3
       type: s3
-  storageClassName: gp3 # <3>
+  storageClassName: gp3
   tenants:
     mode: openshift-network
 ----
-<1> The installation examples in this documentation use the same namespace, `netobserv`, across all components. You can optionally use a different namespace.
-<2> Specify the deployment size. In the {loki-op} 5.8 and later versions, the supported size options for production instances of Loki are `1x.extra-small`, `1x.small`, or `1x.medium`.
++
+where:
+
+`metadata.namespace`:: Specifies the namespace for the `LokiStack` resource. While this example uses `netobserv-loki`, you can use a different namespace for different components.
+`spec.size`:: Specifies the deployment size. In {loki-op} 5.8 and later versions, the supported size options for production instances of Loki are `1x.extra-small`, `1x.small`, or `1x.medium`.
 +
 [IMPORTANT]
 ====
 It is not possible to change the number `1x` for the deployment size.
 ====
-<3> Use a storage class name that is available on the cluster for `ReadWriteOnce` access mode. For best performance, specify a storage class that allocates block storage. You can use `oc get storageclasses` to see what is available on your cluster.
+`spec.storageClassName`:: Specifies a storage class name that is available on the cluster for `ReadWriteOnce` access mode. For best performance, specify a storage class that allocates block storage. Use the `oc get storageclasses` command to see available storage classes on your cluster.
 +
 [IMPORTANT]
 ====
-You must not reuse the same `LokiStack` CR that is used for {logging}.
+You must not reuse the same `LokiStack` custom resource that is used for {logging}.
 ====
---
 
 . Click *Create*.

modules/network-observability-packet-drops.adoc

@@ -36,11 +36,14 @@ spec:
     type: eBPF
     ebpf:
       features:
-       - PacketDrop            <1>
-      privileged: true         <2>
+       - PacketDrop
+      privileged: true
 ----
-<1> You can start reporting the packet drops of each network flow by listing the `PacketDrop` parameter in the `spec.agent.ebpf.features` specification list.
-<2> The `spec.agent.ebpf.privileged` specification value must be `true` for packet drop tracking.
++
+where:
+
+`spec.agent.ebpf.features`:: Specifies the features to enable. Include `PacketDrop` to start reporting packet drops for each network flow.
+`spec.agent.ebpf.privileged`:: Specifies whether privileged mode is enabled. Must be set to `true` for packet drop tracking.
 
 .Verification
 * When you refresh the *Network Traffic* page, the *Overview*, *Traffic Flow*, and *Topology* views display new information about packet drops:

modules/network-observability-packet-translation.adoc

@@ -31,9 +31,10 @@ spec:
     type: eBPF
     ebpf:
       features:
-       - PacketTranslation   <1>
+       - PacketTranslation
 ----
-<1> You can start enriching network flows with translated packet information by listing the `PacketTranslation` parameter in the `spec.agent.ebpf.features` specification list.
++
+** You can start enriching network flows with translated packet information by listing the `PacketTranslation` parameter in the `spec.agent.ebpf.features` specification list.
 +
 . Refresh the *Network Traffic* page to filter for information about translated packets:
 .. Filter the network flow data based on *Destination kind: Service*.

modules/network-observability-tcp-flag-syn-flood.adoc

@@ -61,7 +61,7 @@ metadata:
         message: |-
           {{ $labels.job }}: incoming SYN-flood attack suspected to Host={{ $labels.DstK8S_HostName}}, Namespace={{ $labels.DstK8S_Namespace }}, Resource={{ $labels.DstK8S_Name }}. This is characterized by a high volume of SYN-only flows with different source IPs and/or ports.
         summary: "Incoming SYN-flood"
-      expr: sum(rate(netobserv_flows_with_flags_per_destination_total{Flags="2"}[1m])) by (job, DstK8S_HostName, DstK8S_Namespace, DstK8S_Name) > 300      <1>
+      expr: sum(rate(netobserv_flows_with_flags_per_destination_total{Flags="2"}[1m])) by (job, DstK8S_HostName, DstK8S_Namespace, DstK8S_Name) > 300
       for: 15s
       labels:
         severity: warning
@@ -71,14 +71,15 @@ metadata:
         message: |-
           {{ $labels.job }}: outgoing SYN-flood attack suspected from Host={{ $labels.SrcK8S_HostName}}, Namespace={{ $labels.SrcK8S_Namespace }}, Resource={{ $labels.SrcK8S_Name }}. This is characterized by a high volume of SYN-only flows with different source IPs and/or ports.
         summary: "Outgoing SYN-flood"
-      expr: sum(rate(netobserv_flows_with_flags_per_source_total{Flags="2"}[1m])) by (job, SrcK8S_HostName, SrcK8S_Namespace, SrcK8S_Name) > 300       <1>
+      expr: sum(rate(netobserv_flows_with_flags_per_source_total{Flags="2"}[1m])) by (job, SrcK8S_HostName, SrcK8S_Namespace, SrcK8S_Name) > 300
       for: 15s
       labels:
         severity: warning
         app: netobserv
 # ...
 ----
-<1> In this example, the threshold for the alert is `300`; however, you can adapt this value empirically. A threshold that is too low might produce false-positives, and if it's too high it might miss actual attacks.
++
+In this example, the threshold for the alert is `300`; however, you can adapt this value empirically. A threshold that is too low might produce false-positives, and if it's too high it might miss actual attacks.
 
 .Verification
 . In the web console, click *Manage Columns* in the *Network Traffic* table view and click *TCP flags*.