Shared Values
Humanitec provides you with the required functionality to handle both, Values and Secrets in a scalable and secure way.
Values and Secrets in Humanitec are hierarchical, with each layer being able to use or override Values & Secrets defined at the parent level. This means that Application wide Values & Secrets can be overwritten at the Environment level and passed on to the Workload level, then at the Workload level, Values & Secrets defined further up the tree can also be overwritten or used verbatim.
Hierarchy
Humanitec allows you to define Values and Secrets in a hierarchical way.
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.
For more information, see RBAC.
Application 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.
Environment level
The hierarchical level following the Application 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.
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.
Use Shared Values
Learn to use Shared Values in your Application, Environment, or Workloads.
Variable hierarchy
Humanitec allows you to define Environment Variables and Secrets in a hierarchical way: on App level, Environment level, and Workload level.
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.
Administrator role within your Organization or hold the Owner / Developer role on the App. For more information, see RBAC.Container Environment Variables
File Templates
Results: The Value or Secret will templatized into the Environment Variable or File as defined by the Placeholder at launch-time.
Using Placeholders
In some cases, the value of a configuration may vary depending on the environment in which a workload is deployed. For instance, you might need your workload to connect to a different database in a development environment than in a production environment. To enable this, Humanitec provides placeholders that can be included in variable values and will be resolved to one of the Shared Values & Secrets at deployment time.
Placeholders take the form ${...} and contain a placeholder path. You can include any number of placeholders in a variable’s value. For example:
Hello ${values.PLACEHOLDER_EXAMPLE}!
This will resolve to the shared value PLACEHOLDER_EXAMPLE at deployment time and insert the correct value into the string.
Manage Shared Values
All Shared Values and Secrets defined at the Application level will be inherited by every environment in that Application.
Variable Hierarchy overview
You can define Environment Variables and Secrets in a hierarchical way.
- Application level: The highest hierarchical level is the App level. Define Environment Variables that are important within the context of your Application.
- Environment level: The hierarchical level following the Application level is the Environment level. Define Environment Variables that are important within the context of that specific Environment.
- Workload level: The lowest hierarchical level is the Workload level. Edit Environment Variables and Secrets on the Workload level from the Workload Details Screen.
Administrator role within your Organization or hold the Owner / Developer role on the Application. For more information on Role-Based Access Control (RBAC), see RBAC.Application level
Set Application level Values or Secrets.
Results: The new value will be added to the list of default Values and Secrets for the Application.
Environment level
Set Environment level Values or Secrets.
For example, if your Application default value contains DEBUG_LOGGING, and it is set to WARNING, for the selected Environment, you can choose to turn DEBUG_LOGGING to OFF. 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.
Workload level
Edit Workload level Values or Secrets.
You can also define new variables just used for this Workload.
For example, if your Application default value contains DEBUG_LOGGING, and it is set to WARNING, for the selected Workload, you can choose to turn DEBUG_LOGGING to OFF. Values referenced in the container variables section of a Workload, via ${values.KEY}, will now be resolved to the value defined for the respective Workload.
Shared Application Values
Shared Application Values provide a way to reference the same value or secret from multiple workloads in an Application. These Application wide values and secrets can be overridden on an environment by environment basis. This makes Shared Application Values part of the Environment-Specific Configuration.
Shared Application Values can be referenced using Placeholders in the variables and files properties of the Deployment Set.
Secrets
Shared Application Values can be marked as Secret. This means that they will be treated differently when stored and referenced. When being stored, secret values will be stored encrypted in a dedicated secret store (for example, HashiCorp Vault). Secret values are also not retrievable by Humanitec. This means they will not appear in the UI, CLI or API. They will also not be present in exported Kubernetes Manifests.
Instead of a value, Humanitec’s UI will show the Version ID of a secret. The Version IDs of App values and Environment overrides are independent of each other. This means that even seemingly equal versions of the same key don’t necessarily share the same value, and equal values most likely won’t have the same ID. Version ID increases only when the value is changed, description changes don’t affect it.
Any string containing a Placeholder referencing a Shared Application Value that is a secret will itself be treated as a secret.
Environment overrides
Each Shared Application Value (including values which are secret) must have a base value defined on the Application. This value can be overridden on an Environment by Environment basis. This allows different values to be specified for different environments. For example, the development environment might use a different API key for a third party service than Production. The base value of the API key secret can be the development key, and then the production environment value can be overridden with the production API key.
Value Set Versions
Every change to an Application or Environment Value is recorded in a Value Set Version. Those versions include the entire set of values for a particular Application or Environment, so it is sufficient to reference a single version id when speaking about the state of values at a particular point (similar to a commit in git).
As long as only Application Values are used, the Application and Environment level version histories are the same. Once a particular value is overwritten in an environment, the history of the targeted environment starts to diverge (similar to a git branch). From that point on, all Application level changes will “bubble up” to all environment version histories, so the environment history always includes all explicit changes (by changing overrides) and implicit changes (by changing Application level values).
Defined Values and Secrets can be used in the Webhooks, Variables, and Files sections of the Workload configuration through Placeholders.
Revert
You can revert to a particular value set version, which means that all values or a specific subset of values from this point are added to the top of the history. This allows you to undo secret changes without actually knowing the content of a particular secret value, and can be useful in case of a deployment issue after a secret change.
Purge
Purging allows removing specific values from the value set version history and can be useful if a value has been added accidentally (for example, a secret value was added as non-secret). To reduce the risk of breaking, deploy this operation has a couple of limitations.
- By design, a purge can’t be reverted.
- The current value of a key can’t be purged, which means that you always need to update or delete the respective key before attempting a purge.
- You always need to target the specific version where a value has been introduced to avoid ambiguity in which versions would be affected. For example, if a value for key A was introduced in version 3, you can’t purge key A in version 4 even if the key has been changed in version 5.
When purging a key, the value of that key will be removed in all consecutive versions that have this particular value. For example, when key A had the same value in version 3 and 4 and was updated in version 5, the value will be removed from version 3 and 4, but kept in version
Bulk operations
Bulk changes (for example, a revert or bulk delete) create a single version in the version history.
Versioning
Shared Values and Secrets are versioned, which means that every change generates a new version with information about who made the change and when. You can access the version history either through the user interface or an API. Whether you are working with an App-level shared value or secret, or an Environment-level override, the process for viewing, reverting, or purging the value is the same.
Viewing Value history
To view the version history of a value:
Application level
Environment level
Reverting to a Previous Version
To revert a value to a previous version:
Application level
Environment level
Purging a Version from History
To remove a version from the history: