From 0e61dba1ce88ecd37e5178f8c54ae8beaa021dd9 Mon Sep 17 00:00:00 2001
From: Julien Mailleret <julien.mailleret@elastic.co>
Date: Fri, 31 May 2019 13:59:01 +0200
Subject: [PATCH] add upgrade procedure

---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 49 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 832ea7e8..c9e8fc57 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ The latest Elasticsearch versions of 7.x & 6.x are actively tested.
 ### Notice about multi-instance support
 
 Starting with ansible-elasticsearch:7.0.0, installing more than one instance of Elasticsearch **on the same host** is no more supported.
+
 See https://github.com/elastic/ansible-elasticsearch/issues/554#issuecomment-496804929 for more details about why we remove it.
 
 If you install more than one instance of ElasticSearch on the same host (with different ports, directory and config files), **do not update to ansible-elasticsearch >= 7.0.0**.
@@ -27,13 +28,13 @@ If you install more than one instance of ElasticSearch on the same host (with di
 You are still be able to install Elasticsearch 6.x and 7.x in multi-instance mode by using ansible-elasticsearch commit [25bd09f](https://github.com/elastic/ansible-elasticsearch/commit/25bd09f6835b476b6a078676a7d614489a6739c5) (last commit before multi-instance removal) and overriding `es_version` variable:
 
 ```sh
-cat << EOF >> requirements.yml
+$ cat << EOF >> requirements.yml # require git
 - src: https://github.com/elastic/ansible-elasticsearch
   version: 25bd09f
   name: elasticsearch
 EOF
-ansible-galaxy install -r requirements.yml
-cat << EOF >> playbook.yml
+$ ansible-galaxy install -r requirements.yml
+$ cat << EOF >> playbook.yml
 - hosts: localhost
   roles:
     - role: elasticsearch
@@ -41,10 +42,53 @@ cat << EOF >> playbook.yml
         es_instance_name: "node1"
         es_version: 7.0.1 # or 6.7.2 for example
 EOF
-ansible-playbook playbook.yml
+$ ansible-playbook playbook.yml
 ```
 
-However for multi-instances use cases, we are now recommending using Docker containers using our official images (https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)
+However for multi-instances use cases, we are now recommending using Docker containers using our official images (https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html).
+
+#### Upgrade procedure
+
+If you have single-instances hosts and want to upgrade from previous versions of the role:
+
+1. Override these variables to match previous values:
+```yaml
+
+es_conf_dir: /etc/elasticsearch/{{ instance_name }}
+es_data_dirs:
+  - /var/lib/elasticsearch/{{ node_name }}-{{ instance_name }}
+es_log_dir: /var/log/elasticsearch/{{ node_name }}-{{ instance_name }}
+es_pid_dir: /var/run/elasticsearch/{{ node_name }}-{{ instance_name }}
+```
+
+2. Deploy ansible-role. **Even if these variables are overrided, Elasticsearch config file and default option file will change, which imply an Elasticsearch restart.**
+
+3. After ansible-role new deployment, you can do some cleanup of old Init file and Default file.
+
+Example:
+```bash
+$ ansible-playbook -e '{"es_conf_dir":"/etc/elasticsearch/node1","es_data_dirs":["/var/lib/elasticsearch/localhost-node1"],"es_log_dir":"/var/log/elasticsearch/localhost-node1","es_pid_dir":"/var/run/elasticsearch/localhost-node1"}' playbook.yml
+...
+TASK [elasticsearch : Create Directories] **********************************************************************************************************************************************************************************************************************
+ok: [localhost] => (item=/var/run/elasticsearch/localhost-node1)
+ok: [localhost] => (item=/var/log/elasticsearch/localhost-node1)
+ok: [localhost] => (item=/etc/elasticsearch/node1)
+ok: [localhost] => (item=/var/lib/elasticsearch/localhost-node1)
+
+TASK [elasticsearch : Copy Configuration File] *****************************************************************************************************************************************************************************************************************
+changed: [localhost]
+
+TASK [elasticsearch : Copy Default File] ***********************************************************************************************************************************************************************************************************************
+changed: [localhost]
+...
+PLAY RECAP *****************************************************************************************************************************************************************************************************************************************************
+localhost                  : ok=32   changed=3    unreachable=0    failed=0
+
+$ find /etc -name 'node1_elasticsearch*'
+/etc/default/node1_elasticsearch
+/etc/systemd/system/multi-user.target.wants/node1_elasticsearch.service
+$ rm /etc/default/node1_elasticsearch /etc/systemd/system/multi-user.target.wants/node1_elasticsearch.service
+```
 
 ## Dependency
 This role uses the json_query filter which [requires jmespath](https://github.com/ansible/ansible/issues/24319) on the local machine.