diff --git a/modules/support-log-gather-config-params.adoc b/modules/support-log-gather-config-params.adoc index 600caefcda5..1723f413251 100644 --- a/modules/support-log-gather-config-params.adoc +++ b/modules/support-log-gather-config-params.adoc @@ -56,12 +56,40 @@ Each `MustGather` CR supports only one custom image. To use multiple custom imag |Optional: Specifies the time limit for the `must-gather` command to complete. |The value must be a number with a time unit. The valid units are `s` (seconds), `m` (minutes), or `h` (hours). By default, no time limit is set. +|`spec.obfuscate` +|Optional: Specifies the post-gather obfuscation settings for sensitive data by using must-gather-clean. For more information, see "Data obfuscation in must-gather bundles". +|Object + +|`spec.obfuscate.enabled` +|Optional: Enables data obfuscation. The valid values are `true` and `false`. When set to `true`, you must specify at least one of the following parameters: `uploadTarget`, `storage`, or `obfuscate.source`. The default value is `false`. +|`boolean` + +|`spec.obfuscate.obfuscationConfigRef` +|Optional: Specifies a ConfigMap in the custom resource namespace with a `config.yaml` key that contains `must-gather-clean` rules. If omitted, the default configuration is used, which is consistent IP and MAC address replacement and omitting Secrets and ConfigMaps. +|Object + +|`spec.obfuscate.obfuscationConfigRef.name` +|Specifies the name of the ConfigMap. This field is required when `spec.obfuscate.obfuscationConfigRef` is set. +|`string` + +|`spec.obfuscate.source` +|Optional: Specifies an existing PVC bundle to run in obfuscate-only mode without performing a gather operation. You must specify `spec.uploadTarget` and set `spec.obfuscate.enabled` to true. When you specify this field, you must not specify `spec.imageStreamRef`, `spec.gatherSpec.command`, or set `spec.gatherSpec.audit` to `true`. +|Object + +|`spec.obfuscate.source.claim.name` +|Specifies the name of the source PVC. This field is required when `spec.obfuscate.source` is specified. +|`string` + +|`spec.obfuscate.source.subPath` +|Optional. Specifies a subpath within the source PVC. The value must not contain relative parent directory indicators (`..`). +|`string` + |`spec.retainResourcesOnCompletion` |Optional: Specifies whether to retain the `must-gather` job and its related resources after the completion of data collection. The valid values are `true` and `false`. The default value is `false`. |`boolean` |`spec.serviceAccountName` -a|Optional: Specifies the name of the service account. The default value is `default`. +a|Specifies the name of the service account. The default value is `default`. [NOTE] ==== diff --git a/modules/support-log-gather-configure-cli.adoc b/modules/support-log-gather-configure-cli.adoc index 52d55bb9c7d..c16771ecefa 100644 --- a/modules/support-log-gather-configure-cli.adoc +++ b/modules/support-log-gather-configure-cli.adoc @@ -9,9 +9,6 @@ [role="_abstract"] You must create a `MustGather` custom resource (CR) from the command-line interface (CLI) to automate the collection of diagnostic data from your cluster. This process also automatically uploads the data to a Red{nbsp}Hat Support case. -:FeatureName: Support Log Gather -include::snippets/technology-preview.adoc[] - .Prerequisites * You have installed the {oc-first} tool. @@ -22,6 +19,8 @@ include::snippets/technology-preview.adoc[] * You have created a Kubernetes secret containing your Red Hat Customer Portal credentials. The secret must contain a username field and a password field. +* If you want to persist the archive, you have created a persistant volume claim (PVC) in the CR namespace. + * If you are using a custom image, you have configured an `ImageStream` resource in the Operator namespace that references an approved custom image URL. * You have created a service account. If you are using a custom image, you have created a service account with permissions to access the `ImageStream` resource. @@ -49,10 +48,6 @@ spec: imageStreamRef: name: "network-debug-tools" tag: "v1.2" - proxyConfig: - httpProxy: "http://proxy.example.com:8080" - httpsProxy: "https://proxy.example.com:8443" - noProxy: ".example.com,localhost" mustGatherTimeout: "1h30m9s" uploadTarget: type: SFTP @@ -120,3 +115,14 @@ oc logs -f pod/example-mg-gk8m8 -c upload ---- + When successful, the process must create an archive and upload it to the Red{nbsp}Hat Secure File Transfer Protocol (SFTP) server for the specified case. + +. If no job is created, check validation errors by running the following command: ++ +[source,terminal] +---- +$ oc get mustgather example-mg -o yaml +---- ++ +For failures that the controller detects after the CR is created, the controller sets `status.status` to `Failed`, `status.completed` to `true`, and describes the failure in `status.reason`. ++ +However, if a referenced secret or obfuscation ConfigMap is missing, the controller generates a requeueing error and a `Warning` event without setting `status.status` to `Failed` so that the CR keeps retrying. \ No newline at end of file diff --git a/modules/support-log-gather-install-cli.adoc b/modules/support-log-gather-install-cli.adoc index 57758bbab76..9eed551eb29 100644 --- a/modules/support-log-gather-install-cli.adoc +++ b/modules/support-log-gather-install-cli.adoc @@ -9,9 +9,6 @@ [role="_abstract"] To enable automated log collection for support cases, you can install {support-log-gather} from the command-line interface (CLI). -:FeatureName: Support Log Gather -include::snippets/technology-preview.adoc[] - .Prerequisites * You have access to the cluster with `cluster-admin` privileges. @@ -58,7 +55,7 @@ metadata: name: support-log-gather-operator namespace: must-gather-operator spec: - channel: tech-preview + channel: stable name: support-log-gather-operator source: redhat-operators sourceNamespace: openshift-marketplace @@ -101,7 +98,7 @@ $ oc get subscription -n must-gather-operator [source,terminal] ---- NAME PACKAGE SOURCE CHANNEL -support-log-gather-operator support-log-gather-operator redhat-operators tech-preview +support-log-gather-operator support-log-gather-operator redhat-operators stable ---- . Verify that the Operator is installed by running the following command: diff --git a/modules/support-log-gather-install-console.adoc b/modules/support-log-gather-install-console.adoc index a6b17efdbca..97e50b96052 100644 --- a/modules/support-log-gather-install-console.adoc +++ b/modules/support-log-gather-install-console.adoc @@ -9,9 +9,6 @@ [role="_abstract"] You can use the web console to install the {support-log-gather}. -:FeatureName: Support Log Gather -include::snippets/technology-preview.adoc[] - .Prerequisites * You have access to the cluster with `cluster-admin` privileges. diff --git a/modules/support-log-gather-obfuscation.adoc b/modules/support-log-gather-obfuscation.adoc new file mode 100644 index 00000000000..02e50bca454 --- /dev/null +++ b/modules/support-log-gather-obfuscation.adoc @@ -0,0 +1,165 @@ +// Module included in the following assemblies: +// +// * support/gathering-cluster-data.adoc + +:_mod-docs-content-type: CONCEPT +[id="support-log-gather-obfuscation_{context}"] += Data obfuscation in must-gather bundles + +[role="_abstract"] +The `MustGather` custom resource (CR) supports automatic obfuscation of sensitive data in collected diagnostic bundles before uploading the data to Red{nbsp}Hat Support or persisting it to a Persistent Volume Claim (PVC). + +When obfuscation is enabled, the Operator runs `must-gather-clean` on the collected or referenced bundle. By default, the Operator consistently replaces IP addresses and MAC addresses and omits Kubernetes `Secret` and `ConfigMap` resources. You can customize these obfuscation rules by supplying a `ConfigMap` that contains a `config.yaml` configuration file. + +If the obfuscation process fails, the gather job fails, and the system does not upload or persist the diagnostic bundle. + +== Supported obfuscation modes + +Select one of the following four obfuscation modes based on your storage and collection requirements: + +.Obfuscation modes +[cols="1,3", options="header"] +|=== +| Mode | Description + +| Gather, obfuscate, and upload +| Collects data, applies default or custom obfuscation rules, and uploads the cleaned bundle to SFTP. Requires `spec.obfuscate.enabled: true` and `spec.uploadTarget`. + +| Gather, obfuscate, and upload with custom rules +| Collects data, applies custom rules from a `ConfigMap` referenced in `spec.obfuscate.obfuscationConfigRef`, and uploads the bundle to SFTP. + +| Obfuscate and upload an existing bundle +| Skips the gather phase, obfuscates an existing PVC bundle mounted as read-only, and uploads the result. Requires `spec.obfuscate.source` and `spec.uploadTarget`. + +| Gather, obfuscate, and save to PVC +| Collects data, applies obfuscation rules, and persists raw and cleaned output to a PVC without uploading. Requires `spec.obfuscate.enabled: true` and `spec.storage`. +|=== + +[IMPORTANT] +==== +When configuring data obfuscation, adhere to the following constraints: + +* Setting `spec.obfuscate.enabled: true` requires at least one of the following parameters: `uploadTarget`, `storage`, or `obfuscate.source`. +* Specifying `spec.obfuscate.source` requires both `spec.obfuscate.enabled: true` and `spec.uploadTarget`. +* You must not specify `spec.obfuscate.source` together with `imageStreamRef`, `gatherSpec.command`, or `gatherSpec.audit: true`. +* Specifying an invalid `obfuscationConfigRef` causes the obfuscation step and the Job to fail. +==== + +== Custom obfuscation ConfigMap example + +To override default obfuscation behavior, create a `ConfigMap` in the CR namespace with a key named `config.yaml`: + +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-obfuscation-rules + namespace: must-gather-operator +data: + config.yaml: | + config: + obfuscate: + - type: IP + replacementType: Consistent + target: All + - type: MAC + replacementType: Consistent + target: All + - type: Regex + regex: "my-internal-domain\\.corp\\.example\\.com" + replacementType: Consistent + omit: + - type: Kubernetes + kubernetesResource: + kind: "Secret" +---- + +== MustGather CR configuration examples + +Gather, obfuscate, and upload with default rules:: +[source,yaml] +---- +apiVersion: operator.openshift.io/v1 +kind: MustGather +metadata: + name: obfuscated-gather +spec: + serviceAccountName: must-gather-admin + obfuscate: + enabled: true + uploadTarget: + type: SFTP + sftp: + caseID: '02527285' + caseManagementAccountSecretRef: + name: case-management-creds + internalUser: true +---- + +Gather, obfuscate, and upload with custom rules:: +[source,yaml] +---- +apiVersion: operator.openshift.io/v1 +kind: MustGather +metadata: + name: obfuscated-gather-custom +spec: + serviceAccountName: must-gather-admin + obfuscate: + enabled: true + obfuscationConfigRef: + name: my-obfuscation-rules + uploadTarget: + type: SFTP + sftp: + caseID: '02527285' + caseManagementAccountSecretRef: + name: case-management-creds + internalUser: true +---- + +Obfuscate and upload an existing bundle from a PVC:: +[source,yaml] +---- +apiVersion: operator.openshift.io/v1 +kind: MustGather +metadata: + name: obfuscate-and-upload +spec: + serviceAccountName: must-gather-admin + obfuscate: + enabled: true + source: + claim: + name: must-gather-pvc + subPath: must-gather-data + uploadTarget: + type: SFTP + sftp: + caseID: '02527285' + caseManagementAccountSecretRef: + name: case-management-creds + internalUser: true +---- + +Gather, obfuscate, and save to a PVC:: +When using PVC storage mode, raw output is stored at `{subPath}/{directoryName}/` and cleaned output is stored at `{subPath}/{directoryName}/cleaned/`. The Operator writes the `obfuscation.log` file to both locations. + +[source,yaml] +---- +apiVersion: operator.openshift.io/v1 +kind: MustGather +metadata: + name: obfuscated-gather-pvc +spec: + serviceAccountName: must-gather-admin + obfuscate: + enabled: true + storage: + type: PersistentVolume + persistentVolume: + claim: + name: must-gather-pvc + subPath: collections +---- \ No newline at end of file diff --git a/modules/support-log-gather-overview.adoc b/modules/support-log-gather-overview.adoc index d73be9361ce..a68807070b4 100644 --- a/modules/support-log-gather-overview.adoc +++ b/modules/support-log-gather-overview.adoc @@ -9,13 +9,12 @@ [role="_abstract"] {support-log-gather} Operator builds on the functionality of the traditional `must-gather` tool to automate the collection of debugging data. It streamlines troubleshooting by packaging the collected information into a single `.tar` file and automatically uploading it to the specified Red{nbsp}Hat Support case. -:FeatureName: Support Log Gather -include::snippets/technology-preview.adoc[] - The key features of {support-log-gather} include the following: -* **No administrator privileges required**: Enables you to collect and upload logs without needing elevated permissions, making it easier for non-administrators to gather data securely. +* **Flexible permissions model**: Creates a `MustGather` custom resource without `cluster-admin` privileges. The job runs as the service account that you specify in the CR. Ensure that this service account has sufficient permissions to collect diagnostic data. * **Simplified log collection**: Collects debugging data from the cluster, such as resource definitions and service logs. -* **Configurable data upload**: Provides configuration options to either automatically upload the `.tar` file to a support case, or store it locally for manual upload. \ No newline at end of file +* **Configurable data upload**: Provides configuration options to either automatically upload the `.tar` file to a support case, or store it locally for manual upload. + +* **Optional data obfuscation**: Obfuscates sensitive information such as IP addresses, MAC addresses, secrets, and ConfigMaps from the collected bundle before upload or local persistence by using the integrated must-gather-clean tool. \ No newline at end of file diff --git a/modules/support-log-gather-reduce-size.adoc b/modules/support-log-gather-reduce-size.adoc index 60e6112c8ec..6d415853b5c 100644 --- a/modules/support-log-gather-reduce-size.adoc +++ b/modules/support-log-gather-reduce-size.adoc @@ -17,12 +17,12 @@ You can exclude older, rotated log files, such as `+*.gz+` or `+*.1+` files, fro .Example `MustGather` CR configured to skip rotated logs [source,yaml] ---- -apiVersion: operator.openshift.io/v1alpha1 +apiVersion: operator.openshift.io/v1 kind: MustGather metadata: name: full-mustgather spec: - serviceAccountName: must-gather-operator + serviceAccountName: must-gather-admin gatherSpec: command: - /bin/sh @@ -38,4 +38,9 @@ spec: internalUser: true ---- +[IMPORTANT] +==== +Do not set `serviceAccountName` to the Operator service account when the `MustGather` CR is in the Operator namespace. Use a dedicated service account with permissions to run must-gather tool. +==== + `REDUCE_LOGS=skip_rotated_logs gather`:: Sets the `REDUCE_LOGS` shell variable and executes the `gather` script. As a result, the script excludes the collection of rotated log files. diff --git a/support/gathering-cluster-data.adoc b/support/gathering-cluster-data.adoc index 3f5ad4e5981..29aae967cb0 100644 --- a/support/gathering-cluster-data.adoc +++ b/support/gathering-cluster-data.adoc @@ -106,6 +106,9 @@ include::modules/support-log-gather-reduce-size.adoc[leveloffset=+2] include::modules/support-log-gather-config-params.adoc[leveloffset=+2] +//Obfuscating sensitive data in must-gather bundles +include::modules/support-log-gather-obfuscation.adoc[leveloffset=+2] + //Support log gather uninstallation include::modules/support-log-gather-uninstall-console.adoc[leveloffset=+2]