Merge branch 'documentation/operation_docs_rework' into tmp/octopus/w…

…/2.9/documentation/operation_docs_rework

docs/conf.py

@@ -151,7 +151,7 @@
     }
 
     # Build tag for Scality product documentation
-    if tags.has("scality-product"):
+    if tags.has("scality_product"):
         _kblink = "https://support.scality.com/hc/en-us"
         _homelink = "https://documentation.scality.com"
         html_theme_options["footer_links"] = [

docs/installation/bootstrap.rst

@@ -267,6 +267,6 @@ Validate the install
      storage volumes for both Prometheus and Alertmanager have been successfully
      provisioned.
 
-- If you encouter an error during installation or have difficulties
-  validating a fresh MetalK8s installation, visit our
-  :ref:`Troubleshooting guide <Troubleshooting Guide>`.
+- If you encounter an error during installation or have issues
+  validating a fresh MetalK8s installation, refer to the
+  :ref:`Troubleshooting section <Troubleshooting Installation Section>`.

docs/operation/enable_ip_ip.rst → docs/installation/enable_ip_ip.rst

@@ -1,25 +1,25 @@
 .. _enable IP-in-IP:
 
-Enable IP-in-IP encapsulation
+Enable IP-in-IP Encapsulation
 =============================
 
 .. _IP-in-IP: https://en.wikipedia.org/wiki/IP_in_IP
 .. _Calico: https://docs.projectcalico.org/
 .. _IP-in-IP Calico configuration: https://docs.projectcalico.org/v3.7/networking/vxlan-ipip
 
-By default Calico_ in MetalK8s is configured to use IP-in-IP_ encapsulation
+By default, Calico_ in MetalK8s is configured to use IP-in-IP_ encapsulation
 only for cross-subnet communication.
 
 IP-in-IP_ is needed for any network which enforces source and
 destination fields of IP packets to correspond to the MAC address(es).
 
-To always use IP-in-IP_ encapsulation run the following command:
+To configure IP-in-IP_ encapsulation for all communications, run
+the following command:
 
 .. code-block:: shell
 
     $ kubectl --kubeconfig /etc/kubernetes/admin.conf \
       patch ippool default-ipv4-ippool --type=merge \
       --patch '{"spec": {"ipipMode": "Always"}}'
 
-
-For more details refer to `IP-in-IP Calico configuration`_.
+For more information refer to `IP-in-IP Calico configuration`_.

docs/installation/index.rst

@@ -14,7 +14,9 @@ and shows how to access various services after completing the setup.
    introduction
    setup
    bootstrap
+   enable_ip_ip
    expansion
    post-install
    services
    advanced-guide
+   troubleshooting/index

docs/installation/troubleshooting/bootstrap_installation_errors.rst

@@ -0,0 +1,41 @@
+Bootstrap Installation Errors
+=============================
+
+**Bootstrap installation fails for no obvious reason**
+
+If the Metalk8s installation fails and the console output does not provide
+enough information to identify the cause of the failure, re-run the
+installation with the verbose flag (``--verbose``).
+
+.. parsed-literal::
+
+   root@bootstrap $ /srv/scality/metalk8s-|version|/bootstrap.sh --verbose
+
+**Errors after restarting the bootstrap node**
+
+If you reboot the bootstrap node and some containers (especially the
+salt-master container) do not start, perform the following checks:
+
+#. Ensure that the MetalK8s ISO is mounted properly.
+
+   .. parsed-literal::
+
+      [root@bootstrap vagrant]# mount | grep /srv/scality/metalk8s-|version|
+      /home/centos/metalk8s.iso on /srv/scality/metalk8s-|version| type iso9660 (ro,relatime)
+
+#. If the ISO is unmounted, run the following command to check the
+   the status of the ISO file and remount it automatically.
+
+   .. parsed-literal::
+
+      [root@bootstrap vagrant]# salt-call state.sls metalk8s.archives.mounted saltenv=metalk8s-|version|
+       Summary for local
+       ------------
+       Succeeded: 3
+       Failed:    0
+
+**Bootstrap fails and console log is unscrollable**
+
+If the bootstrap process fails during MetalK8s installation and the console
+output is unscrollable, consult the bootstrap logs in
+``/var/log/metalk8s/bootstrap.log``.

docs/installation/troubleshooting/index.rst

@@ -0,0 +1,20 @@
+.. _Troubleshooting Installation Section:
+
+Troubleshooting
+===============
+
+This section describes common issues users face during and after a
+MetalK8s installation.
+
+.. include:: ../../troubleshooting-get-support.rst
+
+.. toctree::
+
+   bootstrap_installation_errors
+   pod_and_service_CIDR_conflicts
+
+.. todo::
+
+   - Add Salt master/minion logs, and explain how to run a specific state from
+     the Salt master.
+   - Add troubleshooting for networking issues.

docs/installation/troubleshooting/pod_and_service_CIDR_conflicts.rst

@@ -0,0 +1,24 @@
+Pod and Service CIDR Conflicts
+==============================
+
+If, after installing a MetalK8s cluster you notice routing issues in
+pod-to-pod communication:
+
+#. Check the configured values for the internal pod and service networks.
+
+   .. code-block:: shell
+
+      [root@bootstrap]# salt-call pillar.get networks
+      local:
+          ----------
+          control_plane:
+              172.21.254.0/28
+          pod:
+              10.233.0.0/16
+          service:
+              10.96.0.0/12
+          workload_plane:
+              172.21.254.32/27
+
+#. Ensure that the configured IP ranges (CIDR notation) do not conflict
+   with your infrastructure.

docs/operation/account_administration/index.rst

@@ -0,0 +1,18 @@
+Account Administration
+======================
+
+This section covers MetalK8s account administration operations, from
+user authentication and identity management to user authorization.
+
+.. toctree::
+
+   user_authentication_and_identity_management
+   user_authorization
+
+.. todo::
+
+   Add documentation on the following
+
+   - Dex connectors
+
+   - How to add a new connector (LDAP, AD, SAML)