From dd1cbe009e445220a994358eae9f6c5b3c28d820 Mon Sep 17 00:00:00 2001
From: James Sedgwick <jsedgwick@lyft.com>
Date: Tue, 3 Apr 2018 09:14:11 -0700
Subject: [PATCH] docs: /runtime_modify admin endpoint docs (#557)

Signed-off-by: James Sedgwick <jsedgwick@lyft.com>
---
 docs/root/configuration/runtime.rst | 14 ++++++--
 docs/root/intro/version_history.rst |  1 +
 docs/root/operations/admin.rst      | 52 ++++++++++++++++++++++++++---
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/docs/root/configuration/runtime.rst b/docs/root/configuration/runtime.rst
index 1d1458c4..a13bff7a 100644
--- a/docs/root/configuration/runtime.rst
+++ b/docs/root/configuration/runtime.rst
@@ -4,8 +4,18 @@ Runtime
 =======
 
 The :ref:`runtime configuration <arch_overview_runtime>` specifies the location of the local file
-system tree that contains re-loadable configuration elements. If runtime is not configured, a "null"
-provider is used which has the effect of using all defaults built into the code.
+system tree that contains re-loadable configuration elements. Values can be viewed at the
+:ref:`/runtime admin endpoint <operations_admin_interface_runtime>`. Values can be modified and
+added at the :ref:`/runtime_modify admin endpoint <operations_admin_interface_runtime_modify>`. If
+runtime is not configured, an empty provider is used which has the effect of using all defaults
+built into the code, except for any values added via `/runtime_modify`.
+
+.. attention::
+
+  Use the :ref:`/runtime_modify<operations_admin_interface_runtime_modify>` endpoint with care.
+  Changes are effectively immediately. It is **critical** that the admin interface is :ref:`properly
+  secured <operations_admin_interface_security>`.
+
 
 * :ref:`v1 API reference <config_runtime_v1>`
 * :ref:`v2 API reference <envoy_api_msg_config.bootstrap.v2.Runtime>`
diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst
index f772c6d6..28940eee 100644
--- a/docs/root/intro/version_history.rst
+++ b/docs/root/intro/version_history.rst
@@ -9,6 +9,7 @@ Version history
   scheduler now respects endpoint weights and also has improved fidelity across
   picks.
 * admin: added :ref:`/config_dump endpoint <operations_admin_interface_config_dump>` for dumping current configs
+* admin: added :ref:`/runtime_modify endpoint <operations_admin_interface_runtime_modify>` to add or change runtime values
 * admin: removed `/routes` endpoint; route configs can now be found at the :ref:`/config_dump endpoint <operations_admin_interface_config_dump>`.
 * access log: ability to format START_TIME
 * admin: added ``/stats/prometheus`` as an alternative endpoint for getting stats in prometheus format.
diff --git a/docs/root/operations/admin.rst b/docs/root/operations/admin.rst
index 1e75d4ec..b0a2ef3b 100644
--- a/docs/root/operations/admin.rst
+++ b/docs/root/operations/admin.rst
@@ -9,6 +9,8 @@ modify different aspects of the server:
 * :ref:`v1 API reference <config_admin_v1>`
 * :ref:`v2 API reference <envoy_api_msg_config.bootstrap.v2.Admin>`
 
+.. _operations_admin_interface_security:
+
 .. attention::
 
   The administration interface in its current form both allows destructive operations to be
@@ -197,10 +199,50 @@ The fields are:
 
 .. http:get:: /runtime
 
-  Outputs all runtime values on demand in a human-readable format. See
-  :ref:`here <arch_overview_runtime>` for more information on how these values are configured
-  and utilized.
+  Outputs all runtime values on demand in JSON format. See :ref:`here <arch_overview_runtime>` for
+  more information on how these values are configured and utilized. The output include the list of
+  the active runtime override layers and the stack of layer values for each key. Empty strings
+  indicate no value, and the final active value from the stack also is included in a separate key.
+  Example output:
+
+.. code-block:: json
+
+  {
+    "layers": [
+      "disk",
+      "override",
+      "admin",
+    ],
+    "entries": {
+      "my_key": {
+        "layer_values": [
+          "my_disk_value",
+          "",
+          ""
+        ],
+        "final_value": "my_disk_value"
+      },
+      "my_second_key": {
+        "layer_values": [
+          "my_second_disk_value",
+          "my_disk_override_value",
+          "my_admin_override_value"
+        ],
+        "final_value": "my_admin_override_value"
+      }
+    }
+  }
+
+.. _operations_admin_interface_runtime_modify:
+
+.. http:post:: /runtime_modify?key1=value1&key2=value2&keyN=valueN
+
+  Adds or modifies runtime values as passed in query parameters. To delete a previously added key,
+  use an empty string as the value. Note that deletion only applies to overrides added via this
+  endpoint; values loaded from disk can be modified via override but not deleted.
 
-  .. http:get:: /runtime?format=json
+.. attention::
 
-  Outputs /runtime in JSON format. This can be used for programmatic access of runtime values.
+  Use the /runtime_modify endpoint with care. Changes are effectively immediately. It is
+  **critical** that the admin interface is :ref:`properly secured
+  <operations_admin_interface_security>`.