Manage Environment Variables and Secrets
Learn how to manage Environment Variables and Secrets across Apps and Environments.


A central element of Internal Developer Platforms is the ability to create new Environments whenever needed. This requires a solid approach to manage environment-specific configurations. Humanitec provides you with the required functionality to handle both, environment variables and secrets in a scalable and secure way.

Types of Variables

When looking at variables for externalized App configuration, you can distinguish between 3 different types of variables.
Static Environment Variables
Static Environment Variables are - as the name implies - static across all or most of the Environments of a specific App.
A good example is a variable to control the debugging or logging behavior of the Workloads in your App. You typically use a detailed level of logging in your development Environments that allows for better debugging while restricting logging to errors in your production Environment.
Dynamic Environment Variables
Dynamic Environment Variables have Environment-specific values.
Good examples are variables needed to connect to a database (such as username, hostname, and port). While each of the Environments of a specific App might use the same server, the databases themselves are Environment-specific.
You typically need some kind of placeholder system to enable Dynamic Environment Variables.
Secrets are very similar to Environment Variables with the main difference that you cannot retrieve them back in an unencrypted way once you entered them. They are resolved at deployment time to provide the required App configuration.
Good examples are passwords that you need to access databases.

Variable Hierarchy

Humanitec allows you to define Environment Variables and Secrets in a hierarchical way.

App Level

The highest hierarchical level is the App level. You can go to the App Settings Screen in each of your Apps and define Environment Variables that are important within the context of your App.
Example for Environment Variables in the App Settings
As you can see from the example above, you can define Environment Variables as well as Secrets on this level. The variables defined on App level can be referenced within each Environment of the App by using ${values.KEY} in the container variables section of a Workload (see Workload Level for further reference).
Humanitec also allows you to provide a description for each variable you are defining. You can use the description to explain the variable or even to mention the team/person responsible for managing this variable which can become very handy especially in large organizations.

Environment Level

The hierarchical level following the App Level is the Environment level. In the Environment Settings Screen of each Environment you can define Environment Variables that are important within the context of that specific Environment.
Example for Environment Variables on the Environment Settings Screen
In the Shared values and secrets overrides section priorly defined App default values can be overridden. In the example above the value of DEBUG_LOGGING was overridden from warning to info for the development Environment. Variables referenced in the container variables section of a Workload via ${values.KEY} will now be resolved to the value defined for the respective environment.

Workload Level

The lowest hierarchical level is the Workload level. You can edit Environment Variables and Secrets on the Workload Level from the Workload Details Screen.
Example for Environment Variables on the Workload Detail Screen
As you can see in the example above you can reference the variables defined on the App and Environment level by using ${values.KEY} and Humanitec provides autocomplete suggestions. You can also define new variables just used for this Workload.

Variable Substitutions

Variable Substitutions allow you to dynamically reference values that depend on the environment (e.g., the Workload's database name, auto-generated external DNS names, secrets). A variable substitution consists of a string that you enter in the value of an Environment Variable in a Workload’s configuration map. When you deploy your App, Humanitec will replace these strings with the values that they reference.

Database References

Variable substitution name
The name of the database that your module connects to.
externals. postgres.engine
The database engine used. Will always be POSTGRES.
The DNS name or IP of the database server.
externals. postgres.username
The username of the Postgres ROLE that has access to the database defined in name.
externals. postgres.password
The password of the Postgres ROLE that has access to the database defined in name.
externals. postgres.port
The port on the server defined by host.

Workload References

Variable substitution name
The in-cluster DNS name of the Workload.
The DNS name of the Workload, which is generated if you expose the Workload externally.
Last modified 1mo ago