Update and Migration Handbook
Upgrading a GSA
There are various considerations to be taken into account when upgrading GSA software, many of which are dependent on the characteristics of the GSA installation environment and the scope of changes introduced by the new version of the GSA. As such, no two GSA upgrade projects are alike, and each upgrade to the GSA should be prefaced by an level appropriate of analysis and planning.
The following sections provide guidance on how to prepare for and execute a software upgrade to the Google Search Appliance.
Become familiar with the latest version
Each version of the GSA contains new features and fixes, and it is critical to become familiar with what is included in a new version of the GSA to be able to plan for an effective upgrade. The best way to start finding out about a new version’s content is to refer to the “Guide to Software Release X.X” section of the GSA documentation and the Release Notes of the version via the Google Enterprise Support Portal.
Understand your upgrade path
Most GSA upgrades only involve one upgrade step, but in cases where a GSA is multiple versions old, an upgrade may require multiple steps.
You can determine the upgrade path by referring to the list of compatible versions on the “Google Search Appliance Software Updates” page of the Google Enterprise Support Portal.
As an example, to upgrade an appliance from v6.12.0.G.30 to v7.0.114.GXXX, the following steps are required:
- Update from v6.12.0.G.30 to v6.14.0.G.22
- Update from v6.14.0.G.22 to v7.0.14.G114
Determine the scope of the upgrade
The complexity and level of effort involved with a GSA upgrade project is dependent on the type of new features and functionality that will be integrated into the search solution. Analysis should be performed up-front to identify the full scope of desired features to be included as part of the GSA upgrade, based on the user requirements of the search solution, and the compatibility of new features with the existing search environment.
Analyze impact and changes required for the upgrade
Once the scope of the upgrade has been defined, an impact analysis should be performed to determine the changes that will be needed to be made to the GSA environment to accommodate for the upgrade.
Common considerations when performing a GSA upgrade include:
- A complete re-index may be a requirement of upgrading to the new GSA software version. The GSA software update instructions typically provide detail on this requirement.
- Some new features require the re-indexing of content. For example, enabling Entity Recognition and Document Previews in v7.0 require re-indexing content since these features involve index-time processing.
- Enabling new user interface features will always involve changes to existing GSA front-ends
- For custom user interfaces (custom XSLT or custom application layers) the complexity of these changes may be anything from trivial to highly complex, depending on the feature.
- For implementations involving custom XSLT modifications, it is recommended that the new version’s default XSLT stylesheet be used as a starting point, and customizations be re-integrated into it. This is typically a simpler approach than determining the changes required to implement the new feature into an existing XSLT stylesheet.
- When new features to the GSA feeds protocol are introduced, custom feeds should be analyzed to determine whether they may benefit from the new changes. For example, in v7.0, new ACL features such as DENY ACLs and ACL inheritance were introduced and offer significantly increased flexibility for designing feeds for secure content.
- Whilst updates to the GSA feed protocol are generally backward compatible, changes that are introduced to the protocol should be analyzed to ensure that existing GSA feeds are not impacted.
- New GSA upgrades will typically support any existing versions of Google connectors. However, it is recommended that version compatibility of connectors be confirmed prior to upgrading to a new GSA version.
Define an upgrade strategy
The goal of defining an upgrade strategy is to determine the best process to upgrade the appliances in a GSA environment whilst having minimal impact to search users and dependent systems.
It is important to understand the potential impacts of the upgrade process to the GSA deployment environment. This section discusses a number of scenarios, where special considerations should be made when upgrading a search appliance.
- Upgrading multiple environments
- Upgrading an inter-connected GSA network
- Upgrading with connectors or feeds
This section applies to deployment architectures involving multiple environments with various purposes, such as development, testing, and production.
Once a version upgrade or patch release is applied to the GSA, it cannot be reverted to a previous version. Additionally, changes/additions to GSA functionality might occasionally impact the existing functionality of a search solution, for example one where the GSA has been tightly integrated within other applications. For these reasons, version upgrades should be applied through development and testing environments, and first be tested rigorously before updating a production search appliance.
In a deployment where a production environment contains one or more backup search appliances for disaster recovery or failover, the following steps are recommended:
- Switch serving to a backup search appliance
- Update the production search appliance first, before upgrading a backup search appliance
This process allows users to continue using search on the existing, familiar version of the search appliance while verification and cutover of the new version in production is taking place. If mirroring is in use, refer to Upgrading an inter-connected GSA network.
Special considerations must be observed when upgrading deployment architectures involving two or more GSAs connected to each other by the use of Mirroring, Distributed Crawling and Serving, or Unification.
In general, the primary GSA(s) in an interconnected GSA network should be upgraded before secondary/backup GSAs are upgraded.
However, each new release has Update Instructions that provide detailed steps for upgrading interconnected GSAs. It is important that these steps are closely followed, as performing an upgrade incorrectly may result in the integrity of the GSA network and search index being compromised, potentially requiring a complete re-indexing of content. If in doubt, contact Google Enterprise Support or a GSA Qualified Deployment Specialist for clarification.
This section applies to deployment architectures involving the use of GSA connectors or feeds.
If your environment uses GSA connectors or feeds, the downtime associated with upgrading a search appliance must be taken into account and planned for. There are two considerations for downtime when using connectors or feeds:
- Indexing of content
- Serving of content, where connectors are used for authentication and authorization
When upgrading a search appliance that uses connectors or feeds to index documents, theconnector or feeds must be stopped or paused for the duration of the update process, as the GSA will not process feeds during the course of an upgrade.
When connectors are used for authentication and/or authorization, and serving is switched to a mirrored or hot backup search appliance during the upgrade of a master GSA, the connector will need to be configured to respond to authentication/authorization requests from the alternative GSA. This can be achieved by following the instructions in “Configuring Connectors with GSA Mirroring.”
The following steps outline the final preparations recommended prior to executing a version upgrade to the GSA:
Become familiar with the Update Instructions
The Update Instructions for the targeted release version contain critical information related to executing the upgrade, and may include special considerations that apply to certain deployment environments. For example:
- If Mirroring, Distributed Crawling and Serve, or Unification are in use, the Update Instructions for each version will contain specific steps to be followed
- If Policy ACLs or Dynamic Navigation are in use, the Update Instructions may have special considerations for these features.
Determine whether to rebuild or migrate the search index
Most version upgrades will provide the option either to migrate the existing search index to the new version, or wipe the index and force a re-crawl of all content (feeds and connectors will also need to resend all content). In most cases, migrating the index is the most effective means to perform an update.
Situations where rebuilding the index would be appropriate include:
- When re-indexing is required to take advantage of new features. For example, using Document Previews in v7.0 requires content to be re-indexed.
- When updating a Replica search appliance in a mirrored GSA network, the index of the Replica GSA should not be migrated and will need to be synchronized from the Master GSA once the update is complete.
Performing the upgrade
The actual process of upgrading a GSA generally includes the following steps, which are always provided in detail in the Update Instructions for the GSA release:
- Preparing for the upgrade: Specific tasks to perform in preparation for the upgrade, such as backing up GSA configurations and verifying that the Google Search Appliance can access the location to which upgrade files are downloaded.
- Updating the system software: An update to the GSA operating system.
- Rebooting the Google Search Appliance: This step may or may not be required for each update. The Update Instructions specify whether a reboot is required.
- Updating the software version: An update to the GSA software.
- Choosing whether to migrate the index data: The decision chosen in this step will either launch an automated index migration process, or trigger a recrawl of all content on the GSA. Feeds and connectors cannot be run during this step of the update process.
- Update testing and verification: Once the migration is complete, or content has been recrawled, the Admin Console Test Center can be used to run some basic tests to confirm results are being served appropriately by the new version.
- Accepting or reverting the update: Once the update is accepted, it cannot be reverted.