Reorganize Custom Metrics Autoscaler docs

Author: Michael Burke

_topic_maps/_topic_map.yml

@@ -2244,8 +2244,6 @@ Topics:
     Distros: openshift-enterprise,openshift-origin
   - Name: Automatically scaling pods with the horizontal pod autoscaler
     File: nodes-pods-autoscaling
-  - Name: Automatically scaling pods with the custom metrics autoscaler
-    File: nodes-pods-autoscaling-custom
   - Name: Automatically adjust pod resource levels with the vertical pod autoscaler
     File: nodes-pods-vertical-autoscaler
   - Name: Providing sensitive data to pods
@@ -2273,6 +2271,32 @@ Topics:
       File: run-once-duration-override-install
     - Name: Uninstalling the Run Once Duration Override Operator
       File: run-once-duration-override-uninstall
+- Name: Automatically scaling pods with the Custom Metrics Autoscaler Operator
+  Dir: cma
+  Distros: openshift-enterprise,openshift-origin
+  Topics:
+  - Name: Custom Metrics Autoscaler Operator overview
+    File: nodes-cma-autoscaling-custom
+  - Name: Custom Metrics Autoscaler Operator release notes
+    File: nodes-cma-autoscaling-custom-rn
+  - Name: Installing the custom metrics autoscaler
+    File: nodes-cma-autoscaling-custom-install
+  - Name: Understanding the custom metrics autoscaler triggers
+    File: nodes-cma-autoscaling-custom-trigger
+  - Name: Understanding the custom metrics autoscaler trigger authentications
+    File: nodes-cma-autoscaling-custom-trigger-auth
+  - Name: Pausing the custom metrics autoscaler 
+    File: nodes-cma-autoscaling-custom-pausing
+  - Name: Gathering audit logs
+    File: nodes-cma-autoscaling-custom-audit-log
+  - Name: Gathering debugging data
+    File: nodes-cma-autoscaling-custom-debugging
+  - Name: Viewing Operator metrics
+    File: nodes-cma-autoscaling-custom-metrics
+  - Name: Understanding how to add custom metrics autoscalers
+    File: nodes-cma-autoscaling-custom-adding
+  - Name: Removing the Custom Metrics Autoscaler Operator
+    File: nodes-cma-autoscaling-custom-removing
 - Name: Controlling pod placement onto nodes (scheduling)
   Dir: scheduling
   Distros: openshift-enterprise,openshift-origin

modules/nodes-pods-autoscaling-custom-audit.adoc renamed to modules/nodes-cma-autoscaling-custom-audit.adoc

@@ -1,16 +1,12 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-audit-log.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-audit_{context}"]
+[id="nodes-cma-autoscaling-custom-audit_{context}"]
 = Configuring audit logging
 
-// Text borrowed from gathering-cluster-data.adoc. Make into snippet?
-
-You can gather audit logs, which are a security-relevant chronological set of records documenting the sequence of activities that have affected the system by individual users, administrators, or other components of the system.
-
-For example, audit logs can help you understand where an autoscaling request is coming from. This is key information when backends are getting overloaded by autoscaling requests made by user applications and you need to determine which is the troublesome application. You can configure auditing for the Custom Metrics Autoscaler Operator by editing the `KedaController` custom resource. The logs are sent to an audit log file on a volume that is secured by using a persistent volume claim in the `KedaController` CR. 
+You can configure auditing for the Custom Metrics Autoscaler Operator by editing the `KedaController` custom resource. The logs are sent to an audit log file on a volume that is secured by using a persistent volume claim in the `KedaController` CR. 
 
 // You can view the audit log file directly or use the `oc adm must-gather` CLI. The `oc adm must-gather` CLI collects the log along with other information from your cluster that is most likely needed for debugging issues, such as resource definitions and service logs.
 
@@ -30,9 +26,9 @@ metadata:
   name: keda
   namespace: openshift-keda
 spec:
- ...
+# ...
   metricsServer:
- ...
+# ...
     auditConfig:
       logFormat: "json" <1>
       logOutputVolumeClaim: "pvc-audit-log" <2>

modules/nodes-pods-autoscaling-custom-creating-job.adoc renamed to modules/nodes-cma-autoscaling-custom-creating-job.adoc

@@ -1,9 +1,9 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-adding.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-creating-job_{context}"]
+[id="nodes-cma-autoscaling-custom-creating-job_{context}"]
 = Adding a custom metrics autoscaler to a job
 
 You can create a custom metrics autoscaler for any `Job` object.
@@ -132,6 +132,7 @@ scaledjob   100   prometheus   prom-triggerauthentication  True    True      8s
 +
 Note the following fields in the output:
 +
+--
 * `TRIGGERS`: Indicates the trigger, or scaler, that is being used.
 * `AUTHENTICATION`: Indicates the name of any trigger authentication being used.
 * `READY`: Indicates whether the scaled object is ready to start scaling:
@@ -140,4 +141,4 @@ Note the following fields in the output:
 * `ACTIVE`: Indicates whether scaling is taking place:
 ** If `True`, scaling is taking place.
 ** If `False`, scaling is not taking place because there are no metrics or there is a problem in one or more of the objects you created. 
-
+--

modules/nodes-pods-autoscaling-custom-creating-workload.adoc renamed to modules/nodes-cma-autoscaling-custom-creating-workload.adoc

@@ -1,9 +1,9 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-adding.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-creating-workload_{context}"]
+[id="nodes-cma-autoscaling-custom-creating-workload_{context}"]
 = Adding a custom metrics autoscaler to a workload
 
 You can create a custom metrics autoscaler for a workload that is created by a `Deployment`, `StatefulSet`, or `custom resource` object.
@@ -53,7 +53,7 @@ Events:                <none>
 ----
 apiVersion: v1
 kind: Pod
- ...
+# ...
 spec:
   containers:
   - name: app
@@ -62,6 +62,7 @@ spec:
       limits:
         memory: "128Mi"
         cpu: "500m"
+# ...
 ----
 
 .Procedure
@@ -184,6 +185,7 @@ scaledobject    apps/v1.Deployment   example-deployment     0     50    promethe
 +
 Note the following fields in the output:
 +
+--
 * `TRIGGERS`: Indicates the trigger, or scaler, that is being used.
 * `AUTHENTICATION`: Indicates the name of any trigger authentication being used.
 * `READY`: Indicates whether the scaled object is ready to start scaling:
@@ -195,5 +197,5 @@ Note the following fields in the output:
 * `FALLBACK`: Indicates whether the custom metrics autoscaler is able to get metrics from the source
 ** If `False`, the custom metrics autoscaler is getting metrics. 
 ** If `True`, the custom metrics autoscaler is getting metrics because there are no metrics or there is a problem in one or more of the objects you created.
-
+--
 

modules/nodes-pods-autoscaling-custom-gather.adoc renamed to modules/nodes-cma-autoscaling-custom-gather.adoc

@@ -1,26 +1,11 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-debugging.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-gather_{context}"]
+[id="nodes-cma-autoscaling-custom-debugging-gather_{context}"]
 = Gathering debugging data
 
-ifndef::openshift-origin[]
-When opening a support case, it is helpful to provide debugging information about your cluster to Red Hat Support.
-
-It is recommended that you provide the following information:
-
-* Data gathered using the `must-gather` tool.
-* The unique cluster ID.
-endif::openshift-origin[]
-
-You can use the `must-gather` tool to collect data about the Custom Metrics Autoscaler Operator and its components, including:
-
-* The `openshift-keda` namespace and its child objects.
-* The Custom Metric Autoscaler Operator installation objects.
-* The Custom Metric Autoscaler Operator CRD objects.
-
 The following command runs the `must-gather` tool for the Custom Metrics Autoscaler Operator:
 
 [source,terminal]

modules/nodes-pods-autoscaling-custom-install.adoc renamed to modules/nodes-cma-autoscaling-custom-install.adoc

@@ -1,27 +1,19 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-install.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-install_{context}"]
+[id="nodes-cma-autoscaling-custom-install_{context}"]
 = Installing the custom metrics autoscaler
 
-You can use the {product-title} web console to install the Custom Metrics Autoscaler Operator.
-
-The installation creates five CRDs:
-
-* `ClusterTriggerAuthentication`
-* `KedaController`
-* `ScaledJob`
-* `ScaledObject`
-* `TriggerAuthentication`
+You can use the following procedure to install the Custom Metrics Autoscaler Operator.
 
 .Prerequisites
 ifdef::openshift-origin[]
 * Ensure that you have downloaded the {cluster-manager-url-pull} as shown in _Obtaining the installation program_ in the installation documentation for your platform.
 +
 If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_.
-endif::[]
+endif::openshift-origin[]
 
 * If you use the community KEDA:
 

modules/nodes-pods-autoscaling-custom-metrics-access.adoc renamed to modules/nodes-cma-autoscaling-custom-metrics-access.adoc

@@ -1,14 +1,12 @@
 // Module included in the following assemblies:
 //
-// * nodes/pods/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-metrics.adoc
 // Modeled after migration-accessing-performance-metrics.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-metrics-access_{context}"]
+[id="nodes-cma-autoscaling-custom-metrics-access_{context}"]
 = Accessing performance metrics
 
-The Custom Metrics Autoscaler Operator exposes ready-to-use metrics that it pulls from the on-cluster monitoring component. You can query the metrics by using the Prometheus Query Language (PromQL) to analyze and diagnose issues. All metrics are reset when the controller pod restarts.
-
 You can access the metrics and run queries by using the {product-title} web console.
 
 .Procedure

modules/nodes-pods-autoscaling-custom-metrics.adoc renamed to modules/nodes-cma-autoscaling-custom-metrics-provided.adoc

@@ -1,10 +1,10 @@
 // Module included in the following assemblies:
 //
-// * nodes/pods/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-metrics.adoc
 
 :_content-type: REFERENCE
-[id="nodes-pods-autoscaling-custom-metrics_{context}"]
-= Provided metrics
+[id="nodes-cma-autoscaling-custom-metrics-provided_{context}"]
+= Provided Operator metrics
 
 The Custom Metrics Autoscaler Operator exposes the following metrics, which you can view by using the {product-title} web console.
 

modules/nodes-cma-autoscaling-custom-pausing-restart.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * nodes/cma/nodes-cma-autoscaling-custom-pausing.adoc
+
+:_content-type: PROCEDURE
+[id="nodes-cma-autoscaling-custom-pausing-restart_{context}"]
+= Restarting the custom metrics autoscaler for a scaled object
+
+You can restart a paused custom metrics autoscaler by removing the `autoscaling.keda.sh/paused-replicas` annotation for that `ScaledObject`. 
+
+[source,yaml]
+----
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  annotations:
+    autoscaling.keda.sh/paused-replicas: "4"
+# ...
+----
+
+.Procedure
+
+. Use the following command to edit the `ScaledObject` CR for your workload:
++
+[source,terminal]
+----
+$ oc edit ScaledObject scaledobject 
+----
+
+. Remove the `autoscaling.keda.sh/paused-replicas` annotation.
++
+[source,yaml]
+----
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  annotations:
+    autoscaling.keda.sh/paused-replicas: "4" <1>
+  creationTimestamp: "2023-02-08T14:41:01Z"
+  generation: 1
+  name: scaledobject
+  namespace: my-project
+  resourceVersion: "65729"
+  uid: f5aec682-acdf-4232-a783-58b5b82f5dd0
+----
+<1> Remove this annotation to restart a paused custom metrics autoscaler.

modules/nodes-pods-autoscaling-custom-pausing.adoc renamed to modules/nodes-cma-autoscaling-custom-pausing-workload.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * nodes/nodes-pods-autoscaling-custom.adoc
+// * nodes/cma/nodes-cma-autoscaling-custom-pausing.adoc
 
 :_content-type: PROCEDURE
-[id="nodes-pods-autoscaling-custom-pausing_{context}"]
-= Pausing the custom metrics autoscaler for a workload
+[id="nodes-cma-autoscaling-custom-pausing-workload_{context}"]
+= Pausing a custom metrics autoscaler
 
-You can pause the autoscaling of a workload, as needed, by adding the `autoscaling.keda.sh/paused-replicas` annotation to the custom metrics autoscaler for that workload. The custom metrics autoscaler scales the replicas for that workload to the specified value and pauses autoscaling until the annotation is removed.
+You can pause the autoscaling of a scaled object by adding the `autoscaling.keda.sh/paused-replicas` annotation to the custom metrics autoscaler for that scaled object. The custom metrics autoscaler scales the replicas for that workload to the specified value and pauses autoscaling until the annotation is removed.
 
 [source,yaml]
 ----
@@ -15,13 +15,9 @@ kind: ScaledObject
 metadata:
   annotations:
     autoscaling.keda.sh/paused-replicas: "4"
-...
+# ...
 ----
 
-To restart autoscaling, edit the `ScaledObject` CR to remove the annotation.
-
-For example, you might want to pause autoscaling before performing cluster maintenance or to avoid resource starvation by removing non-mission-critical workloads. 
-
 .Procedure
 
 . Use the following command to edit the `ScaledObject` CR for your workload:
@@ -44,8 +40,8 @@ metadata:
   generation: 1
   name: scaledobject
   namespace: my-project
-  resourceVersion: '65729'
-  uid: 'f5aec682-acdf-4232-a783-58b5b82f5dd0'
+  resourceVersion: "65729"
+  uid: f5aec682-acdf-4232-a783-58b5b82f5dd0
 ----
 <1> Specifies that the Custom Metrics Autoscaler Operator is to scale the replicas to the specified value and stop autoscaling.