search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso
App Search Documentation / app search: App Search, Upgrade 7.5 to 7.6
App Search, Upgrade 7.5 to 7.6

From Zero to Search

Guides

API Reference

App Search API Clients

Self-Managed App Search

Resources

App Search, Upgrade 7.5 to 7.6

How do I upgrade App Search to 7.6 from 7.5 on Cloud or when Self-Managing?

App Search releases new features and fixes at a regular cadence. That means you'll want to upgrade!

Keeping your deployment up to date gives you access to new features, security updates, and performance improvements.

This document focuses on the immediate upgrade from 7.5 to 7.6.

For richer detail about the upgrade process, please read the Upgrade Guide.

Upgrading 7.5 to 7.6

Before you begin it is helpful to do the following:

  • Test upgrades in a development environment before rolling them out to production.
  • Stop writing to your Elasticsearch Cluster.
  • Back-up your data with Elasticsearch snapshots. This is required for a rollback, if needed!

There are two recommended upgrade paths. Whichever you choose will depend on your requirements for App Search service availability, on the capabilities of the platform you are using to manage the deployment, on available resources, and so. See the details below to better understand pros and cons of each upgrade path.

  1. In-place Upgrade: replace an App Search instance with a new set running a newer version. Requires operator to shut down, upgrade packages, start back up and let the instances migrate the data if needed. Cause downtime and requires no client-side changes.
  2. Snapshot-based Upgrade: create a snapshot of an Elasticsearch cluster used by App Search, restore the snapshot to a new Elasticsearch cluster, and then start App Search on the new cluster. Does not cause downtime but requires client changes.

In-place Upgrade

If you are able to handle a downtime of the App Search service, then this is the most straight-forward upgrade path. We recommend this method to all customers who are able to schedule a maintenance window for their service or for non-mission-critical applications based on App Search.

Advantages

  1. No need for new infrastructure – everything is done in-place and you do not need to provision any new instances of Elasticsearch or App Search.
  2. No need to change client configurations – all of your API clients can use the same API endpoints before and after the upgrade since new App Search instances will simply replace the existing ones.

Disadvantages

  1. Downtime required – you have to shut down all of your App Search instances to perform the upgrade and your service will not be available until the upgrade is complete. With proper planning, the downtime period can be reduced significantly, but downtime is still unavoidable.
  2. Harder to roll back – if your upgrade fails for any reason, we do not recommend rolling back to the older version of App Search due to potential issues with the partially migrated dataset in Elasticsearch. You would have to restore from a backup to get back to your original state, which would prolong the downtime.
Steps
  1. Stop all of your App Search instances.
  2. Back up your data from Elasticsearch, using snapshots.
  3. Upgrade App Search packages on your servers or change your container image tags to point to the latest version if you use Docker or Kubernetes.
  4. Start up the new version of App Search and new instances will take care of coordinating. They will then perform the upgrade before starting up and accepting your API traffic.

Snapshot-based Upgrade

For situations where App Search downtime is not acceptable or in cases where you want to ensure a rollback is possible – no matter what happens during an upgrade – the safest way to perform the upgrade is through snapshot-based cloning of a deployment. The snapshot-based process is more involved, but it does guarantee data consistency and allows you to perform a migration without a downtime of the Search API

Advantages

  • Write downtime only – both the old App Search deployment and the new one are able to handle search traffic throughout the upgrade process, meaning your clients should not notice the migration at all. You will lose the ability to index or write data.
  • Easy to rollback – if you notice any issues with the new deployment (B) of App Search, you can retry the migration as many times as you need to, since your original deployment is still functional.

Disadvantages

  • Requires additional infrastructure – you need to provision a new Elasticsearch cluster and deploy a set of new App Search instances during the upgrade. This requires some coordination and additional compute resources during the upgrade process.
  • The need to change the client configuration – your API clients need to be switched to the new deployment endpoint after you perform the upgrade. Please note: You could proxy your traffic through a load-balancer (ELB, ALB, etc) or a CDN to keep your API endpoint stable while you replace the App Search cluster behind the proxy.
Steps
  1. Stop writes into your App Search deployment (A) -- you can do this manually by disabling your indexing jobs and so on -- or use the Elasticsearch API to put a write lock on all App Search indexes.
  2. Create a backup of your Elasticsearch cluster (A) using snapshots.
  3. Create a new Elasticsearch cluster (B) and restore data from the latest snapshot.
  4. Deploy a new set of App Search instances (B) using the the new Elasticsearch cluster (B) as the data store.
  5. At this point you should have two separate App Search deployments both serving the same data. You should spot-check to make sure the new deployment (B) looks correct to you.
  6. Switch API traffic from the original App Search deployment (A) to the new one (B).
  7. Shut down the old App Search and Elasticsearch clusters.

Upgrading on Elastic Cloud

When deploying App Search on Elastic Cloud, you have access to two separate upgrade paths depending on your tolerance for App Search downtime:

  1. The default upgrade path -- via the Cloud Console -- is performed in-place via a full cluster restart, meaning App Search will be unavailable for the duration of the upgrade. In future versions of App Search, this mode will allow for in-place upgrades via read-only mode, but as of 7.6.0 downtime is required.

  2. If downtime is unacceptable for your use case, we recommend the Snapshot-based Upgrade process, that involves taking a snapshot of your deployment and then creating a new App Search deployment from the snapshot using a newer App Search version. Please note: The snapshot-based upgrade process requires client-side changes to switch users to another deployment, but guarantees availability of the service during the upgrade process. If you want to keep your client configuration stable, you can proxy your API traffic through a load balancer -- ELB, ALB, or simialr -- or a CDN endpoint.

Warning: If you are using Elastic Cloud or ECE versions 2.4.0 to 2.4.4, there is a known problem with App Search upgrades from versions 7.5 to 7.6 -- rolling upgrades could lead to limited data loss if you are actively modifying new engines during the upgrade process. As a workaround, before upgrading the 7.5 App Search instances to 7.6, you can stop the traffic towards those instances by clicking the Stop routing button in the UI. Once all 7.5 instances are no longer routing traffic, it is safe to perform the upgrade by clicking the Upgrade button.

Troubleshooting

As with any software upgrades, there is always a chance that things will not go according to plan. This means you need to plan and prepare for the possibility of your App Search upgrade failing. You can review the comparison of different upgrade methods above and ensure you are comfortable with the risks associated with your preferred upgrade method before starting the upgrade process.

If you experience an upgrade failure, the information below should help you identify the causes of the issue and allow you to retry the upgrade if needed. App Search should be able to recover from many potential failures, meaning you should be able to retry an upgrade if it fails.

If your App Search upgrade fails, please do the following:

  1. Check the App Search application logs of the new deployment -- log/app-search.log or /var/log/app-search/app-search.log -- to see the details of what happened.
  2. If the upgrade failed due to an issue with Elasticsearch that you can fix, do that and then re-attempt the upgrade by starting a new App Search instance again.
  3. If the process consistently fails, rollback using a method specific to your preferred upgrade path.
  4. Capture the app-search.log file and file a support case with Elastic if you need further help troubleshooting the upgrade process.

Stuck? Looking for help? Contact support or check out the App Search community forum!