Variable

Choose a scope

There are three different scopes in which you can define a variable, depending on how much you want it to be shared.

  • for common use cases, use higher scopes to reuse the same variable on multiple dashboards
  • for more specific needs, use lower scopes to restrict the variable availability to a specific set of (or even a single) dashboard(s).

Dashboard level

That’s the usual level to define a variable.

interface DashboardSpec {
  // ... existing dashboard spec ...
  variables: VariableSpec[];
}

Project level

In case you would like to share a variable across different dashboards in the same project, you will need to create a Variable.

kind: "Variable"
metadata:
  name: <string>
  project: <string>
spec: <Variable specification>

Global level

When we talk about scope and user permission in a REST API, the easiest way is to associate one permission per endpoint. If we want to provide a variable shared by all projects, then it makes sense to have a different object that is living outside a project.

That’s why we have another resource called GlobalVariable

kind: "GlobalVariable"
metadata:
  name: <string>
spec: <Variable specification>

Variable specification

We are supporting two different types of variables: TextVariable and ListVariable.

TextVariable

kind: "TextVariable"
spec: <Text Variable specification>

Text Variable specification

# It is a mandatory attribute when you are defining a variable directly in a dashboard.
# If you are creating a GlobalVariable or a Variable, you don't have to use this attribute as it is replaced by metadata.name.
# This is the unique name of the variable that can be used in another variable or in the different dashboard to use
[ name: <string> ]

[ display: <Display specification> ]
value: <string>
[ constant: <boolean> | default = false ]

Example

kind: "Variable"  # Alternatively, "GlobalVariable"
metadata:
  name: "text"
  project: "perses"
spec:
  kind: "TextVariable"
  spec:
    value: "my text"

Or in case you are defining the variable in a dashboard

variables:
  - kind: "TextVariable"
    spec:
      name: "text"
      value: "my text"

ListVariable

kind: "ListVariable"
spec: <List Variable specification>

List Variable specification

# It is a mandatory attribute when you are defining a variable directly in a dashboard.
# If you are creating a GlobalVariable or a Variable, you don't have to use this attribute as it is replaced by metadata.name.
# This is the unique name of the variable that can be used in another variable or in the different dashboard to use
[ name: <string> ]

[ display: <Display specification> ]

# It's a value from the list to be selected by default
# It can be a single value or a list.
[ defaultValue: <string> | <array of string> ]

# Whether to append the "All" value that allows selecting all available values at once.
[ allowAllValue: <boolean> | default = false ]

# Whether to allow multi-selection of values.
[ allMultiple: <boolean> | default = false ]

# It is a custom value that will be used if allowAllValue is true and if then `all` is selected
[ customAllValue: <string> ]

# CapturingRegexp is the regexp used to catch and filter the result of the query.
# If empty, then nothing is filtered. This is the equivalent of setting capturingRegexp with (.*)
[ capturingRegexp: <string> ]

# The method to apply when rendering the list of values
[ sort: <enum = "none" | "alphabetical-asc" | "alphabetical-desc" | "numerical-asc" | "numerical-desc" | "alphabetical-ci-asc" | "alphabetical-ci-desc"> | default = "none" ]

# The definition of the plugin variable
plugin: <Plugin specification>

Display specification

# The new name of the variable. If set, it will replace `metadata.name` in the variable title in the UI.
# Note that it cannot be used when you are querying the API. Only `metadata.name` can be used to reference the variable.
# This is just for display purpose.
[ name: <string> ]

# The description of the variable
[ description: <string> ]

# If true, the variable won't be displayed above the dashboard.
[ hidden: <boolean> | default = false ]

Plugin definition

# The type of the variable. For example, `PrometheusPromQLVariable`
kind: <string>

# The actual definition of the variable. It will depend on the type defined in the previous field `kind`
spec: <Plugin specification>

We are supporting only prometheus for the variables for the moment. Please take a look at the documentation to know the spec for the Prometheus variable.

API Definition

Variable

Get a list of Variable

GET /api/v1/projects/<project_name>/variables

URL query parameters:

  • name = <string> : filters the list of variables based on their name (prefix match).

Get a single Variable

GET /api/v1/projects/<project_name>/variables/<variable_name>

Create a single Variable

POST /api/v1/projects/<project_name>/variables

Update a single Variable

PUT /api/v1/projects/<project_name>/variables/<variable_name>

Delete a single Variable

DELETE /api/v1/projects/<project_name>/variables/<variable_name>

GlobalVariable

Get a list of GlobalVariable

GET /api/v1/globalvariables

URL query parameters:

  • name = <string> : filters the list of variables based on their name (prefix match).

Get a single GlobalVariable

GET /api/v1/globalvariables/<name>

Create a single GlobalVariable

POST /api/v1/globalvariables

Update a single GlobalVariable

PUT /api/v1/globalvariables/<name>

Delete a single GlobalVariable

DELETE /api/v1/globalvariables/<name>