document output_schema and output_schema masking per StackStorm/st2#5319

docs/source/actions.rst

@@ -305,7 +305,7 @@ In the example above, the ``to_number`` parameter contains the attribute ``secre
 
   Does your parameter only accept certain values? Use ``enum:`` with a list of allowed values. When the
   action is executed, it will only allow those specific values. And the in Web UI, it will be rendered
-  as a drop-down list. 
+  as a drop-down list.
 
   See the `examples.weather </~https://github.com/StackStorm/st2/blob/master/contrib/examples/actions/weather.yaml#L16>`_
   action in the examples pack for how to use this.
@@ -328,32 +328,63 @@ You can define the schema as follows:
     ---
     ...
     output_schema:
+      type: object
+      properties:
         errors:
-           type: array
-           items:
-               type: string
-       output:
-           required: true
-           type: array
-           items:
-               type: number
-       status_code:
-           required: true
-           type: integer
+          type: array
+          items:
+            type: string
+        output:
+          required: true
+          type: array
+          items:
+            type: number
+        status_code:
+          required: true
+          type: integer
+      additionalProperties: false
 
 If the action output does not return the correct fields it will fail validation and the action
 itself will fail. This prevents propagating corrupt data to other actions in a workflow, which
 could lead to unpredictable results. In future this information will be used for pre-run workflow
 validation.
 
 Output schema validation is disabled by default in current versions of |st2|. To enable it, set
-``validate_output_schema = True`` under ``[system]`` in ``/etc/st2/st2.conf``. 
+``validate_output_schema = True`` under ``[system]`` in ``/etc/st2/st2.conf``.
 
 If an action does not define any output schema, no enforcement is done. This allows you to
 progressively update your actions, rather than doing them all at once.
 
 As with all other input and output schema definitions in Stackstorm, we leverage
-JSONschema to define ``output_schema``.
+JSONschema (draft 4) to define ``output_schema``. We extend JSONSchema with a ``secret`` parameter
+so that the entire output, or a single field of the output, can be marked as secret.
+If any part of the output is marked as a secret, the value of that secret will be masked in the
+|st2| service logs.
+
+For example, you have a python action that returns a secret token as a string.
+You can define the schema as follows:
+
+.. code-block:: yaml
+
+    ---
+    ...
+    output_schema:
+      type: string
+      secret: true
+
+Or the python action could return the secret token as an object field:
+
+.. code-block:: yaml
+
+    ---
+    ...
+    output_schema:
+      type: object
+      properties:
+        super-awesome-token:
+          type: string
+          secret: true
+      additionalProperties: false
 
 
 Parameters in Actions

docs/source/reference/secrets_masking.rst

@@ -31,7 +31,8 @@ all the API responses which operate on the following system entities:
 in the action metadata file.
 
 Any action parameter that has the ``secret: true`` attribute will be treated as a secret for
-masking purposes.
+masking purposes. Action output, or part of it, will also be treated as a secret if it has
+``secret: true`` in its ``output_schema``.
 
 Masking can be disabled on a per-API request basis, by passing the ``?show_secrets=True`` query
 parameter to all of the supported API endpoints. This is only available to users with the admin

docs/source/upgrade_notes.rst

@@ -3,6 +3,53 @@
 Upgrade Notes
 =============
 
+.. _ref-upgrade-notes-v3-8:
+
+|st2| v3.8
+----------
+
+* For anyone that uses ``output_schema``, which is disabled by default:
+  If you have ``[system].validate_output_schema = True`` in st2.conf AND you have added
+  ``output_schema`` to any of your packs, then you must update your action metadata.
+
+  ``output_schema`` must be a full jsonschema now. If a schema is not well-formed, it will be ignored.
+  Now, ``output`` can be types other than object such as list, bool, int, etc.
+  This also means that all of an action's output can be masked as a secret.
+
+  To get the same behavior, you'll need to update your output schema.
+  For example, this schema (used prior to 3.8.0):
+
+  .. code-block:: yaml
+
+    output_schema:
+      property1:
+        type: bool
+      property2:
+        type: str
+        secret: true
+
+  should be updated to a full JSON Schema like this:
+
+  .. code-block:: yaml
+
+    output_schema:
+      type: object
+      properties:
+        property1:
+          type: bool
+        property2:
+          type: str
+          secret: true
+      additionalProperties: false
+
+  Invalid schemas are ignored, so we recommend coordinating your pack updates with the update
+  to StackStorm 3.8.0, especially if you rely on ``output_schema`` for secret masking
+  (via ``secret: true``). If you update packs to use the new ``output_schema`` before updating
+  to 3.8.0, then the schema will be ignored until the upgrade is complete. If you update to 3.8.0
+  before you update the packs, then the schemas will be ignored until the packs are updated.
+  You can also install pack updates during an upgrade, while StackStorm is not running, by using
+  the ``st2-pack-install`` utility: ``st2-pack-install <pack1> <pack2> <pack3>``.
+
 .. _ref-upgrade-notes-v3-7:
 
 |st2| v3.7