DXCDT-387: Keyword preservation documentation (#759)

* Updating keyword replacement section * Updating configuration markdown file * Cleaning up --------- Co-authored-by: Will Vedder <[email protected]> Co-authored-by: Sergiu Ghitea <[email protected]>
auth0 · Mar 3, 2023 · 84b04aa · 84b04aa
1 parent 025193b
commit 84b04aa
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 2 deletions.
diff --git a/docs/configuring-the-deploy-cli.md b/docs/configuring-the-deploy-cli.md
@@ -111,6 +111,14 @@ Mapping of specific keywords to facilities dynamic replacement. See also: [keywo
 }
 ```
 
+### `AUTH0_PRESERVE_KEYWORDS`
+
+Boolean. When enabled, will attempt to preserve keyword replacement markers in local resource files during export. Otherwise, the remote values will overwrite those manually-placed keyword markers.
+
+This configuration requires the presence of local configuration files and defined keyword replace mappings via the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property.
+
+See also: [Preserving Keywords on Export](keyword-replacement.md#preserving-keywords-on-export).
+
 ### `AUTH0_EXPORT_IDENTIFIERS`
 
 Boolean. When enabled, will return identifiers of all resources. May be useful for certain debugging or record-keeping scenarios within a single-tenant context. Default: `false`.

diff --git a/docs/keyword-replacement.md b/docs/keyword-replacement.md
@@ -58,9 +58,16 @@ clients:
     web_origins: [ "http://production-app.com", "https://production-app.com", ##GLOBAL_WEB_ORIGINS## ]
 ```
 
-## Uni-directional Limitation
+## Preserving Keywords on Export
 
-Currently, the Deploy CLI only preserves keywords during import. Once added, keywords are overwritten with subsequent exports. For this reason, it is recommended that if a workflow heavily depends on keyword replacement, to only perform imports in perpetuity. This limitation is noted in [this Github issue](https://github.com/auth0/auth0-deploy-cli/issues/328).
+Generally, the Deploy CLI works best when operating in a uni-directional workflow from your lower-level environments (ex: dev, test) up to your production environments. However, there will be times when it is necessary to export configuration from a higher-level environment onto your local configuration directory. By default, the remote values will overwrite your local values, **causing the deletion of your keyword markers**. However, keyword replacement preservation can be enabled through the `AUTH0_PRESERVE_KEYWORDS` boolean configuration property. By enabling this configuration, the Deploy CLI will attempt to preserve the keyword markers defined in your local configuration files during export.
+
+The keyword preservation functionality will attempt to preserve as many keywords while also maintaining the accuracy of your resource configuration files. And it the majority of cases, it will work without any intervention by the user. However, some key limitations exist:
+
+- In the case of a keyword-replaced configuration field with differing values between local and remote, the local configuration value will _always_ be favored. This will
+- Arrays without a specific identifiers are not eligible for preservation. Ex: `[ "http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##" ]`. This is because the ordering of these values are non-deterministic. Alternatively, to preserve these values, it is recommended to leverage the `@@ARRAY_REPLACE@@` keyword replace syntax with the entire value.
+
+To learn more about the history and technical challenges of of keyword preservation, refer to [RFC: Keyword Preservation During Export](https://github.com/auth0/auth0-deploy-cli/issues/688).
 
 ---