How to integrate OpenSearch with an application¶

Integrations (formerly “relations”) are connections between two applications with compatible endpoints. These connections simplify creating and managing users, passwords, and other shared data.

This guide will walk you through integrating your charm with OpenSearch via the opensearch_client interface or the data-integrator charm.

Integrate a different charm with OpenSearch¶

The Charmed OpenSearch provides the opensearch_client interface to allow other charms to connect to it. This interface manages users, passwords, and other shared data.

Add the `opensearch_client` interface to your charm¶

To integrate your client application you must define the opensearch_client interface in your charm’s metadata.yaml file.

requires:
  opensearch:
    interface: opensearch_client

Import the database interface libraries and define database event handlers¶

To integrate with the opensearch_client interface, import the database interface libraries and define the database event handlers in your charm’s charm.py file.

First, navigate to your charm directory and fetch the data_interfaces charm library from Charmhub:

charmcraft fetch-lib charms.data_platform_libs.v0.data_interfaces

Next, import the OpenSearchRequires class from the data_interfaces library in your charm.py file:

from charms.data_platform.libs.interfaces.opensearch_client import OpenSearchRequires

Then, instantiate the OpenSearchRequires class in your charm. The class takes the following parameters:

charm: The charm instance
relation_name: The name of the relation to which to connect. This should match the name of the relation defined in the metadata.yaml file (opensearch in the example above).
index: The name of the index the client application will connect to.
extra_user_roles: A string containing the additional roles to assign to the user. This is optional and defaults to None.
addional_secret_fields: A list of additional secret fields to be shared with the client application. This is optional and defaults to an empty list.

class MyCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.opensearch = OpenSearchRequires(self, "opensearch", "my_index")

Finally, define a callback function to handle the index_created event. This function will be called when the index is created in the OpenSearch cluster.

class MyCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.opensearch = OpenSearchRequires(self, "opensearch", "my_index")
        self.framework.observe(self.opensearch.on.index_created, self._on_index_created)

    def _on_index_created(self, event):
        # Handle the index_created event
        pass

Integrate the client application with OpenSearch¶

To integrate opensearch with your client application, run:

juju integrate opensearch <application>

To remove the integration, run:

juju remove-relation opensearch <application>

Integrate an application outside of Juju with OpenSearch¶

The data-integrator charm is a bare-bones charm that allows for central management of database users, providing support for different kinds of data platform products (e.g. MongoDB, MySQL, PostgreSQL, Kafka, etc) with a consistent, opinionated and robust user experience.

Deploy the `data-integrator` charm¶

To deploy the data-integrator charm, run:

juju deploy data-integrator --config index-name=<index-name>

Relate the `data-integrator` charm to an OpenSearch cluster¶

Once the data-integrator charm is deployed it will blocked until it is related to an OpenSearch cluster. To relate the data-integrator charm to an OpenSearch cluster, run:

juju integrate data-integrator opensearch

Remove the client integration¶

To remove the integration (also known as “relation”) between the data-integrator charm and the OpenSearch cluster, run:

juju remove-relation data-integrator opensearch

Rotate the client password¶

To rotate the client password, remove the relation between the client application and the OpenSearch cluster and then re-add the relation. This will generate a user with a new password.

juju remove-relation opensearch <application>
juju integrate opensearch <application>

Rotate the `admin` password in the OpenSearch cluster¶

To rotate the admin password in the OpenSearch cluster, run the following:

juju run opensearch/leader set-password password=<new-password>

A random password will be generated if you do not specify a password.

juju run opensearch/leader set-password

To get the password, run:

juju run opensearch/leader get-password