docs: Scoped Variables Draft + Other Fixes (Ephemeral Doc Alignment)

docs/SUMMARY.md

@@ -32,6 +32,7 @@
     * [API Tokens](user-guide/global-configurations/authorization/api-tokens.md)
   * [Manage Notification](user-guide/global-configurations/manage-notification.md)
   * [External links](user-guide/global-configurations/external-links.md)
+  * [Scoped Variables](user-guide/global-configurations/scoped-variables.md)
   * [Tags Policy](user-guide/global-configurations/tags-policy.md)
 * [Devtron Upgrade](setup/upgrade/README.md)
   * [Update Devtron from Devtron UI](setup/upgrade/upgrade-devtron-ui.md)

docs/user-guide/app-details/ephemeral-containers.md

@@ -1,4 +1,4 @@
-# Using Ephemeral Containers on Devtron
+# Using Ephemeral Containers in Devtron
 
 ## Introduction
 
@@ -33,22 +33,26 @@ Wherever you can access pod resources in Devtron, you can launch an ephemeral co
     ![Figure 2: Launching an Ephemeral Container](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/launch-ec-new.jpg)
 
 7. You get 2 tabs:
-    * **Basic** - It provides the bare minimum configurations required to launch an ephemeral container.
+    1. **Basic** - It provides the bare minimum configurations required to launch an ephemeral container.
 
     ![Figure 3: Basic View](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/basic.jpg)
 
     It contains 3 mandatory fields:
-        * **Container name prefix** - Type a prefix to give to your ephemeral container, for e.g., *debug*. Your container name would look like `debug-jndvs`.
-        * **Image** - Choose an image to run from the dropdown. Ephemeral containers need an image to run and provide the capability to debug, such as `curl`. You can use a custom image too.
-        * **Target Container name** - Since a pod can have one or more containers, choose a target container you wish to debug, from the dropdown.
 
-    * **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options.
+    * **Container name prefix** - Type a prefix to give to your ephemeral container, for e.g., *debug*. Your container name would look like `debug-jndvs`.
+
+    * **Image** - Choose an image to run from the dropdown. Ephemeral containers need an image to run and provide the capability to debug, such as `curl`. You can use a custom image too.
+
+    * **Target Container name** - Since a pod can have one or more containers, choose a target container you wish to debug, from the dropdown.
+
+    2. **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options.
 
     ![Figure 4: Advanced View](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/debugging-deployment-and-monitoring/advanced.jpg)
 
     {% hint style="info" %}
     Devtron ignores the `command` field while launching an ephemeral container
     {% endhint %}
+
 8. Click **Launch Container**.
 
 ### From Devtron (Resource Browser)

docs/user-guide/global-configurations/scoped-variables.md

@@ -0,0 +1,168 @@
+# Using Scoped Variables in Devtron
+
+## Introduction
+
+In any piece of software or code, variables are used for holding data such as numbers or strings. Variables are created by declaring them, which involves specifying the variable's name and type, followed by assigning it a value.
+
+Devtron offers super-admins the capability to define scoped variables (key-value pairs). It means, while the key remains the same, its value can change depending on the following context: 
+
+* **Global**: Variable values will be universally same for everybody in Devtron.
+* **Cluster**: Variable values might differ for each Kubernetes cluster.
+* **Environment**: Variable values might differ for each environment within a cluster, e.g., staging, dev, prod.
+* **Application**: Variable values might differ for each application.
+* **Environment + Application**: Variable values might differ for each application on a specific environment.
+
+**Advantages of using scoped variables**
+
+* **Reduces repeatability**: Configuration management team can centrally maintain the static data.
+* **Simplifies bulk edits**: All the places that use a variable get updated when you change the value of the variable.
+* **Keeps data secure**: You can decide the exposure of a variable's value to prevent misuse or leakage of sensitive data.
+
+---
+
+## How to Define a Scoped Variable
+
+On Devtron, a super-admin can download a YAML template. It will contain a schema for defining the variables.
+
+### Download the Template
+
+1. From the left sidebar, go to **Global Configurations** → **Scoped Variables**
+
+2. Click **Download template**. 
+
+    ![Figure 1: Downloading the Template](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/template-downloader.jpg)
+
+3. Open the downloaded template using any code editor (say VS Code). 
+
+### Enter the Values
+
+The YAML file contains key-value pairs that follow the below schema:
+
+| Field                    | Type    | Description                                                                     |
+| ------------------------ | ------- | ------------------------------------------------------------------------------- |
+| `apiVersion`             | string  | The API version of the resource (comes pre-filled)                              |
+| `kind`                   | string  | The kind of resource (i.e. Variable, comes pre-filled)                          |
+| `spec`                   | object  | The complete specification object containing all the variables                  |
+| `spec.name`              | string  | Unique name of the variable, e.g. *DB_URL*                                      |
+| `spec.shortDescription`  | string  | A short description of the variable (up to 120 characters)                      |
+| `spec.notes`             | string  | Additional details about the variable (will not be shown on UI)                 |
+| `spec.isSensitive`       | boolean | Whether the variable value is confidential (will not be shown on UI if true)    |
+| `spec.values`            | array   | The complete values object containing all the variable values as per context    |
+
+The `spec.values` array further contains the following elements:
+
+| Field                    | Type    | Description                                                                                          |
+| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
+| `category`                                      | string | The context, e.g., Global, Cluster, Application, Env, ApplicationEnv           |
+| `value`                                         | string | The value of the variable                                                      |
+| `selectors`                                     | object | A set of selectors that restrict the scope of the variable                     |
+| `selectors.attributeSelectors`                  | object | A map of attribute selectors to values                                         |
+| `selectors.attributeSelectors.<selector_key>`   | string | The key of the attribute selector, e.g., *ApplicationName*, *EnvName*, *ClusterName* |
+| `selectors.attributeSelectors.<selector_value>` | string | The value of the attribute selector                                            |
+
+
+Here's a truncated template containing the specification of two variables for your understanding:
+
+    apiVersion: devtron.ai/v1beta1
+    kind: Variable
+    spec:
+
+    # First example of a variable
+    - name: DB_URL 
+    shortDescription: My application's customers are stored
+    notes: The DB is a MySQL DB running version 7.0. The DB contains confidential information.
+    isSensitive: true 
+    values: 
+        - category: Global 
+        value: mysql.example.com 
+
+    # Second example of a variable
+    - name: DB_Name
+    shortDescription: My database name to recognize the DB
+    notes: NA
+    isSensitive: false 
+    values: 
+        - category: Global 
+        value: Devtron 
+        - category: ApplicationEnv 
+        value: app1-p
+        selectors:
+            attributeSelectors:
+            ApplicationName: MyFirstApplication
+            EnvName: prod
+
+### Upload the Template
+
+1. Once you save the YAML file, go back to the screen where you downloaded the template.
+
+2. Use the file uploader utility to upload your YAML file.
+
+    ![Figure 2: Uploading the Template](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/file-uploader.jpg)
+
+3. The content of the file will be uploaded for you to review and edit. Click **Review Changes**.
+
+    ![Figure 3: Reviewing the YAML file](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/file-preview.jpg)
+
+4. You may check the changes between the last saved file and the current one before clicking **Save**.
+
+    ![Figure 4: Saving the file](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/save.jpg)
+
+5. Click the **Variable List** tab to view the variables. Check the [How to Use a Scoped Variable](#how-to-use-a-scoped-variable) section to know more.
+
+    ![Figure 5: List of Variables](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/variable-list.jpg)
+
+---
+
+## How to Edit an Exiting Scoped Variable
+
+Only a super-admin can edit existing scoped variables.
+
+**Option 1**: Directly edit using the UI
+
+![Figure 6: Editing from UI](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/edit.jpg)
+
+**Option 2**: Reupload the updated YAML file
+
+![Figure 7: Reuploading New File](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/reupload.jpg)
+
+---
+
+## How to Use a Scoped Variable
+
+Once a variable is defined, it can be used by your authorized users on Devtron. A scoped variable widget would appear only on the screens that support its usage. 
+
+Currently, the widget is shown only on `Edit build pipeline` and `Edit deployment pipeline` screens under **App Configuration** → **Workflow Editor**.
+
+![Figure 8: Unexpanded Widget](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/widget1.jpg)
+
+Upon clicking on the widget, a list of variables will be visible. 
+
+![Figure 9: Expanded Widget](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/widget-expanded.jpg)
+
+Use the copy button to copy a relevant variable of your choice.
+
+![Figure 10: Copying a Variable](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/display-value.jpg)
+
+It would appear in the following format upon pasting it within an input field: `@{{variable-name}}`
+
+![Figure 11: Pasting a Variable](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/scoped-variables/paste-value.jpg)
+
+
+{% hint style="info" %}
+### Order of Precedence
+
+When multiple values are associated with a scoped variable, the precedence order is as follows, with the highest priority at the top:
+
+1. Environment + App
+2. App
+3. Environment
+4. Cluster
+5. Global
+
+{% endhint %}
+
+
+
+
+
+