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.

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.

Container Environment Variables

  1. Starting on the Container details screen of the Container in which you wish to use the shared Value or Secret, navigate to the Variables section.
  2. Enter the following options and then click Save.
    1. Enter a key - This is the name of the Environment Variable as expected by the container.
    2. Enter a value - Here you can use Placeholders (for example, {values.SHARED_VALUE_NAME}) to template in the shared Values and Secrets defined at the App or Environment levels.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

File Templates

  1. Starting on the Container details screen of the Container in which you wish to use the shared Value or Secret, navigate to the Files section and select Add Files.
  2. Enter the following options and then click Save.
    1. Enter a path - This is the fully qualified path name (i.e. it includes the filename) as expected by the container.
    2. Enter a mode - This is the file access permissions in Unix Octal Mode format.
    3. Enter the file’s content - Here you can define the content of your file, using Placeholders (for example, {values.SHARED_VALUE_NAME}) to template in the shared Values and Secrets defined at the App or Environment levels.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

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.

Application level

Set Application level Values or Secrets.

  1. Starting on the Application overview screen of the Application to which you want to add a Value or Secret, navigate to the Values & Secrets section.
  2. Click Add Variables.
  3. Enter the following options and then select Add.
    1. Enter a key.
    2. Enter a value.
    3. (optional) Enter a description.
    4. Choose if the value is a secret.
  4. You can edit or delete the value by selecting the corresponding options next to the value.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

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.

  1. From the Applications overview, select the name of the Application and the Environment where you’d like to edit Values or Secrets.
  2. Select Secret & value overrides tab.
  3. Edit and override any of the Values or Secrets for that Environment.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

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.

  1. From the Application overview, select the name of the Application you’d like to edit Values or Secrets.
  2. Choose your Workload and Container.
  3. In the Variables section, edit any variables for that Workload as shown in Container Environment Variables.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

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 Placeholders 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.

  1. By design, a purge can’t be reverted.
  2. 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.
  3. 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

  1. Go to the Application overview screen and select the Values & Secrets section.
  2. Click the history icon next to each entry in the table.
  3. This opens a modal dialog where you can browse through different versions and see who made each change.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Environment level

  1. Go to the Environment overview screen and select the Secret & value overrides section.
  2. Click the history icon on the far right of each row in the table.
  3. This opens a modal dialog where you can browse through different versions and see who made each change.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Reverting to a Previous Version

To revert a value to a previous version:

Application level

  1. Go to the Application overview screen and select the Values & Secrets section.
  2. Click the history icon between the edit and delete icons next to each entry in the table.
  3. This opens a modal dialog where you can browse through different versions.
  4. Click Revert on the row that you want to restore.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Environment level

  1. Go to the Environment overview screen and select the Secret & value overrides section.
  2. Click the history icon on the far right of each row in the table.
  3. This opens a modal dialog where you can browse through different versions.
  4. Click Revert on the row that you want to restore.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Purging a Version from History

To remove a version from the history:

Application level

  1. Go to the Application overview screen and select the Values & Secrets section.
  2. Click the history icon between the edit and delete icons next to each entry in the table.
  3. This opens a modal dialog where you can browse through different versions.
  4. Click Purge on the row that you want to remove.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Environment level

  1. Go to the Environment overview screen and select the Secret & value overrides section.
  2. Click the history icon on the far right of each row in the table.
  3. This opens a modal dialog where you can browse through different versions.
  4. Click Purge on the row that you want to remove.

Instructions coming soon.

Instructions coming soon.

Instructions coming soon.

Lifecycle

Application level Shared Values, including those which are secret, are deleted when the Application is deleted.

Environment overrides, including those which are secret, are deleted when the Environment is deleted (which also occurs when the Application is deleted).

Secrets used via secret references are never deleted.

Using secret references

You can use secret references to read secrets from secret stores, and provide them as Shared Vaules. Go here to see examples.

Top