From 8e7a67bfd734830aa985b26856a94d153c509ce7 Mon Sep 17 00:00:00 2001 From: "Dr. Jens Harbott" Date: Tue, 28 Nov 2023 15:18:16 +0100 Subject: [PATCH] Update etcd docs and reno Just some minor formatting and wording updates Change-Id: Ia42944512f8d14a1993bd4ae3d09f0f2ab431322 --- doc/source/admin/etcd.rst | 31 ++++++++++--------- doc/source/user/adding-and-removing-hosts.rst | 14 ++++----- .../notes/managed-etcd-72fb2d3fbba516d9.yaml | 9 +++--- 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/doc/source/admin/etcd.rst b/doc/source/admin/etcd.rst index 35c6f31624..6353c33831 100644 --- a/doc/source/admin/etcd.rst +++ b/doc/source/admin/etcd.rst @@ -7,8 +7,8 @@ Managing etcd Kolla Ansible can manage the lifecycle of an etcd cluster and supports the following operations: -* Bootstrapping a clean multi-node etcd cluster -* Adding a new member to the etcd cluster +* Bootstrapping a clean multi-node etcd cluster. +* Adding a new member to the etcd cluster. * Optionally, automatically removing a deleted node from the etcd cluster. It is highly recommended to read the operator documentation for the version @@ -22,17 +22,17 @@ of etcd deployed in the cluster. This pattern is very different from many other Kolla Ansible services, and is a source of confusion for operators unfamiliar with etcd. -Cluster vs Node Bootstrapping -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cluster vs. Node Bootstrapping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kolla Ansible distinguishes between two forms of bootstrapping in an etcd cluster: -* Bootstrapping multiple nodes at the same time to bring up a new cluster -* Bootstrapping a single node to add it to an existing cluster +* Bootstrapping multiple nodes at the same time to bring up a new cluster. +* Bootstrapping a single node to add it to an existing cluster. -These corresponds to the `new` and `existing` parameters for -`ETCD_INITIAL_CLUSTER_STATE` in the upstream documentation. Once an etcd node +These corresponds to the ``new`` and ``existing`` parameters for +``ETCD_INITIAL_CLUSTER_STATE`` in the upstream documentation. Once an etcd node has completed bootstrap, the bootstrap configuration is ignored, even if it is changed. @@ -43,12 +43,12 @@ a healthy etcd cluster and it will add a new node to it. Forcing Bootstrapping ~~~~~~~~~~~~~~~~~~~~~ -Kolla Ansible looks for the `kolla_etcd` volume on the node. If this volume +Kolla Ansible looks for the ``kolla_etcd`` volume on the node. If this volume is available, it assumes that the bootstrap process has run on the node and the volume contains the required config. However, if the process was interrupted (externally, or by an error), this -volume might be misconfigured. In order to prevent dataloss, manual +volume might be misconfigured. In order to prevent data loss, manual intervention is required. Before retriggering bootstrap make sure that there is no valuable data on the @@ -56,9 +56,11 @@ volume. This could be because the node was not in service, or that the data is persisted elsewhere. To retrigger a bootstrap (for either the cluster, or for a single node), -remove the volume, from all affected nodes: +remove the volume from all affected nodes by running: -``docker volume rm kolla_etcd`` +.. code-block:: console + + docker volume rm kolla_etcd Rerunning Kolla Ansible will then trigger the appropriate workflow and either a blank cluster will be bootstrapped, or an empty member will be added to @@ -68,10 +70,11 @@ Manual Commands ~~~~~~~~~~~~~~~ In order to manage etcd manually, the ``etcdctl`` command can be used inside -the `etcd` container. This command has been set up with the appropriate +the ``etcd`` container. This command has been set up with the appropriate environment variables for integrating with automation. -``etcdctl`` is configured with json output by default: +``etcdctl`` is configured with json output by default, you can override that +if you are running it yourself: .. code-block:: console diff --git a/doc/source/user/adding-and-removing-hosts.rst b/doc/source/user/adding-and-removing-hosts.rst index 4e244e995b..524e3ead3f 100644 --- a/doc/source/user/adding-and-removing-hosts.rst +++ b/doc/source/user/adding-and-removing-hosts.rst @@ -171,16 +171,16 @@ For each host, clean up its services: openstack compute service delete --os-compute-api-version 2.53 $id done -.. _removing-existing-compute-nodes: +If the node is also running the ``etcd`` service, set +``etcd_remove_deleted_members: "yes"`` in ``globals.yml`` to automatically +remove nodes from the ``etcd`` cluster that have been removed from the inventory. -If the node is also running the `etcd` service, set -``etcd_remove_deleted_members: "yes"`` in `globals.yml` to automatically -remove nodes from the `etcd` cluster that have been removed from the inventory. - -Alternatively the `etcd` members can be removed manually with `etcdctl`. For -more details, please consult the `runtime reconfiguration` documentation +Alternatively the ``etcd`` members can be removed manually with ``etcdctl``. +For more details, please consult the ``runtime reconfiguration`` documentation section for the version of etcd in operation. +.. _removing-existing-compute-nodes: + Removing existing compute nodes ------------------------------- diff --git a/releasenotes/notes/managed-etcd-72fb2d3fbba516d9.yaml b/releasenotes/notes/managed-etcd-72fb2d3fbba516d9.yaml index 6c8a91a54a..9d59616658 100644 --- a/releasenotes/notes/managed-etcd-72fb2d3fbba516d9.yaml +++ b/releasenotes/notes/managed-etcd-72fb2d3fbba516d9.yaml @@ -1,11 +1,12 @@ --- fixes: - | - The `etcd` tooling has been updated to better serialize restarts when - applying configuration or updates. Previously minor outages might occur - since all services were restarted in the same task. + The ``etcd`` tooling has been updated to better serialize restarts when + applying configuration or updates. Previously minor outages might have + occurred since all services were restarted in the same task. +features: - | - The `etcd` tooling has been updated to handle adding and removing nodes. + The ``etcd`` tooling has been updated to handle adding and removing nodes. Previously this was an undocumented manual process and required creating service containers. Operators can refer to the `etcd admin guide `__