Must Gather Operator

The Must Gather operator helps collecting must-gather information on a cluster and uploading it to a case. To use the operator, a cluster administrator can create the following MustGather CR:

apiVersion: managed.openshift.io/v1alpha1
kind: MustGather
metadata:
  name: example-mustgather-basic
spec:
  caseID: '02527285'
  caseManagementAccountSecretRef:
    name: case-management-creds
  serviceAccountRef:
    name: must-gather-admin

This request will collect the standard must-gather info and upload it to case #02527285 using the credentials found in the caseManagementCreds secret.

A more complex example:

apiVersion: managed.openshift.io/v1alpha1
kind: MustGather
metadata:
  name: example-mustgather-full
spec:
  caseID: '02527285'
  caseManagementAccountSecretRef:
    name: case-management-creds
  serviceAccountRef:
    name: must-gather-admin
  mustGatherImages:
  - quay.io/kubevirt/must-gather:latest
  - quay.io/ocs-dev/ocs-must-gather

In this example we are using a specific service account (which must have cluster-admin permissions as per must-gather requirements), and we are specifying a couple of additional must gather images to be run for the kubevirt and ocs subsystem. If not specified, serviceAccountRef.Name will default to default. Also the standard must gather image: quay.io/openshift/origin-must-gather:latest is always added by default.

Proxy Support

The Must Gather operator supports using a proxy. The proxy setting can be specified in the MustGather object. If not specified, the cluster default proxy setting will be used. Here is an example:

apiVersion: managed.openshift.io/v1alpha1
kind: MustGather
metadata:
  name: example-mustgather-proxy
spec:
  caseID: '02527285'
  caseManagementAccountSecretRef:
    name: case-management-creds
  serviceAccountRef:
    name: must-gather-admin
  proxyConfig:
    http_proxy: http://myproxy
    https_proxy: https://my_http_proxy
    no_proxy: master-api

Garbage collection

MustGather instances are cleaned up by the Must Gather operator about 6 hours after completion, regardless of whether they were successful. This is a way to prevent the accumulation of unwanted MustGather resources and their corresponding job resources.

Deploying the Operator

This is a cluster-level operator that you can deploy in any namespace; must-gather-operator is recommended.

Deploying directly with manifests

Here are the instructions to install the latest release creating the manifest directly in OCP.

git clone [email protected]:openshift/must-gather-operator.git; cd must-gather-operator
oc apply -f deploy/crds/managed.openshift.io_mustgathers_crd.yaml
oc new-project must-gather-operator
oc -n must-gather-operator apply -f deploy

Meeting the operator requirements

In order to run, the operator needs a secret to be created by the admin as follows (this assumes the operator is running in the must-gather-operator namespace).

oc create secret generic case-management-creds --from-literal=username=<username> --from-literal=password=<password>

Local Development

Execute the following steps to develop the functionality locally. It is recommended that development be done using a cluster with cluster-admin permissions.

In the operator's Deployment.yaml file, add a variable to the deployment's spec.template.spec.containers.env list called OPERATOR_IMAGE and set the value to your local copy of the image:

          env:
            - name: OPERATOR_IMAGE
              value: "registry.example/repo/image:latest"

Then run:

go mod download

Using the operator-sdk, run the operator locally:

oc apply -f deploy/crds/managed.openshift.io_mustgathers_crd.yaml
oc new-project must-gather-operator
export DEFAULT_MUST_GATHER_IMAGE='quay.io/openshift/origin-must-gather:latest'
export JOB_TEMPLATE_FILE_NAME=./build/templates/job.template.yaml
OPERATOR_NAME=must-gather-operator operator-sdk run --verbose --local --namespace ''