Update and Migration Handbook

Migration Planning


The following sections provide guidance in migrating Google Search Appliances in various deployment scenarios.

Migration methods

There are two methods of migrating a single search appliance to another:

Migrating search index and configurations

GSA Mirroring is a feature primarily used to provide high availability and high capacity serving, but it can also be used for migrating configurations and search indexes between appliances. In fact, mirroring is the only means to completely migrate an index from one Google Search Appliance to another, and should be used for GSA migration whenever possible.

This migration method is most appropriate when:

  • Re-indexing of all content takes significant time, due to large index size or slow crawl rates
  • No changes are planned to deployment architecture and content source integration
  • Features in the new software release on the new appliance(s) do not require re-indexing of content (refer to version release notes for guidance)
Advantages of this migration method:
  • Saves time in content indexing (mirroring is much faster than re-indexing of content)
  • Minimal user impact on existing production search experience, as the new appliance’s search index will be an exact “replica” of the existing appliance
Disadvantages of this migration method:
  • Procedure is more complicated than migrating configuration only
  • The crawl cycle on the production system will be temporarily paused and new content will not be acquired during the migration process


For mirroring to be configured, both search appliances must meet the following requirements:

  • They must be on the same GSA version, and be of v6.8 or higher
  • They must be of compatible search appliance models
  • The master GSA must be licensed for equal or lower document count than the replica GSA


The following steps describe the approach of migrating a search appliance by mirroring:

  1. Examine the GSA version of the “target” GSA and check release notes of this version and of any later patches, for issues that may affect the deployment environment. Upgrade the target GSA to the appropriate patch if necessary.
  2. Ensure both GSAs are on the same software version, have the same document license count and are of compatible search appliance models (see mirroring link below). In many cases, the “source” GSA will need to be updated to the same version as the target GSA.
  3. Pause crawling on the source search appliance, as well as any feeds or connector traversals.
  4. Configure mirroring, with the source GSA set up as a master, and the target GSA set up as a replica.
  5. Allow the data sync to complete to 100%, to ensure all content and configurations are copied.
  6. Disable mirroring between the source appliance and the target appliance.
  7. Resume crawl on the target search appliance, and re-configure any feeds or connectors to start sending new content to the new target search appliance.
  8. [optional] If a production backup appliance is in use, enable mirroring and setup the already configured appliance as the master, and the new production backup as the replica. Let the replica sync to 100%.
  9. Cutover to new appliance(s) and decommission old appliance(s).

For more information on mirroring, including compatible appliance models and data that is copied and not copied during mirroring, see “Configuring GSA Mirroring”.

Migration configurations only

The alternative method to GSA migration is through exporting the configuration files from one search appliance and importing it into another.

Since importing a configuration file does not copy the search index from one search appliance to another, a full crawl is required to populate the search index. Furthermore, any feeds or connectors must be configured to re-send documents to the new GSA after the configuration has been imported.

This migration method is most appropriate when:

  • Changes are planned to deployment architecture, such as new content sources being integrated
  • New GSA features are desired that require re-indexing of content
Advantages of this migration method:
  • Provides ability to control what content is indexed on the new appliance
  • Minimal impact to the deployment of existing production GSAs, as the new GSAs can be configured and tested independently before cutting over
Disadvantages of this migration method:
  • More time-intensive than mirroring, as all content needs to be re-crawled or re-fed by connectors and feeds
  • Additional connectors or feed clients may need to be set up on new hosts, since existing connectors and feeds may need to continue to send to the production GSA (for content freshness and/or authorization)
  • Creates additional load to target content servers during re-crawl


  • Configuration file migration is generally recommended only between appliances of the same version
  • Configuration file compatibility between different GSA versions is not guaranteed, and if performed, configurations should be verified to ensure all settings are included.


The following steps describe the approach of migrating a search appliance by configuration files:

  1. Examine the GSA version of the “target” GSA and check release notes of this version and of any later patches, for issues that may affect the deployment environment. Update the target GSA to the appropriate patch if necessary.
  2. Export configuration file(s) from existing GSA and import them into the new appliance. If the source and target GSA software versions are the same, the overall GSA configuration file can be exported and imported. If not, choose various components of the admin console to export (eg. front-end XSLT or collection definitions).
  3. [optional] If there are feed clients or connectors in use, new instances of the feed clients or connectors need to be setup with the target appliance, to index all content.
  4. [optional] If it is critical to have fresh content in production system and the content servers can take on extra load, the existing appliance should be kept crawling. If freshness is not critical, pause the crawl on the existing appliance and any connectors or feed clients.
  5. Allow the new appliance to completely crawl and index all content.
  6. [optional] If a production backup appliance is in use, enable mirroring and setup the already configured appliance as the master, and the new production backup as the replica. Let the replica sync to 100%.
  7. Cutover to new appliance(s) and decommission old appliance(s).

For details on how to perform a configuration file import and export, refer to the GSA Admin Help page for Administration > Import and Export.

Migration scenarios

This section describes considerations and approaches to be taken in common scenarios for migration:

Renewing search appliances

The most common scenario for migrating a GSA is during the renewal of a GSA license. Since new and more powerful hardware is provided with each renewal, migration planning is a critical component of the renewal process.

With every renewal of appliances, a decision must be made on how to migrate from existing to new appliances. The following table outlines the advantages and disadvantages of each migration method, where new appliances are of a different version to existing appliances.

  Advantages Disadvantages
Migrating index and configurations - Ensures complete search index replication- Does not require re-indexing of content*- Mirroring index is faster than re-crawling content - Requires upgrading existing GSAs to same version as new GSAs- Requires appropriate license capacity**- More complex of a process, particularly with distributed architectures
Migrating configurations only - Allows control over what content is indexed on new GSAs- Can be performed on GSAs with differing versions- Minimal impact to existing GSA configurations - Requires re-indexing of all content (can be time intensive)- Creates additional load on content servers during re-crawl- May require additional connector and feed clients to be configured

* Re-indexing of content may be required in some cases (eg. new features requiring re-index)
** Migrating index via mirroring can be performed if license is increased on new appliances, but not if decreased

Promoting a GSA configuration from one environment to another

For migrating between environments (eg. test to production), a manual configuration approach is recommended, since server names and URLs to crawl will usually vary. An export of similar configurations (eg. front-end XSLT and collection definitions) should be performed, combined with manual entry of settings in the admin console.

Increasing license count

In most cases where a GSA license limit is increased, the new license file can be applied to the existing appliance, without any hardware migration being necessary. If a license is increased as part of a GSA renewal however, certain considerations will need to be made, depending on the required changes to deployment architecture.

Single-node to Multi-node

When an architecture changes from a single GSA to multiple GSAs (eg. over 100M documents, requiring two G500 appliances instead of one), Distributed Crawl and Serve will need to be configured. As a result, the search index will either need to be re-indexed on the new architecture, or migrated. In this scenario, when Distributed Crawl and Serve is enabled, the Master GSA node will distribute the index evenly across the GSAs configured in the multi-node GSA network.

Multi-node to multi-node

When an existing Distributed Crawl and Serve architecture is modified (eg. using GB9009s and moving from 60M to 90M documents, requiring three GB9009 appliances instead of two), the new GSA can be added as a new shard/node to the architecture, and the entire search index will be re-distributed evenly across all GSAs. For example, if 54M documents have been indexed across two GSAs, and a third 30M GSA is added to the network as a new shard, the index will be re-distributed and each GSA will have 18M docs.

Migrating with existing mirrored GSAs

The following scenarios describe detailed approaches to migrating to new search appliances where GSA Mirroring is already in use on existing appliances.

Scenario A: New appliances are of the same model and software version

In a scenario where new appliances are of the same model and software version, mirroring can used to migrate the index and configurations to a new appliance, which is then used as the master appliance of a new GSA mirroring network. This scenario the same as that is described in the above section, Migrating search index and configurations.

Scenario B: New appliances are NOT of the same model and software version.

In a scenario where new appliances are not of the same model or software version, the recommended form of GSA migration would be to migrate configurations only, and re-index all content on the new appliances.

However, if migration via mirroring is desired, and assuming that the new GSA model is compatible for mirroring with the existing GSA model in use, an approach that could be taken would be to upgrade an existing appliance (eg. backup replica appliance from the existing mirroring network), then mirror the upgraded GSA to one of the new appliances, and use this GSA as a master in a new GSA mirroring network. In this scenario, the following general steps would be taken:

  1. Pause the crawl from the primary master appliance.
  2. Remove a backup appliance from the existing mirroring network.
  3. Upgrade this appliance to the same version as the new appliance(s).
  4. Configure mirroring from this backup appliance to a new appliance, and complete the sync.
  5. Disable mirroring between the backup appliance and the new appliance.
  6. Configure mirroring on the new appliance to make it the primary master of a new mirroring configuration.
  7. Add additional new appliance(s) to the new mirroring network.
  8. Cutover to new appliances and decommission old appliances.

Migrating with a distributed GSA architecture

In both Distributed Crawl and Serve, as well as Unification architectures, GSA Mirroring can be used to expedite migration from one set of appliances to a new set of hardware (eg. in renewal), per one of the above methods. In this scenario, it is critical that the node assignment and configuration remains the same for each appliance in the target architecture.

For example, when renewing hardware in a three shard architecture in Distributed Crawl and Serve, shards A, B and C will have temporary mirrors of A2, B2 and C2 (ie. the new hardware). When this new hardware is configured with Distributed Crawl and Serve, they must be assigned the same shards (A2 must be master, B2 should be the second shard, and C2 should be the third shard).

This is however, more complex and an advanced migration option than most GSA environments require, and it is generally recommended that migration by reconfiguration and re-indexing be performed when migrating a distributed GSA architecture.

For details on configuring mirroring in distributed GSA architectures, refer to documentation on “Configuring Distributed Crawling and Serving” and “Configuring GSA Unification”.

Replacing a failed search appliance

Another common scenario for migrating a search appliance is when a GSA has encountered a hardware failure and needs to be replaced. Migration from a backup or disaster recovery search appliance needs to occur once a replacement GSA is received, and can be done by any of the above mentioned approaches.

Some additional considerations when replacing a failed search appliance include:

  • In cases where a failed appliance was part of a mirroring network (eg. a master appliance), a master appliance must be re-established first. For example, one of the replicas must be promoted to be a master appliance, which then can be mirrored to the replacement appliance.
  • The appropriate GSA licensing must be applied to the main production serving appliance(s). If a GSA with a production license was the one that failed, the replacement appliance must have a production license to receive the appropriate level of support from Google Enterprise Support.

Moving a search appliance to another location

In some cases, it is required that a search appliance be moved to a new physical location. For example, this may occur with changes to data centers.

Some considerations when physically moving a search appliance include:

  • System availability - Actions should be taken to assess and handle impacts of system downtime. For example, stopping feeds and connectors, disabling GSA mirroring if configured, and switching search serving to a failover GSA environment.
  • GSA mirroring - When changing the IP addresses of GSAs, it's best to disable mirroring prior to relocation, then re-configure the GSA^n setup once the move has been completed, the network has been properly provisioned and service has been resumed on the primary GSA.
  • Network configuration changes - For versions older than GSA v7.0, new network settings should be configured prior to moving the appliances, by utilizing the Administration > Networks Settings page to setup the configuration for the new network whilst the GSA is still on the old network, and then modifying the IP address via the Installation Wizard on the address from a laptop connected directly to the appliance. For more information, see Configuring the Network Settings. For versions GSA v7.0 and later, new network settings can be configured once the GSA has been physically moved, via the Installation Wizard as described above.
  • Shutting down and powering up the GSA - The GSA should be shutdown from the admin console prior to moving, via Administration > Shutdown. Powering-up the GSA is achieved via the power-up button on the front of the appliance.
  • GSA Bezel key - Make sure the GSA bezel key from Google is available during the move. If a GSA bezel key has been misplaced, Google Support should be contacted for a replacement.
  • Physical access and Google Support access to the GSA - For all moves, physical access to the GSA should be made available for the GSA administrator to configure the installation wizard from a laptop physically connected to the GSA on the new LAN. Furthermore, it is best practice that where possible, SSH access be enabled to the GSA prior to moving the GSA, so that remote access may be made possible if needed.

The following links provide some guidance for troubleshooting any network issues that may be encountered:

Was this helpful?
How can we improve it?