fix Lucie's comments v1

docs/operation/cluster_and_service_configuration.rst

@@ -2,10 +2,8 @@ Cluster and Services Configurations
 ===================================
 
 This section contains information describing the list of available Cluster and
-Services Configurations, the :term:`Namespace` to which they belong,
-the :term:`ConfigMap` where these configurations are store and finally the
-different ways of customizing and applying any given Cluster and Services
-Configurations.
+Services Configurations including procedures for customizing and applying any
+given Cluster and Services Configurations.
 
 Managing Cluster and Services Configurations
 ********************************************
@@ -21,44 +19,159 @@ documented procedure to the later.
    time of a deployed MetalK8s cluster even after operations like Node reboots,
    cluster upgrade or downgrade scenarios.
 
-List of available Cluster and Services Configurations
------------------------------------------------------
+Managing Authentication
+^^^^^^^^^^^^^^^^^^^^^^^
 
-The table below summarizes the list of services, their respective customizable
-Cluster and Services Configurations and the storage location (ConfigMap) for
-each.
+Add a local static user
+"""""""""""""""""""""""
 
-.. note::
+Local authentication via static users is enabled by default after a fresh
+MetalK8s installation.
 
-   MetalK8s comes with a set of addon applications. Some of these addon
-   applications come along with Service configurations that require
-   customizations by Admin users to fit their respective use cases.
+   .. important::
 
-.. table::
+      To continue to use MetalK8s in cases where the external authentication
+      system fails, we advise MetalK8s administrators to leave the default
+      superadmin account enabled at all times.
+
+To add a new static user, perform the following operations:
+
+#. Generate a password hash. The command below requires **apache-utils**
+   package to be installed.
+
+   .. code-block:: shell
+
+      $ htpasswd -bnBC 12 "" <password> | tr -d ':\n'
+
+#. From the Bootstrap node, edit the ConfigMap ``metalk8s-dex-config`` and then
+   add a new entry to the already existing list using:
+
+   .. code-block:: shell
+
+      $ kubectl --kubeconfig /etc/kubernetes/admin.conf \
+         edit configmaps metalk8s-dex-config -n metalk8s-auth
+
+   The new entry should be unique and possess mandatory fields like ``email``,
+   ``hash``, ``username`` and ``userID`` like in the example below.
+
+   .. code-block:: yaml
+
+      data:
+         config.yaml: |-
+            spec:
+               localuserstore:
+                  userlist:
+                    - email: "<email>"
+                      hash: "<replace-with-hash>"
+                      username: "<username>"
+                      userID: "<uuidv4>"
+
+#. Save and apply the changes.
 
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    |      **Cluster & Services Configurations**       | **Addon Service** |    **Namespace**    |         **ConfigMap**        |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    |                                                  | Alertmanager      | metalk8s-monitoring | metalk8s-alertmanager-config |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | Number of replicas                               | Dex               | metalk8s-auth       | metalk8s-dex-config          |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    |                                                  | Grafana           | metalk8s-monitoring | metalk8s-grafana-config      |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    |                                                  | Prometheus        | metalk8s-monitoring | metalk8s-prometheus-config   |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | Alerting Channels(Slack, email, VictorOps)       | Alertmanager      | metalk8s-monitoring | metalk8s-alertmanager-config |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | Change Login credentials                         | Dex               | metalk8s-auth       | metalk8s-dex-config          |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | Enable/Disable static users                      | Dex               | metalk8s-auth       | metalk8s-dex-config          |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | External OIDC connectors(LDAP, Active Directory) | Dex               | metalk8s-auth       | metalk8s-dex-config          |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
-    | Provision new static users                       | Dex               | metalk8s-auth       | metalk8s-dex-config          |
-    +--------------------------------------------------+-------------------+---------------------+------------------------------+
+
+#. Connect to the Salt master container using:
+
+   .. code-block:: shell
+
+      $ crictl exec -it $(crictl ps -q --label io.kubernetes.container.name=salt-master) bash
+
+#. From the Salt master container, apply the following salt-states to propogate
+   the new changes down to the underline services.
+
+   .. code-block:: shell
+
+      $ salt-run state.sls metalk8s.addons.dex.deployed saltenv=metalk8s-<version>
+
+
+Disable Local Authentication
+""""""""""""""""""""""""""""
 
 .. todo::
 
-    - Document how to change any given Cluster and Services Configurations from
-      the table provided above
+   Add documentation on the following tracked topics
+
+   - Change static user password (issue #2075)
+
+   - External authentication (issue #2013)
+
+      - Configuring LDAP
+      - Configuring Active Directory(AD)
+
+Managing Cluster Monitoring
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MetalK8s ships with Prometheus Operator which takes charge of deploying the
+monitoring stack (Prometheus, Alertmanager and Grafana).
+Service configurations for the 3 main services that make up the monitoring
+stack can be found in the :term:`Namespace` metalk8s-monitoring under the
+following ConfigMaps:
+
+.. _Monitoring-ConfigMaps:
+
+.. table::
+
+   +-------------------+------------------------------+
+   | **Service**       |         **ConfigMap-Name**   |
+   +-------------------+------------------------------+
+   | Alertmanager      | metalk8s-alertmanager-config |
+   +-------------------+------------------------------+
+   | Grafana           | metalk8s-grafana-config      |
+   +-------------------+------------------------------+
+   | Prometheus        | metalk8s-prometheus-config   |
+   +-------------------+------------------------------+
+
+Configuring replicas count
+""""""""""""""""""""""""""
+
+MetalK8s administrators can scale the monitoring stack directly by changing
+the number of replicas which is by default set to a single pod per service
+after a fresh MetalK8s installation.
+
+To change the number of replicas for any of the services listed above,
+perform the following operations:
+
+#. From the Bootstrap node, edit the ConfigMap ``<ConfigMap-Name>`` and then
+   modify the replicas entry.
+
+   .. code-block:: shell
+
+      $ kubectl --kubeconfig /etc/kubernetes/admin.conf \
+         edit configmaps <ConfigMap-Name> -n metalk8s-monitoring
+
+   For each service in the MetalK8s monitoring stack, consult the
+   :ref:`Monitoring Services<Monitoring-ConfigMaps>` table to obtain the
+   ConfigMap-Name to be used for the above command.
+
+   Make sure to replace **<number-of-replicas>** field with an integer value
+   (For example 2).
+
+   .. code-block:: yaml
+
+      data:
+         config.yaml: |-
+            spec:
+               deployment:
+                  replicas: <number-of-replicas>
+
+#. Save and apply the changes.
+
+#. Connect to the Salt master container using:
+
+   .. code-block:: shell
+
+      $ crictl exec -it $(crictl ps -q --label io.kubernetes.container.name=salt-master) bash
+
+#. From the Salt master container, apply the following salt-states to propogate
+   the new changes down to the underline services.
+
+   .. note::
+
+      Scaling the number of pods for services like Prometheus and Alertmanager
+      require provisioning extra persistent volumes for these pods to startup
+      normally. Refer to :ref:`this procedure <Provision Prometheus storage>`
+      for more information.
+
+   .. code-block:: shell
+
+      $ salt-run state.sls metalk8s.addons.prometheus-operator.deployed \
+         saltenv=metalk8s-<version>