diff --git a/INSTALLING.md b/INSTALLING.md index 7b4f2b7..79ce3c3 100644 --- a/INSTALLING.md +++ b/INSTALLING.md @@ -20,7 +20,7 @@ _Example_: For Linux platform. Checkout, build and install the plugin. -_Example_: Install Anomaly Detection(Job Scheduler plugin which is a dependency). +_Example_: Install Anomaly Detection and Job Scheduler plugins. ``` ~/OpenSearch (main)> git clone https://github.com/opensearch-project/job-scheduler.git diff --git a/UPGRADING.md b/UPGRADING.md index b138c0e..3292b71 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -5,7 +5,9 @@ These are all the steps to upgrade plugins to work with OpenSearch and OpenSearc - [OpenSearch Plugins](#opensearch-plugins) - [Building](#building) - [Naming Conventions](#naming-conventions) - - [Settings Backwards Compatibility](#settings-backwards-compatibility) + - [Backwards Compatibility support](#backwards-compatibility-support) + - [Settings Backwards Compatibility](#settings-backwards-compatibility) + - [RestAPIs Backwards Compatibility](#rest-apis-backward-compatibility) - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins) - [Building](#building) - [Naming Conventions](#naming-conventions) @@ -16,7 +18,7 @@ These are all the steps to upgrade plugins to work with OpenSearch and OpenSearc 1. Consume artifacts from your dependencies, including OpenSearch, see [BUILDING](BUILDING.md). 2. Change the namespaces from `org.elasticsearch` to `org.opensearch`. Use the naming convention below. -3. Consume dependencies with OpenSearch/Dashboards 1.0.0. Continue using `org.elasticsearch` dependencies for `securemock`, `mocksocket` and `jna-build`. +3. Consume dependencies with OpenSearch/Dashboards 1.0.0-beta1. Continue using `org.elasticsearch` dependencies for `securemock`, `mocksocket` and `jna-build`. 4. Ensure CI works end-to-end, build and test your plugin. 5. Report all runtime failures of OpenSearch to [OpenSearch Issues](http://github.com/opensearch-project/opensearch/issues) and runtime failures of plugins in plugin repositories. @@ -37,7 +39,21 @@ The following naming convention has been adopted for Elasticsearch. See below for Kibana-related naming conventions. -#### Settings Backwards Compatibility +#### Backwards Compatibility support + +There are a bunch of items to think about and support backwards compatibility. + +* Renaming, and Backwards Compatibility for Settings +* Renaming, and Backwards Compatibility for Rest APIs +* Renaming Namespaces (e.g. `com.amazon.opendistroforelasticsearch` to `org.opensearch`) - TODO +* Renaming Classes, Methods, Variables - TODO +* Renaming Remaining Identifiers (e.g. `Opendistro` to `OpenSearch`) - TODO +* Renaming, and Backwards Compatibility for Indices - TODO +* Run in a backwards compatible way on top of OpenSearch 1.0 that has joined an ES 7.10.x cluster - TODO +* Run in a backwards compatible way on top of OpenSearch 1.0 that has joined an ODFE 1.13.x cluster - TODO +* Drop in replacement for the Opendistro version 1.13 of the plugin - TODO + +##### Settings Backwards Compatibility 1. Assuming your settings live in a single class, make a copy of that class and prepend `LegacyOpenDistro` to the copy. Do not rename the settings here in the legacy class. For example: @@ -61,7 +77,6 @@ See below for Kibana-related naming conventions. "opendistro.jobscheduler.request_timeout", TimeValue.timeValueSeconds(10), Setting.Property.NodeScope, Setting.Property.Dynamic, Setting.Property.Deprecated); - } ``` @@ -91,7 +106,6 @@ See below for Kibana-related naming conventions. "opensearch.jobscheduler.request_timeout", LegacyOpenDistroJobSchedulerSettings.REQUEST_TIMEOUT, Setting.Property.NodeScope, Setting.Property.Dynamic); - } ``` @@ -129,6 +143,81 @@ See below for Kibana-related naming conventions. See [job-scheduler#20](https://github.com/opensearch-project/job-scheduler/pull/20) for an example. +#### Rest APIs Backward Compatibility + +All APIs which have to be migrated can follow this design. +From here on the doc will be focussed on an ODFE plugin as an example. + +1. All plugins extend `BaseRestHandler` class to implement their own RestAPIs. +2. All the existing APIs with `_opendistro` should be supported but for maintenance mode only. +3. All new APIs will be implemented with `_plugins` as defined in the [Naming Conventions](./CONVENTIONS.md). +4. The method `replacedRoutes()` is overriden and this should now have both `_opendistro` and `_plugins` APIs. + ```java + public static final String LEGACY_AD_BASE = "/_opendistro/_anomaly_detection"; + public static final String LEGACY_OPENDISTRO_AD_BASE_URI = LEGACY_AD_BASE + "/detectors"; + public static final String AD_BASE_URI = "/_plugins/_anomaly_detection"; + public static final String AD_BASE_DETECTORS_URI = AD_BASE_URI + "/detectors"; + + @Override + public List replacedRoutes() { + return ImmutableList + .of( + // delete anomaly detector document + new ReplacedRoute( + RestRequest.Method.DELETE, + String.format(Locale.ROOT, "%s/{%s}", AnomalyDetectorPlugin.AD_BASE_DETECTORS_URI, DETECTOR_ID), + RestRequest.Method.DELETE, + String.format(Locale.ROOT, "%s/{%s}", AnomalyDetectorPlugin.LEGACY_OPENDISTRO_AD_BASE_URI, DETECTOR_ID) + ) + ); + } + ``` +5. Add new tests to cover both old and new APIs. + ```java + public void testBackwardCompatibilityWithOpenDistro() throws IOException { + // Create a detector + AnomalyDetector detector = TestHelpers.randomAnomalyDetector(TestHelpers.randomUiMetadata(), null); + String indexName = detector.getIndices().get(0); + TestHelpers.createIndex(client(), indexName, toHttpEntity("{\"name\": \"test\"}")); + + // Verify the detector is created using legacy _opendistro API + Response response = TestHelpers + .makeRequest( + client(), + "POST", + TestHelpers.LEGACY_OPENDISTRO_AD_BASE_DETECTORS_URI, + ImmutableMap.of(), + toHttpEntity(detector), + null + ); + assertEquals("Create anomaly detector failed", RestStatus.CREATED, restStatus(response)); + Map responseMap = entityAsMap(response); + String id = (String) responseMap.get("_id"); + int version = (int) responseMap.get("_version"); + assertNotEquals("response is missing Id", AnomalyDetector.NO_ID, id); + assertTrue("incorrect version", version > 0); + + // Get the detector using new _plugins API + AnomalyDetector createdDetector = getAnomalyDetector(id, client()); + assertEquals("Get anomaly detector failed", createdDetector.getDetectorId(), id); + + // Delete the detector using legacy _opendistro API + response = TestHelpers + .makeRequest( + client(), + "DELETE", + TestHelpers.LEGACY_OPENDISTRO_AD_BASE_DETECTORS_URI + "/" + createdDetector.getDetectorId(), + ImmutableMap.of(), + "", + null + ); + assertEquals("Delete anomaly detector failed", RestStatus.OK, restStatus(response)); + } + ``` +6. Add documentation for the new APIs. For example, [documentation-website](https://github.com/opensearch-project/documentation-website/blob/main/docs/ad/api.md) + +See [anomaly-detection#35](https://github.com/opensearch-project/anomaly-detection/pull/35) for an example. + ### OpenSearch Dashboard Plugins #### Building @@ -154,4 +243,4 @@ See [job-scheduler#20](https://github.com/opensearch-project/job-scheduler/pull/ | `Kib` | `Osd` | | `KIB` | `OSD` | -See [anomaly-detection-dashboards-plugin#1](https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/pull/1) for an example. \ No newline at end of file +See [anomaly-detection-dashboards-plugin#1](https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/pull/1) for an example.