Using the Insights Operator - Remote health monitoring with connected clusters | Support

Configuring Insights Operator
- Creating the insights-config ConfigMap object
Understanding Insights Operator alerts
- Disabling Insights Operator alerts
- Enabling Insights Operator alerts
Downloading your Insights Operator archive
Running an Insights Operator gather operation
Obfuscating Deployment Validation Operator data

The Insights Operator periodically gathers configuration and component failure status and, by default, reports that data every two hours to Red Hat. This information enables Red Hat to assess configuration and deeper failure data than is reported through Telemetry. Users of OKD can display the report in the Insights Advisor service on Red Hat Hybrid Cloud Console.

Additional resources

The Insights Operator is installed and enabled by default. If you need to opt out of remote health reporting, see Opting out of remote health reporting.
For more information on using Insights Advisor to identify issues with your cluster, see Using Insights to identify issues with your cluster.

Configuring Insights Operator

Insights Operator configuration is a combination of the default Operator configuration and the configuration that is stored in either the insights-config ConfigMap object in the openshift-insights namespace, OR in the support secret in the openshift-config namespace.

When a ConfigMap object or support secret exists, the contained attribute values override the default Operator configuration values. If both a ConfigMap object and a support secret exist, the Operator reads the ConfigMap object.

The ConfigMap object does not exist by default, so an OKD cluster administrator must create it.

ConfigMap object configuration structure

This example of an insights-config ConfigMap object (config.yaml configuration) shows configuration options using standard YAML formatting.

Example of Insights Operator ConfigMap object

Configurable attributes and default values

The table below describes the available configuration attributes:

The insights-config ConfigMap object follows standard YAML formatting, wherein child values are below the parent attribute and indented two spaces. For the Obfuscation attribute, enter values as bulleted children of the parent attribute.

Table 1. Insights Operator configurable attributes
Attribute name	Description	Value type	Default value
`Obfuscation: - networking`	Enables the global obfuscation of IP addresses and the cluster domain name.	Boolean	`false`
`Obfuscation: - workload_names`	Obfuscate data coming from the Deployment Validation Operator if it is installed.	Boolean	`false`
`sca: interval`	Specifies the frequency of the simple content access entitlements download.	Time interval	`8h`
`sca: disabled`	Disables the simple content access entitlements download.	Boolean	`false`
`alerting: disabled`	Disables Insights Operator alerts to the cluster Prometheus instance.	Boolean	`false`
`httpProxy`, `httpsProxy`, `noProxy`	Set custom proxy for Insights Operator	URL	No default

Creating the insights-config ConfigMap object

This procedure describes how to create the insights-config ConfigMap object for the Insights Operator to set custom configurations.

Red Hat recommends you consult Red Hat Support before making changes to the default Insights Operator configuration.

Prerequisites

Remote health reporting is enabled, which is the default.
You are logged in to the OKD web console as a user with cluster-admin role.

Procedure

Go to Workloads → ConfigMaps and select Project: openshift-insights.
Click Create ConfigMap.

Select Configure via: YAML view and enter your configuration preferences, for example

apiVersion: v1
kind: ConfigMap
metadata:
  name: insights-config
  namespace: openshift-insights
data:
  config.yaml: |
    dataReporting:
      obfuscation:
        - networking
        - workload_names
    sca:
      disable: false
      interval: 2h
    alerting:
       disabled: false
binaryData: {}
immutable: false

Optional: Select Form view and enter the necessary information that way.
In the ConfigMap Name field, enter insights-config.
In the Key field, enter config.yaml.
For the Value field, either browse for a file to drag and drop into the field or enter your configuration parameters manually.
Click Create and you can see the ConfigMap object and configuration information.

Understanding Insights Operator alerts

The Insights Operator declares alerts through the Prometheus monitoring system to the Alertmanager. You can view these alerts in the Alerting UI in the OKD web console by using one of the following methods:

In the Administrator perspective, click Observe → Alerting.
In the Developer perspective, click Observe → <project_name> → Alerts tab.

Currently, Insights Operator sends the following alerts when the conditions are met:

Table 2. Insights Operator alerts
Alert	Description
`InsightsDisabled`	Insights Operator is disabled.
`SimpleContentAccessNotAvailable`	Simple content access is not enabled in Red Hat Subscription Management.
`InsightsRecommendationActive`	Insights has an active recommendation for the cluster.

Disabling Insights Operator alerts

To prevent the Insights Operator from sending alerts to the cluster Prometheus instance, you create or edit the insights-config ConfigMap object.

Previously, a cluster administrator would create or edit the Insights Operator configuration using a support secret in the openshift-config namespace. Red Hat Insights now supports the creation of a ConfigMap object to configure the Operator. The Operator gives preference to the config map configuration over the support secret if both exist.

If the insights-config ConfigMap object does not exist, you must create it when you first add custom configurations. Note that configurations within the ConfigMap object take precedence over the default settings defined in the config/pod.yaml file.

Prerequisites

Remote health reporting is enabled, which is the default.
You are logged in to the OKD web console as cluster-admin.
The insights-config ConfigMap object exists in the openshift-insights namespace.

Procedure

Go to Workloads → ConfigMaps and select Project: openshift-insights.
Click on the insights-config ConfigMap object to open it.
Click Actions and select Edit ConfigMap.
Click the YAML view radio button.

In the file, set the alerting attribute to disabled: true.

apiVersion: v1
kind: ConfigMap
# ...
data:
  config.yaml: |
    alerting:
      disabled: true
# ...

Click Save. The insights-config config-map details page opens.
Verify that the value of the config.yaml alerting attribute is set to disabled: true.

After you save the changes, Insights Operator no longer sends alerts to the cluster Prometheus instance.

Enabling Insights Operator alerts

When alerts are disabled, the Insights Operator no longer sends alerts to the cluster Prometheus instance. You can reenable them.

Prerequisites

Remote health reporting is enabled, which is the default.
You are logged in to the OKD web console as cluster-admin.
The insights-config ConfigMap object exists in the openshift-insights namespace.

Procedure

Go to Workloads → ConfigMaps and select Project: openshift-insights.
Click on the insights-config ConfigMap object to open it.
Click Actions and select Edit ConfigMap.
Click the YAML view radio button.

In the file, set the alerting attribute to disabled: false.

apiVersion: v1
kind: ConfigMap
# ...
data:
  config.yaml: |
    alerting:
      disabled: false
# ...

Click Save. The insights-config config-map details page opens.
Verify that the value of the config.yaml alerting attribute is set to disabled: false.

After you save the changes, Insights Operator again sends alerts to the cluster Prometheus instance.

Downloading your Insights Operator archive

Insights Operator stores gathered data in an archive located in the openshift-insights namespace of your cluster. You can download and review the data that is gathered by the Insights Operator.

Prerequisites

You have access to the cluster as a user with the cluster-admin role.

Procedure

Find the name of the running pod for the Insights Operator:

$ oc get pods --namespace=openshift-insights -o custom-columns=:metadata.name --no-headers  --field-selector=status.phase=Running

Copy the recent data archives collected by the Insights Operator:
```
$ oc cp openshift-insights/<insights_operator_pod_name>:/var/lib/insights-operator ./insights-data (1)
```
1 Replace <insights_operator_pod_name> with the pod name output from the preceding command.

The recent Insights Operator archives are now available in the insights-data directory.

Running an Insights Operator gather operation

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.

The DataGather custom resource is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

If you enable Technology Preview in your cluster, the Insights Operator runs gather operations in individual pods. This is part of the Technology Preview feature set for the Insights Operator and supports the new data gathering features.

Viewing Insights Operator gather durations

You can view the time it takes for the Insights Operator to gather the information contained in the archive. This helps you to understand Insights Operator resource usage and issues with Insights Advisor.

Prerequisites

A recent copy of your Insights Operator archive.

Procedure

From your archive, open /insights-operator/gathers.json.

The file contains a list of Insights Operator gather operations:

    {
      "name": "clusterconfig/authentication",
      "duration_in_ms": 730, (1)
      "records_count": 1,
      "errors": null,
      "panic": null
    }

1	`duration_in_ms` is the amount of time in milliseconds for each gather operation.

Inspect each gather operation for abnormalities.

Running an Insights Operator gather operation from the web console

To collect data, you can run an Insights Operator gather operation by using the OKD web console.

Prerequisites

You are logged in to the OKD web console as a user with the cluster-admin role.

Procedure

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 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.

apiVersion: insights.openshift.io/v1alpha1
kind: DataGather
metadata:
  name: <your_data_gather> (1)
spec:
 gatherers: (2)
   - name: workloads
     state: Disabled

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.

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.

Verification

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.
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.

Running an Insights Operator gather operation from the OpenShift CLI

You can run an Insights Operator gather operation by using the OKD command line interface.

Prerequisites

You are logged in to OKD as a user with the cluster-admin role.

Procedure

Enter the following command to run the gather operation:

$ oc apply -f <your_datagather_definition>.yaml

Replace <your_datagather_definition>.yaml with a configuration file that contains the following parameters:

apiVersion: insights.openshift.io/v1alpha1
kind: DataGather
metadata:
  name: <your_data_gather> (1)
spec:
 gatherers: (2)
   - name: workloads
     state: Disabled

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.

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.

Verification

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.

Additional resources

Insights Operator Gathered Data GitHub repository

Disabling the Insights Operator 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.

The InsightsDataGather custom resource is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Prerequisites

You are logged in to the OKD web console as a user with the cluster-admin role.

Procedure

Navigate to Administration → CustomResourceDefinitions.
On the CustomResourceDefinitions page, use the Search by name field to find the InsightsDataGather resource definition and click it.
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:
1. To disable all the gather operations, enter all under the disabledGatherers key:
  apiVersion: config.openshift.io/v1alpha1 kind: InsightsDataGather metadata: .... spec: (1) gatherConfig: disabledGatherers: - all (2)
  1 The spec parameter specifies gather configurations.
  
  2 The all value disables all gather operations.
2. To disable individual gather operations, enter their values under the disabledGatherers key:
  spec: gatherConfig: disabledGatherers: - clusterconfig/container_images (1) - clusterconfig/host_subnets - workloads/workload_info
  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.

Disabling gather operations degrades Insights Advisor’s ability to offer effective recommendations for your cluster.

Enabling the Insights Operator gather operations

You can enable the Insights Operator gather operations, if the gather operations have been disabled.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Prerequisites

You are logged in to the OKD web console as a user with the cluster-admin role.

Procedure

Navigate to Administration → CustomResourceDefinitions.
On the CustomResourceDefinitions page, use the Search by name field to find the InsightsDataGather resource definition and click it.
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:

To enable all disabled gather operations, remove the gatherConfig stanza:

apiVersion: config.openshift.io/v1alpha1
kind: InsightsDataGather
metadata:
....

spec:
  gatherConfig: (1)
    disabledGatherers: all

1	Remove the `gatherConfig` stanza to enable all gather operations.

To enable individual gather operations, remove their values under the disabledGatherers key:

spec:
  gatherConfig:
    disabledGatherers:
      - clusterconfig/container_images (1)
      - clusterconfig/host_subnets
      - workloads/workload_info

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.

Disabling gather operations degrades Insights Advisor’s ability to offer effective recommendations for your cluster.

Obfuscating Deployment Validation Operator data

Cluster administrators can configure the Insight Operator to obfuscate data from the Deployment Validation Operator (DVO), if the Operator is installed. When the workload_names value is added to the insights-config ConfigMap object, workload names—rather than UIDs—are displayed in Insights for Openshift, making them more recognizable for cluster administrators.

Prerequisites

Remote health reporting is enabled, which is the default.
You are logged in to the OKD web console with the "cluster-admin" role.
The insights-config ConfigMap object exists in the openshift-insights namespace.
The cluster is self managed and the Deployment Validation Operator is installed.

Procedure

Go to Workloads → ConfigMaps and select Project: openshift-insights.
Click on the insights-config ConfigMap object to open it.
Click Actions and select Edit ConfigMap.
Click the YAML view radio button.

In the file, set the obfuscation attribute with the workload_names value.

apiVersion: v1
kind: ConfigMap
# ...
data:
  config.yaml: |
    dataReporting:
      obfuscation:
        - workload_names
# ...

Click Save. The insights-config config-map details page opens.
Verify that the value of the config.yaml obfuscation attribute is set to - workload_names.

1	The `spec` parameter specifies gather configurations.
2	The `all` value disables all gather operations.