Provision an OpenSearch cluster

Jira will automatically create the required indexes when you provision an OpenSearch cluster.

1. Provision an OpenSearch cluster, either on premises or as a managed service, such as AWS OpenSearch Service.
   For detailed instructions, refer to the OpenSearch documentation for setting up a cluster.

2. Configure your cluster with the appropriate level of security.
   Refer to Securing an OpenSearch cluster for the recommended security configuration.

Configure Jira to use OpenSearch

To configure Jira to use OpenSearch:

• Tell Jira that you’re using OpenSearch

• provide Jira with the OpenSearch cluster location and authentication details

You can do this by setting properties in the jirahome/jira-config.properties file. If this file is missing from your Jira installation, you need to create it manually.

The examples below cover these minimum configuration options, and other configuration options are available too. For more configuration options, refer to Recognized application properties.

Tell Jira to use OpenSearch

Set the search.platform property to opensearch (the default is lucene).

For example, in jira-config.properties:

search.platform=opensearch

Provide cluster location and authentication details

Use either basic auth (username and password) or AWS Identity and Access Management (IAM) to authenticate with your OpenSearch cluster.

Option 1: Authenticate with basic authentication

Specify the following properties:

• opensearch.http.url (This is the HTTP(S) URL of the OpenSearch cluster, or multiple URLs separated by commas.)

• opensearch.username

• opensearch.password

For example, in jira-config.properties:

opensearch.http.url=https://10.1.1.10:9200,https://10.1.1.11:9200
opensearch.username=admin
opensearch.password=my-password

Option 2: Authenticate to Amazon OpenSearch Service with AWS request signing

AWS request signing allows you to use Amazon OpenSearch Service with Jira. This lets you secure your Amazon OpenSearch Service cluster to only allow requests from the IAM user that the node Jira is running on inside of AWS EC2 has.

To use Amazon OpenSearch Service with request signing, you must specify the following properties:

• opensearch.http.url (The domain name of the OpenSearch domain, such as the URL without https:// and without the trailing slash at the end.)

• opensearch.aws.region (The AWS region of the OpenSearch domain.)

For example, in jira-config.properties:

opensearch.http.url=vpc-jira.us-east-1.es.amazonaws.com
opensearch.aws.region=us-east-1

Migrate the Lucene index

Now that you’ve reconfigured Jira to use OpenSearch, it’s time to repopulate the index with the existing data.

Simple index migration with downtime

The simplest approach is to rebuild your index as soon as you’ve reconfigured your instance to use OpenSearch. However, this will cause your search functionality to be temporarily unavailable, or returning incomplete results, until the index is fully rebuilt. This is the only approach available for instances on a single node. You can use the Re-indexing admin UI to rebuild your index.

Notable changes

There are some key differences when switching from Lucene to OpenSearch to be aware of, as it might require some changes in your existing processes.

Production backup strategies

Currently, you might take backups of your Lucene index in the home directory, which will avoid the need for a full re-index when restoring. After switching to OpenSearch, you'll need to employ a different strategy using snapshots. Refer to Backing up data for more details.

Search window limit

OpenSearch has a default result window limit of 10,000. This is the maximum number of results you can search for, and the default is set to limit memory usage. If your search request exceeds this limit (for example, if an existing app is programmed to search for more than that limit), you'll get the following error:

{code

Result window is too large, from + size must be less than or equal to: [10000] but was [10010]. See the scroll api for a more efficient way to request large data sets. This limit can be set by changing the [index.max_result_window] index level setting.

If this limitation is causing a problem on your environment, contact Support or your app developers: there are memory-efficient ways to work with a large number of search results that developers can employ to avoid this limitation.

Alternatively, as an immediate workaround, you can increase the index.max_result_window setting on your OpenSearch index. Search requests take heap memory and time proportional to the result window, so make sure your OpenSearch data node has enough memory. Consult OpenSearch documentation about this index setting.

During OpenSearch EAP, we recommend setting max_result_window to 2147483647 as some features are still attempting to retrieve over 10,000 hits.

Analyzers

The default OpenSearch indexing analyzer differs slightly from the default Lucene analyzer used previously. SubTokenFilter was set to keep email addresses as a single token and didn't provide a split on dots or other characters. This isn't the case anymore, and when provided with an email address it'll be split into parts.

For example: jira@atlassian.com will be split into jira, atlassian, com, and it'll also contain jira@atlassian.com.

Customer impact: Previously, when searching for Atlassian, results containing jira@atlassian.com weren't included. In OpenSearch, however, more results will be included, as documents containing email addresses will have more matching tokens.

Recognized application properties

The table below covers the configuration options in the jira-config.properties file.