diff --git a/docs/source/actions.rst b/docs/source/actions.rst index 63e0d145..5c63cbfc 100644 --- a/docs/source/actions.rst +++ b/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 `_ action in the examples pack for how to use this. @@ -328,18 +328,21 @@ 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 @@ -347,13 +350,41 @@ could lead to unpredictable results. In future this information will be used for 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 diff --git a/docs/source/reference/secrets_masking.rst b/docs/source/reference/secrets_masking.rst index 7ec72b92..11b9de38 100644 --- a/docs/source/reference/secrets_masking.rst +++ b/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 diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst index 0c41e40b..171b5125 100644 --- a/docs/source/upgrade_notes.rst +++ b/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 ``. + .. _ref-upgrade-notes-v3-7: |st2| v3.7