|
| 1 | +# How to update |
| 2 | + |
| 3 | +This document contains information on how to upgrade the solution from one version to the next. It is also possible to skip multiple versions. |
| 4 | + |
| 5 | +The basic principle of the solution is that no files delivered with a release are changed. This is the best way to ensure that the solution can be updated without any problems. Only your .env file(s) must be carried over from one release to the next. It is not planned to backport bugfixes or enhancements in older releases. |
| 6 | + |
| 7 | +Currently, we describe how to update based on Docker Compose. As soon as a deployment via HELM charts on a Kubernetes cluster is supported, that will also be documented here. |
| 8 | + |
| 9 | +## Zero-downtime upgrade |
| 10 | + |
| 11 | +With the following steps you can update the solution without downtime. Of course, this requires that all components (Logstash, API Builder, Memcached) are running at least 2x and configured accordingly. So all filebeats have to communicate with all logstash hosts. |
| 12 | + |
| 13 | +### General overview |
| 14 | + |
| 15 | +The core component is the API Builder project which provides the information about the necessary configuration. In principle, it contains the desired or necessary state suitable for the version, especially about the Elasticsearch configuration, such as index templates, ILM policies, etc. If the version is updated, the API builder checks the current configuration in Elasticsearch and adjusts it if necessary to fit the corresponding version. This includes necessary changes for bug fixes or enhancements. |
| 16 | + |
| 17 | +- Load and unpack the current or desired release |
| 18 | + - it is recommended to unpack it next to the existing release |
| 19 | + - `wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.0/axway-apim-elk-v2.0.0.tar.gz -O - | tar -xvz` |
| 20 | +- Copy your `.env` file from the existing installation |
| 21 | + - recommended is to use a sym-link to a central `.env` file, which should also be versioned if necessary |
| 22 | + - it is pointed out in this document, if parameters have changed or new ones have been added. |
| 23 | +- depending on which components have changed |
| 24 | + - these containers must be stopped and then restarted based on the new release with `docker-compose up -d` |
| 25 | + - e.g. if no change is noted in logstash, then this component can continue to run |
| 26 | +- the API builder delivers the configuration for Elasticsearch as well |
| 27 | + - If the API builder is updated, then it checks on restart and periodically if the Elasticsearch configuration is correct. |
| 28 | + - In addition, the API builder checks whether the filebeat and logstash configuration corresponds to the expected version. |
| 29 | + |
| 30 | +## Release history - Changed components |
| 31 | + |
| 32 | +| Ver | API-Builder | Logstash | Memcached | Filebeat | ANM-Config | Dashboards | Params | ELK-Ver.| Notes | |
| 33 | +| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :--- | |
| 34 | +| 1.0.0 | N/A | N/A | N/A | N/A | N/A | N/A | N/A | 7.9.2 | | |
| 35 | +| 2.0.0 | [X](#api_builder_logstash_memcached)| [X](#api_builder_logstash_memcached)| [X](#api_builder_logstash_memcached)| [X](#filebeat)| [X](#anm_config)| [X](#dashboards)| [X](#parameters)| 7.10.0 | | |
| 36 | +| 2.0.1 | [X](#api_builder_logstash_memcached)| - | - | - | - | - | - | 7.10.0 | | |
| 37 | +| 2.0.2 | [X](#api_builder_logstash_memcached)| - | - | - | - | - | - | 7.10.0 | | |
| 38 | + |
| 39 | +### Update from Version 1.0.0 |
| 40 | + |
| 41 | +If you are upgrading from Release 1.0.0 and encounter problems, please open an issue. |
| 42 | + |
| 43 | +### Upgrade components |
| 44 | + |
| 45 | +#### Filebeat |
| 46 | + |
| 47 | +The following steps illustrates an update to version 2.0.2: |
| 48 | +``` |
| 49 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 50 | +cd axway-apim-elk-v2.0.2 |
| 51 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 52 | +docker-compose -f filebeat/docker-compose.filebeat.yml stop |
| 53 | +docker-compose -f filebeat/docker-compose.filebeat.yml up -d |
| 54 | +``` |
| 55 | + |
| 56 | +#### API-Builder/Logstash/Memcached |
| 57 | + |
| 58 | +If Filebeat should be updated with one of the releases that are between the current one and the new one, then please [update Filebeat](#filebeat) in advance. |
| 59 | + |
| 60 | +API Builder, Logstash and Memcache work as a tight unit and should be stopped, updated together if possible. The following steps illustrates an update to version 2.0.2: |
| 61 | +``` |
| 62 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 63 | +cd axway-apim-elk-v2.0.2 |
| 64 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 65 | +docker-compose stop |
| 66 | +docker-compose up -d |
| 67 | +``` |
| 68 | +Repeat these steps on all machines running Logstash/API-Builder/Memcache. |
| 69 | + |
| 70 | +#### ANM config |
| 71 | + |
| 72 | +Please follow the instructions to [setup the Admin-Node-Manager](README.MD#setup-admin-node-manager) based on the most recent Policy-Fragment shipped with the release. |
| 73 | + |
| 74 | +#### Dashboards |
| 75 | + |
| 76 | +Please follow the instructions to [import Kibana-Dashboards](README.MD#kibana) based on the most recent Dashboards shipped with the release. |
| 77 | + |
| 78 | +#### Parameters |
| 79 | + |
| 80 | +Sometimes it may be necessary to include newly introduced parameters in your `.env` file or you may want to use optional parameters. To do this, use the supplied `env-sample` as a reference and copy the desired parameters. |
| 81 | + |
| 82 | +#### Elastic-Stack version |
| 83 | + |
| 84 | +If the Elasticsearch version needs to be updated, for example because a problem has been fixed, please follow these steps: |
| 85 | +- Open your `.env` file and change the parameter: `ELASTIC_VERSION` to the necessary version as specified in the release or the version you would like to use |
| 86 | + - Make sure that the `.env` file contains the correct/same version on all machines |
| 87 | +- To avoid any downtime, double check all Elasticsearch clients have multiple or all Elasticsearch nodes configured so that they can fail over |
| 88 | +__1. Update Elasticsearch cluster__ |
| 89 | +Updating the Elasticsearch cluster happens one node after next. Before updating the next node it's strongly recommended that the cluster state is green and remaining nodes have enough disk space to take over the shards from the node to be upgraded. |
| 90 | +``` |
| 91 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 92 | +cd axway-apim-elk-v2.0.2 |
| 93 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 94 | +docker-compose -f elasticsearch/docker-compose.es01.yml stop |
| 95 | +docker-compose -f elasticsearch/docker-compose.es01.yml up -d |
| 96 | +``` |
| 97 | +Repeat these steps on the remaining Eleasticsearch nodes, but only after the Elasticsearch cluster has returned to Green status. |
| 98 | + |
| 99 | +__2. Update Kibana__ |
| 100 | + |
| 101 | +To update Kibana you need to perform the following steps after adjusting the `ELASTIC_VERSION` accordingly. |
| 102 | + |
| 103 | +``` |
| 104 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 105 | +cd axway-apim-elk-v2.0.2 |
| 106 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 107 | +docker-compose -f kibana/docker-compose.kibana.yml stop |
| 108 | +docker-compose -f kibana/docker-compose.kibana.yml up -d |
| 109 | +``` |
| 110 | + |
| 111 | +__3. Update Logstash__ |
| 112 | + |
| 113 | +Same procedure as for Kibana but repeat this on all Logstash nodes. |
| 114 | +``` |
| 115 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 116 | +cd axway-apim-elk-v2.0.2 |
| 117 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 118 | +docker-compose stop |
| 119 | +docker-compose up -d |
| 120 | +``` |
| 121 | + |
| 122 | +__4. Update Filebeat__ |
| 123 | + |
| 124 | +Same procedure as for Kibana and Logstash but repeat this on all Filebeat nodes. |
| 125 | +``` |
| 126 | +wget --no-check-certificate https://github.com/Axway-API-Management-Plus/apigateway-openlogging-elk/releases/download/v2.0.2/axway-apim-elk-v2.0.2.tar.gz -O - | tar -xvz |
| 127 | +cd axway-apim-elk-v2.0.2 |
| 128 | +cp ~/axway-apim-elk-v2.0.0/.env . |
| 129 | +docker-compose -f filebeat/docker-compose.filebeat.yml stop |
| 130 | +docker-compose -f filebeat/docker-compose.filebeat.yml up -d |
| 131 | +``` |
| 132 | + |
| 133 | +## Update FAQ |
| 134 | + |
| 135 | +### Do I need to update the Elasticsearch version? |
| 136 | + |
| 137 | +The solution ships a defined Elasticsearch version with each release, which is used by all components of the Elastic stack (Filebeat, Kibana, ...). If nothing else is specified, then you can stay on the Elastic Stack version defined in your `.env` file. |
| 138 | + |
| 139 | +### Can I skip several versions for an upgrade? |
| 140 | + |
| 141 | +Yes, you can. Please note which components have been updated between the current and the new version. |
0 commit comments