Merge pull request #99193 from michelle-purcell/HCCDOC-4014

HCCDOC4014 Update obsolete Insights Operator 'DataGather' API instructions

Author: dfitzmau

modules/disabling-insights-operator-gather.adoc

@@ -5,9 +5,15 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="disabling-insights-operator-gather_{context}"]
-= Disabling the Insights Operator gather operations
+= Disabling the Insights Operator periodic gather operations 
 
-You can disable the Insights Operator gather operations. Disabling the gather operations gives you the ability to increase privacy for your organization as Insights Operator will no longer gather and send Insights cluster reports to Red Hat. This will disable Insights analysis and recommendations for your cluster without affecting other core functions that require communication with Red Hat such as cluster transfers. You can view a list of attempted gather operations for your cluster from the `/insights-operator/gathers.json` file in your Insights Operator archive. Be aware that some gather operations only occur when certain conditions are met and might not appear in your most recent archive.
+
+[role="_abstract"]
+You can optionally disable the periodic `InsightsDataGather` operations that the Insights Operator runs every 2 hours by default. Disabling the periodic data gather operations increases privacy for your organization as Insights Operator will no longer gather and send Insights cluster reports to Red{nbsp}Hat. 
+
+Disabling gather operations will also disable Insights analysis and recommendations for your cluster without affecting other core functions that require communication with Red{nbsp}Hat such as cluster transfers. 
+
+You can view a list of attempted gather operations for your cluster from the `/insights-operator/gathers.json` file in your Insights Operator archive. Be aware that some gather operations occur only when certain conditions are met and might not show in your most recent archive.
 
 :FeatureName: The `InsightsDataGather` custom resource
 include::snippets/technology-preview.adoc[]
@@ -28,52 +34,54 @@ endif::openshift-rosa,openshift-dedicated[]
 
 .Procedure
 
-. Navigate to *Administration* -> *CustomResourceDefinitions*.
-. On the *CustomResourceDefinitions* page, use the *Search by name* field to find the *InsightsDataGather* resource definition and click it.
+. Navigate to *Administration* > *CustomResourceDefinitions*.
+. On the *CustomResourceDefinitions* page, use the *Search by name* field to find the *InsightsDataGather* custom resource definition (CRD), and click to open.
 . On the *CustomResourceDefinition details* page, click the *Instances* tab.
 . Click *cluster*, and then click the *YAML* tab.
-. Disable the gather operations by performing one of the following edits to the `InsightsDataGather` configuration file:
-.. To disable all the gather operations, enter `all` under the `disabledGatherers` key:
+. Edit the `InsightsDataGather` CRD, and complete one of the following steps:
+** To disable all the gather operations and data collection, define the `gatherers` specification and set the `mode` to *None* as outlined in the following example extract:
 +
 [source,yaml]
 ----
-apiVersion: config.openshift.io/v1alpha1
+
+apiVersion: insights.openshift.io/v1alpha2
 kind: InsightsDataGather
 metadata:
-....
-
-spec: <1>
-  gatherConfig:
-    disabledGatherers:
-      - all <2>
+  name: cluster
+spec:
+# Gatherers configuration
+  gatherers:
+    mode: None # Options: All, None, Custom
 ----
-+
---
-<1> The `spec` parameter specifies gather configurations.
-<2> The `all` value disables all gather operations.
---
-
-.. To disable individual gather operations, enter their values under the `disabledGatherers` key:
+** To disable individual gather operations, under `gatherers`, set the `mode` to *Custom* and then specify the individual gatherer that you intend to disable. For example, to disable the workload gatherer, define the following specification:
 +
 [source,yaml]
 ----
+apiVersion: insights.openshift.io/v1alpha2
+kind: InsightsDataGather
+metadata:
+  name: cluster
 spec:
-  gatherConfig:
-    disabledGatherers:
-      - clusterconfig/container_images <1>
-      - clusterconfig/host_subnets
-      - workloads/workload_info
+    # Gatherers configuration
+  gatherers:
+    mode: Custom  # Options: All, None, Custom
+    custom:
+      configs:
+        # Essential cluster configuration gatherers
+        - name: clusterconfig/authentication
+          state: Enabled
+        - name: clusterconfig/clusteroperators
+          state: Enabled
+        - name: workloads
+          state: Disabled
 ----
-+
---
-<1> Example individual gather operation
---
-+
 . Click *Save*.
-+
-After you save the changes, the Insights Operator gather configurations are updated and the operations will no longer occur.
+
+.Results
+
+After you save the changes, the Insights Operator gather configurations are updated and the operations that you disabled in the configuration will no longer occur.
 
 [NOTE]
 ====
-Disabling gather operations degrades the Insights advisor service's ability to offer effective recommendations for your cluster.
+Disabling gather operations restricts the ability of the Insights Advisor service to offer effective recommendations for your cluster.
 ====

modules/enabling-insights-operator-gather.adoc

@@ -5,9 +5,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="enabling-insights-operator-gather_{context}"]
-= Enabling the Insights Operator gather operations
+= Re-enabling the Insights Operator periodic gather operations
 
-You can enable the Insights Operator gather operations, if the gather operations have been disabled.
+If you disabled the default `InsightsDataGather` data gather operations, you can enable them again so that the Insights Operator resumes the periodic data collection, and sends the resulting Insights cluster reports to Red Hat. 
 
 :FeatureName: The `InsightsDataGather` custom resource
 include::snippets/technology-preview.adoc[]
@@ -23,51 +23,55 @@ endif::openshift-rosa,openshift-dedicated[]
 
 .Procedure
 
-. Navigate to *Administration* -> *CustomResourceDefinitions*.
-. On the *CustomResourceDefinitions* page, use the *Search by name* field to find the *InsightsDataGather* resource definition and click it.
+. Navigate to *Administration* > *CustomResourceDefinitions*.
+. On the *CustomResourceDefinitions* page, use the *Search by name* field to find the *InsightsDataGather* custom resource definition (CRD), and click to open.
 . On the *CustomResourceDefinition details* page, click the *Instances* tab.
 . Click *cluster*, and then click the *YAML* tab.
-. Enable the gather operations by performing one of the following edits:
+. Edit the `InsightsDataGather` CRD, and complete one of the following steps:
 
-** To enable all disabled gather operations, remove the `gatherConfig` stanza:
+** To enable all disabled gather operations, under the `gatherers` specification, set the `mode` back to *All* as outlined in the following example extract:
 +
 [source,yaml]
 ----
-apiVersion: config.openshift.io/v1alpha1
+
+apiVersion: insights.openshift.io/v1alpha2
 kind: InsightsDataGather
 metadata:
-....
-
+  name: cluster
 spec:
-  gatherConfig: <1>
-    disabledGatherers: all
+# Gatherers configuration
+  gatherers:
+    mode: All # Options: All, None, Custom
 ----
-+
---
-<1> Remove the `gatherConfig` stanza to enable all gather operations.
---
 
-** To enable individual gather operations, remove their values under the `disabledGatherers` key:
+** To enable individual gather operations that were previously disabled, find the name of the gatherer operation under the `gatherers:custom:configs` key section and change the `state` to *Enabled*. Alternatively, under the `config` specification, remove the `name` and `state` configuration lines for the operation you want to enable. 
 +
 [source,yaml]
 ----
+apiVersion: insights.openshift.io/v1alpha2
+kind: InsightsDataGather
+metadata:
+  name: cluster
 spec:
-  gatherConfig:
-    disabledGatherers:
-      - clusterconfig/container_images <1>
-      - clusterconfig/host_subnets
-      - workloads/workload_info
+    # Gatherers configuration
+  gatherers:
+    mode: Custom  # Options: All, None, Custom
+    custom:
+      configs:
+        # Essential cluster configuration gatherers
+        - name: clusterconfig/authentication
+          state: Enabled
+        - name: clusterconfig/clusteroperators
+          state: Enabled
+        - name: workloads
+          state: Enabled
 ----
 +
---
-<1> Remove one or more gather operations.
---
-+
 . Click *Save*.
 +
 After you save the changes, the Insights Operator gather configurations are updated and the affected gather operations start.
 
 [NOTE]
 ====
-Disabling gather operations degrades Insights Advisor's ability to offer effective recommendations for your cluster.
+Disabling gather operations restricts the ability of the Insights Advisor service to offer effective recommendations for your cluster.
 ====

modules/insights-operator-configuring.adoc

@@ -95,7 +95,7 @@ The *insights-config* `ConfigMap` object follows standard YAML formatting, where
 |dataReporting:
     obfuscation:
     - workload_names
-|Enables the obfuscation of Data Validation Operator data. The cluster resource the resource ID is only visible in the archive file and not the resource name.
+|Enables the obfuscation of Data Validation Operator data. The cluster resource ID is only visible in the archive file and not the resource name.
 |String
 |Not applicable
 

modules/running-insights-operator-gather-cli.adoc

@@ -5,45 +5,106 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="running-insights-operator-gather-openshift-cli_{context}"]
-= Running an Insights Operator gather operation from the OpenShift CLI
-You can run an Insights Operator gather operation by using the {product-title} command-line interface.
+= Gathering data on demand with the Insights Operator from the OpenShift CLI
+
+You can run a custom Insights Operator gather operation on-demand from the  {product-title} command-line interface (CLI). 
+An on-demand `DataGather` operation is useful for one-off data collections that require different configurations to the periodic data gathering (`InsightsDataGather`) specification.
+
+Use the following procedure to create a `DataGather` custom resource definition (CRD), and then run the data gather operation on demand from the CLI.
 
 .Prerequisites
 
 * You are logged in to {product-title} as a user with the `cluster-admin` role.
 
 .Procedure
-* Enter the following command to run the gather operation:
+
+. Create a YAML file with the following `DataGather` specification:
 +
-[source,terminal]
+[source,yaml]
 ----
-$ oc apply -f <your_datagather_definition>.yaml
+
+apiVersion: insights.openshift.io/v1alpha2
+kind: DataGather
+metadata:
+  name: <your_data_gather>
+spec:
+# Gatherers configuration
+  gatherers:
+    mode: All # Options: All, Custom
+# ...
 ----
 +
-Replace `<your_datagather_definition>.yaml` with a configuration file that contains the following parameters:
+[IMPORTANT]
+====
+* The name you specify for your gather operation, `<your_data_gather>`, must be unique and must not include a prefix of `periodic-gathering-` because this string is reserved for other administrative operations and might impact the intended gather operation.
+* If the `spec` of `DataGather` CRD is undefined, the default Insights Operator data collection job will run. This means that all gather operations will run, the collected data will be unobfuscated and the archive file will not be retained.
+====
++
+. Optional: To customize the data gather operation, you can configure any of the following options in your `DataGather` YAML file:
+* To disable specific gatherers, change the value of `mode` to *Custom*, and then specify the individual gatherer that you intend to disable. For example, to disable the workload gatherer, add the following example:
 +
 [source,yaml]
 ----
-apiVersion: insights.openshift.io/v1alpha1
+apiVersion: insights.openshift.io/v1alpha2
 kind: DataGather
 metadata:
-  name: <your_data_gather> <1>
+  name: <your_data_gather> 
 spec:
- gatherers: <2>
-   - name: workloads
-     state: Disabled
+    # Gatherers configuration
+  gatherers:
+    mode: Custom  # Options: All, Custom
+    custom:
+      configs:
+        # Essential cluster configuration gatherers
+        - name: clusterconfig/authentication
+          state: Enabled
+        - name: clusterconfig/clusteroperators
+          state: Enabled
+        - name: workloads
+          state: Disabled
+----
+* To enable persistent storage to retain the data archive file and history for up to the last 10 data gathering jobs, define the `storage` specification. Set *type* to `PersistentVolume`, and define the `mountPath` and `name` of the volume, as outlined in the following example:
++
+[source,yaml]
+----
+apiVersion: insights.openshift.io/v1alpha2
+kind: DataGather
+metadata:
+  name: <your_data_gather>
+spec:
+  storage:
+    type: PersistentVolume
+    mountPath: /data
+    persistentVolume:
+      claim:
+        name: on-demand-gather-pvc
 ----
 +
---
-<1> Under *metadata*, replace `<your_data_gather>` with a unique name for the gather operation.
-<2> Under *gatherers*, specify any individual gather operations that you intend to disable. In the example provided, `workloads` is the only data gather operation that is disabled and all of the other default operations are set to run.
-When the `spec` parameter is empty, all of the default gather operations run.
---
-
 [IMPORTANT]
 ====
-Do not add a prefix of `periodic-gathering-` to the name of your gather operation because this string is reserved for other administrative operations and might impact the intended gather operation.
+Ensure that the volume name specified matches the existing `PersistentVolumeClaim` value in the `openshift-insights` namespace. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/storage/understanding-persistent-storage#persistent-volume-claims_understanding-persistent-storage[Persistent volume claims].
 ====
++
+* To enable data obfuscation, define the `dataPolicy` key and required values. For example, to obfuscate IP addresses and workload names, add the following configuration:
++
+[source,yaml]
+----
+apiVersion: insights.openshift.io/v1alpha2
+kind: DataGather
+metadata:
+  name: <your_data_gather> 
+spec:
+  dataPolicy:
+    - ObfuscateNetworking
+    - WorkloadNames
+----
++
+. On the {product-title} CLI, enter the following command to run the gather operation:
++
+[source,terminal]
+----
+$ oc apply -f <your_data_gather_definition>.yaml
+----
 
 .Verification