From dd22cd4ac79757a765632b40195880fe511cd187 Mon Sep 17 00:00:00 2001 From: Pan Ousley Date: Tue, 10 Sep 2019 18:59:59 -0400 Subject: [PATCH] CNV-2386: must-gather tool --- _topic_map.yml | 2 + .../cnv-collecting-cnv-data.adoc | 22 +++++++++ modules/about-must-gather.adoc | 29 ++++++++++++ modules/cnv-about-collecting-cnv-data.adoc | 20 ++++++++ modules/gathering-data-specific-features.adoc | 47 +++++++++++++++++++ modules/support-gather-data.adoc | 30 +++++------- support/gathering-cluster-data.adoc | 1 + 7 files changed, 133 insertions(+), 18 deletions(-) create mode 100644 cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc create mode 100644 modules/about-must-gather.adoc create mode 100644 modules/cnv-about-collecting-cnv-data.adoc create mode 100644 modules/gathering-data-specific-features.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 92a30e070e..0c42484b9b 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1043,6 +1043,8 @@ Topics: File: cnv-events - Name: OpenShift cluster monitoring, logging, and Telemetry File: cnv-openshift-cluster-monitoring + - Name: Collecting container-native virtualization data for Red Hat Support + File: cnv-collecting-cnv-data - Name: Container-native Virtualization 2.0 release notes Dir: cnv_release_notes Topics: diff --git a/cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc b/cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc new file mode 100644 index 0000000000..7865b35572 --- /dev/null +++ b/cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc @@ -0,0 +1,22 @@ +[id="cnv-collecting-cnv-data"] += Collecting {CNVProductName} data for Red Hat Support +include::modules/cnv-document-attributes.adoc[] +:context: cnv-collecting-cnv-data +toc::[] + + +The `must-gather` tool enables you to collect diagnostic information about your +{product-title} cluster, including virtual machines and other data related to +{CNVProductName}. + +:FeatureName: {CNVProductNameStart} + +include::modules/technology-preview.adoc[leveloffset=+1] + +include::modules/about-must-gather.adoc[leveloffset=+1] + +include::modules/cnv-about-collecting-cnv-data.adoc[leveloffset=+1] + +include::modules/gathering-data-specific-features.adoc[leveloffset=+1] + + diff --git a/modules/about-must-gather.adoc b/modules/about-must-gather.adoc new file mode 100644 index 0000000000..5e16b5e715 --- /dev/null +++ b/modules/about-must-gather.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc +// * support/gathering-cluster-data.adoc + +[id="about-must-gather_{context}"] += About the must-gather tool + +When opening a support case, it is often helpful to provide debugging +information about your cluster to Red Hat Support. You can gather this +information by using the `oc adm must-gather` CLI command. + +The `oc adm must-gather` CLI command collects the information from your cluster +that is most likely needed for debugging issues, such as: + +* Resource definitions +* Audit logs +* Service logs + +You can specify one or more images when you run the command by including the +`--image` argument. When you specify an image, the tool collects data related to +that feature or product. + +When you run `oc adm must-gather`, a new Pod is created on the cluster. The data +is collected on that Pod and saved in a new directory that starts with +`must-gather.local`. This directory is created in the current working +directory. + +// todo: table or ref module listing available images? \ No newline at end of file diff --git a/modules/cnv-about-collecting-cnv-data.adoc b/modules/cnv-about-collecting-cnv-data.adoc new file mode 100644 index 0000000000..94cc91b6c5 --- /dev/null +++ b/modules/cnv-about-collecting-cnv-data.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc + +[id="cnv-about-collecting-cnv-data_{context}"] += About collecting {CNVProductName} data + +You can use the `oc adm must-gather` CLI command to collect information about your +cluster, including features and objects associated with {CNVProductName}: + +* The Hyperconverged Cluster Operator namespaces (and child objects) +* All namespaces (and their child objects) that belong to any {CNVProductName} +resources +* All {CNVProductName} Custom Resource Definitions (CRDs) +* All namespaces that contain virtual machines +* All virtual machine definitions + +To collect {CNVProductName} data with `must-gather`, you must specify the +{CNVProductName} image: +`--image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8`. \ No newline at end of file diff --git a/modules/gathering-data-specific-features.adoc b/modules/gathering-data-specific-features.adoc new file mode 100644 index 0000000000..067e98e252 --- /dev/null +++ b/modules/gathering-data-specific-features.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * support/gathering-cluster-data.adoc +// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc +// Dependency: modules/cnv-document-attributes.adoc + +[id="gathering-data-specific-features_{context}"] += Gathering data about specific features + +You can gather debugging information about specific features by using the +`oc adm must-gather` CLI command with the `--image` or `--image-stream` argument. +The `must-gather` tool supports multiple images, so you can gather data about +more than one feature by running a single command. + +.Prerequisites + +* Access to the cluster as a user with the `cluster-admin` role. +* The {product-title} CLI (`oc`) installed. + +.Procedure + +. Navigate to the directory where you want to store the `must-gather` data. + +. Run the `oc adm must-gather` command with one or more `--image` or `--image-stream` +arguments. For example, the following command gathers both the default cluster +data and information specific to {CNVProductName}: ++ +---- +$ oc adm must-gather \ + --image-stream=openshift/must-gather \ <1> + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8 <2> +---- +<1> Default {product-title} must-gather image +<2> {CNVProductNameStart} must-gather image + +. Create a compressed file from the `must-gather` directory that was just created +in your working directory. For example, on a computer that uses a Linux +operating system, run the following command: ++ +---- +$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1> +---- +<1> Make sure to replace `must-gather-local.5421342344627712289/` with the +actual directory name. + +. Attach the compressed file to your support case on the +link:https://access.redhat.com[Red Hat Customer Portal]. diff --git a/modules/support-gather-data.adoc b/modules/support-gather-data.adoc index d77b388b82..8029c0554b 100644 --- a/modules/support-gather-data.adoc +++ b/modules/support-gather-data.adoc @@ -5,39 +5,33 @@ [id="support_gathering_data_{context}"] = Gathering data about your cluster for Red Hat Support -When opening a support case, it is often helpful to provide debugging -information about your cluster to Red Hat Support. You can gather this -information by using the `oc adm must-gather` CLI command. - -The `oc adm must-gather` CLI command collects the information from your cluster -that is most likely needed for debugging issues, such as: - -* Resource definitions -* Audit logs -* Service logs +You can gather debugging information about your cluster by using the +`oc adm must-gather` CLI command. .Prerequisites * Access to the cluster as a user with the `cluster-admin` role. +* The {product-title} CLI (`oc`) installed. .Procedure +. Navigate to the directory where you want to store the `must-gather` data. + . Run the `oc adm must-gather` command: + ---- $ oc adm must-gather ---- -+ -This creates a Pod on the cluster to perform the data collection on. All of the -collected resources and data from your cluster are saved in the current -directory in a new directory that starts with `must-gather.local`. -. Create a compressed file from the `must-gather` directory. For example, on a -computer that uses a Linux operating system, run the following command: +. Create a compressed file from the `must-gather` directory that was just created +in your working directory. For example, on a computer that uses a Linux +operating system, run the following command: + ---- -$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ +$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1> ---- +<1> Make sure to replace `must-gather-local.5421342344627712289/` with the +actual directory name. . Attach the compressed file to your support case on the -link:http://access.redhat.com[Red Hat Customer Portal]. +link:https://access.redhat.com[Red Hat Customer Portal]. diff --git a/support/gathering-cluster-data.adoc b/support/gathering-cluster-data.adoc index cb9b290661..6256199d3a 100644 --- a/support/gathering-cluster-data.adoc +++ b/support/gathering-cluster-data.adoc @@ -6,4 +6,5 @@ include::modules/common-attributes.adoc[] toc::[] // Gathering data about your cluster for Red Hat Support +include::modules/about-must-gather.adoc[leveloffset=+1] include::modules/support-gather-data.adoc[leveloffset=+1]