Variable On this page 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>