Read-only mode

Enterprise Search supports a read-only mode, which allows a product operator to disable all writes from the application to the underlying Elasticsearch instance while keeping the application running and handling search requests. This mode could be used to perform maintenance on a deployment, create a consistent snapshot of the deployment’s data, or to perform a graceful upgrade to a newer version of the product without downtime.

After read-only mode is enabled on an Enterprise Search deployment, all write requests to Elasticsearch indexes used by the application will start to fail and the application will handle those errors properly according to the situation. All API requests attempting to modify the state of the deployment will respond with an HTTP 503 message explaining the situation to the caller.

The following functionality will function as expected in read-only mode:

The implementation of the read-only mode means that after you change the read-only flag, all indexing requests will start failing with an HTTP 503 error and will need to be retried later. Your indexing code should be ready to properly handle those responses and retry until indexing succeeds.

Only service operators — people with access to the infrastructure running the application that can run bin/enterprise-search — and owners of an admin API token can manage the read-only mode on an Enterprise Search deployment.

Please note: After the value of the read-only flag is set to true, it is persisted in Elasticsearch index settings. That means the read-only mode block will survive a full restart of the service and that of the underlying Elasticsearch cluster and will need to be explicitly removed from all indexes to disable the read-only mode.

To manage the read-only flag, an operator can run one of the following CLI commands:

./bin/enterprise-search --enable-read-only-mode
./bin/enterprise-search --disable-read-only-mode

The read-only mode status can also be viewed and managed via a set of internal APIs:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/ent/v1/internal/read_only_mode'
curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/ent/v1/internal/read_only_mode' -d '{ "enabled": true }' -H "Content-Type: application/json"
curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/ent/v1/internal/read_only_mode' -d '{ "enabled": false }' -H "Content-Type: application/json"

To call the read-only mode API, you must have Elasticsearch credentials (username/password) with a manage Elasticsearch cluster privilege.