From a98e17850acb14c32f55ec18983954d0ea44682f Mon Sep 17 00:00:00 2001
From: Kawika Avilla <kavilla414@gmail.com>
Date: Wed, 25 Dec 2024 10:41:41 -0800
Subject: [PATCH] [docs] update dev guide to connect to external cluster
 (#9080)

* [docs] update dev guide to connect to external cluster

An alternative to developing locally and setting up OpenSearch locally
by pointing to a running cluster.

Issue:
n/a

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

* dont include port

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

* Changeset file for PR #9080 created/updated

---------

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>
Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com>
---
 DEVELOPER_GUIDE.md            | 47 ++++++++++++++++++++++++++++++++++-
 changelogs/fragments/9080.yml |  2 ++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/fragments/9080.yml

diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
index 899de4c0634a..46df57956e97 100644
--- a/DEVELOPER_GUIDE.md
+++ b/DEVELOPER_GUIDE.md
@@ -132,7 +132,11 @@ $ yarn osd clean
 
 ### Run OpenSearch
 
-OpenSearch Dashboards requires a running version of OpenSearch to connect to. In a separate terminal you can run the latest snapshot built using:
+OpenSearch Dashboards requires a running version of OpenSearch to connect to. You can choose to run OpenSearch locally yourself or point to an existing cluster.
+
+#### Run a local OpenSearch cluster 
+
+In a separate terminal you can run the latest snapshot built using:
 
 _(Linux, Windows, Darwin (MacOS) only - for others, you'll need to [set up using Docker](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/docs/docker-dev/docker-dev-setup-manual.md) or [run OpenSearch from a tarball](#alternative---run-opensearch-from-tarball) instead)_
 
@@ -140,6 +144,47 @@ _(Linux, Windows, Darwin (MacOS) only - for others, you'll need to [set up using
 $ yarn opensearch snapshot
 ```
 
+#### Alternative - Connect to an external OpenSearch cluster
+
+Instead of running OpenSearch locally, you can point OpenSearch Dashboards to an existing OpenSearch cluster:
+
+1. Clone the security dashboards plugin inside your OpenSearch Dashboards plugins folder and bootstrap:
+```bash
+$ cd plugins
+$ git clone https://github.com/opensearch-project/security-dashboards-plugin.git
+$ cd ..
+$ yarn osd bootstrap --single-version=loose
+```
+2. Create a configuration directory outside your repository to avoid accidentally committing credentials. For example:
+```bash
+$ mkdir -p /configs/me
+$ mkdir -p /configs/prod
+```
+3. Create `opensearch_dashboards.yml` file(s) in your config directories. Here's an example config:
+```yaml
+opensearch.hosts: ["https://your-opensearch-host"]
+opensearch.username: 'admin' 
+opensearch.password: 'your-password'
+opensearch.ignoreVersionMismatch: true
+opensearch.ssl.verificationMode: none
+opensearch.requestHeadersWhitelist: [authorization]
+opensearch_security.multitenancy.enabled: false
+opensearch_security.readonly_mode.roles: [kibana_read_only]
+opensearch_security.cookie.secure: false
+```
+4. Set the `OSD_PATH_CONF` environment variable to point to your config directory:
+```bash
+$ export OSD_PATH_CONF=/absolute/path/to/configs/me
+```
+
+This approach allows you to:
+- Develop against a production-like environment
+- Avoid running resource-intensive local clusters
+- Maintain different configurations for different environments
+- Keep sensitive credentials out of your repository
+
+Note: Make sure your OpenSearch cluster is accessible and credentials are valid before starting OpenSearch Dashboards.
+
 ### Run OpenSearch Dashboards
 
 _**Warning:** Starting the OpenSearch Dashboards instance before the OpenSearch server is fully initialized can cause Dashboards to misbehave. Ensure that the OpenSearch server instance is up and running first. You can validate by running `curl localhost:9200` in another console tab or window (see [OpenSearch developer guide](https://github.com/opensearch-project/OpenSearch/blob/main/DEVELOPER_GUIDE.md#run-opensearch))._
diff --git a/changelogs/fragments/9080.yml b/changelogs/fragments/9080.yml
new file mode 100644
index 000000000000..5d05588145c0
--- /dev/null
+++ b/changelogs/fragments/9080.yml
@@ -0,0 +1,2 @@
+doc:
+- Update dev guide to connect to external cluster ([#9080](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/9080))
\ No newline at end of file