Qovery makes Environment Variables available to your services at runtime, as well as during builds and deploys.

If your projects and applications rely on sensitive data like credentials, API keys, certificates, Qovery offers you a way to store them as a Secret. Secrets are special environment variable safely encrypted, and their values can not be retrieved via Qovery API - they are only accessible for your application during build and runtime.

Qovery automatically generates for you some special environment variable (called BUILT_IN) which allows you to setup your service interconnection. See the BUILT_IN Section section.

Environment Variable definition

An environment variable is defined by:

• A type: two types are supported today
  • Variable: classic key/value pairs where the value can be retrieved at build and run time by using its name (key). Example: Key = THIRD_PARTY_URL, Value = https://mythirdparty.com
  • Variable as File: key/value/path triplets where the value will be stored as a file on the specified path. Your application can then retrieve the path of the file at run time by using the variable name (key). Only text files are supported. Example: Key = MY_CONFIG, Path = /tmp/config.json Value = {"key1":"value1","key2":"value2"}
• A scope: the accessibility level of this variable: application, environment, project (see scopes section below)
• A secret flag: it determines if the variable value needs to be encrypted and should be accessed ONLY by your applications (no access via the API/UI)

Environment variable vs Environment variable as file

Depending on your use case, you might decide to use a simple key value environment variable or instead use the environment variable as a file.

Environment Variable

If you need to store a simple value that needs to be retrieved at build or run time, than you can use a key/value environment variable

Example: You have a 3rd party application running on the endpoint https://mythirdparty.com. You can create an environment variable called THIRD_PARTY_URL that will contain the 3rd party URL:

Your application will then be able to retrieve the url by getting the value of the environment variable THIRD_PARTY_URL.

Environment Variable as file

If your application needs to load configuration files at run time, than you can use the environment variable as file.

Example: Grafana allows you to override the default configuration by setting a few environment variables pointing to your own configuration files. By default, the variable GF_PATHS_CONFIG points to '/etc/grafana/grafana.ini' but in case you want to specify a different configuration, you can create an environment variable as file like this:

When the grafana container will load the env var GF_PATHS_CONFIG, it will retrieve the path where the configuration file is stored and load its content.

Scopes

The scope of a variable allows you to define at which level this environment variable can be accessed (e.g. : only by one specific service).

There are three scopes for the Environment Variables:

Scope	Level	Description
PROJECT	1	Variables at the project level are shared across all environments and all applications of the project
ENVIRONMENT	2	Variables at the environment level are shared across all applications of the project in one, given environment
APPLICATION	3	Variables available for one application in one environment

BUILT_IN variables

Qovery automatically generates some variables (called BUILT_IN) which allow you to easily configure your service interconnection or to access some of the environment/application information.

By default, every environment contains the following BUILT_IN variables:

Name	Description
QOVERY_PROJECT_ID	Current project ID
QOVERY_ENVIRONMENT_ID	Current environment ID
QOVERY_APPLICATION_ID	Current service ID (for application with source = git repository)
QOVERY_CONTAINER_ID	Current service ID (for application with source = container registry)
QOVERY_JOB_ID	Current service ID (for lifecycle job and cronjob)
QOVERY_CLOUD_PROVIDER_REGION	Cloud provider region of the Kubernetes cluster running this environment
QOVERY_KUBERNETES_NAMESPACE_NAME	Namespace used in Kubernetes to run the application of this environment
QOVERY_KUBERNETES_CLUSTER_NAME	Name of the Kubernetes cluster running this environment

For any service within your environment (database, application, job), your application get access to a set of BUILT_IN variables. These can be used, to configure the interconnection between your services.

Naming Convention:

We use the following naming convention for additional built-in variables:

QOVERY_<SERVICE_TYPE>_<SERVICE_ID>_<SPEC>

For more information on how to use the BUILT_IN environment variables to:

• connect to a database, have a look at this section.
• connect to another service, have a look at this section.

Aliases and overrides

For a given environment variable, you can create aliases and overrides:

• Alias: it defines an alias for the environment variable. You can access its value by its original name or by its alias name.
• Override: it overrides the value of the environment variable. Example: you have an environment variable with scope = project having a particular value but you want to define a special value only for one environment. Instead of creating a separate environment variable only for that project, you can create an override of that variable within the environment requiring the special value.

Variables Interpolation

You can define an environment variable as a composition of text and other environment variables value (environment variables interpolation). For example, you can define your APP_URL environment variable as a composition of your HOST_URL and HOST_PORT in this way:

• Name = APP_URL
• Value = https://{{HOST_URL}}:{{HOST_PORT}}

Important information on this feature:

• the pattern used is {{VAR_NAME}}
• if a referenced variable doesn't exist, it is replaced by an empty string
• composition coherency using built in variables is kept when cloning an environment. Example: you can create a variable APP_URL = https://{{QOVERY_APPLICATION_ZEC0A2975_HOST_INTERNAL}} and when the environment is cloned, the "ZEC0A2975" is replaced with the right ID.
• there is no check at creation / edition / deletion if the referenced variable doesn't exist
• "inner replacements" are not supported (e.g VAR_1 = {{VAR_2}} and VAR_2={{VAR_3}} )

Naming Rules

• Environment variable name should use only alphanumeric characters and the underscore character (_) to ensure they are accessible from all programming languages. Environment variable keys should not include the hyphen character.
• Environment variable name should not begin with a double underscore (__).
• An environment variable’s name should not begin with QOVERY_ unless it is set by the Qovery platform itself.

Create an Environment Variable

Do you want to bulk import your Environment Variables or Secrets? Check out this tutorial

1. Navigate to Console

2. Select your project, environment and application

3. Select Environment Variables tab in the left panel and click New Variable button. Select if you want to create a classic environment variable or an environment variable as file.

   

4. Select the name, value and scope of your new environment variable

   

   If the variable you are trying to create is a Variable as File, define the Path where the file should be stored. Remember that in this case the Value field should contain the content of your file. If the variable you are trying to create is a Secret, select the Secret checkbox.

How was it? Did this tutorial work?  Yes  No

Delete an Environment Variable

1. Navigate to Console

2. Select your project, environment and application

3. Select the Environment Variables tab in the left panel

4. Select variable you want to delete and click the Delete button from the submenu:

   

How was it? Did this tutorial work?  Yes  No

Update an Environment Variable

1. Navigate to Console

2. Select your project, environment and application

3. Select the Environment Variables tab in the left panel

4. Select variable you want to update and click the Edit button from the submenu:

   

5. Update the variable in the popup window

   Note: if the variable is a Secret, you won't be able to see its value

How was it? Did this tutorial work?  Yes  No

Override Environment Variable

If you want to override a value of an environment variable, follow those steps:

1. Navigate to Console

2. Select your project, environment and application

3. Select the Environment Variables tab in the left panel

4. Select variable you want to override and click the Override button from the submenu

5. Select the override the variable and its scope in the popup window

How was it? Did this tutorial work?  Yes  No

\

You can only override environment variables of a higher scope, e.g. Environment scope variable can override Project variable, but can't override Application variable.

Alias Environment Variable

You can create an alias for the existing environment variable.

Let's suppose that your application requires a DATABASE_URL variable. Qovery provides your application with the QOVERY_DATABASE_MY_POSTGRESQL_3498225_URL variable with a database password. Instead of copy-pasting its value, you can create an alias to QOVERY_DATABASE_MY_POSTGRESQL_3498225_URL.

1. Navigate to Console

2. Select your project, environment and application

3. Select the Environment Variables tab in the left panel

4. Select variable you want to alias and click the Alias button from the submenu:

5. Define the alias of the variable and its scope in the popup window

How was it? Did this tutorial work?  Yes  No

Import environment variables

You can add a set of environment variables into Qovery by importing an .env file. The .env file contains a list of your environment variables, in a MY_KEY = VALUE format.

To import environment variables into your Qovery environment, follow the steps below.

1. On an application page, click on the Environment variable tabs > Import button.

   

2. Drag & Drop the .env file into the modal, or click on the interface to open the file explorer.

3. The file is loaded and a new modal is displayed, where you can configure the import of your variables.

   

   Overwrites variables

   When this option is enabled, if an existing variable and an imported variable share the same name, the existing value will be overwritten by the imported one. If the option is disabled, the imported value will be ignored. However, to avoid conflicts in the architecture of your environment variables, some of them will intentionally not be imported. To understand how we handle conflicts, please take a look to the Importation conflicts section.

   Configure variables import

   On this modal, you can define for each variable the following parameters:

   • name: upate variable name
   • Value: update variable value
   • Scope: Specify the scope in which you want to import the variable
   • Secret: Specify if this value is considered as a secret or not

   Preset variables

   To help you import a large number of variables quickly, you can predefine scope and secret settings. This will change the scope and secret value of all listed variables. If the secret and scope of one or more specific variables are subsequently updated, this will not change the predefined setting.

4. When you have finished the configuration, click on the Import button.

5. A pop-up message is displayed to inform you that your environment variables have been imported.

How was it? Did this tutorial work?  Yes  No

Importation conflicts

To avoid conflicts between already existing and imported environment variables, some of them will not be imported, even if the overwrite option is activated. The different cases are described below.

Imported variable has same name as BUILT_IN variable

Type	Name	Value	Scope
Existing variables
VALUE	MY_VAR	42	Built_in
Variables to import
VALUE	MY_VAR	10	Application

Built_in environment variables are generated and managed by Qovery and will not be overwritten, even if the overwriting option is activated.

Imported variable has same name as an existing ALIAS

Type	Name	Value	Scope
Existing variables
VALUE	MY_VAR	42	Environment
ALIAS	MY_VAR_ALIAS	MY_VAR	Application
Variables to import
VALUE	MY_VAR_ALIAS	10	Application

The value cannot be rewritten because the link between the original variable and the alias would be lost.

Imported variable has same name as an existing secret (or vice versa)

Type	Name	Value	Scope	Secret
Existing variables
VALUE	MY_VAR	1	Application	Ye
Variables to import
VALUE	MY_VAR	2	Application	No

The value cannot be imported because this will overwrite the existing secret.

Overwriting and limitations

Some overwriting cases are not supported for now. They are summarized in the following table.

Existing variable scope	Imported variable scope	Supported
PROJECT	PROJECT / ENVIRONMENT / APPLICATION	YES
ENVIRONMENT	PROJECT	NO
ENVIRONMENT	ENVIRONMENT / APPLICATION	YES
APPLICATION	PROJECT / ENVIRONMENT	NO
APPLICATION	APPLICATION	YES

Service interconnection

Connecting to a database

To access a database managed by Qovery from your application, you can use the BUILT_IN environment variables and secrets that have been automatically created by Qovery during the database creation process. You can find all the BUILT_IN variables on the Qovery console within the Environment Variable section of your application (see the credentials and connectivity section for the full list).

In order to match the naming convention of the database connection variables used within your code, you can create an alias for each variable in the Qovery console so that you don't need to change your code.

Once you have defined an alias for each variable, you can redeploy the application and check that it has finally access to the database.

Example

You have created a postgres database on the Qovery console. Within the code of your application you need some environment variables containing the connection parameters of the database: DATABASE_URL, DATABASE_USER, DATABASE_PASSWORD, DATABASE_PORT, DATABASE_NAME

example.py

DB_NAME = os.getenv("DATABASE_NAME", "nemo")
DB_USER = os.getenv("DATABASE_USER", "nemo")
DB_PASSWORD = os.getenv("DATABASE_PASSWORD", "password")
DB_HOST = os.getenv("DATABASE_HOST", "localhost")
DB_PORT = os.getenv("DATABASE_PORT", "5432")

To match your internal naming convention, you can create aliases for each of the corresponding variables in this way:

Connecting to another application

To access another application managed by Qovery, you can use the BUILT_IN environment variables that have been automatically created by Qovery during the creation of that particular application. You can find all the BUILT_IN variables on the Qovery console within the Environment Variable section of your application.

Please note that two BUILT_IN might exist:

• QOVERY_APPLICATION_<APPID>_HOST_INTERNAL : it contains the INTERNAL host of the application that can be used inside your Kubernetes cluster (and thus by any application running on it)
• QOVERY_APPLICATION_<APPID>_HOST_EXTERNAL : it contains the EXTERNAL host of the application that can be used to reach your application from outside your Kubernetes cluster (if the application is publicly exposing one of its ports)

In order to match the naming convention of the connection variables used within your code, you can create an alias for the HOST_INTERNAL variable so that you don't need to change your code.

Once you have defined an alias for each variable, you can redeploy the application and check that it can reach the other application.

Example

You have created a backend application on the Qovery console and a BUILD_IN variable has been created containing the application HOST called QOVERY_APPLICATION_Z9D8DAA08_HOST_INTERNAL. Within the code of your front-end application you need some environment variables containing the host of the backend application (BACKEND_HOST)

To match your internal naming convention, you can create alias for the corresponding variable in this way: