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

Configure multiple Jira instances

You can connect multiple Jira instances to the same OpenSearch instance. To prevent index conflicts, make sure each Jira instance uses a unique issues index name.

To set a custom issues index name for a Jira instance:

1. Open the jira-config.properties file for your Jira instance.

2. Add or update the following property with a unique value:

   opensearch.index.issues.name=jira-cluster-a-issues

   
   

3. Replace jira-cluster-a-issues with a name that is unique to your Jira instance.

Check your configuration

To confirm that Jira is connected to OpenSearch:

• In your system information, check that search.platform displays “opensearch”. More about viewing your system information

• Check out your Instance Health to make sure OpenSearch is working as expected. More about Instance Health

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.

Alternatively, you can migrate to OpenSearch without downtime.

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

Jira uses the jira.search.platform.max.result.window property to control the maximum number of search results returned by a JQL query. The default value is 10000. This property applies to both OpenSearch and Lucene:

• For OpenSearch, this limit is enforced by default.

• For Lucene, the limit only applies when the com.atlassian.jira.lucene.search.limit feature flag is enabled.

This limit helps prevent excessive memory usage and protects the stability of your Jira instance. If your search request exceeds this limit (for example, if an app is programmed to request more results), you’ll get an error like this:

Search limit exceeded. We couldn't complete your search because it requests 20000 results which exceeded the search platform limit of 10000. Try refining your query or contact your Jira administrator. Repeating the same search may not work.

Explore how to prevent crashes with JQL resilience in Jira

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 lists configuration options available in the jira-config.properties file. Some indexing-related application properties can also be edited on the Search indexing or Configuring advanced settings pages.

java.io.IOException: entity content is too long [464] for the configured buffer limit [1]