Search Guard - Enterprise Security for Elasticsearch
Version: SG FLX
Community

Upgrade from Search Guard 7 to 8

Content

Upgrading Elasticsearch and Search Guard from 7 to 8 can mean two things, depending on your currently deployed Search Guard version:

  • Upgrading Search Guard 7 Classic to 8 FLX or
  • Upgrading Search Guard 7 FLX to 8 FLX

Upgrading Search Guard 7 Classic to 8 FLX

Prerequisites

To perform an upgrade from Search Guard 7 Classic to 8 FLX, you need to run at least:

  • Elasticsearch 7.17.28 (Elasticsearch requirement)
  • Search Guard Classic 53.10.0 (Search Guard requirement)

If you run older versions of Elasticsearch and/or Search Guard, please upgrade first.

Multitenancy and DLS/FLS/Field Masking check

The upgrade path to Search Guard 8 FLX depends on whether you use Multitenancy or DLS/FLS/Field Masking features.

How to check if Multi-Tenancy is enabled
To verify if Multi-Tenancy is enabled, please check the Kibana configuration file and the existence of indices dedicated to each tenant. (For further information, please refer to the documentation).

How to check if DLS/FLS/Field Masking is enabled
If sg_roles.yml contains any role with dls: or fls: or masked_fields: attributes, DLS/FLS/Field Masking is enabled.

If you use any of them, the upgrade differs and requires additional steps. The upgrade path would look like 7.17.28-53.10.0 -> 7.17.28-1.6.0 -> 8.7.1-1.6.0 -> 8.19.19-4.1.2 It’s also possible to skip the 7.17.28-1.6.0 step and go directly from 7.17.28-53.10.0 to 8.7.1-1.6.0 in case less testing is tolerable.

If neither Multi-Tenancy nor DLS/FLS/Field Masking is enabled, you can upgrade in a single step directly to 8.19.6-3.1.3 (but not to Search Guard 4.x.x). Upgrading to Search Guard 4.x.x would require an additional update (which should be done together with upgrading to Elasticsearch 9).

Upgrading Search Guard 7 FLX to 8 FLX

Upgrading Search Guard from 7.17.x to 8.x.x can be done while you upgrade Elasticsearch from 7.17.x to 8.x.x. You can do this by performing a full cluster restart, or by doing a rolling restart:

Search Guard supports running a mixed cluster of 7.17.x and 8.x.x nodes and is thus compatible with the Elasticsearch upgrade path.

If you have not already done so, make yourself familiar with Elastic’s own upgrade instructions for the Elastic Stack:

Review breaking changes

Prerequisites

To perform an upgrade from 7.x to 8.x, you need to run at least:

  • Elasticsearch 7.17.x (Elasticsearch requirement)
  • Search Guard FLX 1.0.0 (Search Guard requirement)
  • Upgrading from Search Guard classic (i.e., Search Guard versions 53 and before) is not supported

If you run older versions of Elasticsearch and/or Search Guard, please upgrade first.

Upgrading Search Guard

Upgrading from Search Guard 7 classic (i.e., Search Guard versions 53 and before) is not supported. You first need to migrate Search Guard classic to Search Guard FLX.

After upgrading a node from ES 7 to 8, simply install the correct version of Search Guard on this node.

No changes in elasticsearch.yml are required.

Upgrading Kibana

Kibana should be upgraded after the Elasticsearch / Search Guard upgrade is completed. Just install the correct version of the Search Guard plugin to Kibana.

The following changes in kibana.yml are required:

  • Remove xpack.security.enabled property
  • Remove xpack.spaces.enabled property if present
  • Remove xpack.ml.enabled property if present
  • Remove xpack.apm.enabled property if present
  • Remove xpack.graph.enabled property if present
  • Remove xpack.monitoring.enabled property if present
  • Add security.showInsecureClusterWarning: false if not already present

Important Notes and Troubleshooting

Expected warnings or log messages

  • In Kibana you can ignore all warnings and errors in the logs that originate from plugins.security.* or plugins.securitySolution or plugins.alerting or plugins.taskManager.

elasticsearch.keystore

  • In case you get an org.elasticsearch.ElasticsearchSecurityException which complains about invalid configuration for xpack.security ... is not set, but the following settings have been configured in elasticsearch.yml: ... please remove the elasticsearch.keystore file in the config/ folder and restart the node.

Legacy ldap module removed

  • The original implementation of the legacy ldap authentication and authorization backend was removed in Search Guard FLX for Elasticsearch 8. The implementation was replaced with another implementation which should exactly behave like the original one. In case you use the legacy ldap authentication or authorization backend and experience any issues please contact us via the support portal or through the community support forum.

Running in mixed mode: Limitations

Elasticsearch and Search Guard support running your cluster in mixed mode, that is, with 7.17.x and 8.x nodes. This makes it possible to upgrade via rolling restart.

Running a cluster in mixed mode should only be done while upgrading from 7 to 8. It’s not supposed to be a permanent situation, and you should aim to minimize the duration where a mixed cluster exists.

While running in mixed mode, the following limitations apply:

Monitoring

While running in mixed mode, X-Pack monitoring might return incorrect values or throw Exceptions which you can safely ignore.

Questions? Drop us a note!

Not what you were looking for? Try the search.