Version: SG Tech Preview
Community

Production Cluster: Migrating from Search Guard 52 and before

This chapter describes how to migrate a cluster running legacy Search Guard configuration to the new structure with minimal outage.

Please Note:

  • You should do a test run on a test cluster before doing the actual migration.
  • Users that were logged into Kibana while the update is performed, will need to log in again after the update is finalized.

Prerequisites

In order to perform the migration, you need the following:

  • The file sg_config.yml from the existing Elasticsearch setup.
  • Sometimes, sg_config.yml references further files, such as PEM files. You need these as well.
  • The file kibana.yml from the config directory of the existing Kibana setup.
  • You need to download the sgctl tool. It does not require any special installation, just copy it to a suitable place and execute it.

Migrating the Configuration

Open a shell and perform the following steps:

  • Create a work directly
  • Call sgctl migrate-fe /path/to/legacy/sg_config.yml /path/to/legacy/kibana.yml -o /path/to/your/work/directory. Be sure to specify the correct paths to the files sg_config.yml and kibana.yml. If you are using Elasticsearch 7.11 or newer, additionally specify the option --target-platform es711.
  • sgctl will now create new configuration files and print additional information to the console. Carefully review the printed information and the produced configuration.
  • The new Search Guard version requires that users who shall be allowed to log into Kibana have a certain privilege. If your users are mapped to the role SGS_KIBANA_USER (which was already a recommended practice before), the users will automatically have that privilege. If your users are not mapped to the role, you need to edit your role mapping accordingly.

Applying the Configuration

To execute the update, follow this process:

  • Perform a rolling update of the Search Guard Elasticsearch plugin.
  • Use sgadmin or sgctl to upload the sg_frontend_config.yml file produced by sgctl.
  • Perform an update of the Search Guard Kibana plugin. Also, copy the new kibana.yml file to the config directory of the Kibana installation.
  • Restart the Kibana instance.

The update is now finished. Users which were logged in before, will now have to login again once.

You should now remove authc config entries from sg_config.yml. These are all authc entries for SAML or OIDC; the configuration which is now in use is located in sg_frontend_config.yml.



Not what you were looking for? Try the search.