{"_id":"5a8fae0468264c001f20cc30","category":{"_id":"5a8fae0368264c001f20cc03","version":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-23T20:11:49.377Z","from_sync":false,"order":6,"slug":"best-practices","title":"Elasticsearch Tips & Tricks"},"project":"5633ebff7e9e880d00af1a53","user":"5633ec9b35355017003ca3f2","parentDoc":null,"version":{"_id":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":4,"createdAt":"2018-02-23T06:00:34.961Z","releaseDate":"2018-02-23T06:00:34.961Z","categories":["5a8fae0268264c001f20cc01","5a8fae0268264c001f20cc02","5a8fae0368264c001f20cc03","5a8fae0368264c001f20cc04","5a8fae0368264c001f20cc05","5a8fae0368264c001f20cc06","5a8fae0368264c001f20cc07","5a8fae0368264c001f20cc08","5a8fae0368264c001f20cc09","5abaa7eb72d6dc0028a07bf3","5b8ee7842790f8000333f9ba","5b8ee8f244a21a00034b5cd9"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-09T16:41:35.474Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"Bonsai makes upgrading major versions of Elasticsearch as painless as possible. There is no need to manage the operational details of deploying software upgrades to nodes or spinning up new servers. With Bonsai, version upgrades are instant and can be performed with zero downtime. \n\nIn this document, we'll cover some general best practices and offer some Bonsai-specific guidelines for migrating your app to a new version of Elasticsearch.\n\n### Use one Elasticsearch cluster per environment\n\nThis means having one cluster for production, and another for staging, another for development, and so on. Some users like to put staging indices alongside production indices on the same cluster in order to ensure identical behaviors between staging and production applications. First, this is a terrible idea in general; you should never run staging/dev applications on the same resources as production. This is a recipe for disaster.\n\nSecond, separating out your environments allows for upgrading them one at a time. While this may sound tedious, it is the most prudent approach and allows you to discover potential problems _before_ they impact production.\n\n### Read the Release Notes Carefully\n\nMake sure to perform your due diligence by reading the release notes that accompany the version you're targeting for the upgrade. It's also a good idea to read the release notes for the versions _between_ your current version and target version. Bonsai has some tools to facilitate this part, discussed later in this document.\n\nAnother thing to investigate is whether your application's Elasticsearch client supports the upgrade candidate. There have been cases where a popular client or framework was several support versions behind the official Elasticsearch release; some of these have resulted in hours of down time for users who upgraded the Elasticsearch cluster beyond the version supported by their Elasticsearch client.\n\n### Validate In Development\n\nUpgrading across major versions sometimes comes with breaking changes, new dependencies, and tweaks in behavior. It is important to validate that the upgrade is safe before pushing it out to production.\n\nOne tool Bonsai has to facilitate this is the Migration Checker. This checker will run a test suite against any cluster to confirm compatibility with the upgrade candidate. To use the checker, navigate to your new cluster dashboard and click the ‘Run Migration Tests’ button:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3040905-01.png\",\n        \"01.png\",\n        1490,\n        844,\n        \"#f4f5ea\"\n      ]\n    }\n  ]\n}\n[/block]\nA new window will open up and automatically run tests against your indices. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b998c26-02.png\",\n        \"02.png\",\n        1490,\n        736,\n        \"#235170\"\n      ]\n    }\n  ]\n}\n[/block]\nIf the checker yields failing tests, you should correct each issue before upgrading. The checker provides links to documentation to help you make changes to your data and index mappings prepare for migration. Click on the \"docs\" link next to each line-item test to read about break changes and how to fix them in your integration.\n\nIf all checks pass, you can start your upgrade process. We advise starting by upgrading the **least critical** environment first. Ensure it works as expected, and make any changes as needed. Deploy those changes to the next least critical environment and then upgrade the cluster for that environment. Continue in this fashion until reaching the production environment. By that point, you should be fairly confident that the application and search will work as expected.\n\nMake sure to validate that searches will work as expected in terms of relevancy. Also make sure to test full deletion and reindexing in the least critical environments before upgrading production. Reindexing is something you should be familiar with anyway as a part of normal usage of Elasticsearch, such as changing analyzer settings, backfilling a new field, or - in this case - upgrading to a new major version.\n\n### Launch to production!\n\nOnce you are satisfied that the candidate version will work in production as expected, the final step is to take it live. There are two ways to do this: upgrading in place, or provisioning a new cluster altogether. The latter is preferred because it not only allows for a zero-downtime switch, but it also provides a fallback in case something breaks.\n\n***Provision a new production cluster (preferred)***\n\nThe first step is to provision a new cluster running on the target version of Elasticsearch. For detailed documentation on this process, check out the relevant documentation here:\n\n* [Bonsai.io users](doc:creating-your-first-cluster)\n* [Heroku users](doc:getting-started-with-heroku#installing-bonsai-elasticsearch)\n* [Manifold users](doc:getting-started-with-manifold#creating-a-bonsai-elasticsearch-cluster)\n\nOnce you have your new production cluster ready to go, you'll need to index it. Check the documentation for your language/framework for specifics on how to perform this action.\n\nWhen the new cluster is fully populated, update the application to serve traffic to the new cluster. This generally involves pointing the Elasticsearch client to the new cluster URL. How this is performed will depend heavily on the application stack, so consult the documentation for your Elasticsearch client.\n\nThe old cluster will remain as a back up in case anything goes wrong after the switch. When you have satisfied yourself that the application is running smoothly in production on the new version of Elasticsearch, you can deprovision the old cluster. You can find more information about this process in the documentation:\n\n* [Bonsai.io users](doc:managing-your-cluster#deprovision)\n* [Heroku users](doc:removing-the-add-on)\n* [Manifold users](doc:removing-the-resource)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"We're Pros at Proration\",\n  \"body\": \"When you deprovision your cluster, Bonsai will issue a service credit for time unused on the subscription. This ensures that your hard earned cash isn't wasted in the process of upgrading to a new version of Elasticsearch.\"\n}\n[/block]\n***Upgrade the current production cluster***\nThere are cases where the preferred approach is not possible. For example, if your application is not able to serve traffic to one cluster while indexing to another in the background. Costs may also be a concern, or the cluster may be running on a subscription that is no longer available and you would like to keep it. \n\nWhatever the reason, the existing cluster can be upgraded in place. A Bonsai cluster can not be upgraded to a new version when it is populated with data. Bonsai will show the following error message if there is data in a cluster to be upgraded:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4382ac3-upgrade_unavailable.png\",\n        \"upgrade unavailable.png\",\n        871,\n        217,\n        \"#f3eded\"\n      ]\n    }\n  ]\n}\n[/block]\nData can be removed from the cluster using a tool like `curl` or the Interactive Console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# See the current indices:\\nGET /_cat/indices\\ngreen open users_production       1 1 1015123 0  32M  64M \\ngreen open notes_production       1 1 1016456 0  35M  70M \\ngreen open comments_production    1 1 1017123 0  39M  78M\\n\\n# Delete the existing indices\\nDELETE /users_production,notes_production,comments_production\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf there is no data in the cluster, the warning message will be a little different and the upgrade button will be blue:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ac5b21b-upgrade-available.png\",\n        \"upgrade-available.png\",\n        877,\n        252,\n        \"#f3eeee\"\n      ]\n    }\n  ]\n}\n[/block]\nClicking on the blue upgrade button will upgrade your cluster to the target version. **This action is irreversible.** Once the cluster is on the new version, it will need to be reindexed.\n\n### Ask Support\n\nUpgrading major versions of Elasticsearch while running a production application can be tricky. If you're unsure of what to do, are concerned about an edge case or special circumstance, or simply want to sanity check a plan, please do not hesitate to reach out to [support:::at:::bonsai.io](mailto:support@bonsai.io). We're here to help ensure the smoothest upgrade possible.","excerpt":"In this post, we’ll walk through the best way to handle migrating your cluster between major versions of Elasticsearch","slug":"upgrading-your-version","type":"basic","title":"Upgrading Major Versions"}

Upgrading Major Versions

In this post, we’ll walk through the best way to handle migrating your cluster between major versions of Elasticsearch

Bonsai makes upgrading major versions of Elasticsearch as painless as possible. There is no need to manage the operational details of deploying software upgrades to nodes or spinning up new servers. With Bonsai, version upgrades are instant and can be performed with zero downtime. In this document, we'll cover some general best practices and offer some Bonsai-specific guidelines for migrating your app to a new version of Elasticsearch. ### Use one Elasticsearch cluster per environment This means having one cluster for production, and another for staging, another for development, and so on. Some users like to put staging indices alongside production indices on the same cluster in order to ensure identical behaviors between staging and production applications. First, this is a terrible idea in general; you should never run staging/dev applications on the same resources as production. This is a recipe for disaster. Second, separating out your environments allows for upgrading them one at a time. While this may sound tedious, it is the most prudent approach and allows you to discover potential problems _before_ they impact production. ### Read the Release Notes Carefully Make sure to perform your due diligence by reading the release notes that accompany the version you're targeting for the upgrade. It's also a good idea to read the release notes for the versions _between_ your current version and target version. Bonsai has some tools to facilitate this part, discussed later in this document. Another thing to investigate is whether your application's Elasticsearch client supports the upgrade candidate. There have been cases where a popular client or framework was several support versions behind the official Elasticsearch release; some of these have resulted in hours of down time for users who upgraded the Elasticsearch cluster beyond the version supported by their Elasticsearch client. ### Validate In Development Upgrading across major versions sometimes comes with breaking changes, new dependencies, and tweaks in behavior. It is important to validate that the upgrade is safe before pushing it out to production. One tool Bonsai has to facilitate this is the Migration Checker. This checker will run a test suite against any cluster to confirm compatibility with the upgrade candidate. To use the checker, navigate to your new cluster dashboard and click the ‘Run Migration Tests’ button: [block:image] { "images": [ { "image": [ "https://files.readme.io/3040905-01.png", "01.png", 1490, 844, "#f4f5ea" ] } ] } [/block] A new window will open up and automatically run tests against your indices. [block:image] { "images": [ { "image": [ "https://files.readme.io/b998c26-02.png", "02.png", 1490, 736, "#235170" ] } ] } [/block] If the checker yields failing tests, you should correct each issue before upgrading. The checker provides links to documentation to help you make changes to your data and index mappings prepare for migration. Click on the "docs" link next to each line-item test to read about break changes and how to fix them in your integration. If all checks pass, you can start your upgrade process. We advise starting by upgrading the **least critical** environment first. Ensure it works as expected, and make any changes as needed. Deploy those changes to the next least critical environment and then upgrade the cluster for that environment. Continue in this fashion until reaching the production environment. By that point, you should be fairly confident that the application and search will work as expected. Make sure to validate that searches will work as expected in terms of relevancy. Also make sure to test full deletion and reindexing in the least critical environments before upgrading production. Reindexing is something you should be familiar with anyway as a part of normal usage of Elasticsearch, such as changing analyzer settings, backfilling a new field, or - in this case - upgrading to a new major version. ### Launch to production! Once you are satisfied that the candidate version will work in production as expected, the final step is to take it live. There are two ways to do this: upgrading in place, or provisioning a new cluster altogether. The latter is preferred because it not only allows for a zero-downtime switch, but it also provides a fallback in case something breaks. ***Provision a new production cluster (preferred)*** The first step is to provision a new cluster running on the target version of Elasticsearch. For detailed documentation on this process, check out the relevant documentation here: * [Bonsai.io users](doc:creating-your-first-cluster) * [Heroku users](doc:getting-started-with-heroku#installing-bonsai-elasticsearch) * [Manifold users](doc:getting-started-with-manifold#creating-a-bonsai-elasticsearch-cluster) Once you have your new production cluster ready to go, you'll need to index it. Check the documentation for your language/framework for specifics on how to perform this action. When the new cluster is fully populated, update the application to serve traffic to the new cluster. This generally involves pointing the Elasticsearch client to the new cluster URL. How this is performed will depend heavily on the application stack, so consult the documentation for your Elasticsearch client. The old cluster will remain as a back up in case anything goes wrong after the switch. When you have satisfied yourself that the application is running smoothly in production on the new version of Elasticsearch, you can deprovision the old cluster. You can find more information about this process in the documentation: * [Bonsai.io users](doc:managing-your-cluster#deprovision) * [Heroku users](doc:removing-the-add-on) * [Manifold users](doc:removing-the-resource) [block:callout] { "type": "info", "title": "We're Pros at Proration", "body": "When you deprovision your cluster, Bonsai will issue a service credit for time unused on the subscription. This ensures that your hard earned cash isn't wasted in the process of upgrading to a new version of Elasticsearch." } [/block] ***Upgrade the current production cluster*** There are cases where the preferred approach is not possible. For example, if your application is not able to serve traffic to one cluster while indexing to another in the background. Costs may also be a concern, or the cluster may be running on a subscription that is no longer available and you would like to keep it. Whatever the reason, the existing cluster can be upgraded in place. A Bonsai cluster can not be upgraded to a new version when it is populated with data. Bonsai will show the following error message if there is data in a cluster to be upgraded: [block:image] { "images": [ { "image": [ "https://files.readme.io/4382ac3-upgrade_unavailable.png", "upgrade unavailable.png", 871, 217, "#f3eded" ] } ] } [/block] Data can be removed from the cluster using a tool like `curl` or the Interactive Console: [block:code] { "codes": [ { "code": "# See the current indices:\nGET /_cat/indices\ngreen open users_production 1 1 1015123 0 32M 64M \ngreen open notes_production 1 1 1016456 0 35M 70M \ngreen open comments_production 1 1 1017123 0 39M 78M\n\n# Delete the existing indices\nDELETE /users_production,notes_production,comments_production", "language": "text" } ] } [/block] If there is no data in the cluster, the warning message will be a little different and the upgrade button will be blue: [block:image] { "images": [ { "image": [ "https://files.readme.io/ac5b21b-upgrade-available.png", "upgrade-available.png", 877, 252, "#f3eeee" ] } ] } [/block] Clicking on the blue upgrade button will upgrade your cluster to the target version. **This action is irreversible.** Once the cluster is on the new version, it will need to be reindexed. ### Ask Support Upgrading major versions of Elasticsearch while running a production application can be tricky. If you're unsure of what to do, are concerned about an edge case or special circumstance, or simply want to sanity check a plan, please do not hesitate to reach out to [support@bonsai.io](mailto:support@bonsai.io). We're here to help ensure the smoothest upgrade possible.