From c5af773757b771226820834bb449302bfcae4ff1 Mon Sep 17 00:00:00 2001
From: Eric Peterson <ericpeterson@spotify.com>
Date: Wed, 15 Jun 2022 12:07:44 +0200
Subject: [PATCH] Note the (technically) breaking change and update docs.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
---
 .changeset/search-lightning-cult.md    | 24 ++++++++++++++++++++++++
 docs/features/search/search-engines.md | 21 ++++++++++++++++-----
 2 files changed, 40 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/search-lightning-cult.md

diff --git a/.changeset/search-lightning-cult.md b/.changeset/search-lightning-cult.md
new file mode 100644
index 0000000000..79cd256e77
--- /dev/null
+++ b/.changeset/search-lightning-cult.md
@@ -0,0 +1,24 @@
+---
+'@backstage/plugin-search-backend-module-elasticsearch': minor
+---
+
+**BREAKING**: In order to remain interoperable with all currently supported
+deployments of Elasticsearch, this package will now conditionally use either
+the `@elastic/elasticsearch` or `@opensearch-project/opensearch` client when
+communicating with your deployed cluster.
+
+If you do not rely on types exported from this package, or if you do not make
+use of the `createElasticSearchClientOptions` or `newClient` methods on the
+`ElasticSearchSearchEngine` class, then upgrading to this version should not
+require any further action on your part. Everything will continue to work as it
+always has.
+
+If you _do_ rely on either of the above methods or any underlying types, some
+changes may be needed to your custom code. A type guard is now exported by this
+package (`isOpenSearchCompatible(options)`), which you may use to help clarify
+which client options are compatible with which client constructors.
+
+If you are using this package with the `search.elasticsearch.provider` set to
+`aws`, and you are making use of the `newClient` method in particular, you may
+wish to start using the `@opensearch-project/opensearch` client in your custom
+code.
diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md
index 9bb8b8c343..a5ff780c8a 100644
--- a/docs/features/search/search-engines.md
+++ b/docs/features/search/search-engines.md
@@ -80,15 +80,16 @@ const searchEngine = await ElasticSearchSearchEngine.initialize({
 const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });
 ```
 
-For the engine to be available, your backend package needs a dependency into
+For the engine to be available, your backend package needs a dependency on
 package `@backstage/plugin-search-backend-module-elasticsearch`.
 
 ElasticSearch needs some additional configuration before it is ready to use
 within your instance. The configuration options are documented in the
 [configuration schema definition file.](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-elasticsearch/config.d.ts)
 
-The underlying functionality is using official ElasticSearch client version 7.x,
-meaning that ElasticSearch version 7 is the only one confirmed to be supported.
+The underlying functionality uses either the official ElasticSearch client
+version 7.x (meaning that ElasticSearch version 7 is the only one confirmed to
+be supported), or the OpenSearch client, when the `aws` provider is configured.
 
 Should you need to create your own bespoke search experiences that require more
 than just a query translator (such as faceted search or Relay pagination), you
@@ -97,9 +98,19 @@ search clients. The version of the client need not be the same as one used
 internally by the elastic search engine plugin. For example:
 
 ```typescript
-import { Client } from '@elastic/elastic-search';
+import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch';
+import { Client as ElasticClient } from '@elastic/elastic-search';
+import { Client as OpenSearchClient } from '@opensearch-project/opensearch';
 
-const client = searchEngine.newClient(options => new Client(options));
+const client = searchEngine.newClient(options => {
+  // In reality, you would only import / instantiate one of the following, but
+  // for illustrative purposes, here are both:
+  if (isOpenSearchCompatible(options)) {
+    return new OpenSearchClient(options);
+  } else {
+    return new ElasticClient(options);
+  }
+});
 ```
 
 #### Set custom index template