Documented settings backwards compatibility.

Signed-off-by: dblock <[email protected]>
opensearch-project · May 6, 2021 · f1b41a6 · f1b41a6
1 parent 35a765f
commit f1b41a6
Showing 1 changed file with 95 additions and 0 deletions.
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -5,6 +5,7 @@ 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)
 - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
    - [Building](#building)
    - [Naming Conventions](#naming-conventions)
@@ -36,6 +37,100 @@ The following naming convention has been adopted for Elasticsearch.
 
 See below for Kibana-related naming conventions.
 
+#### 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:
+
+   ```java
+   package com.amazon.opendistroforelasticsearch.jobscheduler;
+
+   import org.opensearch.common.settings.Setting;
+   import org.opensearch.common.unit.TimeValue;
+
+   public class LegacyOpenDistroJobSchedulerSettings {
+
+   }
+   ```
+
+2. Add `Setting.Property.Deprecated` to each existing setting to mark them deprecated. For example:
+
+   ```java
+   public class LegacyOpenDistroJobSchedulerSettings {
+
+      public static final Setting<TimeValue> REQUEST_TIMEOUT = Setting.positiveTimeSetting(
+               "opendistro.jobscheduler.request_timeout",
+               TimeValue.timeValueSeconds(10),
+               Setting.Property.NodeScope, Setting.Property.Dynamic, Setting.Property.Deprecated);
+
+   }
+   ```
+
+3. Include legacy settings in `Plugin#getSettings`. Example:
+
+   ```java
+   public class JobSchedulerPlugin extends Plugin implements ExtensiblePlugin {
+
+      @Override
+      public List<Setting<?>> getSettings() {
+         List<Setting<?>> settingList = new ArrayList<>();
+         settingList.add(LegacyOpenDistroJobSchedulerSettings.REQUEST_TIMEOUT);
+         settingList.add(JobSchedulerSettings.REQUEST_TIMEOUT);
+         return settingList;
+      }
+   }
+   ```
+
+   If you do not add your legacy settings here they will be archived upon the node joining the OpenSearch cluster.
+
+4. In the non-legacy class, rename settings and re-declare them to fallback on the legacy settings.
+
+   ```java
+   public class JobSchedulerSettings {
+
+       public static final Setting<TimeValue> REQUEST_TIMEOUT = Setting.positiveTimeSetting(
+            "opensearch.jobscheduler.request_timeout",
+            LegacyOpenDistroJobSchedulerSettings.REQUEST_TIMEOUT,
+            Setting.Property.NodeScope, Setting.Property.Dynamic);
+
+   }
+   ```
+
+   Note that this setting does not have a default value, but defaults to falling back to `LegacyOpenDistroJobSchedulerSettings.REQUEST_TIMEOUT`.
+
+5. Make sure you have implemented a listener to update the setting value. If a setting is set in `opensearch.yml`, you're all set. But if the setting is set via API, the node will start, settings will be read, defaults applied (fallback value will be used), and only afterwards fetched from the cluster and set on your node. Thus your setting will end up with the default value of the fallback.
+
+   To fix this, add a listener. For example:
+
+   ```java
+   clusterService.getClusterSettings().addSettingsUpdateConsumer(JobSchedulerSettings.REQUEST_TIMEOUT,
+      value -> {
+         this.requestTimeout = value;
+         log.debug("Setting request timeout: " + this.requestTimeout.getMinutes());
+      });
+   ```
+
+6. Write tests.
+
+   ```java
+    public void testSettingsGetValueWithLegacyFallback() {
+        Settings settings = Settings.builder()
+            .put("opendistro.jobscheduler.retry_count", 3)
+        .build();
+
+        assertEquals(JobSchedulerSettings.RETRY_COUNT.get(settings), Integer.valueOf(3)); 
+
+        assertSettingDeprecationsAndWarnings(new Setting[]{
+            LegacyOpenDistroJobSchedulerSettings.RETRY_COUNT
+        });
+    }   
+   ```
+
+7. Document your newly renamed settings.
+
+   TODO
+
+See [job-scheduler#20](https://github.com/opensearch-project/job-scheduler/pull/20) for an example.
+
 ### OpenSearch Dashboard Plugins
 
 #### Building