This is an older version of Search Guard. Switch to Latest version
Upgrading Search Guard
Content
If you’re looking for specific upgrade instructions from 6.x to 7.x, please follow the steps described here.
The following instructions assume that Search Guard has been installed on your cluster previously and that the Search Guard configuration index already exists.
There are two types of upgrades to distinguish:
- Upgrading Search Guard for your current Elasticsearch version
- for example, upgrading from 7.5.1-38.0.0 to 7.5.1-38.1.0
- Upgrading Search Guard and Elasticsearch
- for example, upgrading from 7.5.1-38.0.0 to 7.5.1-38.0.0
In the first case you only need to re-install Search Guard. This can be done with a rolling restart of your Elasticsearch nodes, without any downtime.
In the latter case, you need to first upgrade your Elasticsearch installation, and after that install the correct Search Guard version. If you need to perform a full cluster restart or not depends on the Elasticsearch version you are upgrading from and to. Please consult the official Elasticsearch documentation:
https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html
Before starting the upgrade, check if there are any breaking changes either in Elasticsearch or Search Guard:
Elasticsearch Breaking Changes
Check permission schema
The permission schema can change from Elasticsearch version to Elasticsearch version. If there are any known changes in the permission schema, they will be reflected in the sg_roles.yml
and sg_action_groups.yml
file that ships with Search Guard. Therefore always prefer using action groups instead of assigning single permissions to roles directly.
This applies for all Elasticsearch upgrades.
Upgrading Search Guard Only
Upgrades from one version of Search Guard to another can be done with a rolling restart. If there are no breaking changes mentioned in the Search Guard changelog, you don’t need to adapt any configuration files.
Given there are no breaking changes, you can directly upgrade to the latest Search Guard version and do not need to upgrade one version at a time. To do so:
- Stop your Elasticsearch node
- Remove the old version of Search Guard
bin/elasticsearch-plugin remove search-guard-7
- Install the new version of Search Guard
- See the chapter Installing Search Guard for instructions
After that, restart your node and check that Elasticsearch and Search Guard are starting without errors.
Then, repeat this process for all other nodes in the cluster.
Upgrading Elasticsearch and Search Guard
If you’re looking for specific upgrade instructions from 6.x to 7.x, please follow the steps described here.
First check with the official Elasticsearch documentation if your upgrade requires a full cluster restart, or if it can be performed via a rolling restart:
Minor Upgrades - Rolling restart
Follow the official Elasticsearch guideline for rolling upgrades for your Elasticsearch version:
Depending on your configured authentication and authorisation modules, you need to provide additional credentials in the curl
calls mentioned in the rolling upgrade guide.
You can either use a user that has full cluster management permissions, or use an admin certificate, which has full access as well.
Example: Using HTTP Basic authentication
curl -Ss -u admin:admin --insecure -XPUT 'https://localhost:9200/_cluster/settings?pretty' \
-H 'Content-Type: application/json' -d'
{
"persistent": {
"cluster.routing.allocation.enable": "none"
}
}
'
Example: Using an admin certificate
curl -Ss -XPUT 'https://localhost:9200/_cluster/settings?pretty' \
-E "certificates/CN=kirk,OU=client,O=client,L=Test,C=DE.all.pem" \
--cacert "certificates/chain-ca.pem" \
-H 'Content-Type: application/json' -d'
{
"persistent": {
"cluster.routing.allocation.enable": "none"
}
}
'
Steps
Steps from the Rolling upgrades guide:
- Disable shard allocation
- Stop non-essential indexing and perform a synced flush (Optional)
- Stop and upgrade a single node
- Upgrade any plugins: Upgrade the Search Guard plugin
- Start the upgraded node
- Reenable shard allocation
- Wait for the node to recover
- Repeat for all nodes
- If there are any changes in the permission schema, change the
sg_roles.yml
and/orsg_action_groups.yml
and update the Search Guard configuration withsgadmin
Major Upgrades - Full cluster restart
Follow the official Elasticsearch guideline for full cluster restart upgrades for your Elasticsearch version:
The same rules for the curl
commands as above apply, you need to execute them by using an admin certificate or by providing credentials for a user that has full cluster management permissions.
Back up the Search Guard configuration (Optional)
In case you do not have acces to your original Search Guard configuration files anymore, you can retrieve the current configuration of your running cluster by using sgadmin
with the -r
(--retrieve
) switch:
./sgadmin.sh \
-ks kirk.jks -kspass changeit \
-ts truststore.jks -tspass changeit \
-icl -nhnv -r
This will retrieve and save all Search Guard configuration files to your working directory. You can later use these files to initialize Search Guard after the upgrade.
For a major upgrade, the permission schema has very likely changed. so compare especially the sg_roles.yml
and sg_action_groups.yml
files with the versions that ship with the Search Guard plugin.