Skip to content

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> # Optional

display: <Display specification> # Optional
value: <string>
constant: <boolean> | default = false # Optional

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> # Optional

# 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> # Optional

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

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

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

# 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> # Optional

# 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" # Optional

# 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> # Optional

# The description of the variable
description: <string> # Optional

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

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>