Upgrading from 6.x to 7.x
Content
- Review breaking changes
- Prerequisites
- Pause processes that use the REST management API or sgadmin
- Check your Search Guard configuration
- Upgrading Search Guard
- Demo roles and action groups
- Upgrading Kibana
- Running in mixed mode: Limitations
- Migrating to the new built-in roles
- Migrating to the new built-in action groups
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 then run
./sgadmin7/tools/sgadmin.sh -vc 6 -cd "./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 |