Flatten monitoring docs structure

rh-max · kalexand-rh · commit 45ae5cd25952 · 2019-04-09T17:00:34.000-04:00
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -514,5 +514,16 @@ Name: Monitoring
 Dir: monitoring
 Distros: openshift-*
 Topics:
-- Name: Monitoring
-  File: monitoring
+- Name: Cluster monitoring
+  Dir: cluster-monitoring
+  Topics:
+  - Name: About cluster monitoring
+    File: about-cluster-monitoring
+  - Name: Configuring the monitoring stack
+    File: configuring-the-monitoring-stack
+  - Name: Managing alerts using Alertmanager UI
+    File: managing-alerts-using-alertmanager-ui
+  - Name: Accessing Prometheus, Alertmanager, and Grafana
+    File: prometheus-alertmanager-and-grafana
+- Name: Application monitoring
+  File: application-monitoring
diff --git a/logging/efk-logging-curator.adoc b/logging/efk-logging-curator.adoc
@@ -106,7 +106,7 @@ Optionally, you can use the actions file, *_actions.yaml_*, directly. Editing th
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-elasticsearch-storage.adoc b/logging/efk-logging-elasticsearch-storage.adoc
@@ -39,7 +39,7 @@ metadata:
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-elasticsearch.adoc b/logging/efk-logging-elasticsearch.adoc
@@ -19,7 +19,7 @@ or higher memory. Each Elasticsearch node can operate with a lower memory settin
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-external.adoc b/logging/efk-logging-external.adoc
@@ -10,7 +10,7 @@ or an external syslog server. You can also configure Fluentd to send logs to an
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-fluentd.adoc b/logging/efk-logging-fluentd.adoc
@@ -11,7 +11,7 @@ You can configure log rotation, log location, use an external log aggregator, an
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-kibana.adoc b/logging/efk-logging-kibana.adoc
@@ -11,7 +11,7 @@ You can scale Kibana for redundancy and configure the CPU and memory for your Ki
 
 [NOTE]
 ====
-Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc#efk-logging-management[Changing the cluster logging management state].
+Procedures in this topic require your cluster to be in an unmanaged state. For more information, see xref:../logging/efk-logging-management.adoc[Changing the cluster logging management state].
 ====
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/efk-logging-management.adoc b/logging/efk-logging-management.adoc
@@ -1,5 +1,5 @@
 :context: efk-logging-curator
-[id='efk-logging-management']
+[id="efk-logging-management"]
 = Changing cluster logging management state
 include::modules/common-attributes.adoc[]
 
@@ -10,7 +10,7 @@ The Cluster Logging Operator and Elasticsearch Operator can be in a _Managed_ or
 
 By default, the Cluster Logging and Elasticsearch operators are set to Managed. However, in order to modify the components managed by the Cluster Logging Operator,
 you need to set cluster logging to the _unmanaged_ state. In order to modify the components managed by the Elasticsearch Operator,
-you need to set Elasticsearch to the _unmanaged_ state. 
+you need to set Elasticsearch to the _unmanaged_ state.
 
 // The following include statements pull in the module files that comprise
 // the assembly. Include any combination of concept, procedure, or reference
diff --git a/modules/deployments-comparing-deploymentconfigs.adoc b/modules/deployments-comparing-deploymentconfigs.adoc
@@ -13,7 +13,7 @@ provided by DeploymentConfigs.
 The following sections go into more detail on the differences between the two
 object types to further help you decide which type to use.
 
-[id='deployments-design-{context}']
+[id="deployments-design-{context}"]
 == Design
 
 One important difference between Deployments and DeploymentConfigs is the
diff --git a/modules/efk-logging-elasticsearch-ha.adoc b/modules/efk-logging-elasticsearch-ha.adoc
@@ -2,22 +2,22 @@
 //
 // * logging/efk-logging-elasticsearch.adoc
 
-[id='efk-logging-elasticsearch-ha_{context}']
+[id="efk-logging-elasticsearch-ha_{context}"]
 = Configuring Elasticsearch replication policy
 
 You can define how Elasticsearch shards are replicated across data nodes in the cluster:
 
-* *FullRedundancy*. Elasticsearch fully replicates the primary shards for each index 
+* *FullRedundancy*. Elasticsearch fully replicates the primary shards for each index
 to every data node. This provides the highest safety, but at the cost of the highest amount of disk required and the poorest performance.
 * *MultipleRedundancy*. Elasticsearch fully replicates the primary shards for each index to half of the data nodes.
 This provides a good tradeoff between safety and performance.
-* *SingleRedundancy*. Elasticsearch makes one copy of the primary shards for each index. 
+* *SingleRedundancy*. Elasticsearch makes one copy of the primary shards for each index.
 Logs are always available and recoverable as long as at least two data nodes exist.
-Better performance than MultipleRedundancy, when using 5 or more nodes.  You cannot 
+Better performance than MultipleRedundancy, when using 5 or more nodes.  You cannot
 apply this policy on deployments of single Elasticsearch node.
-* *ZeroRedundancy*. Elasticsearch does not make copies of the primary shards. 
+* *ZeroRedundancy*. Elasticsearch does not make copies of the primary shards.
 Logs might be unavailable or lost in the event a node is down or fails.
-Use this mode when you are more concerned with performance than safety, or have 
+Use this mode when you are more concerned with performance than safety, or have
 implemented your own disk/PVC backup/restore strategy.
 
 
@@ -37,7 +37,7 @@ instance   112m
 
 .Procedure
 
-Edit the Cluster Logging Custom Resource (CR) in the `openshift-logging` project: 
+Edit the Cluster Logging Custom Resource (CR) in the `openshift-logging` project:
 
 [source,yaml]
 ----
@@ -51,7 +51,7 @@ metadata:
 spec:
   logStore:
     type: "elasticsearch"
-    elasticsearch: 
+    elasticsearch:
       redundancyPolicy: "SingleRedundancy" <1>
 ----
 <1> Specify a redundancy policy for the shards. The change is applied upon saving the changes.
diff --git a/modules/efk-logging-management-state-changing-es.adoc b/modules/efk-logging-management-state-changing-es.adoc
@@ -2,16 +2,16 @@
 //
 // * logging/efk-logging-management.adoc
 
-[id='efk-logging-management-state-changing-es-{context}']
+[id="efk-logging-management-state-changing-es-{context}"]
 = Changing the Elasticsearch management state
 
 In managed state, the Elasticsearch Operator (EO) responds to changes in the Elaticsearch Custom Resource (CR)
-and attempts to update the Elasticsearch cluster to match the CR.  
+and attempts to update the Elasticsearch cluster to match the CR.
 
-In an unmanaged state, the EO does not respond to changes in the CR. 
-The administrator assumes full control of individual component configurations 
+In an unmanaged state, the EO does not respond to changes in the CR.
+The administrator assumes full control of individual component configurations
 and upgrades when in unmanaged state. If you make changes to a CR in managed state,
-the Elasticsearch Operator can revert those changes. 
+the Elasticsearch Operator can revert those changes.
 
 [NOTE]
 ====
@@ -37,7 +37,7 @@ Edit the Elasticsearch Custom Resource (CR) in the `openshift-logging` project:
 [source,yaml]
 ----
 $ oc edit Elasticsearch elasticsearch
- 
+
 apiVersion: logging.openshift.io/v1alpha1
 kind: Elasticsearch
 metadata:
@@ -48,6 +48,6 @@ metadata:
 
 spec:
   managementState: "Managed" <1>
----- 
+----
 
 <1> Specify the management state as `Managed` or `Unmanaged`.
diff --git a/modules/infrastructure-moving-monitoring.adoc b/modules/infrastructure-moving-monitoring.adoc
@@ -2,7 +2,7 @@
 //
 // * machine_management/creating-infrastructure-machinesets.adoc
 
-[id='infrastructure-moving-monitoring-{context}']
+[id="infrastructure-moving-monitoring-{context}"]
 = Moving the monitoring solution
 
 [IMPORTANT]
diff --git a/modules/monitoring-accessing-prometheus-alertmanager-grafana.adoc b/modules/monitoring-accessing-prometheus-alertmanager-grafana.adoc
@@ -1,23 +1,29 @@
-// Module included in the following assemblies:
-//
-// * monitoring/configuring-the-monitoring-stack.adoc
-
-[id="accessing-prometheus-alertmanager-and-grafana-{context}"]
+[id="monitoring-accessing-prometheus-alertmanager-grafana-{context}"]
 = Accessing Prometheus, Alertmanager, and Grafana
 
-You can get the addresses for accessing Prometheus, Alertmanager, and Grafana web UIs.
+You can access Prometheus, Alertmanager, and Grafana web UIs using the `oc` tool and a Web browser.
+
+.Prerequisites
+
+* Authentication is performed against the {product-title} identity and uses the same credentials or means of authentication as is used elsewhere in {product-title}. You need to use a role that has read access to all namespaces, such as the `cluster-monitoring-view` cluster role.
 
 .Procedure
 
-* Run:
+. Run:
 +
 [subs=quotes]
   $ oc -n openshift-monitoring get routes
   NAME                HOST/PORT                                                     ...
   alertmanager-main   alertmanager-main-openshift-monitoring.apps._url_.openshift.com ...
   grafana             grafana-openshift-monitoring.apps._url_.openshift.com           ...
   prometheus-k8s      prometheus-k8s-openshift-monitoring.apps._url_.openshift.com    ...
+
+. Prepend `https://` to the address, you cannot access web UIs using unencrypted connection.
 +
-Prepend `https://` to these addresses. You cannot access web UIs using unencrypted connection.
+For example, this is the resulting URL for Alertmanager:
 +
-Authentication is performed against the {product-title} identity and uses the same credentials or means of authentication as is used elsewhere in {product-title}. You need to use a role that has read access to all namespaces, such as the `cluster-monitoring-view` cluster role.
+[subs=quotes]
+  https://alertmanager-main-openshift-monitoring.apps._url_.openshift.com
+
+. Navigate to the address using a Web browser and authenticate.
+
diff --git a/modules/monitoring-alerting-rules.adoc b/modules/monitoring-alerting-rules.adoc
@@ -14,6 +14,8 @@ Note that:
 * Some alerting rules have identical names. This is intentional. They are sending alerts about the same event with different thresholds, with different severity, or both.
 * With the inhibition rules, the lower severity is inhibited when the higher severity is firing.
 
+////
 .Additional resources
 
 * See the link:https://github.com/openshift/cluster-monitoring-operator/blob/master/Documentation/user-guides/default-alerts.md[default alerts table].
+////
diff --git a/modules/monitoring-configurable-monitoring-components.adoc b/modules/monitoring-configurable-monitoring-components.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='configurable-monitoring-components-{context}']
+[id="configurable-monitoring-components-{context}"]
 = Configurable monitoring components
 
 This table shows the monitoring components you can configure and the keys used to specify the components in the ConfigMap:
diff --git a/modules/monitoring-configuring-a-persistent-volume-claim.adoc b/modules/monitoring-configuring-a-persistent-volume-claim.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='configuring-a-persistent-volume-claim-{context}']
+[id="configuring-a-persistent-volume-claim-{context}"]
 = Configuring a persistent volume claim
 
 For the Prometheus or Alertmanager to use a persistent volume (PV), you first need to configure a persistent volume claim (PVC).
diff --git a/modules/monitoring-configuring-cluster-for-application-monitoring.adoc b/modules/monitoring-configuring-cluster-for-application-monitoring.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/monitoring.adoc
 
-[id='configuring-cluster-for-application-monitoring-{context}']
+[id="configuring-cluster-for-application-monitoring-{context}"]
 = Configuring cluster for application monitoring
 
 Before application developers can monitor their applications, the human operator of the cluster needs to configure the cluster accordingly. This procedure shows how to.
diff --git a/modules/monitoring-configuring-monitoring-for-an-application.adoc b/modules/monitoring-configuring-monitoring-for-an-application.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/monitoring.adoc
 
-[id='configuring-monitoring-for-an-application-{context}']
+[id="configuring-monitoring-for-an-application-{context}"]
 = Configuring monitoring for an application
 
 This procedure shows, on an example, how an application developer can deploy an application and configure monitoring for it.
diff --git a/modules/monitoring-configuring-the-cluster-monitoring-stack.adoc b/modules/monitoring-configuring-the-cluster-monitoring-stack.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='configuring-the-cluster-monitoring-stack-{context}']
+[id="configuring-the-cluster-monitoring-stack-{context}"]
 = Configuring the cluster monitoring stack
 
 You can configure the Prometheus Cluster Monitoring stack using ConfigMaps. ConfigMaps configure the Cluster Monitoring Operator, which in turn configures components of the stack.
diff --git a/modules/monitoring-contents-of-alertmanager-ui.adoc b/modules/monitoring-contents-of-alertmanager-ui.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='contents-of-alertmanager-ui-{context}']
+[id="contents-of-alertmanager-ui-{context}"]
 = Contents of Alertmanager UI
 
 This section shows and explains the contents of the Alertmanager UI.
diff --git a/modules/monitoring-creating-cluster-monitoring-configmap.adoc b/modules/monitoring-creating-cluster-monitoring-configmap.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='creating-cluster-monitoring-configmap-{context}']
+[id="creating-cluster-monitoring-configmap-{context}"]
 = Creating cluster monitoring ConfigMap
 
 To configure the Prometheus Cluster Monitoring stack, you need to create the cluster monitoring Configmap.
diff --git a/modules/monitoring-editing-silences.adoc b/modules/monitoring-editing-silences.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='editing-silences-{context}']
+[id="editing-silences-{context}"]
 = Editing silences
 
 You can edit a silence, which will expire the existing silence and create a new silence with the changed configuration.
diff --git a/modules/monitoring-expiring-silences.adoc b/modules/monitoring-expiring-silences.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-cluster-monitoring.adoc
 
-[id='expiring-silences-{context}']
+[id="expiring-silences-{context}"]
 = Expiring silences
 
 You can expire a silence. Expiring a silence deactivates it forever.
diff --git a/modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc b/modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/monitoring.adoc
 
-[id='exposing-custom-application-metrics-for-horizontal-pod-autoscaling-{context}']
+[id="exposing-custom-application-metrics-for-horizontal-pod-autoscaling-{context}"]
 = Exposing custom application metrics for horizontal pod autoscaling
 
 You can use the `prometheus-adapter` resource to expose custom application metrics for the horizontal pod autoscaler.
diff --git a/modules/monitoring-getting-information-about-alerts-and-alerting-rules.adoc b/modules/monitoring-getting-information-about-alerts-and-alerting-rules.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='getting-information-about-alerts-and-alerting-rules-{context}']
+[id="getting-information-about-alerts-and-alerting-rules-{context}"]
 = Getting information about alerts and alerting rules
 
 You can find an alert and see information about it or its governing alerting rule.
diff --git a/modules/monitoring-getting-information-about-silences.adoc b/modules/monitoring-getting-information-about-silences.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='getting-information-about-silences-{context}']
+[id="getting-information-about-silences-{context}"]
 = Getting information about silences
 
 You can find a silence and view its details.
diff --git a/modules/monitoring-maintenance-and-support.adoc b/modules/monitoring-maintenance-and-support.adoc
@@ -2,7 +2,7 @@
 //
 // * monitoring/configuring-the-monitoring-stack.adoc
 
-[id='maintenance-and-support-{context}']
+[id="maintenance-and-support-{context}"]
 = Maintenance and support
 
 The supported way of configuring {product-title} Monitoring is by configuring it using the options described in this document. *Do not use other configuration, it is unsupported.* The reason is that configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use other configuration than is described in this section, your changes will dissappear, because the cluster-monitoring-operator reconciles any differences. It is by default and by design that the operator reverses everything to the defined state.
diff --git a/modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc b/modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='modifying-retention-time-for-prometheus-metrics-data-{context}']
+[id="modifying-retention-time-for-prometheus-metrics-data-{context}"]
 = Modifying retention time for Prometheus metrics data
 
 By default, the Prometheus Cluster Monitoring stack configures the retention time for Prometheus data to be 15 days. You can modify the retention time to change how soon the data is deleted.
diff --git a/modules/monitoring-monitoring-overview.adoc b/modules/monitoring-monitoring-overview.adoc
@@ -55,6 +55,8 @@ Other {product-title} framework components might be exposing metrics as well. Se
 In order to be able to deliver updates with guaranteed compatibility, configurability of the {product-title} Monitoring stack is limited to the explicitly available options.
 ====
 
+////
 .Additional resources
 
 For more information about the {product-title} Cluster Monitoring Operator, see the link:https://github.com/openshift/cluster-monitoring-operator[Cluster Monitoring Operator] GitHub project.
+////
diff --git a/modules/monitoring-moving-monitoring-components-to-different-nodes.adoc b/modules/monitoring-moving-monitoring-components-to-different-nodes.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='moving-monitoring-components-to-different-nodes-{context}']
+[id="moving-monitoring-components-to-different-nodes-{context}"]
 = Moving monitoring components to different nodes
 
 You can move the monitoring stack components to specific nodes.
diff --git a/modules/monitoring-silencing-alerts.adoc b/modules/monitoring-silencing-alerts.adoc
@@ -2,7 +2,7 @@
 //
 // monitoring/configuring-the-monitoring-stack.adoc
 
-[id='monitoring-silencing-alerts-{context}']
+[id="monitoring-silencing-alerts-{context}"]
 = Silencing alerts
 
 You can either silence a specific alert or silence alerts that match a specification that you define.
diff --git a/modules/monitoring-stack-components-and-monitored-targets.adoc b/modules/monitoring-stack-components-and-monitored-targets.adoc
diff --git a/modules/monitoring-update-and-compatibility-guarantees.adoc b/modules/monitoring-update-and-compatibility-guarantees.adoc
diff --git a/modules/olm-deleting-operators-from-a-cluster-using-cli.adoc b/modules/olm-deleting-operators-from-a-cluster-using-cli.adoc
diff --git a/modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc b/modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc
diff --git a/modules/upgrade-upgrading-web.adoc b/modules/upgrade-upgrading-web.adoc
diff --git a/monitoring/accessing-prometheus-alertmanager-grafana.adoc b/monitoring/accessing-prometheus-alertmanager-grafana.adoc
diff --git a/monitoring/application-monitoring.adoc b/monitoring/application-monitoring.adoc
diff --git a/monitoring/cluster-monitoring/about-cluster-monitoring.adoc b/monitoring/cluster-monitoring/about-cluster-monitoring.adoc
diff --git a/monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc b/monitoring/cluster-monitoring/configuring-the-monitoring-stack.adoc
diff --git a/monitoring/cluster-monitoring/managing-alerts-using-alertmanager-ui.adoc b/monitoring/cluster-monitoring/managing-alerts-using-alertmanager-ui.adoc
diff --git a/monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc b/monitoring/cluster-monitoring/prometheus-alertmanager-and-grafana.adoc
diff --git a/monitoring/monitoring.adoc b/monitoring/monitoring.adoc
diff --git a/storage/dynamic-provisioning.adoc b/storage/dynamic-provisioning.adoc
diff --git a/updating/updating-cluster.adoc b/updating/updating-cluster.adoc
