Must gather

Usage

mas must-gather [options]

Destination

  • -d|--directory MG_DIR Directory where the must-gather will be saved, defaults to /tmp/must-gather (or /must-gather if the directory exists)
  • -k|--keep-files Do not delete individual files after creating the must-gather compressed tar archive

General Controls

  • --summary-only Perform a much faster must-gather that only gathers high level summary information
  • --no-logs Skip collection of pod logs, greatly speeds up must-gather collection time when pod logs are not required
  • --secret-data Include secrets content in the must-gather

MAS Content Controls:

  • --mas-instance-ids Limit must-gather to a list of MAS instance IDs (comma-seperated list)
  • --mas-app-ids Limit must-gather to a subset of MAS namespaces (comma-seperated list)

Disable Collectors:

  • --no-ocp Disable must-gather for the OCP cluster itself
  • --no-dependencies Disable must-gather for in-cluster dependencies (Db2, Cloud Pak for Data, Cloud Pak Foundational Services, Mongo)
  • --no-sls Disable must-gather for IBM Suite License Service

Additional Collectors:

  • --extra-namespaces Enable must-gather in custom namespaces (comma-seperated list)

Artifactory Upload:

  • --artifactory-token ARTIFACTORY_TOKEN Provide a token for Artifactory to automatically upload the file to ARTIFACTORY_UPLOAD_DIRECTORY
  • --artifactory-upload-directory ARTIFACTORY_UPLOAD_DIRECTORY Working URL to the root directory in Artifactory where the must-gather file should be uploaded

Content

/must-gather/
├── 20230423-204411
│   ├── reconcile-logs
│   │   └── mas-inst1-core
│   │   |   ├── Suite
│   │   |   │   └── 20230423-172432.log
│   │   |   │   └── 20230423-204010.log
│   │   |   ├── Workspace
│   │   |   │   └── 20230423-113224.log
│   │   |   └── MongoCfg
│   │   |       └── 20230423-130043.log
│   ├── resources
│   │   ├── _cluster
│   |   │   ├── clusterversions.txt
│   |   │   ├── namespaces.txt
│   |   │   ├── operatorconditions.txt
│   |   │   ├── packagemanifests.txt
│   |   │   └── storageclasses.txt
│   │   ├── mas-inst1-core
│   │   |   ├── clusterserviceversions
│   │   |   │   └── <contain definition of every ClusterServiceVersion in the namespace>
│   │   |   ├── configmaps
│   │   |   │   ├── ibm-cpp-config.yaml
│   │   |   │   └── ibm-licensing-upload-config.yaml
│   │   |   ├── deployments
│   │   |   │   ├── inst1-coreapi.yaml
│   │   |   │   └── isnt2-internalapi.yaml
│   │   |   ├── installplans
│   │   |   │   └── <contain definition of every InstallPlan in the namespace>
│   │   |   ├── jobs
│   │   |   │   └── <contain definition of every Job in the namespace>
│   │   |   ├── operatorconditions
│   │   |   │   └── <contain definition of every OperatorCondition in the namespace>
│   │   |   ├── pods
│   │   |   │   ├── app1
│   │   |   │   |   ├── logs
│   │   |   │   |   |   └── inst1-coreapi-28037940-njx4_coreapi.log
│   │   |   │   |   ├── inst1-coreapi-28037940-njx4.txt
│   │   |   │   |   └── inst1-coreapi-28037940-njx4.yaml
│   │   |   │   ├── app2
│   │   |   │   └── app3
│   │   |   ├── pvc
│   │   |   │   └── <contain definition of every PVC in the namespace>
│   │   |   ├── roles
│   │   |   │   └── <contain definition of every Role in the namespace>
│   │   |   ├── rolebindings
│   │   |   │   └── <contain definition of every RoleBinding in the namespace>
│   │   |   ├── routes
│   │   |   │   └── <contain definition of every Route in the namespace>
│   │   |   ├── secrets
│   │   |   │   └── <contain definition of every Secret in the namespace>
│   │   |   ├── serviceaccounts
│   │   |   │   └── <contain definition of every ServiceAccount in the namespace>
│   │   |   ├── services
│   │   |   │   └── <contain definition of every Service in the namespace>
│   │   |   ├── statefulsets
│   │   |   │   └── <contain definition of every StatefulSet in the namespace>
│   │   |   ├── subscriptions
│   │   |   │   └── <contain definition of every Subscription in the namespace>
│   │   |   ├── clusterserviceversions.txt
│   │   |   ├── configmaps.txt
│   │   |   ├── deployments.txt
│   │   |   ├── installplans.txt
│   │   |   ├── jobs.txt
│   │   |   ├── operatorconditions.txt
│   |   │   ├── pods.txt
│   |   │   ├── pvc.txt
│   |   │   ├── roles.txt
│   |   │   ├── rolebindings.txt
│   |   │   ├── routes.txt
│   |   │   ├── secrets.txt
│   |   │   ├── serviceaccounts.txt
│   |   │   ├── services.txt
│   |   │   ├── statefulsets.txt
│   │   |   └── subscriptions.txt
│   │   └── mas-inst1-appId
│   │   |   └── <contain must-gather from mas-inst1-appId>
│   │   ├── mas-inst2-core
│   │   |   └── <contain must-gather from mas-inst2-core>
│   │   └── mas-inst2-appId
│   │       └── <contain must-gather from mas-inst2-appId>
│   ├── cp4d.txt
│   ├── db2u.txt
│   ├── ibm-common-services.txt
│   ├── mas-inst1-core.txt
│   ├── mas-inst1-appId.txt
│   ├── mas-inst2-core.txt
│   ├── mas-inst2-appId.txt
└── must-gather-20230423-204411.tgz

Usage

As with other CLI functions, the must-gather will run against the currently connected cluster, use oc login to connect to a cluster before running mas must-gather.

# Start the container in docker
docker run -ti --rm -v /~:/mnt/home --pull always quay.io/ibmmas/cli
# Login to the cluster and run the must-gather, which will be available in the home directory on the local system
oc login --token=xxx --server=https://xxx:xxx
mas must-gather -d /mnt/home/must-gather

# Start the container in podman
podman run -ti --rm -v /~:/mnt/home:z --pull always quay.io/ibmmas/cli
# Login to the cluster and run the must-gather, which will be available in the home directory on the local system
oc login --token=xxx --server=https://xxx:xxx
mas must-gather -d /mnt/home/must-gather

Examples

Cluster-scoped must-gather: Collect data for all MAS instances, critical cluster resources, and most MAS dependencies (Db2, Cloud Pak Foundational Services, Cloud Pak for Data, etc).

mas must-gather -d /mnt/home/must-gather

Include secret data: By default secret data is not included in the must-gather archive, only the existence of the secret is recorded and how many fields it contains. Adding the --secret-data flag will trigger the inclusion of the secret data as well.

mas must-gather -d /mnt/home/must-gather --secret-data

Quick must-gather: This must-gather will omit pod logs and details of standard Kubernetes resources, it runs incredibly fast but it's usage is situational.

mas must-gather -d /mnt/home/must-gather --summary-only

Target a specific MAS instance: By setting ---mas-instance-ids to a comma-separated list of instance IDs you can instruct the must-gather to focus on specific instances only.

mas must-gather -d /mnt/home/must-gather --mas-instance-ids inst1

Target specific applications: Setting --mas-app-ids to a comma-separated list of MAS application IDs will restict the MAS-specific must-gather to those applications only, which can be combined with --no-ocp, --no-dependencies, --no-sls, & --mas-instance-ids to focus the collection to a specific namespace/MAS application.

# Target Core in inst1
mas must-gather -d /mnt/home/must-gather --no-ocp --no-dependencies --no-sls --mas-instance-ids "inst1" --mas-app-ids "core"

# Target Core + Manage in inst2
mas must-gather -d /mnt/home/must-gather --no-ocp --no-dependencies --no-sls --mas-instance-ids "inst2" --mas-app-ids "core,manage"

Execute the Must-Gather in non-interactive mode

docker run --rm -v /~:/mnt/home:z quay.io/ibmmas/cli /bin/bash -c "oc login --token=sha256~XFnSk...fc8U --server=https://api.<openshift domain>:6443/ --insecure-skip-tls-verify; mas must-gather -d /mnt/home/must-gather"

Execute the Must-Gather in non-interactive mode using podman

podman run --rm -v /data:/mnt/home:z quay.io/ibmmas/cli /bin/bash -c "oc login --token=sha256~XFnSk...fc8U --server=https://api.<openshift domain>:6443/ --insecure-skip-tls-verify; mas must-gather -d /mnt/home/must-gather"