Manage Environment Variables and Secrets

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

Introduction
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.
Type
Description
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
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.
To create or update App default variables & secrets, you will need to have the Administrator role within your Organization or hold the Owner/ Developer role on the App. Learn more about RBAC in Humanitec here.
UI
CLI
API
Start on the App Settings Page and navigate to the App default values & secrets section.
As you can see from the example below, 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). Additionally each value can be overridden on Environment level.
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.
Example for Environment Variables in the App Settings
Our CLI is currently in closed beta. Please contact us if you want to learn more.
App default values & secrets can be defined via the Create Shared Value endpoint.
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.
To create or update shared values and secrets overrides, you will need to have the Administrator role within your Organization or hold the Owner/ Developer role on the App. Learn more about RBAC in Humanitec here.
UI
CLI
API
Start on the Environment Settings Screen and navigate to the shared values and secrets overrides section.
As you can see from the example below, priorly defined App default values can be overridden. The value of DEBUG_LOGGING was overridden from warning to off for this Environment. Values referenced in the container variables section of a Workload, via ${values.KEY}, will now be resolved to the value defined for the respective environment.
Example for Environment Variables on the Environment Settings Screen
Our CLI is currently in closed beta. Please contact us if you want to learn more.
Environment level value and secret overrides can be defined via the Create Shared Value endpoint.
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.
To create or update a Workloads environment variables, you will need to have the Administrator role within your Organization or hold the Owner/ Developer role on the App. Learn more about RBAC in Humanitec here.
UI
CLI
API
As you can see in the example below 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.
Example for Environment Variables on the Workload Detail Screen
Our CLI is currently in closed beta. Please contact us if you want to learn more.
You can update environment variables by creating a new Deployment Delta.
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
Description
externals.
postgres.name
The name of the database that your module connects to.
externals.
postgres.engine
The database engine used. Will always be POSTGRES.
externals.
postgres.host
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
Description
modules.{WORKLOAD-NAME}.service.name
The in-cluster DNS name of the Workload.
modules.{WORKLOAD-NAME}.service.external-name
The DNS name of the Workload, which is generated if you expose the Workload externally.

Type	Description
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	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 substitution name	Description
`externals.` `postgres.name`	The name of the database that your module connects to.
`externals.` `postgres.engine`	The database engine used. Will always be POSTGRES.
`externals.` `postgres.host`	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`.

Variable substitution name	Description
`modules.{WORKLOAD-NAME}.service.name`	The in-cluster DNS name of the Workload.
`modules.{WORKLOAD-NAME}.service.external-name`	The DNS name of the Workload, which is generated if you expose the Workload externally.

Define Namespace Names

Add Configuration as a File on the Container Level

Last modified 2mo ago