Output example
```yaml opensearch: endpoints: 10.95.38.139:9200,10.95.38.212:9200,10.95.38.94:9200 index: test-index password: j3JWFnDkoumCxn0CtKZRCmdRMUlYTZFI tls-ca: |- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- username: opensearch-client_5 version: 2.14.0 ```Output example
```text backup-id: "2026-01-01t10:30:00z" status: in_progress ```Output example
```text backup-id | backup-status ------------------------------------- 2026-01-01t10:30:00z | in_progress 2026-01-01t10:00:00z | success 2026-01-01t09:00:00z | failed ```Output example
```text Model Controller Cloud/Region Version SLA Timestamp oauth overlord microk8s-cluster/localhost 3.6.10 unsupported 15:38:54Z App Version Status Scale Charm Channel Rev Address Exposed Message hydra v2.3.0 active 1 hydra latest/edge 339 10.152.183.124 no identity-platform-login-ui-operator 0.21.2 active 1 identity-platform-login-ui-operator latest/edge 146 10.152.183.25 no kratos v1.3.1 active 1 kratos latest/edge 500 10.152.183.20 no kratos-external-idp-integrator blocked 1 kratos-external-idp-integrator latest/edge 245 10.152.183.113 no Invalid configuration: Missing required configuration 'client_id' for provider 'generic' postgresql-k8s 14.15 active 1 postgresql-k8s 14/stable 495 10.152.183.109 no self-signed-certificates active 1 self-signed-certificates 1/stable 317 10.152.183.250 no traefik-admin v2.11.0 active 1 traefik-k8s latest/stable 176 10.241.7.40 no traefik-public v2.11.0 active 1 traefik-k8s latest/stable 176 10.241.7.39 no Unit Workload Agent Address Ports Message hydra/0* active idle 10.1.156.80 identity-platform-login-ui-operator/0* active idle 10.1.156.81 kratos-external-idp-integrator/0* blocked idle 10.1.156.82 Invalid configuration: Missing required configuration 'client_id' for provider 'generic' kratos/0* active idle 10.1.156.91 postgresql-k8s/0* active idle 10.1.156.89 Primary self-signed-certificates/0* active idle 10.1.156.83 traefik-admin/0* active idle 10.1.156.90 traefik-public/0* active idle 10.1.156.86 ```- Incompatibility between OpenSearch Dashboards and OpenSearch Service
- Insufficient memory
- OpenSearch is in red state | | OpenSearchDashboardsYellow |  | Triggered when OpenSearch Dashboards is yellow. Dashboard plugins might be degraded or shards may be relocating or initializing. | | OpenSearchDashboardsPluginRed |  | Triggered when OpenSearch Dashboards plugin or core component are in red state. | | OpenSearchDashboardsPluginYellow |  | Triggered when OpenSearch Dashboards plugin or core component are in yellow state. | | OpenSearchDashboardsNoMetrics |  | Triggered when exporter failed to collect status metrics. | | OpenSearchDashboardsLongResponseTime |  | Triggered when the server is up and responsive, however with a high latency. | # index.html.md # Release notes * [Revision 21](https://canonical.com/data/opensearch/docs/2//dashboards/docs/reference/release-notes/revision-21.md) # index.html.md # Revision 21 24 September 2024 Charmed OpenSearch Dashboards Revision 21 has been deployed to the [`2/stable` channel](https://charmhub.io/opensearch-dashboards?channel=2/stable) on Charmhub. ## Requirements and compatibility * Juju `v3.5.3+` * Older minor versions of Juju 3 may be compatible, but are not officially supported. * This charm was built to be integrated with [Charmed OpenSearch](https://charmhub.io/opensearch) * See: [Deploy, connect, and scale](https://canonical.com/data/opensearch/docs/2//dashboards/docs/how-to/deploy-connect-scale.md#dashboard-how-to-deploy-connect-scale) ## Highlights * Encryption via TLS * See: [Manage security](https://canonical.com/data/opensearch/docs/2//dashboards/docs/how-to/manage-security.md#dashboard-how-to-manage-security) * High availability deployment support * Automated rolling restart * Monitoring via COS * See: [Enable monitoring](https://canonical.com/data/opensearch/docs/2//dashboards/docs/how-to/enable-monitoring.md#dashboard-how-to-enable-monitoring) ## Join the community Charmed OpenSearch Dashboards is an official distribution of [OpenSearch Dashboards](https://opensearch.org/docs/latest/dashboards/). It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback. * Raise an issue or feature request in the [Github repository](https://github.com/canonical/opensearch-dashboards-operator/issues). * Meet the community and chat with us in our [Matrix channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) * See the Charmed OpenSearch [contribution guidelines](https://github.com/canonical/opensearch-operator/blob/main/CONTRIBUTING.md) on GitHub and read the Ubuntu Community’s [Code of Conduct](https://ubuntu.com/community/code-of-conduct). # index.html.md # Tutorial This tutorial guides you through how to get Charmed OpenSearch Dashboards up and running. It also provides a quick introduction to the following: * Set up an environment using [Multipass](https://multipass.run/) with [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/). * Deploy OpenSearch Dashboards using a single command. * Configure TLS certificate equally simple. This tutorial focuses on OpenSearch Dashboards deployment, assuming that you have familiarity with: * Basic terminal commands. * OpenSearch and OpenSearch Dashboards concepts * The [Charmed OpenSearch Operator](https://charmhub.io/opensearch) ## Set up the environment In this section, you will set up your environment by: * installing and setting up Multipass * installing Juju and bootstrapping LXD * setting up a graphical interface with Multipass ### Install and set up Multipass [Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses the “[cloud-init](https://cloud-init.io/)” standard to install and configure all the necessary parts automatically. Installation of Multipass from [Snap](https://snapcraft.io/multipass) and launching a new VM using “[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)” cloud-init config goes as: ```shell sudo snap install multipass && \ multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs ``` The full set of launch parameters is described in the [launch command reference](https://multipass.run/docs/launch-command). Multipass [commands](https://multipass.run/docs/multipass-cli-commands) are generally short and intuitive. For example, to show all running VMs: ```shell multipass list ``` When the new VM is up and running, connect using: ```shell multipass shell my-vm ``` You can exit the Multipass VM using `Ctrl + D` or the exit command. ### Install and set up Juju The next step is to install Juju and initialize [LXD](https://canonical.com/lxd) (a lightweight container hypervisor). ```shell sudo snap install juju --classic --channel=3.5/stable sudo snap install lxd lxd init --auto ``` Files `/var/log/cloud-init.log` and `/var/log/cloud-init-output.log` contain all low-level installation details. Now that LXD and Juju are installed, the next step is to bootstrap Juju to use local LXD: ```shell juju bootstrap localhost overlord ``` The controller can work with different models. Most applications such as OpenSearch or OpenSearch Dashboards. To set up a new “model” called tutorial, run: ```shell juju add-model tutorial ``` You can now view the model you created above by entering the command `juju status`. You should see something similar to the following output: ```text Model Controller Cloud/Region Version SLA Timestamp tutorial overlord localhost/localhost 3.5.3 unsupported 14:22:02+02:00 Model "admin/tutorial" is empty. ``` ### Set up a graphical interface There are graphical interfaces available for Multipass (see more details in the [Multipass Graphical Interface chapter](https://multipass.run/docs/set-up-a-graphical-interface)). We recommend to use RDP: ```shell sudo apt install ubuntu-desktop xrdp remmina-plugin-rdp remmina sudo passwd ubuntu # Set password here ``` Now you should be able to connect using the IP of the earlier Multipass list command: ```shell remmina -c rdp://
| Alert | Severity | Notes |
|---|---|---|
| OpenSearchScrapeFailed |  |
Triggered when the prometheus scrape fails. |
| OpenSearchClusterRed | |
Triggered when the health status of the cluster is red, meaning that principal shards are not allocated. |
| OpenSearchClusterYellowTemp |  |
Triggered when shards are still reallocating or initializing. |
| OpenSearchClusterYellow | |
Triggered when some replicas shards are unassigned. Might require scale the application to host all shards |
| OpenSearchWriteRequestsRejectionJumps | |
Triggered when the write request rejection is bigger than 5%. Might indicate that the node may not keep up with the indexing speed. |
| OpenSearchNodeDiskLowWatermarkReached | |
Triggered when disks reach 85% of the capacity. |
| OpenSearchNodeDiskHighWatermarkReached |  |
Triggered when disks reach 90% of the capacity. |
| OpenSearchJVMHeapUseHigh |  |
Triggered when the JVM Heap usage in a node reaches 75%. |
| OpenSearchHostSystemCPUHigh | |
Triggered when system CPU usage in a node reaches 90%. |
| OpenSearchProcessCPUHigh | |
Triggered when process CPU usage in a node reaches 90%. |
| OpenSearchThrottling | |
Triggered when a cluster is throttling. Might indicate that is necessary to review indexing request rate, index lifecycle or scale the application. |
| OpenSearchThrottlingTooLong | |
Triggered when a cluster is constantly throttling for at least 20 minutes. Might indicate that is necessary to review indexing request rate, index lifecycle or scale the application. |
\\\\ Check the [X.509 certificates topic](https://charmhub.io/topics/security-with-x-509-certificates) for an overview of the TLS certificates charms available. ## Configure TLS Before enabling TLS on Charmed OpenSearch we must first deploy the `self-signed-certificates` charm: ```shell juju deploy self-signed-certificates --channel 1/stable --config ca-common-name="Tutorial CA" ``` Wait until `self-signed-certificates` is active. Use `juju status --watch 1s` to monitor the progress. ```text Model Controller Cloud/Region Version SLA Timestamp tutorial opensearch-demo localhost/localhost 3.6.23 unsupported 12:39:22Z App Version Status Scale Charm Channel Rev Exposed Message opensearch blocked 3 opensearch 2/stable 344 no Missing TLS relation with this cluster. self-signed-certificates active 1 self-signed-certificates 1/stable 586 no Unit Workload Agent Machine Public address Ports Message opensearch/0 blocked idle 0 10.95.38.94 Missing TLS relation with this cluster. opensearch/1 blocked idle 1 10.95.38.139 Missing TLS relation with this cluster. opensearch/2* blocked idle 2 10.95.38.212 Missing TLS relation with this cluster. self-signed-certificates/0* active idle 3 10.95.38.54 Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running 3 started 10.95.38.54 juju-be3883-3 ubuntu@24.04 Running ``` ## Integrate with OpenSearch To enable TLS on Charmed OpenSearch, you must integrate (also known as “relate”) the two applications. We will go over integrations in more detail in the [next page](https://canonical.com/data/opensearch/docs/2//tutorial/4-integrate-with-a-client-application.md#tutorial-4-integrate-with-a-client-application) of this tutorial. To integrate `self-signed-certificates` with `opensearch`, run the following command: ```shell juju integrate opensearch:certificates self-signed-certificates ``` The OpenSearch service will start. This might take some time. Once done, you can see the new integrations with `juju status --relations`. ```text Model Controller Cloud/Region Version SLA Timestamp tutorial opensearch-demo localhost/localhost 3.6.23 unsupported 12:41:22Z App Version Status Scale Charm Channel Rev Exposed Message opensearch active 3 opensearch 2/stable 344 no self-signed-certificates active 1 self-signed-certificates 1/stable 586 no Unit Workload Agent Machine Public address Ports Message opensearch/0 active idle 0 10.95.38.94 9200/tcp opensearch/1 active idle 1 10.95.38.139 9200/tcp opensearch/2* active idle 2 10.95.38.212 9200/tcp self-signed-certificates/0* active idle 3 10.95.38.54 Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running 3 started 10.95.38.54 juju-be3883-3 ubuntu@24.04 Running Integration provider Requirer Interface Type Message opensearch:node-lock-fallback opensearch:node-lock-fallback node_lock_fallback peer opensearch:opensearch-peers opensearch:opensearch-peers opensearch_peers peer opensearch:upgrade-version-a opensearch:upgrade-version-a upgrade peer self-signed-certificates:certificates opensearch:certificates tls-certificates regular ``` Notice the last relation: `self-signed-certificates:certificates opensearch:certificates tls-certificates regular`. #### NOTE **Next step:** [4. Integrate with a client application](https://canonical.com/data/opensearch/docs/2//tutorial/4-integrate-with-a-client-application.md#tutorial-4-integrate-with-a-client-application) # index.html.md # 2. Deploy OpenSearch > [Charmed OpenSearch Tutorial](https://canonical.com/data/opensearch/docs/2//tutorial/index.md#tutorial-index) > 2. Deploy OpenSearch Charmed OpenSearch supports performance profiles. It is recommended in a single host deployment with LXD to use the `testing` profile, which will only consume 1G RAM per container. To deploy Charmed OpenSearch, run the following command: ```shell juju deploy opensearch -n 3 ``` #### NOTE The `-n` flag is optional and specifies the number of units to deploy. In this case, we are deploying three units of Charmed OpenSearch. We recommend deploying at least three units for high availability. This command will fetch the charm from [Charmhub](https://charmhub.io/opensearch) and deploy 3 units to the LXD cloud. This process can take several minutes depending on your machine. You can track the progress by running: ```bash juju status --watch 1s ``` #### NOTE This command is useful for checking the status of your Juju model, including the applications and machines it hosts. Helpful information it displays includes IP addresses, ports, state, etc. The output of this command updates once every other second. When the application is ready, `juju status` will show something similar to the sample output below: ```text Model Controller Cloud/Region Version SLA Timestamp tutorial opensearch-demo localhost/localhost 3.6.23 unsupported 12:36:56Z App Version Status Scale Charm Channel Rev Exposed Message opensearch blocked 3 opensearch 2/stable 344 no Missing TLS relation with this cluster. Unit Workload Agent Machine Public address Ports Message opensearch/0 blocked idle 0 10.95.38.94 Missing TLS relation with this cluster. opensearch/1 blocked idle 1 10.95.38.139 Missing TLS relation with this cluster. opensearch/2* blocked idle 2 10.95.38.212 Missing TLS relation with this cluster. Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running ``` To exit the `juju status` screen, enter `Ctrl + C`. The status message `Missing TLS relation with this cluster.` is displayed because Charmed OpenSearch requires TLS to be configured before use, to ensure data is encrypted in transit for the HTTP and Transport layers. We will do this in the next step. If you see the following status message: ```text Missing requirements: vm.swappiness should be at most 0 ``` you need to [set the correct kernel parameters](https://canonical.com/data/opensearch/docs/2//tutorial/1-set-up-the-environment.md#tutorial-1-set-up-the-environment) to continue. #### NOTE **Next step:** [3. Enable TLS](https://canonical.com/data/opensearch/docs/2//tutorial/3-enable-encryption.md#tutorial-3-enable-encryption) # index.html.md # 4. Integrate with a client application > [Charmed OpenSearch Tutorial](https://canonical.com/data/opensearch/docs/2//tutorial/index.md#tutorial-index) > 4. Integrate with a client application [Integrations](https://documentation.ubuntu.com/juju/3.6/reference/relation/) (also known as “relations”) are the easiest way to connect to Charmed OpenSearch. Integrations automatically create a username, password, and database for the desired user/application, and define access permissions. ## Deploy the Data Integrator charm The best way to create a user and password for manual use (i.e. connecting to OpenSearch directly using `curl`, which is what we’ll be doing later) is to add a relation between Charmed OpenSearch and the [Data Integrator Charm](https://charmhub.io/data-integrator). Data Integrator 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 and robust user experience. Deploy Data Integrator as follows: ```shell juju deploy data-integrator --channel=stable --config index-name=test-index --config extra-user-roles=admin ``` The expected output: ```text Deployed "data-integrator" from charm-hub charm "data-integrator", revision 362 in channel latest/stable on ubuntu@24.04/stable ``` Wait for `juju status --watch 1s` to show: ```text Model Controller Cloud/Region Version SLA Timestamp tutorial opensearch-demo localhost/localhost 3.6.23 unsupported 12:43:22Z App Version Status Scale Charm Channel Rev Exposed Message data-integrator blocked 1 data-integrator latest/stable 362 no Please relate the data-integrator with the desired product opensearch active 3 opensearch 2/stable 344 no self-signed-certificates active 1 self-signed-certificates 1/stable 586 no Unit Workload Agent Machine Public address Ports Message data-integrator/0* blocked idle 4 10.95.38.22 Please relate the data-integrator with the desired product opensearch/0 active idle 0 10.95.38.94 9200/tcp opensearch/1 active idle 1 10.95.38.139 9200/tcp opensearch/2* active idle 2 10.95.38.212 9200/tcp self-signed-certificates/0* active idle 3 10.95.38.54 Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running 3 started 10.95.38.54 juju-be3883-3 ubuntu@24.04 Running 4 started 10.95.38.22 juju-be3883-4 ubuntu@24.04 Running Integration provider Requirer Interface Type Message data-integrator:data-integrator-peers data-integrator:data-integrator-peers data-integrator-peers peer opensearch:node-lock-fallback opensearch:node-lock-fallback node_lock_fallback peer opensearch:opensearch-peers opensearch:opensearch-peers opensearch_peers peer opensearch:upgrade-version-a opensearch:upgrade-version-a upgrade peer self-signed-certificates:certificates opensearch:certificates tls-certificates regular ``` Notice that the status of the `data-integrator` application is `blocked`. This is because it is waiting for a relation to be established with another application namely `opensearch`. ## Integrate with OpenSearch Now that the Database Integrator charm has been set up, we can relate it to Charmed OpenSearch. This will automatically create a username, password, and CA certificate for the Database Integrator charm. Integrate the two applications with: ```shell juju integrate data-integrator opensearch ``` Wait for `juju status --relations --watch 1s` to show that the `data-integrator` application is now active: Model Controller Cloud/Region Version SLA Timestamp tutorial opensearch-demo localhost/localhost 3.6.23 unsupported 12:44:43Z App Version Status Scale Charm Channel Rev Exposed Message data-integrator active 1 data-integrator latest/stable 362 no
\\\\ opensearch active 3 opensearch 2/stable 344 no
\\\\ self-signed-certificates active 1 self-signed-certificates 1/stable 586 no Unit Workload Agent Machine Public address Ports Message data-integrator/0\* active idle 4 10.95.38.22
\\\\ opensearch/0 active idle 0 10.95.38.94 9200/tcp
\\\\ opensearch/1 active idle 1 10.95.38.139 9200/tcp
\\\\ opensearch/2\* active idle 2 10.95.38.212 9200/tcp
\\\\ self-signed-certificates/0\* active idle 3 10.95.38.54 Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running 3 started 10.95.38.54 juju-be3883-3 ubuntu@24.04 Running 4 started 10.95.38.22 juju-be3883-4 ubuntu@24.04 Running Integration provider Requirer Interface Type Message data-integrator:data-integrator-peers data-integrator:data-integrator-peers data-integrator-peers peer opensearch:node-lock-fallback opensearch:node-lock-fallback node_lock_fallback peer opensearch:opensearch-client data-integrator:opensearch opensearch_client regular opensearch:opensearch-peers opensearch:opensearch-peers opensearch_peers peer opensearch:upgrade-version-a opensearch:upgrade-version-a upgrade peer self-signed-certificates:certificates opensearch:certificates tls-certificates regular ```default Notice the new relation `opensearch:opensearch-client data-integrator:opensearch opensearch_client regular`. This relation created the user, password, and CA certificate for the `data-integrator` application. To retrieve information such as the username, password, and database. Run the following command: ```bash juju run data-integrator/leader get-credentials ``` This should output something like: ```yaml Running operation 1 with 1 task - task 2 on unit-data-integrator-0 Waiting for task 2... ok: "True" opensearch: data: '{"extra-user-roles": "admin", "index": "test-index", "requested-secrets": "[\"username\", \"password\", \"tls\", \"tls-ca\", \"uris\"]"}' endpoints: 10.95.38.139:9200,10.95.38.212:9200,10.95.38.94:9200 index: test-index password: j3JWFnDkoumCxn0CtKZRCmdRMUlYTZFI tls-ca: |- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- username: opensearch-client_5 version: 2.14.0 ``` Save the CA certificate (value of `tls-ca` in the previous response), username, and password, because you will need them in the next section. ## Create and access OpenSearch indices Before connecting to OpenSearch, it is mandatory that you [enable TLS on this cluster](https://canonical.com/data/opensearch/docs/2//tutorial/3-enable-encryption.md#tutorial-3-enable-encryption), following the previous step in the tutorial. You can access the OpenSearch REST API in any way you prefer. In this tutorial, we will use `curl`. Get the IP of an OpenSearch node from the output of `juju status` (any of the nodes should work fine), and store the CA certificate in a local file (e.g. `demo-ca.pem`). Then, replacing `
\\\\ self-signed-certificates active 1 self-signed-certificates 1/stable 586 no Unit Workload Agent Machine Public address Ports Message data-integrator/0\* blocked idle 4 10.95.38.22 Please relate the data-integrator with the desired product opensearch/0 active idle 0 10.95.38.94 9200/tcp
\\\\ opensearch/1 active idle 1 10.95.38.139 9200/tcp
\\\\ opensearch/2\* active idle 2 10.95.38.212 9200/tcp
\\\\ self-signed-certificates/0\* active idle 3 10.95.38.54 Machine State Address Inst id Base AZ Message 0 started 10.95.38.94 juju-be3883-0 ubuntu@24.04 Running 1 started 10.95.38.139 juju-be3883-1 ubuntu@24.04 Running 2 started 10.95.38.212 juju-be3883-2 ubuntu@24.04 Running 3 started 10.95.38.54 juju-be3883-3 ubuntu@24.04 Running 4 started 10.95.38.22 juju-be3883-4 ubuntu@24.04 Running Integration provider Requirer Interface Type Message data-integrator:data-integrator-peers data-integrator:data-integrator-peers data-integrator-peers peer opensearch:node-lock-fallback opensearch:node-lock-fallback node_lock_fallback peer opensearch:opensearch-peers opensearch:opensearch-peers opensearch_peers peer opensearch:upgrade-version-a opensearch:upgrade-version-a upgrade peer self-signed-certificates:certificates opensearch:certificates tls-certificates regular ```default Now try again to connect in the same way as the previous section ```bash curl --cacert demo-ca.pem -XGET https://