Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Required modules

Last updated on
29 August 2025

You must install the following modules in order to use Elasticsearch Connector

Search API

Drupal's Search API module is a framework for connecting Drupal to a search back-end. Elasticsearch Connector builds on the concepts, libraries, and frameworks in Search API. For more information, please see the Documentation for Search API 8.x+.

Installing Search API

Download a version of Search API in the 8.x-1.x release series by running composer require 'drupal/search_api:^1'.

Don't forget to commit the changes to your project's composer.json and composer.lock.

Find Search API in the list of modules at /admin/modules (it's in the Search section), check it, and click the Install button at the bottom of the page.

You don't need to install the sub-modules that ship with Search API, Database Search and Database Search Default.

Configure Search API's permissions from /admin/people/permissions/module/search_api, then click the Save permissions button at the bottom of the page. 

Exactly which permissions to assign depends on your site and use-case, but as of search_api-8.x-1.38, all of the permissions that Search API defines should probably only be granted to administrators.

If you're using Configuration Management, this is a good time to export configuration and commit the changes, so you have a "Save point" to go back to.

Configuring Search API

Search API has an administration page at /admin/config/search/search-api, but we have to install Elasticsearch Connector (see below) before you can configure anything!

Background information

Some key Search API concepts needed to get started with Elasticsearch Connector are Indexes and Servers. At a high level, an Index stores copies of Drupal's data for searching, and a Server is a container for one or more Indexes. In Elasticsearch terms, an Elasticsearch Index corresponds 1-to-1 with a Search API Index; and an Elasticsearch Cluster corresponds 1-to-1 with a Search API Server.

One more important concept is a Search API Tracker. A Search API Tracker copies Drupal's content to the Search API Index when the Drupal content is created, modified, or deleted. By default, Search API Trackers are push-based, which is to say that the Search API Tracker pushes the change to Search API Index proactively. This is different from a crawler-based approach, where something periodically crawls the Drupal content and updates the index.

Key

Drupal's Key module is a framework for securely storing and retrieving API Keys (among other things).

Technically, if you are connecting to a local, development Elasticsearch cluster, then the Key module is optional and you can skip forward to the Elasticsearch Connector section. But, if you're connecting to an Elasticsearch server using an API key (which is the only option when you use Elastic Cloud), then you will need to install and configure the Key module.

Installing Key

Download a version of Key in the 8.x-1.x release series by running composer require 'drupal/key:^1'.

Don't forget to commit the changes to your project's composer.json and composer.lock.

Find Key in the list of modules at /admin/modules (it's in the Security section), check it, and click the Install button at the bottom of the page.

Configure its permissions at /admin/people/permissions/module/key, then click the Save permissions button at the bottom of the page.

Exactly which permissions to assign depends on your site and use-case, but as of key-8.x-1.20, all of the permissions that Key defines should probably only be granted to administrators.

If you're using Configuration Management, this is a good time to export configuration and commit the changes, so you have a "Save point" to go back to.

Configuring Key

The Key module was created because it is insecure to commit secrets to version control. However, version control makes deployment easier.

The Key module lets you create easy-to-deploy Drupal configuration entities, which act as stable "gateways" to more-secure ways of storing secrets. At time-of-writing, the Key module supports the following more-secure ways of storing secrets:

  1. retrieving a secret from an environment variable (i.e.: Key provider = Environment);
  2. retrieving a secret from a file stored outside of the webroot (i.e.: Key provider = File);
  3. with additional helper modules: Lockr, Townsend, AWS Secrets Manager, and Hashicorp Vault; and;
  4. as a fallback, storing the secret in configuration (which isn't normally secure, see the tip below).

This means that, in order to select the correct Key provider when you're creating a key, you need to know a bit about how your hosting provider supports passing secrets to your application.

While storing a secret in configuration isn't normally secure, you can make it more-secure by:

  1. storing a fake/placeholder value in the Key's configuration instead; then,
  2. overriding the fake/placeholder value in web/sites/default/settings.php or web/sites/default/settings.local.php

(the settings[.local].php files are not usually version-controlled because Drupal normally stores it's database-connection secrets there)

You can override a Key whose Key provider = Configuration in settings[.local].php with a line that looks like...

$config['key.key.MACHINE_NAME']['key_provider_settings']['key_value'] = 'VALUE';

... where MACHINE_NAME is the machine name of the key, and VALUE is the secret (e.g.: Elastic Cloud API key).

Key has a configuration page at /admin/config/system/keys.

If you have an API key from Elastic Cloud, click the + Add Key button at the top of the page or go to /admin/config/system/keys/add

  1. Enter a Key name (e.g.: Elastic Cloud API key),
  2. If you plan to override configuration in settings.php as described in the tip above, note the MACHINE_NAME that is generated from the Key name,
  3. Enter a Description that will help you to understand who generated it, and when it was generated. This will help if you ever need to rotate the key in the future.
  4. Under Type settings, set Key type = Authentication
  5. Under Provider settings, set Key provider and tell the Key module where to find the secret in the controls that appear.
    1. If you plan to override configuration in settings.php as described in the tip above, set Key provider = Configuration
  6. If you plan to override configuration in settings.php as described in the tip above, under Value, set Key value = 00000000000000000000000000000000000000000000000000000000000= (don't forget the = at the end). This is a fake/placeholder value.
  7. Click the Save button.
  8. If you're using Configuration Management, export configuration and commit the changes.

Next, you will need to store the API key generated by Elastic Cloud in whatever you chose as your Key provider, i.e.: an environment variable, file outside the webroot, secure vault, or in the settings[.local].php file as described above.

For more information, please see the Documentation for Key 8.x.

Elasticsearch Connector

Drupal's Elasticsearch Connector module tells Search API how to connect to an Elasticsearch cluster, how to send documents to an Elasticsearch Index to build a search index, and how to query an Elasticsearch Index when a user makes a search.

Installing Elasticsearch Connector

Download a version of Elasticsearch Connector in the 8.0.x release series by running composer require 'drupal/elasticsearch_connector:^8@alpha'.

Don't forget to commit the changes to your project's composer.json and composer.lock.

Find Elasticsearch Connector in the list of modules at /admin/modules (it's in the Search section), check it, and click the Install button at the bottom of the page.

Note that Elasticsearch Connector doesn't define any permissions of its own.

If you're using Configuration Management, this is a good time to export configuration and commit the changes, so you have a "Save point" to go back to.

Configuring Elasticsearch Connector

Note that Elasticsearch Connector doesn't have a configuration page of its own: its configuration is managed through Search API. The documentation page Set up a Search API Server with an Elasticsearch backend has more instructions on how to start configuring Elasticsearch Connector.

Continue to Recommended modules, or Set up a Search API Server with an Elasticsearch backend

Help improve this page

Page status: No known problems

You can: