Merge pull request #51875 from sheriff-rh/CMP-1618

CMP-1618 update Compliance Operator docs

Author: EricPonvelle

modules/compliance-anatomy.adoc

@@ -13,34 +13,34 @@ The compliance content is stored in `Profile` objects that are generated from a
 
 [source,terminal]
 ----
-$ oc get profilebundle.compliance
+$ oc get -n openshift-compliance profilebundle.compliance
 ----
 
 [source,terminal]
 ----
-$ oc get profile.compliance
+$ oc get -n openshift-compliance profile.compliance
 ----
 
 The `ProfileBundle` objects are processed by deployments labeled with the `Bundle` name. To troubleshoot an issue with the `Bundle`, you can find the deployment and view logs of the pods in a deployment:
 
 [source,terminal]
 ----
-$ oc logs -lprofile-bundle=ocp4 -c profileparser
+$ oc logs -n openshift-compliance -lprofile-bundle=ocp4 -c profileparser
 ----
 
 [source,terminal]
 ----
-$ oc get deployments,pods -lprofile-bundle=ocp4
+$ oc get -n openshift-compliance deployments,pods -lprofile-bundle=ocp4
 ----
 
 [source,terminal]
 ----
-$ oc logs pods/<pod-name>
+$ oc logs -n openshift-compliance pods/<pod-name>
 ----
 
 [source,terminal]
 ----
-$ oc describe pod/<pod-name> -c profileparser
+$ oc describe -n openshift-compliance pod/<pod-name> -c profileparser
 ----
 
 [id="compliance-anatomy-scan-setting-scan-binding-lifecycle_{context}"]
@@ -123,14 +123,15 @@ In this phase, several config maps that contain either environment for the scann
 
 [source,terminal]
 ----
-$ oc get cm -lcompliance.openshift.io/scan-name=rhcos4-e8-worker,complianceoperator.openshift.io/scan-script=
+$ oc -n openshift-compliance get cm \
+-l compliance.openshift.io/scan-name=rhcos4-e8-worker,complianceoperator.openshift.io/scan-script=
 ----
 
 These config maps will be used by the scanner pods. If you ever needed to modify the scanner behavior, change the scanner debug level or print the raw results, modifying the config maps is the way to go. Afterwards, a persistent volume claim is created per scan to store the raw ARF results:
 
 [source,terminal]
 ----
-$ oc get pvc -lcompliance.openshift.io/scan-name=<scan_name>
+$ oc get pvc -n openshift-compliance -lcompliance.openshift.io/scan-name=rhcos4-e8-worker
 ----
 
 The PVCs are mounted by a per-scan `ResultServer` deployment. A `ResultServer` is a simple HTTP server where the individual scanner pods upload the full ARF results to. Each server can run on a different node. The full ARF results might be very large and you cannot presume that it would be possible to create a volume that could be mounted from multiple nodes at the same time. After the scan is finished, the `ResultServer` deployment is scaled down. The PVC with the raw results can be mounted from another custom pod and the results can be fetched or inspected. The traffic between the scanner pods and the `ResultServer` is protected by mutual TLS protocols.
@@ -147,8 +148,9 @@ $ oc get pods -lcompliance.openshift.io/scan-name=rhcos4-e8-worker,workload=scan
 ----
 NAME                                                              READY   STATUS      RESTARTS   AGE   LABELS
 rhcos4-e8-worker-ip-10-0-169-90.eu-north-1.compute.internal-pod   0/2     Completed   0          39m   compliance.openshift.io/scan-name=rhcos4-e8-worker,targetNode=ip-10-0-169-90.eu-north-1.compute.internal,workload=scanner
-At this point, the scan proceeds to the Running phase.
 ----
++
+The scan then proceeds to the Running phase.
 
 [id="compliance-scan-running-phase_{context}"]
 === Running phase
@@ -158,7 +160,7 @@ The running phase waits until the scanner pods finish. The following terms and p
 
 * *scanner*: This container runs the scan. For node scans, the container mounts the node filesystem as `/host` and mounts the content delivered by the init container. The container also mounts the `entrypoint` `ConfigMap` created in the Launching phase and executes it. The default script in the entrypoint `ConfigMap` executes OpenSCAP and stores the result files in the `/results` directory shared between the pod's containers. Logs from this pod can be viewed to determine what the OpenSCAP scanner checked. More verbose output can be viewed with the `debug` flag.
 
-* *logcollector*: The logcollector container waits until the scanner container finishes. Then, it uploads the full ARF results to the `ResultServer` and separately uploads the XCCDF results along with scan result and OpenSCAP result code as a `ConfigMap.` These result config maps are labeled with the scan name (`compliance.openshift.io/scan-name=<scan_name>`):
+* *logcollector*: The logcollector container waits until the scanner container finishes. Then, it uploads the full ARF results to the `ResultServer` and separately uploads the XCCDF results along with scan result and OpenSCAP result code as a `ConfigMap.` These result config maps are labeled with the scan name (`compliance.openshift.io/scan-name=rhcos4-e8-worker`):
 +
 [source,terminal]
 ----
@@ -243,7 +245,8 @@ It is also possible to trigger a re-run of a scan in the Done phase by annotatin
 
 [source,terminal]
 ----
-$ oc annotate compliancescans/<scan_name> compliance.openshift.io/rescan=
+$ oc -n openshift-compliance \
+annotate compliancescans/rhcos4-e8-worker compliance.openshift.io/rescan=
 ----
 
 After the scan reaches the Done phase, nothing else happens on its own unless the remediations are set to be applied automatically with `autoApplyRemediations: true`. The {product-title} administrator would now review the remediations and apply them as needed. If the remediations are set to be applied automatically, the `ComplianceSuite` controller takes over in the Done phase, pauses the machine config pool to which the scan maps to and applies all the remediations in one go. If a remediation is applied, the `ComplianceRemediation` controller takes over.
@@ -299,14 +302,16 @@ The remediation loop ends once the rendered machine config is updated, if needed
 
 [source,terminal]
 ----
-$ oc annotate compliancescans/<scan_name> compliance.openshift.io/rescan=
+$ oc -n openshift-compliance \
+annotate compliancescans/rhcos4-e8-worker compliance.openshift.io/rescan=
 ----
 
 The scan will run and finish. Check for the remediation to pass:
 
 [source,terminal]
 ----
-$ oc get compliancecheckresults/rhcos4-e8-worker-audit-rules-dac-modification-chmod
+$ oc -n openshift-compliance \
+get compliancecheckresults/rhcos4-e8-worker-audit-rules-dac-modification-chmod
 ----
 
 .Example output

modules/compliance-apply-remediation-for-customized-mcp.adoc

@@ -15,7 +15,7 @@ Do not set `protectKernelDefaults: false` in the `KubeletConfig` file, because t
 +
 [source,terminal]
 ----
-$ oc get nodes
+$ oc get nodes -n openshift-compliance
 ----
 +
 .Example output
@@ -34,7 +34,9 @@ ip-10-0-197-35.us-east-2.compute.internal  Ready   master 5h22m  v1.25.0
 +
 [source,terminal]
 ----
-$ oc label node ip-10-0-166-81.us-east-2.compute.internal node-role.kubernetes.io/<machine_config_pool_name>=
+$ oc -n openshift-compliance \
+label node ip-10-0-166-81.us-east-2.compute.internal \
+node-role.kubernetes.io/<machine_config_pool_name>=
 ----
 +
 .Example output

modules/compliance-apply-remediations-from-scans.adoc

@@ -14,5 +14,6 @@ Although you can use the `autoApplyRemediations` boolean parameter in a `Complia
 
 [source,terminal]
 ----
-$ oc annotate compliancesuites/<suite-_name> compliance.openshift.io/apply-remediations=
+$ oc -n openshift-compliance \
+annotate compliancesuites/workers-compliancesuite compliance.openshift.io/apply-remediations=
 ----

modules/compliance-applying.adoc

@@ -9,7 +9,9 @@ The boolean attribute `spec.apply` controls whether the remediation should be ap
 
 [source,terminal]
 ----
-$ oc patch complianceremediations/<scan_name>-sysctl-net-ipv4-conf-all-accept-redirects --patch '{"spec":{"apply":true}}' --type=merge
+$ oc -n openshift-compliance \
+patch complianceremediations/<scan-name>-sysctl-net-ipv4-conf-all-accept-redirects \
+--patch '{"spec":{"apply":true}}' --type=merge
 ----
 
 After the Compliance Operator processes the applied remediation, the `status.ApplicationState` attribute would change to *Applied* or to *Error* if incorrect. When a machine config remediation is applied, that remediation along with all other applied remediations are rendered into a `MachineConfig` object named `75-$scan-name-$suite-name`. That `MachineConfig` object is subsequently rendered by the Machine Config Operator and finally applied to all the nodes in a machine config pool by an instance of the machine control daemon running on each node.

modules/compliance-auto-update-remediations.adoc

@@ -14,7 +14,8 @@ In some cases, a scan with newer content might mark remediations as `OUTDATED`.
 
 [source,terminal]
 ----
-$ oc annotate compliancesuites/<suite_name> compliance.openshift.io/remove-outdated=
+$ oc -n openshift-compliance \
+annotate compliancesuites/workers-compliancesuite compliance.openshift.io/remove-outdated=
 ----
 
 Alternatively, set the `autoUpdateRemediations` flag in a `ScanSetting` or `ComplianceSuite` object to update the remediations automatically.

modules/compliance-crd-compliance-check-result.adoc

@@ -46,5 +46,6 @@ status: FAIL <2>
 To get all the check results from a suite, run the following command:
 [source,terminal]
 ----
-oc get compliancecheckresults -l compliance.openshift.io/suite=<suit name>
+oc get compliancecheckresults \
+-l compliance.openshift.io/suite=workers-compliancesuite
 ----

modules/compliance-crd-compliance-remediation.adoc

@@ -53,17 +53,20 @@ spec:
 To get all the remediations from a suite, run the following command:
 [source,terminal]
 ----
-oc get complianceremediations -l compliance.openshift.io/suite=<suite name>
+oc get complianceremediations \
+-l compliance.openshift.io/suite=workers-compliancesuite
 ----
 
 To list all failing checks that can be remediated automatically, run the following command:
 [source,terminal]
 ----
-oc get compliancecheckresults -l 'compliance.openshift.io/check-status in (FAIL),compliance.openshift.io/automated-remediation'
+oc get compliancecheckresults \
+-l 'compliance.openshift.io/check-status in (FAIL),compliance.openshift.io/automated-remediation'
 ----
 
 To list all failing checks that can be remediated manually, run the following command:
 [source,terminal]
 ----
-oc get compliancecheckresults -l 'compliance.openshift.io/check-status in (FAIL),!compliance.openshift.io/automated-remediation'
+oc get compliancecheckresults \
+-l 'compliance.openshift.io/check-status in (FAIL),!compliance.openshift.io/automated-remediation'
 ----

modules/compliance-crd-profile-bundle.adoc

@@ -5,7 +5,7 @@
 :_content-type: CONCEPT
 [id="profile-bundle-object_{context}"]
 = ProfileBundle object
-When you install the Compliance Operator, it includes ready-to-run `ProfileBundle` object. The Compliance Operator parses the `ProfileBundle` object and creates a `Profile` object for each profile in the bundle. It also parses `Rule` and `Variable` objects, which are used by the `Profile` object.
+When you install the Compliance Operator, it includes ready-to-run `ProfileBundle` objects. The Compliance Operator parses the `ProfileBundle` object and creates a `Profile` object for each profile in the bundle. It also parses `Rule` and `Variable` objects, which are used by the `Profile` object.
 
 
 .Example `ProfileBundle` object
@@ -15,15 +15,10 @@ apiVersion: compliance.openshift.io/v1alpha1
 kind: ProfileBundle
   name: <profile bundle name>
   namespace: openshift-compliance
-spec:
-  contentFile: ssg-ocp4-ds.xml <1>
-  contentImage: quay.io/complianceascode/ocp4:latest <2>
 status:
-  dataStreamStatus: VALID <3>
+  dataStreamStatus: VALID <1>
 ----
-<1> Specify a path from the root directory (/) where the profile file is located.
-<2> Specify the container image that encapsulates the profile files.
-<3> Indicates whether the Compliance Operator was able to parse the content files.
+<1> Indicates whether the Compliance Operator was able to parse the content files.
 
 [NOTE]
 ====

modules/compliance-crd-scan-setting.adoc

@@ -14,26 +14,79 @@ By default, the Compliance Operator creates the following `ScanSetting` objects:
 .Example `ScanSetting` object
 [source,yaml]
 ----
-apiVersion: compliance.openshift.io/v1alpha1
-kind: ScanSetting
-metadata:
-  name: <name of the scan>
-autoApplyRemediations: false <1>
-autoUpdateRemediations: false <2>
-schedule: "0 1 * * *" <3>
-rawResultStorage:
-  size: "2Gi" <4>
-  rotation: 10 <5>
-roles: <6>
-  - worker
-  - master
+Name:                      default-auto-apply
+Namespace:                 openshift-compliance
+Labels:                    <none>
+Annotations:               <none>
+API Version:               compliance.openshift.io/v1alpha1
+Auto Apply Remediations:   true
+Auto Update Remediations:  true
+Kind:                      ScanSetting
+Metadata:
+  Creation Timestamp:  2022-10-18T20:21:00Z
+  Generation:          1
+  Managed Fields:
+    API Version:  compliance.openshift.io/v1alpha1
+    Fields Type:  FieldsV1
+    fieldsV1:
+      f:autoApplyRemediations: <1>
+      f:autoUpdateRemediations: <2>
+      f:rawResultStorage:
+        .:
+        f:nodeSelector:
+          .:
+          f:node-role.kubernetes.io/master:
+        f:pvAccessModes:
+        f:rotation:
+        f:size:
+        f:tolerations:
+      f:roles:
+      f:scanTolerations:
+      f:schedule:
+      f:showNotApplicable:
+      f:strictNodeScan:
+    Manager:         compliance-operator
+    Operation:       Update
+    Time:            2022-10-18T20:21:00Z
+  Resource Version:  38840
+  UID:               8cb0967d-05e0-4d7a-ac1c-08a7f7e89e84
+Raw Result Storage:
+  Node Selector:
+    node-role.kubernetes.io/master:
+  Pv Access Modes:
+    ReadWriteOnce
+  Rotation:  3 <3>
+  Size:      1Gi <4>
+  Tolerations:
+    Effect:              NoSchedule
+    Key:                 node-role.kubernetes.io/master
+    Operator:            Exists
+    Effect:              NoExecute
+    Key:                 node.kubernetes.io/not-ready
+    Operator:            Exists
+    Toleration Seconds:  300
+    Effect:              NoExecute
+    Key:                 node.kubernetes.io/unreachable
+    Operator:            Exists
+    Toleration Seconds:  300
+    Effect:              NoSchedule
+    Key:                 node.kubernetes.io/memory-pressure
+    Operator:            Exists
+Roles: <6>
+  master
+  worker
+Scan Tolerations:
+  Operator:           Exists
+Schedule:             "0 1 * * *" <5>
+Show Not Applicable:  false
+Strict Node Scan:     true
+Events:               <none>
 ----
-
 <1> Set to `true` to enable auto remediations. Set to `false` to disable auto remediations.
 <2> Set to `true` to enable auto remediations for content updates. Set to `false` to disable auto remediations for content updates.
-<3> Specify how often the scan should be run in cron format.
+<3> Specify the number of stored scans in the raw result format. The default value is `3`. As the older results get rotated, the administrator must store the results elsewhere before the rotation happens.
 <4> Specify the storage size that should be created for the scan to store the raw results. The default value is `1Gi`
-<5> Specify the amount of scans for which the raw results will be stored. The default value is `3`. As the older results get rotated, the administrator has to store the results elsewhere before the rotation happens.
+<5> Specify how often the scan should be run in cron format.
 +
 [NOTE]
 ====

modules/compliance-crd-tailored-profile.adoc

@@ -47,7 +47,7 @@ With the `TailoredProfile` object, it is possible to create a new `Profile` obje
 +
 [source,yaml]
 ----
-compliance.openshift.io/product-type: <scan type>
+compliance.openshift.io/product-type: Platform/Node
 ----
 +
 [NOTE]