From 8fad9fe9972355265979528ac472fbe5f686a037 Mon Sep 17 00:00:00 2001
From: Hongbin Lu <hongbin.lu@huawei.com>
Date: Sun, 24 Sep 2017 00:33:27 -0400
Subject: [PATCH] Add etcd3 to installation tutorial

Etcd is a base service [1] so it should be include in the installation
tutorial so that other services can assume that it is installed.

Right now, there is no package available for etcd3. This patch suggest
to download the released tarball in github [2] instead. The installation
steps are similar to the automated installation script in devstack [3].

[1] https://governance.openstack.org/tc/reference/base-services.html
[2] https://github.com/coreos/etcd/releases/tag/v3.1.7
[3] https://github.com/openstack-dev/devstack/blob/master/lib/etcd3

Change-Id: Ic532e5a01571900d60d51c3e94ba170e22a30e93
---
 .../source/environment-etcd-ubuntu.rst        | 101 ++++++++++++++++++
 doc/install-guide/source/environment-etcd.rst |  12 +++
 doc/install-guide/source/environment.rst      |   1 +
 3 files changed, 114 insertions(+)
 create mode 100644 doc/install-guide/source/environment-etcd-ubuntu.rst
 create mode 100644 doc/install-guide/source/environment-etcd.rst

diff --git a/doc/install-guide/source/environment-etcd-ubuntu.rst b/doc/install-guide/source/environment-etcd-ubuntu.rst
new file mode 100644
index 0000000000..65f3c0b1a7
--- /dev/null
+++ b/doc/install-guide/source/environment-etcd-ubuntu.rst
@@ -0,0 +1,101 @@
+===============
+Etcd for Ubuntu
+===============
+
+Right now, there is no distro package available for etcd3. This guide uses
+the tarball installation as a workaround until proper distro packages are
+available.
+
+Install and configure components
+--------------------------------
+
+#. Install etcd:
+
+   - Create etcd user:
+
+     .. code-block:: console
+
+        # groupadd --system etcd
+        # useradd --home-dir "/var/lib/etcd" \
+              --system \
+              --shell /bin/false \
+              -g etcd \
+              etcd
+
+     .. end
+
+   - Create the necessary directories:
+
+     .. code-block:: console
+
+        # mkdir -p /etc/etcd
+        # chown etcd:etcd /etc/etcd
+        # mkdir -p /var/lib/etcd
+        # chown etcd:etcd /var/lib/etcd
+
+     .. end
+
+   - Download and install the etcd tarball:
+
+     .. code-block:: console
+
+        # ETCD_VER=v3.2.7
+        # rm -rf /tmp/etcd && mkdir -p /tmp/etcd
+        # curl -L https://github.com/coreos/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz -o /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz
+        # tar xzvf /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz -C /tmp/etcd --strip-components=1
+        # cp /tmp/etcd/etcd /usr/bin/etcd
+        # cp /tmp/etcd/etcdctl /usr/bin/etcdctl
+
+     .. end
+
+2. Create and edit the ``/etc/etcd/etcd.conf.yml`` file
+   and set the ``initial-cluster``, ``initial-advertise-peer-urls``,
+   ``advertise-client-urls``, ``listen-client-urls`` to the management
+   IP address of the controller node to enable access by other nodes via
+   the management network:
+
+   .. code-block:: yaml
+
+      name: controller
+      data-dir: /var/lib/etcd
+      initial-cluster-state: 'new'
+      initial-cluster-token: 'etcd-cluster-01'
+      initial-cluster: controller=http://10.0.0.11:2380
+      initial-advertise-peer-urls: http://10.0.0.11:2380
+      advertise-client-urls: http://10.0.0.11:2379
+      listen-peer-urls: http://0.0.0.0:2380
+      listen-client-urls: http://10.0.0.11:2379
+
+   .. end
+
+3. Create and edit the ``/lib/systemd/system/etcd.service`` file:
+
+   .. code-block:: ini
+
+      [Unit]
+      After=network.target
+      Description=etcd - highly-available key value store
+
+      [Service]
+      LimitNOFILE=65536
+      Restart=on-failure
+      Type=notify
+      ExecStart=/usr/bin/etcd --config-file /etc/etcd/etcd.conf.yml
+      User=etcd
+
+      [Install]
+      WantedBy=multi-user.target
+
+   .. end
+
+Finalize installation
+---------------------
+
+#. Enable and start the etcd service:
+
+   .. code-block:: console
+
+      # systemctl enable etcd
+      # systemctl start etcd
+
+   .. end
diff --git a/doc/install-guide/source/environment-etcd.rst b/doc/install-guide/source/environment-etcd.rst
new file mode 100644
index 0000000000..7fe7a218aa
--- /dev/null
+++ b/doc/install-guide/source/environment-etcd.rst
@@ -0,0 +1,12 @@
+Etcd
+~~~~
+
+OpenStack services may use Etcd, a distributed reliable key-value store
+for distributed key locking, storing configuration, keeping track of service
+live-ness and other scenarios.
+
+.. toctree::
+   :glob:
+
+   environment-etcd-*
+
diff --git a/doc/install-guide/source/environment.rst b/doc/install-guide/source/environment.rst
index 834aff1e77..8b3c228292 100644
--- a/doc/install-guide/source/environment.rst
+++ b/doc/install-guide/source/environment.rst
@@ -80,3 +80,4 @@ For more information about system requirements, see the
    environment-sql-database.rst
    environment-messaging.rst
    environment-memcached.rst
+   environment-etcd.rst