Version: 7.x-36.0.0

Upgrading from 6.x to 7.x

Upgrading Search Guard from 6.7.x to 7.x.x can be done while you upgrade Elasticsearch from 6.7.x to 7.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 6.7.x and 7.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 instruction for the Elastic stack:

Review breaking changes

Prerequisites

In order to to perform a rolling restart and upgrade from 6.x to 7.x, you need to run at least:

  • Elasticsearch 6.7.x (Elasticsearch requirement)
  • Search Guard 6.7.x-25.0 (Search Guard requirement)

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

Pause processes that use the REST management API or sgadmin

If you have jobs or processes running which use the Search Guard REST management API you may want to pause them until the cluster is fully migrated. During migration the REST management API will not work properly and should not be used. The same is true for sgadmin.

Check your Search Guard configuration

If you miss this step your cluster can become uninitialized which will result in a downtime.

Download standalone sgadmin 7 and unpack it in a folder called sgadmin7. It is recommended to do this on the machine from where you typically run sgadmin. Then run

  • ./sgadmin7/tools/sgadmin.sh -backup "./sgadmin7" <other parameters like -ks -cert etc>

If the command completes successfully the run

  • ./sgadmin7/tools/sgadmin.sh -vc 6 "./sgadmin7"

If the output looks like

./sgadmin7/sg_action_groups.yml OK
./sgadmin7/sg_internal_users.yml OK
./sgadmin7/sg_roles.yml OK
./sgadmin7/sg_roles_mapping.yml OK
./sgadmin7/sg_config.yml OK

then your configuration is valid and you can proceed.

If there are errors you need to fix them before you start the upgrade.

Fix the errors, check them with sgadmin.sh -vc 6 command from above and if no further errors are reported upload them into the cluster:

  • ./sgadmin7/tools/sgadmin.sh -cd "./sgadmin7" <other parameters like -ks -cert etc>

Upgrading Search Guard

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

Search Guard 7 is able to read the Search Guard configuration index created with Search Guard 6.x. You do not need to change any settings during the upgrade process.

After all nodes have been upgraded to 7.x, it is mandatory to migrate the Search Guard configuration to the new format.

Migrate Search Guard configuration

Run sgadmin with the -migrate switch:

mkdir my_migrate_dir
./sgadmin.sh -migrate my_migrate_dir <other parameters like -ks -cert etc> 

This will retrieve and save all your original Search Guard configuration files to the my_migrate_dir/ directory. It will then migrate the files to the new configuration format and automatically upload them into your cluster.

As long as this migrate step is not completed you can not use the REST management API.

Demo roles and action groups

If you use any of the Search Guard demo roles and/or actions groups in production, you should migrate them to the new built-in static roles and static action groups.

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. There are no configuration changes in kibana.yml.

Running in mixed mode: Limitations

Elasticsearch and Search Guard support running your cluster in mixed mode, means with 6.7.x and 7.x nodes. This makes it possible to upgrade via rolling restart.

Running a cluster in mixed mode should only be done while upgrading from 6 to 7. 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:

Omit Search Guard configuration changes

Search Guard 7 uses a new format for the Search Guard configuration index, and is also able to read and configuration indices created with Search Guard 6.

While running in mixed mode, do not perform changes to the Search Guard configuration index.

This applies to sgadmin and the REST management API. Configuration changes are possible again after all nodes have been upgraded.

Monitoring

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

Migrating to the new built-in roles

Search Guard 6 shipped with a couple of demo users, roles and action groups. In Search Guard 7, some of them are now built-in and cannot be changed. This was done so whenever the permission schema changes with a new Elasticsearch version, the built-in roles are also updated in the corresponding Search Guard version. This ensures a smooth and automatic upgrade path.

We encourage you to switch from the demo roles to the new built-in roles. Usually it is sufficient to adapt the sg_roles_mapping configuration.

Static Role name (SG 7) Demo role name (SG 6)
SGS_ALL_ACCESS sg_all_access
SGS_READALL sg_readall
SGS_READALL_AND_MONITOR sg_readall_and_monitor
SGS_KIBANA_SERVER sg_kibana_server
SGS_KIBANA_USER sg_kibana_user
SGS_LOGSTASH sg_logstash
SGS_MANAGE_SNAPSHOTS sg_manage_snapshots
SGS_OWN_INDEX sg_own_index
SGS_XP_MONITORING sg_xp_monitoring
SGS_XP_ALERTING sg_xp_alerting
SGS_XP_MACHINE_LEARNING sg_xp_machine_learning

Migrating to the new built-in action groups

General

Static action group name (SG 7) Demo action group name (SG 6)
SGS_UNLIMITED UNLIMITED

Index-level action groups

Static action group name (SG 7) Demo action group name (SG 6)
SGS_INDICES_ALL INDICES_ALL
SGS_READ READ
SGS_SEARCH SEARCH
SGS_DELETE DELETE
SGS_WRITE WRITE
SGS_CRUD CRUD
SGS_GET GET
SGS_SUGGEST SUGGEST
SGS_CREATE_INDEX CREATE_INDEX
SGS_MANAGE_ALIASES MANAGE_ALIASES
SGS_INDICES_MONITOR INDICES_MONITOR
SGS_MANAGE MANAGE
SGS_INDICES_MANAGE_ILM INDICES_MANAGE_ILM

Cluster-level action groups

Static action group name (SG 7) Demo action group name (SG 6)
SGS_CLUSTER_ALL CLUSTER_ALL
SGS_CLUSTER_MONITOR CLUSTER_MONITOR
SGS_CLUSTER_COMPOSITE_OPS_RO CLUSTER_COMPOSITE_OPS_RO
SGS_CLUSTER_COMPOSITE_OPS CLUSTER_COMPOSITE_OPS
SGS_MANAGE_SNAPSHOTS MANAGE_SNAPSHOTS
SGS_CLUSTER_MANAGE_ILM CLUSTER_MANAGE_ILM
SGS_CLUSTER_READ_ILM CLUSTER_READ_ILM
SGS_CLUSTER_MANAGE_INDEX_TEMPLATES CLUSTER_MANAGE_INDEX_TEMPLATES
SGS_CLUSTER_MANAGE_PIPELINES CLUSTER_MANAGE_PIPELINES

Not what you were looking for? Try the search.