From 4e65045f3bc6b28547e7a7c9f710e7b5259eefd7 Mon Sep 17 00:00:00 2001
From: pollfly <75068813+pollfly@users.noreply.github.com>
Date: Sun, 7 Nov 2021 10:58:22 +0200
Subject: [PATCH] Add configuration hierarchy clarification (#103)

---
 docs/configs/clearml_conf.md        | 17 +++++++++++------
 docs/configs/configuring_clearml.md | 23 +++++++++++++++++++++++
 docs/configs/env_vars.md            |  3 ++-
 sidebars.js                         |  2 +-
 4 files changed, 37 insertions(+), 8 deletions(-)
 create mode 100644 docs/configs/configuring_clearml.md

diff --git a/docs/configs/clearml_conf.md b/docs/configs/clearml_conf.md
index cf3163d9..1a2f90d7 100644
--- a/docs/configs/clearml_conf.md
+++ b/docs/configs/clearml_conf.md
@@ -12,9 +12,14 @@ This reference page is organized by configuration file section:
 * [sdk](#sdk-section) - Contains **ClearML** and **ClearML Agent** configuration options for **ClearML Python Package** and **ClearML Server**.
 
 An example configuration file is located [here](https://github.com/allegroai/clearml-agent/blob/master/docs/clearml.conf), 
-in the **ClearML** GitHub repositories  
+in the **ClearML Agent** GitHub repository. 
 
-## Editing Your Configuration File
+:::info
+The values in the ClearML configuration file can be overridden by environment variables, the [configuration vault](../webapp/webapp_profile.md#configuration-vault), 
+and command-line arguments. 
+:::
+
+# Editing Your Configuration File
 
 To add, change, or delete options, edit your configuration file.
 
@@ -97,7 +102,7 @@ Supported from Docker 0.6.5
 * The following variables can be used:
   * `task_id`
   * `worker_id` 
-  * `rand_string` - random lower-case letters string, up to 32 characters)
+  * `rand_string` - random lower-case letters string (up to 32 characters)
 
 * The resulting name must start with an alphanumeric character, while the rest of the name may contain alphanumeric characters, 
   underscores (`_`), dots (`.`) and / or dashes (`-`)
@@ -218,7 +223,7 @@ Supported from Docker 0.6.5
   * The values are:
     
     * `true` - ignore any requested python version
-    * `false` - if a task was using a specific python version and the system supports multiple versions, the agent will 
+    * `false` - if a task was using a specific python version, and the system supports multiple versions, the agent will 
       use the requested python version (default)
 
 ___
@@ -1045,7 +1050,7 @@ will not exceed the value of `matplotlib_untitled_history_size`
 * Specify a list of direct access objects using glob patterns which matches sets of files using wildcards. Direct access 
   objects are not downloaded or cached, and any download request will return a direct reference.
 
-## Configuration vault
+## Configuration Vault
 
 :::note
 This feature is only supported by the **ClearML Enterprise Server**
@@ -1056,4 +1061,4 @@ the vault is enabled, the configurations will be merged into the ClearML and Cle
 
 These configurations override the configurations written in the configuration file. 
 
-See [configuration vault](../webapp/webapp_profile.md#configuration-vault). 
\ No newline at end of file
+See [configuration vault](../webapp/webapp_profile.md#configuration-vault). 
diff --git a/docs/configs/configuring_clearml.md b/docs/configs/configuring_clearml.md
new file mode 100644
index 00000000..235619f9
--- /dev/null
+++ b/docs/configs/configuring_clearml.md
@@ -0,0 +1,23 @@
+---
+title: Configuring ClearML
+---
+
+ClearML can be tailored to your requirements by setting configurations in a variety of methods. All ClearML and ClearML 
+Agent configurations can be set in the `clearml.conf` file, which serves as the baseline configuration of both packages. 
+For detailed information about the configurable options in ClearML and ClearML Agent, see the 
+[Configuration File](clearml_conf.md) reference page. 
+
+ClearML supports reading configuration values from environment variables. Configuration entries specified
+in this manner override values specified in the `clearml.conf` file. See [Environment Variables](env_vars.md) for parameter
+specification.
+
+Enterprise users can insert configuration snippets into the configuration vault. When enabled, configuration entries 
+from the vault are applied on top of the configuration specified in `clearml.conf`. New definitions will extend the
+`clearml.conf` configurations, and existing definitions will be overridden. For more information, see [Configuration vault](../webapp/webapp_profile.md#configuration-vault).
+
+The different ClearML configuration methods take precedence as summarized in the following list (higher ordered methods 
+override the lower ones):
+1. Command-line arguments
+1. Environment variables
+1. Configuration vault
+1. Configuration file
diff --git a/docs/configs/env_vars.md b/docs/configs/env_vars.md
index 093e8751..79019126 100644
--- a/docs/configs/env_vars.md
+++ b/docs/configs/env_vars.md
@@ -3,7 +3,8 @@ title: Environment Variables
 ---
 
 :::info
-ClearML's environment variables override the clearml.conf file and SDK
+ClearML's environment variables override the clearml.conf file, SDK, and [configuration vault](../webapp/webapp_profile.md#configuration-vault), 
+but can be overridden by command-line arguments. 
 :::
 
 ## ClearML SDK Variables
diff --git a/sidebars.js b/sidebars.js
index 7a1a01e3..131afdb9 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -33,7 +33,7 @@ module.exports = {
                     'webapp/webapp_archiving']
             },
             'webapp/webapp_profile', 'webapp/webapp_workers_queues']},
-        {'Configurations': ['configs/clearml_conf', 'configs/env_vars']},
+        {'Configurations': ['configs/configuring_clearml', 'configs/clearml_conf', 'configs/env_vars']},
         //'References': ['references/clearml_ref','references/clearml_agent_ref'],
         {'ClearML Server': ['deploying_clearml/clearml_server',
             {