From fb39f7d4732faad33a23388aa707366db97d3527 Mon Sep 17 00:00:00 2001 From: Kristen Tian <105667444+kristenTian@users.noreply.github.com> Date: Mon, 3 Oct 2022 18:12:47 -0700 Subject: [PATCH] Add dataSource & dataSourceManagement ReadMe (#2448) Signed-off-by: Kristen Tian Signed-off-by: Kristen Tian --- CHANGELOG.md | 1 + src/plugins/data_source/README.md | 68 +++++++++++++++++++- src/plugins/data_source_management/README.md | 16 ++++- 3 files changed, 81 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74ed9a731e57..57181ef33f45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,6 +66,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) * README.md for saving index pattern relationship ([#2276](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2276)) * Remove extra typo from README. ([#2403](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2403)) * Add sample config for multi data source feature in yml template. ([#2428](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2428)) +* README.md for dataSource and dataSourceManagement Plugin ([#2448](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2448)) ### 🛠 Maintenance diff --git a/src/plugins/data_source/README.md b/src/plugins/data_source/README.md index 53a96aa2146b..cfda79a2908f 100755 --- a/src/plugins/data_source/README.md +++ b/src/plugins/data_source/README.md @@ -1,9 +1,73 @@ -# data_source +# DataSource Plugin An OpenSearch Dashboards plugin -This plugin introduces OpenSearch data source into OpenSearch Dashboards, and provides related functions to connect to OpenSearch data sources. +This plugin introduces support for multiple data sources into OpenSearch Dashboards and provides related functions to connect to OpenSearch data sources. +## Configuration +Update the following configuration in the `opensearch_dashboards.yml` file to apply changes. Refer to the schema [here](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/data_source/config.ts) for supported configurations. + +1. The dataSource plugin is disabled by default; to enable it: +`data_source.enabled: true` + +2. The audit trail is enabled by default for logging the access to data source; to disable it: +`data_source.audit.enabled: false` + + - Current auditor configuration: +``` +data_source.audit.appender.kind: 'file' +data_source.audit.appender.layout.kind: 'pattern' +data_source.audit.appender.path: '/tmp/opensearch-dashboards-data-source-audit.log' +``` + +3. The default encryption-related configuration parameters are: +``` +data_source.encryption.wrappingKeyName: 'changeme' +data_source.encryption.wrappingKeyNamespace: 'changeme' +data_source.encryption.wrappingKey: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] +``` +Note that if any of the encryption keyring configuration values change (wrappingKeyName/wrappingKeyNamespace/wrappingKey), none of the previously-encrypted credentials can be decrypted; therefore, credentials of previously created data sources must be updated to continue use. + +**What are the best practices for generating a secure wrapping key?** +WrappingKey is an array of 32 random numbers. Read [more](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) about best practices for generating a secure wrapping key. + +## Public +The public plugin is used to enable and disable the features related to multi data source available in other plugins. e.g. data_source_management, index_pattern_management + +- Add as a required dependency for whole plugin on/off switch +- Add as opitional dependency for partial flow changes control + +## Server +The provided data source client is integrated with default search strategy in data plugin. When data source id presented in IOpenSearchSearchRequest, data source client will be used. + +### Data Source Service +The data source service will provide a data source client given a data source id and optional client configurations. + +Currently supported client config is: +- `data_source.clientPool.size` + +Data source service uses LRU cache to cache the root client to improve client pool usage. +#### Example usage: +In the RequestHandler, get an instance of the client using: +```ts +client: OpenSearchClient = await context.dataSource.opensearch.getClient(dataSourceId); + +//Support for legacy client +apiCaller: LegacyAPICaller = context.dataSource.opensearch.legacy.getClient(dataSourceId).callAPI; +``` + +### Data Source Client Wrapper +The data source saved object client wrapper overrides the write related action for data source object in order to perform validation and encryption actions of the authentication information inside data source. + +### Cryptography Client +The research for choosing a suitable stack can be found in: [#1756](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/1756) +#### Example usage: +```ts +//Encrypt +const encryptedPassword = await this.cryptographyClient.encryptAndEncode(password); +//Decrypt +const decodedPassword = await this.cryptographyClient.decodeAndDecrypt(password); +``` --- ## Development diff --git a/src/plugins/data_source_management/README.md b/src/plugins/data_source_management/README.md index 6d8556a1f325..a792069823a3 100755 --- a/src/plugins/data_source_management/README.md +++ b/src/plugins/data_source_management/README.md @@ -1,6 +1,18 @@ -# dataSourceManagement +# DataSourceManagement Plugin -An OpenSearch Dashboards plugin +An OpenSearch Dashboards plugin for managing the creation, updating, and listing actions for data sources. + +## Creation +Required inputs: + +- Title: the title of the data source which is unique throughout the instance. +- Endpoint URL: the connection endpoint of the data source. +- Authentication: authentication information for the data source; must be one the two types of authentication currently supported: + - No Authentication: no authentication required, and + - Username & Password: authenticating using a username and password combination. + +## Update +Endpoint URL is immutable; if you need to change an endpoint URL, a new data source connection needs to be created. ---