From aae7cbc3a18a76e44ddc65da47814ec9b625aca3 Mon Sep 17 00:00:00 2001 From: Kristen Tian Date: Wed, 28 Sep 2022 12:16:33 -0700 Subject: [PATCH] Add dataSource & dataSourceManagement ReadMe 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 b7e933afff88..88718ca45b5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,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)) +* 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..8a4cd38d261b 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 [here](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/data_source/config.ts) for supported configurations. + +1. The dataSource plugin is by default disabled, to enable it: +`data_source.enabled: true` + +2. The audit trail is by default enabled 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 encryption related config are default to: +``` +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 config value changed (wrappingKeyName/wrappingKeyNamespace/wrappingKey), all current encrypted credientails cannot be decrypted; Therefore, credentials of previously created data sources must be updated to continue use. + +**What is the best practice for generate 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 been used to control the enablement/disablement of the multidata source related feature in other plugin's public side. 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 data source client as such: +```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 issue regarding the solution selection: [#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..2b78b2e702c6 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 creation, update, list actions for data sources. + +## Creation +Required inputs: + +- Title: title of the data source, no duplicted titles are allowed. +- Endpoint URL: the connection endpoint of the data source. +- Authentication: authentication information for the data source, currently two types of authentication are supported: + - No auth: no authentication information needed. + - Basic auth: username & password. + +## Update +Endpoint URL is immutable. If need to modify endpoint, create a new data source connection to work around. ---