diff --git a/modules/disabling-insights-operator-gather.adoc b/modules/disabling-insights-operator-gather.adoc index f1906d529b..af3bbf9bdc 100644 --- a/modules/disabling-insights-operator-gather.adoc +++ b/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. ==== diff --git a/modules/enabling-insights-operator-gather.adoc b/modules/enabling-insights-operator-gather.adoc index 6449cc0441..1c379719e6 100644 --- a/modules/enabling-insights-operator-gather.adoc +++ b/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. ==== diff --git a/modules/insights-operator-configuring.adoc b/modules/insights-operator-configuring.adoc index bc249c73d7..f3a20d6a1e 100644 --- a/modules/insights-operator-configuring.adoc +++ b/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 diff --git a/modules/running-insights-operator-gather-cli.adoc b/modules/running-insights-operator-gather-cli.adoc index 6a0c6e83ff..1b8d22ed6d 100644 --- a/modules/running-insights-operator-gather-cli.adoc +++ b/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: -+ -[source,terminal] ----- -$ oc apply -f .yaml ----- -+ -Replace `.yaml` with a configuration file that contains the following parameters: + +. Create a YAML file with the following `DataGather` specification: + [source,yaml] ---- -apiVersion: insights.openshift.io/v1alpha1 + +apiVersion: insights.openshift.io/v1alpha2 kind: DataGather metadata: - name: <1> + name: spec: - gatherers: <2> - - name: workloads - state: Disabled +# Gatherers configuration + gatherers: + mode: All # Options: All, Custom +# ... ---- + --- -<1> Under *metadata*, replace `` 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. +* The name you specify for your gather operation, ``, 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/v1alpha2 +kind: DataGather +metadata: + name: +spec: + # 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: +spec: + storage: + type: PersistentVolume + mountPath: /data + persistentVolume: + claim: + name: on-demand-gather-pvc +---- ++ +[IMPORTANT] +==== +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: +spec: + dataPolicy: + - ObfuscateNetworking + - WorkloadNames +---- ++ +. On the {product-title} CLI, enter the following command to run the gather operation: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- .Verification diff --git a/modules/running-insights-operator-gather-web-console.adoc b/modules/running-insights-operator-gather-web-console.adoc index 8b3573d4a8..fecfbd65fa 100644 --- a/modules/running-insights-operator-gather-web-console.adoc +++ b/modules/running-insights-operator-gather-web-console.adoc @@ -6,8 +6,11 @@ :_mod-docs-content-type: PROCEDURE [id="running-insights-operator-gather-web-console_{context}"] -= Running an Insights Operator gather operation from the web console -To collect data, you can run an Insights Operator gather operation by using the {product-title} web console. += Gathering data on demand with the Insights Operator from the web console + +You can run a custom Insights Operator gather operation on-demand from the {product-title} web console. 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 web console. .Prerequisites @@ -15,38 +18,94 @@ To collect data, you can run an Insights Operator gather operation by using the .Procedure -. On the console, select *Administration* -> *CustomResourceDefinitions*. +. On the console, select *Administration* > *CustomResourceDefinitions*. . On the *CustomResourceDefinitions* page, in the *Search by name* field, find the *DataGather* resource definition, and then click it. . On the *CustomResourceDefinition details* page, click the *Instances* tab. . Click *Create DataGather*. -. To create a new `DataGather` operation, edit the following configuration file and then save your changes. +. To create a new `DataGather` operation where all gather operations will run, complete the following YAML specification, and then save your changes. + [source,yaml] ---- -apiVersion: insights.openshift.io/v1alpha1 + +apiVersion: insights.openshift.io/v1alpha2 kind: DataGather metadata: - name: <1> + name: spec: - gatherers: <2> - - name: workloads - state: Disabled +# Gatherers configuration + gatherers: + mode: All # Options: All, Custom +# ... ---- + --- -<1> Under *metadata*, replace `` 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. +* The name you specify for your gather operation, ``, 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/v1alpha2 +kind: DataGather +metadata: + name: +spec: + # 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: +spec: + storage: + type: PersistentVolume + mountPath: /data + persistentVolume: + claim: + name: on-demand-gather-pvc +---- ++ +[IMPORTANT] +==== +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: +spec: + dataPolicy: + - ObfuscateNetworking + - WorkloadNames +---- + .Verification -. On the console, select to *Workloads* -> *Pods*. +. On the console, select to *Workloads* > *Pods*. . On the Pods page, go to the *Project* pull-down menu, and then select *Show default projects*. . Select the `openshift-insights` project from the *Project* pull-down menu. . Check that your new gather operation is prefixed with your chosen name under the list of pods in the `openshift-insights` project. Upon completion, the Insights Operator automatically uploads the data to Red Hat for processing. diff --git a/support/remote_health_monitoring/using-insights-operator.adoc b/support/remote_health_monitoring/using-insights-operator.adoc index 63706ae2d9..5937021d86 100644 --- a/support/remote_health_monitoring/using-insights-operator.adoc +++ b/support/remote_health_monitoring/using-insights-operator.adoc @@ -41,9 +41,37 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] // tech preview feature ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] [id="running-insights-operator-gather_using-insights-operator"] -== Running an Insights Operator gather operation +== Running an Insights Operator gather operation on-demand + +Instead of waiting for the next periodic data gather operation, you can run a custom on-demand Insights Operator data gather operation by using the {product-title} web console or command-line interface (CLI). + +A periodic data gather operation uses the `InsightsDataGather` custom resource definition (CRD) for configuration instructions, whereas an on-demand equivalent requires a `DataGather` CRD to be configured. + +An on-demand `DataGather` operation is: + +* Useful for one-off data collections that require different CRD configurations to the periodic data gathering (`InsightsDataGather`) specification. +* Independent from the periodic data gathering. When you create an on-demand `DataGather` CRD, the configuration is independent from the `InsightsDataGather` CRD specification of your periodic data gathering job. + +**Custom specification options** + +You can optionally customize the following items for the on-demand data gather operation: + +* *Enable and define data obfuscation:* By defining the `DataGather` `dataPolicy` specification, you can enable additional obfuscation of the Insights archive data, for example, the IP address or workload names. + +* *Enable persistant storage:* By default, the Insights Operator uses ephemeral storage, which means that a new pod will be created for each gather operation and the history of gather operations and data collected is not retained. You can switch to persistent storage to retain the data and history for up to the last 10 gather operations by defining the `DataGather` `storage` specification in the CRD. + +* *Exclude specific data gather operations:* You can choose to disable specific gather operations from running by defining the `DataGather` `gatherers` specification. For example, you can choose to disable the cluster authentication operation or the workload data operation. + +[IMPORTANT] +==== +Excluding gather operations from the default list might reduce or limit the recommendations offered by the Insights Advisor for your cluster. +==== + + +If you do not configure any custom specification options in the `DataGather` CRD, 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. + +When you run a gather operation on-demand, any configuration that was previously applied to disable Insights Operator gather operations for your cluster will be overridden. -You can run Insights Operator data gather operations on demand. The following procedures describe how to run the default list of gather operations using the OpenShift web console or CLI. You can customize the on demand gather function to exclude any gather operations you choose. Disabling gather operations from the default list degrades Insights Advisor's ability to offer effective recommendations for your cluster. If you have previously disabled Insights Operator gather operations in your cluster, this procedure will override those parameters. :FeatureName: The `DataGather` custom resource include::snippets/technology-preview.adoc[]