The following installation guide has been written as an example of an in-place full-cluster restart upgrade from Elasticsearch 7.10.2 to OpenSearch 2.0.1 on Debian Linux 10. It is meant to be used as a supplemental guide to the official OpenSearch installation guide for tarball installation. For a full set of installation instructions for OpenSearch software, see the OpenSearch documentation.

Installation Prerequisites

  1. Confirm the minimum software requirements are met.
  2. Determine average daily and hourly volume ingest by Graylog node(s).
  3. Confirm Graylog journal(s) are configured appropriately, e.g. review capacity, configurations, and test high-utilization of journal(s).
  4. Register a snapshot repository within the Elasticsearch cluster, unless one already exists.
  5. Create a full-cluster snapshot of the Elasticsearch cluster.
  6. Pause Message Processing on Graylog node(s). (Go to the web interface of each node, then navigate to System > Nodes. Click on the More Actions dropdown next to each node, and then select Pause Message Processing.)
  7. Disable shard replication in your Elasticsearch cluster:
Copy
curl -X PUT "http://hostame-of-an-OpenSearch-node:9200/_cluster/settings" -H 'Content-Type: application/json' -d'{

  "transient" : {

     "cluster.routing.allocation.enable" : "primaries"

  }

}

'
  1. Shut down the Elasticsearch cluster (and confirm it is down before proceeding to installation).

OpenSearch Installation

  1. Install OpenSearch 2.0.1 software on all Elasticsearch nodes.
Copy
#Download OpenSearch 2.0.1
wget https://artifacts.opensearch.org/releases/bundle/opensearch/1.3.4/opensearch-1.3.4-linux-x64.tar.gz

#Create user & group
sudo adduser --system --disabled-password --disabled-login --home /var/empty --no-create-home --quiet --force-badname --group opensearch

#Create Directories
sudo mkdir -p /var/lib/opensearch /var/log/opensearch

#Extract Contents from tar
sudo tar -zxf opensearch-2.0.1-linux-x64.tar.gz 
sudo mv opensearch-2.0.1 opensearch 
sudo mv opensearch /usr/share/

#Set Permissions
sudo chown -R opensearch:opensearch /usr/share/opensearch /var/log/opensearch /var/lib/opensearch
sudo chmod -R 2750 /usr/share/opensearch /var/log/opensearch /var/lib/opensearch

#Create System Service
sudo su -
cat > /etc/systemd/system/opensearch.service <<EOF
[Unit]
Description=OpenSearch
Documentation=https://OpenSearch.org/docs/latest
Requires=network.target remote-fs.target
After=network.target remote-fs.target
ConditionPathExists=/usr/share/opensearch
ConditionPathExists=/var/lib/opensearch
[Service]
Environment=OpenSearch_HOME=/usr/share/opensearch
Environment=OpenSearch_PATH_CONF=usr/share/opensearch/config
ReadWritePaths=/var/log/opensearch
User=opensearch
Group=opensearch
WorkingDirectory=/usr/share/opensearch
ExecStart=/usr/share/opensearch/bin/opensearch
# Specifies the maximum file descriptor number that can be opened by this process
LimitNOFILE=65535
# Specifies the maximum number of processes
LimitNPROC=4096
# Specifies the maximum size of virtual memory
LimitAS=infinity
# Specifies the maximum file size
LimitFSIZE=infinity
# Disable timeout logic and wait until process is stopped
TimeoutStopSec=0
# SIGTERM signal is used to stop the Java process
KillSignal=SIGTERM
# Send the signal only to the JVM rather than its control group
KillMode=process
# Java process is never killed
SendSIGKILL=no
# When a JVM receives a SIGTERM signal it exits with code 143
SuccessExitStatus=143
# Allow a slow startup before the systemd notifier module kicks in to extend the timeout
TimeoutStartSec=180
[Install]
WantedBy=multi-user.target
EOF
  1. Take note of the PATH assigned to parameter path.data in the elasticsearch.yml file of your Elasticsearch nodes.
  2. Copy the contents of the elasticsearch.yml path.data PATH to the opensearch.yml path.data:
Copy
sudo rsync -avP /var/lib/elasticsearch/* /var/lib/opensearch/
  1. Update the ownership of the /var/lib/opensearch directory to opensearch:opensearch so OpenSearch can read the Elasticsearch data:
Copy
 sudo chown -R opensearch:opensearch /var/lib/opensearch
  1. Edit opensearch.yml file on all Elasticsearch nodes. If you have Elasticsearch nodes with defined roles such as data, leader, etc., then these roles should be defined differently in OpenSearch. For example:

Data node

Copy
a. elasticsearch.yml: 

    node.data: true 

    node.master: false

b. opensearch.yml:

    node.roles: ['data']

Dedicated leader node

Copy
a. elasticsearch.yml: 

    node.data: false 

    node.master: true

b. opensearch.yml: 

    node.roles: ['master']

The opensearch.yml configuration file(s) will then look something like this at a minimum:

Copy
action.auto_create_index: false

cluster.name: test-cluster1

discovery.seed_hosts: node2,node3

cluster.initial_master_nodes: node1,node2,node3

node.name: node1

path.data: /var/lib/opensearch

path.logs: /var/log/opensearch

plugins.security.disabled: true
  1. Start OpenSearch on all OpenSearch (formerly Elasticsearch) nodes.
  2. Wait for the OpenSearch cluster to start. Check the _nodes summary to verify that all nodes are available and running the expected version:
Copy
curl -XGET 'http://hostame-of-an-OpenSearch-node:9200/_nodes/_all?pretty=true'
  1. Next, check to confirm all indices are shown. Then, continue to refresh and monitor this output until all indices are green:
Copy
curl -XGET 'http://hostame-of-an-OpenSearch-node:9200/_cat/indices?v'
  1. After the cluster is green and all nodes are using the new version, re-enable shard allocation:
Copy
curl -X PUT "http://hostame-of-an-OpenSearch-node:9200/_cluster/settings" -H 'Content-Type: application/json' -d'

{

  "transient" : {

     "cluster.routing.allocation.enable" : "all"

  }

}

'
  1. Restart all Graylog node(s).
HintThere is no need to resume message processing on Graylog node(s) after restarting them as they will automatically resume on restart.