Scoped Variables
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 may change depending on the following context:
Global: Variable value will be universally same throughout Devtron.
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
From the left sidebar, go to Global Configurations → Scoped Variables
Click Download template.
Figure 1: Downloading the Template 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 |
---|---|---|
| string | The API version of the resource (comes pre-filled) |
| string | The kind of resource (i.e. Variable, comes pre-filled) |
| object | The complete specification object containing all the variables |
| string | Unique name of the variable, e.g. DB_URL |
| string | A short description of the variable (up to 120 characters) |
| string | Additional details about the variable (will not be shown on UI) |
| boolean | Whether the variable value is confidential (will not be shown on UI if true) |
| 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 |
---|---|---|
| string | The context, e.g., Global, Cluster, Application, Env, ApplicationEnv |
| string | The value of the variable |
| object | A set of selectors that restrict the scope of the variable |
| object | A map of attribute selectors to values |
| string | The key of the attribute selector, e.g., ApplicationName, EnvName, ClusterName |
| string | The value of the attribute selector |
Here's a truncated template containing the specification of two variables for your understanding:
Upload the Template
Once you save the YAML file, go back to the screen where you downloaded the template.
Use the file uploader utility to upload your YAML file.
Figure 2: Uploading the Template The content of the file will be uploaded for you to review and edit. Click Review Changes.
Figure 3: Reviewing the YAML file You may check the changes between the last saved file and the current one before clicking Save.
Figure 4: Saving the file Click the Variable List tab to view the variables. Check the How to Use a Scoped Variable section to know more.
Figure 5: List of Variables
How to Edit an Existing Scoped Variable
Only a super-admin can edit existing scoped variables.
Option 1: Directly edit using the UI
![](https://docs.devtron.ai/~gitbook/image?url=https%3A%2F%2Fdevtron-public-asset.s3.us-east-2.amazonaws.com%2Fimages%2Fglobal-configurations%2Fscoped-variables%2Fedit.jpg&width=768&dpr=4&quality=100&sign=1e180d90&sv=1)
Option 2: Reupload the updated YAML file
Reuploading the YAML file will replace the previous file, so any variable that existed in the previous file but not in the latest one will be lost
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 the following screens in App Configuration:
Workflow Editor → Edit build pipeline → Pre-build stage (tab)
Workflow Editor → Edit build pipeline → Post-build stage (tab)
Workflow Editor → Edit deployment pipeline → Post-Deployment stage (tab)
Workflow Editor → Edit deployment pipeline → Post-Deployment stage (tab)
Deployment Template
ConfigMaps
Secrets
![](https://docs.devtron.ai/~gitbook/image?url=https%3A%2F%2Fdevtron-public-asset.s3.us-east-2.amazonaws.com%2Fimages%2Fglobal-configurations%2Fscoped-variables%2Fwidget1.jpg&width=768&dpr=4&quality=100&sign=7a32cccf&sv=1)
Upon clicking on the widget, a list of variables will be visible.
![](https://docs.devtron.ai/~gitbook/image?url=https%3A%2F%2Fdevtron-public-asset.s3.us-east-2.amazonaws.com%2Fimages%2Fglobal-configurations%2Fscoped-variables%2Fwidget-expanded.jpg&width=768&dpr=4&quality=100&sign=2d5f1498&sv=1)
Use the copy button to copy a relevant variable of your choice.
It would appear in the following format upon pasting it within an input field: @{{variable-name}}
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:
Global
Example
Environment + App: This is the most specific scope, and it will take precedence over all other scopes. For example, the value of
DB name
variable for theapp1
application in theprod
environment would beapp1-p
, even though there is a globalDB name
variable set toDevtron
. If a variable value for this scope is not defined, the App scope will be checked.App: This is the next most specific scope, and it will take precedence over the
Environment
,Cluster
, andGlobal
scopes. For example, the value ofDB name
variable for theapp1
application would beproject-tahiti
, even though the value ofDB name
exists in lower scopes. If a variable value for this scope is not defined, the Environment scope will be checked.Environment: This is the next most specific scope, and it will take precedence over the
Cluster
andGlobal
scopes. For example, the value ofDB name
variable in theprod
environment would bedevtron-prod
, even though the value ofDB name
exists in lower scopes. If a variable value for this scope is not defined, the Cluster scope will be checked.Cluster: This is the next most specific scope, and it will take precedence over the
Global
scope. For example, the value ofDB name
variable in thegcp-gke
cluster would beDevtron-gcp
, even though there is a globalDB name
variable set toDevtron-gcp
. If a variable value for this scope is not defined, the Global scope will be checked.Global: This is the least specific scope, and it will only be used if no variable values are found in other higher scopes. The value of
DB name
variable would beDevtron
.
List of Predefined Variables
There are some system variables that exist by default in Devtron that you can readily use if needed:
DEVTRON_NAMESPACE: Provides name of the namespace
DEVTRON_CLUSTER_NAME: Provides name of the cluster configured on Devtron
DEVTRON_ENV_NAME: Provides name of the environment
DEVTRON_IMAGE_TAG: Provides image tag associated with the container image
DEVTRON_IMAGE: Provides full image path of the container image, e.g.,
gcr.io/k8s-minikube/kicbase:v0.0.39
DEVTRON_APP_NAME: Provides name of the application on Devtron
Currently, these variables do not appear in the scoped variable widget, but you may use them.
Last updated