Doc from openstack admin guide (#1083)

doc/source/configuration/cephadm.rst

@@ -1,6 +1,8 @@
-====
-Ceph
-====
+.. _cephadm-kayobe:
+
+================
+Cephadm & Kayobe
+================
 
 This section describes how to use the Cephadm integration included in StackHPC
 Kayobe configuration to deploy Ceph.

doc/source/configuration/ci-cd.rst

@@ -57,26 +57,26 @@ Runner Deployment
     Ideally an Infra VM could be used here or failing that the control host.
     Wherever it is deployed the host will need access to the :code:`admin_network`, :code:`public_network` and the :code:`pulp registry` on the seed.
 
-2. Edit the environment's :code:`${KAYOBE_CONFIG_PATH}/environments/${KAYOBE_ENVIRONMENT}/inventory/groups` to add the predefined :code:`github-runners` group to :code:`infra-vms`
+2. Edit the environment's :code:`$KAYOBE_CONFIG_PATH/environments/$KAYOBE_ENVIRONMENT/inventory/groups` to add the predefined :code:`github-runners` group to :code:`infra-vms`
 
 .. code-block:: ini
 
     [infra-vms:children]
     github-runners
 
-3. Edit the environment's :code:`${KAYOBE_CONFIG_PATH}/environments/${KAYOBE_ENVIRONMENT}/inventory/hosts` to define the host(s) that will host the runners.
+3. Edit the environment's :code:`$KAYOBE_CONFIG_PATH/environments/$KAYOBE_ENVIRONMENT/inventory/hosts` to define the host(s) that will host the runners.
 
 .. code-block:: ini
 
     [github-runners]
     prod-runner-01
 
-4. Provide all the relevant Kayobe :code:`group_vars` for :code:`github-runners` under :code:`${KAYOBE_CONFIG_PATH}/environments/${KAYOBE_ENVIRONMENT}/inventory/group_vars/github-runners`
+4. Provide all the relevant Kayobe :code:`group_vars` for :code:`github-runners` under :code:`$KAYOBE_CONFIG_PATH/environments/$KAYOBE_ENVIRONMENT/inventory/group_vars/github-runners`
     * `infra-vms` ensuring all required `infra_vm_extra_network_interfaces` are defined
     * `network-interfaces`
     * `python-interpreter.yml` ensuring that `ansible_python_interpreter: /usr/bin/python3` has been set
 
-5. Edit the ``${KAYOBE_CONFIG_PATH}/inventory/group_vars/github-runners/runners.yml`` file which will contain the variables required to deploy a series of runners.
+5. Edit the ``$KAYOBE_CONFIG_PATH/inventory/group_vars/github-runners/runners.yml`` file which will contain the variables required to deploy a series of runners.
    Below is a core set of variables that will require consideration and modification for successful deployment of the runners.
    The number of runners deployed can be configured by removing and extending the dict :code:`github-runners`.
    As for how many runners present three is suitable number as this would prevent situations where long running jobs could halt progress other tasks whilst waiting for a free runner.
@@ -120,7 +120,7 @@ Runner Deployment
 
 7. If the host is an actual Infra VM then please refer to upstream `Infrastructure VMs <https://docs.openstack.org/kayobe/latest/configuration/reference/infra-vms.html>`__ documentation for additional configuration and steps.
 
-8. Run :code:`kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/deploy-github-runner.yml`
+8. Run :code:`kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/deploy-github-runner.yml`
 
 9. Check runners have registered properly by visiting the repository's :code:`Action` tab -> :code:`Runners` -> :code:`Self-hosted runners`
 
@@ -130,9 +130,9 @@ Runner Deployment
 Workflow Deployment
 -------------------
 
-1. Edit :code:`${KAYOBE_CONFIG_PATH}/inventory/group_vars/github-writer/writer.yml` in the base configuration making the appropriate changes to your deployments specific needs. See documentation for `stackhpc.kayobe_workflows.github <https://github.com/stackhpc/ansible-collection-kayobe-workflows/tree/main/roles/github>`__.
+1. Edit :code:`$KAYOBE_CONFIG_PATH/inventory/group_vars/github-writer/writer.yml` in the base configuration making the appropriate changes to your deployments specific needs. See documentation for `stackhpc.kayobe_workflows.github <https://github.com/stackhpc/ansible-collection-kayobe-workflows/tree/main/roles/github>`__.
 
-2. Run :code:`kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/write-github-workflows.yml`
+2. Run :code:`kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/write-github-workflows.yml`
 
 3. Add all required secrets and variables to repository either via the GitHub UI or GitHub CLI (may require repository owner)
 

doc/source/configuration/lvm.rst

@@ -93,6 +93,6 @@ hosts:
 
 .. code-block:: console
 
-   mkdir -p ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/pre.d
-   cd ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/pre.d
+   mkdir -p $KAYOBE_CONFIG_PATH/hooks/overcloud-host-configure/pre.d
+   cd $KAYOBE_CONFIG_PATH/hooks/overcloud-host-configure/pre.d
    ln -s ../../../ansible/growroot.yml 30-growroot.yml

doc/source/configuration/monitoring.rst

@@ -2,6 +2,8 @@
 Monitoring
 ==========
 
+.. _monitoring-service-configuration:
+
 Monitoring Configuration
 ========================
 

doc/source/configuration/release-train.rst

@@ -1,4 +1,4 @@
-.. _stackhpc_release_train:
+.. _stackhpc-release-train:
 
 ======================
 StackHPC Release Train

doc/source/configuration/swap.rst

@@ -23,6 +23,6 @@ hosts:
 
 .. code-block:: console
 
-   mkdir -p ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/post.d
-   cd ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/post.d
+   mkdir -p $KAYOBE_CONFIG_PATH/hooks/overcloud-host-configure/post.d
+   cd $KAYOBE_CONFIG_PATH/hooks/overcloud-host-configure/post.d
    ln -s ../../../ansible/swap.yml 10-swap.yml

doc/source/configuration/vault.rst

@@ -1,3 +1,5 @@
+.. _hashicorp-vault:
+
 ================================
 Hashicorp Vault for internal PKI
 ================================
@@ -111,6 +113,9 @@ Certificates generation
 Create the external TLS certificates (testing only)
 ---------------------------------------------------
 
+This method should only be used for testing. For external TLS on production systems,
+See `Installing External TLS Certificates <installing-external-tls-certificates>`__.
+
 Typically external API TLS certificates should be generated by a organisation's trusted internal or third-party CA.
 For test and development purposes it is possible to use Vault as a CA for the external API.
 

doc/source/configuration/wazuh.rst

@@ -2,13 +2,20 @@
 Wazuh
 =====
 
+`Wazuh <https://wazuh.com>`_ is a security monitoring platform.
+It monitors for:
+
+* Security-related system events.
+* Known vulnerabilities (CVEs) in versions of installed software.
+* Misconfigurations in system security.
+
 The short version
 =================
 
 #. Create an infrastructure VM for the Wazuh manager, and add it to the wazuh-manager group
 #. Configure the infrastructure VM with kayobe: ``kayobe infra vm host configure``
 #. Edit your config under
-   ``etc/kayobe/inventory/group_vars/wazuh-manager/wazuh-manager``, in
+   ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-manager``, in
    particular the defaults assume that the ``provision_oc_net`` network will be
    used.
 #. Generate secrets: ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml``
@@ -27,14 +34,14 @@ Provisioning an infra VM for Wazuh Manager.
 Kayobe supports :kayobe-doc:`provisioning infra VMs <deployment.html#infrastructure-vms>`.
 The following configuration may be used as a guide. Config for infra VMs is documented :kayobe-doc:`here <configuration/reference/infra-vms>`.
 
-Add a Wazuh Manager host to the ``wazuh-manager`` group in ``etc/kayobe/inventory/hosts``.
+Add a Wazuh Manager host to the ``wazuh-manager`` group in ``$KAYOBE_CONFIG_PATH/inventory/hosts``.
 
 .. code-block:: ini
 
    [wazuh-manager]
    os-wazuh
 
-Add the ``wazuh-manager`` group to the ``infra-vms`` group in ``etc/kayobe/inventory/groups``.
+Add the ``wazuh-manager`` group to the ``infra-vms`` group in ``$KAYOBE_CONFIG_PATH/inventory/groups``.
 
 .. code-block:: ini
 
@@ -43,7 +50,7 @@ Add the ``wazuh-manager`` group to the ``infra-vms`` group in ``etc/kayobe/inven
    [infra-vms:children]
    wazuh-manager
 
-Define VM sizing in ``etc/kayobe/inventory/group_vars/wazuh-manager/infra-vms``:
+Define VM sizing in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/infra-vms``:
 
 .. code-block:: yaml
 
@@ -57,7 +64,7 @@ Define VM sizing in ``etc/kayobe/inventory/group_vars/wazuh-manager/infra-vms``:
   # Capacity of the infra VM data volume.
   infra_vm_data_capacity: "200G"
 
-Optional: define LVM volumes in ``etc/kayobe/inventory/group_vars/wazuh-manager/lvm``.
+Optional: define LVM volumes in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/lvm``.
 ``/var/ossec`` often requires greater storage space, and ``/var/lib/wazuh-indexer``
 may be beneficial too.
 
@@ -79,7 +86,7 @@ may be beneficial too.
           create: true
 
 
-Define network interfaces ``etc/kayobe/inventory/group_vars/wazuh-manager/network-interfaces``:
+Define network interfaces ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/network-interfaces``:
 
 (The following is an example - the names will depend on your particular network configuration.)
 
@@ -91,7 +98,7 @@ Define network interfaces ``etc/kayobe/inventory/group_vars/wazuh-manager/networ
 
 
 The Wazuh manager may need to be exposed externally, in which case it may require another interface.
-This can be done as follows in ``etc/kayobe/inventory/group_vars/wazuh-manager/network-interfaces``,
+This can be done as follows in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/network-interfaces``,
 with the network defined in ``networks.yml`` as usual.
 
 .. code-block:: yaml
@@ -183,7 +190,7 @@ Deploying Wazuh Manager services
 Setup
 -----
 
-To install a specific version modify the wazuh-ansible entry in ``etc/kayobe/ansible/requirements.yml``:
+To install a specific version modify the wazuh-ansible entry in ``$KAYOBE_CONFIG_PATH/ansible/requirements.yml``:
 
 .. code-block:: yaml
 
@@ -204,7 +211,7 @@ Edit the playbook and variables to your needs:
 Wazuh manager configuration
 ---------------------------
 
-Wazuh manager playbook is located in ``etc/kayobe/ansible/wazuh-manager.yml``.
+Wazuh manager playbook is located in ``$KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml``.
 Running this playbook will:
 
 * generate certificates for wazuh-manager
@@ -214,7 +221,7 @@ Running this playbook will:
 * setup and deploy wazuh-dashboard on wazuh-manager vm
 * copy certificates over to wazuh-manager vm
 
-Wazuh manager variables file is located in ``etc/kayobe/inventory/group_vars/wazuh-manager/wazuh-manager``.
+Wazuh manager variables file is located in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-manager``.
 
 You may need to modify some of the variables, including:
 
@@ -225,31 +232,38 @@ You may need to modify some of the variables, including:
 
     If you are using multiple environments, and you need to customise Wazuh in
     each environment, create override files in an appropriate directory,
-    for example ``etc/kayobe/environments/production/inventory/group_vars/``.
+    for example ``$KAYOBE_CONFIG_PATH/environments/production/inventory/group_vars/``.
 
     Files which values can be overridden (in the context of Wazuh):
 
-    - etc/kayobe/inventory/group_vars/wazuh/wazuh-manager/wazuh-manager
-    - etc/kayobe/wazuh-manager.yml
-    - etc/kayobe/inventory/group_vars/wazuh/wazuh-agent/wazuh-agent
+    - $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh/wazuh-manager/wazuh-manager
+    - $KAYOBE_CONFIG_PATH/wazuh-manager.yml
+    - $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh/wazuh-agent/wazuh-agent
+
+You'll need to run ``wazuh-manager.yml`` playbook again to apply customisation.
 
 Secrets
 -------
 
-Wazuh secrets playbook is located in ``etc/kayobe/ansible/wazuh-secrets.yml``.
+Wazuh requires that secrets or passwords are set for itself and the services with which it communiticates.
+Wazuh secrets playbook is located in ``$KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml``.
 Running this playbook will generate and put pertinent security items into secrets
 vault file which will be placed in ``$KAYOBE_CONFIG_PATH/wazuh-secrets.yml``.
 If using environments it ends up in ``$KAYOBE_CONFIG_PATH/environments/<env_name>/wazuh-secrets.yml``
 Remember to encrypt!
 
-Wazuh secrets template is located in ``etc/kayobe/ansible/templates/wazuh-secrets.yml.j2``.
+Wazuh secrets template is located in ``$KAYOBE_CONFIG_PATH/ansible/templates/wazuh-secrets.yml.j2``.
 It will be used by wazuh secrets playbook to generate wazuh secrets vault file.
 
 
 .. code-block:: console
 
   kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml
 
+.. note:: Use ``ansible-vault`` to view the secrets:
+
+  ``ansible-vault view --vault-password-file ~/vault.password $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-secrets.yml``
+
 Configure Wazuh Dashboard's Server Host
 ---------------------------------------
 
@@ -366,7 +380,7 @@ Verification
 ------------
 
 The Wazuh portal should be accessible on port 443 of the Wazuh
-manager’s IPs (using HTTPS, with the root CA cert in ``etc/kayobe/ansible/wazuh/certificates/wazuh-certificates/root-ca.pem``).
+manager’s IPs (using HTTPS, with the root CA cert in ``$KAYOBE_CONFIG_PATH/ansible/wazuh/certificates/wazuh-certificates/root-ca.pem``).
 The first login should be as the admin user,
 with the opendistro_admin_password password in ``$KAYOBE_CONFIG_PATH/wazuh-secrets.yml``.
 This will create the necessary indices.
@@ -378,9 +392,9 @@ Logs are in ``/var/log/wazuh-indexer/wazuh.log``. There are also logs in the jou
 Wazuh agents
 ============
 
-Wazuh agent playbook is located in ``etc/kayobe/ansible/wazuh-agent.yml``.
+Wazuh agent playbook is located in ``$KAYOBE_CONFIG_PATH/ansible/wazuh-agent.yml``.
 
-Wazuh agent variables file is located in ``etc/kayobe/inventory/group_vars/wazuh-agent/wazuh-agent``.
+Wazuh agent variables file is located in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-agent/wazuh-agent``.
 
 You may need to modify some variables, including:
 
@@ -390,6 +404,25 @@ Deploy the Wazuh agents:
 
 ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-agent.yml``
 
+The Wazuh Agent is deployed to all hosts in the ``wazuh-agent``
+inventory group, comprising the ``seed`` group
+plus the ``overcloud`` group (containing all hosts in the
+OpenStack control plane).
+
+.. code-block:: ini
+
+    [wazuh-agent:children]
+    seed
+    overcloud
+
+The hosts running Wazuh Agent should automatically be registered
+and visible within the Wazuh Manager dashboard.
+
+.. note:: It is good practice to use a `Kayobe deploy hook
+  <https://docs.openstack.org/kayobe/latest/custom-ansible-playbooks.html#hooks>`_
+  to automate deployment and configuration of the Wazuh Agent
+  following a run of ``kayobe overcloud host configure``.
+
 Verification
 ------------
 

doc/source/contributor/pre-commit.rst

@@ -29,12 +29,12 @@ Once done you should find `pre-commit` is available within the `kayobe` virtuale
 
 To run the playbook using the following command
 
-- ``kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/install-pre-commit-hooks.yml``
+- ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/install-pre-commit-hooks.yml``
 
 Whereas to run the playbook when control host bootstrap runs ensure it registered as symlink using the following command
 
-- ``mkdir -p ${KAYOBE_CONFIG_PATH}/hooks/control-host-bootstrap/post.d``
-- ``ln -s ${KAYOBE_CONFIG_PATH}/ansible/install-pre-commit-hooks.yml ${KAYOBE_CONFIG_PATH}/hooks/control-host-bootstrap/post.d/install-pre-commit-hooks.yml``
+- ``mkdir -p $KAYOBE_CONFIG_PATH/hooks/control-host-bootstrap/post.d``
+- ``ln -s $KAYOBE_CONFIG_PATH/ansible/install-pre-commit-hooks.yml $KAYOBE_CONFIG_PATH/hooks/control-host-bootstrap/post.d/install-pre-commit-hooks.yml``
 
 All that remains is the installation of the hooks themselves which can be accomplished either by
 running `pre-commit run` or using `git commit` when you have changes that need to be committed.