Add documentation for templating variables

As part of the MVC to implement templating variables in custom
dashboards, add docs to describe the syntax for adding variables to
dashboard YAML.

doc/user/project/integrations/prometheus.md

@@ -180,6 +180,8 @@ Multiple metrics can be displayed on the same chart if the fields **Name**, **Ty
 
 #### Query Variables
 
+##### Predefined variables
+
 GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are:
 
 - `ci_environment_slug`
@@ -192,6 +194,12 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md)
 NOTE: **Note:**
 Variables for Prometheus queries must be lowercase.
 
+##### User defined variables
+
+[Variables can be defined](#templating-templating-properties) in a custom dashboard YAML file.
+
+##### Using variables
+
 Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7).
 
 Support for the `"%{ci_environment_slug}"` format was
@@ -303,19 +311,29 @@ If you select another branch, this branch should be merged to your **default** b
 
 Dashboards have several components:
 
+- Templating variables.
 - Panel groups, which consist of panels.
 - Panels, which support one or more metrics.
 
 The following tables outline the details of expected properties.
 
-**Dashboard properties:**
+##### **Dashboard (top-level) properties**
 
 | Property | Type | Required | Description |
 | ------ | ------ | ------ | ------ |
 | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. |
 | `panel_groups` | array | yes | The panel groups which should be on the dashboard. |
+| `templating` | Hash | no | Top level key under which templating related options can be added. |
+
+##### **Templating (`templating`) properties**
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `variables` | Hash | no | Variables can be defined here. |
+
+Read the documentation on [templating](../monitoring_dashboards/templating.md).
 
-**Panel group (`panel_groups`) properties:**
+##### **Panel group (`panel_groups`) properties**
 
 | Property | Type | Required | Description |
 | ------ | ------ | ------ | ------ |
@@ -323,7 +341,7 @@ The following tables outline the details of expected properties.
 | `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
 | `panels` | array | required | The panels which should be in the panel group. |
 
-**Panel (`panels`) properties:**
+##### **Panel (`panels`) properties**
 
 | Property | Type | Required | Description |
 | ------ | ------ | ------ | ------- |
@@ -335,7 +353,7 @@ The following tables outline the details of expected properties.
 | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
 | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. |
 
-**Axis (`panels[].y_axis`) properties:**
+##### **Axis (`panels[].y_axis`) properties**
 
 | Property    | Type   | Required                      | Description                                                          |
 | ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- |
@@ -343,7 +361,7 @@ The following tables outline the details of expected properties.
 | `format`    | string | no, defaults to `engineering` | Unit format used. See the [full list of units](prometheus_units.md). |
 | `precision` | number | no, defaults to `2`           | Number of decimal places to display in the number.                                          |                        |
 
-**Metrics (`metrics`) properties:**
+##### **Metrics (`metrics`) properties**
 
 | Property | Type | Required | Description |
 | ------ | ------ | ------ | ------ |

doc/user/project/monitoring_dashboards/templating.md

+---
+stage: Monitor
+group: APM
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Templating
+
+Templating variables can be used to make your dashboard more versatile.
+
+## Templating variable types
+
+`templating` is a top-level key in the [dashboard YAML](../integrations/prometheus.md#dashboard-top-level-properties).
+
+The `variables` key under `templating` is where all your variables should be defined.
+
+The value of the `variables` key should be a hash. Each key under `variables`
+defines a templating variable on the dashboard.
+
+A variable can be used in a Prometheus query in the same dashboard using the syntax
+described [here](../integrations/prometheus.md#using-variables).
+
+### `text` variable type
+
+CAUTION: **Warning:**
+This is an _alpha_ feature, and is subject to change at any time without
+prior notice!
+
+For each `text` variable defined in the dashboard YAML, there will be a free text
+box on the dashboard UI, allowing the user to enter a value for each variable.
+
+The `text` variable type supports a simple and a full syntax.
+
+#### Simple syntax
+
+```yaml
+templating:
+  variables:
+    variable1: 'default value'     # `text` type variable with `default value` as its default.
+```
+
+This creates a variable called `variable1`, with a default value of `default value`.
+
+#### Full syntax
+
+```yaml
+templating:
+  variables:
+    variable1:                       # The variable name that can be used in queries.
+      label: 'Variable 1'            # (Optional) label that will appear in the UI for this text box.
+      type: text
+      options:
+        default_value: 'default'     # (Optional) default value.
+```
+
+This creates a variable called `variable1`, with a default value of `default`.
+The label for the text box on the UI will be the value of the `label` key.
+
+### `custom` variable type
+
+CAUTION: **Warning:**
+This is an _alpha_ feature, and is subject to change at any time without
+prior notice!
+
+For each `custom` variable defined in the dashboard YAML, there will be a dropdown
+selector on the dashboard UI, allowing the user to select a value for each variable.
+
+The `custom` variable type supports a simple and a full syntax.
+
+#### Simple syntax
+
+```yaml
+templating:
+  variables:
+    variable1: ['value1', 'value2', 'value3']
+```
+
+This creates a variable called `variable1`, with a default value of `value1`.
+The dashboard UI will have a dropdown where `value1`, `value2` and `value3` will
+be the choices.
+
+#### Full syntax
+
+```yaml
+templating:
+  variables:
+    variable1:                           # The variable name that can be used in queries.
+      label: 'Variable 1'                # (Optional) label that will appear in the UI for this dropdown.
+      type: custom
+      options:
+        values:
+        - value: 'value option 1'        # The value that will replace the variable in queries.
+          text: 'Option 1'               # (Optional) Text that will appear in the UI dropdown.
+        - value: 'value_option_2'
+          text: 'Option 2'
+          default: true                  # (Optional) This option should be the default value of this variable.
+```
+
+This creates a variable called `variable1`, with a default value of `var1_option_2`.
+The label for the text box on the UI will be the value of the `label` key.
+The dashboard UI will have a dropdown where `Option 1` and `Option 2`
+will be the choices.
+
+If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`.
+Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`.