Shared Values

What are Shared Values? #

Shared Values provide a way to reference the same value or secret from multiple Workloads in an Application. The Humanitec Platform Orchestrator provides you with the required functionality to handle both non-secret and secret values in a scalable and secure way.

Shared Values and secrets in the Platform Orchestrator are hierarchical, with each layer being able to use or override values and secrets defined at the parent level. This means that Application wide values and secrets can be overwritten at the Environment level and passed on to the Workload level. At the Workload level, values and secrets defined further up the tree can also be overwritten or used verbatim.

Hierarchy #

You can define Environment Variables and Secrets in a hierarchical way.

• Application level: The highest hierarchical level is the Application level. Define Environment Variables that are important within the context of your Application. All Shared Values and secrets defined at the Application level will be inherited by every Environment in that 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.

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.

The Platform Orchestrator does not allow Shared Values to be applied to an individual Environment without adding a base value for the Application. This is because it would no longer be possible to clone a Workload that referenced it to another Environment.

Manage Shared Values #

To create or update Application Shared Values and 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 #

Set Application level Values or Secrets.

• Portal
• CLI
• Terraform

        
        
      humctl create value YOUR_KEY your-value \
  -d "The value of your-value stored in YOUR_KEY" \
  --app ${APP_ID}

        
        
      resource "humanitec_value" "app_value" {
  app_id      = "example-app"
  key         = "YOUR_KEY"
  description = "The value of your-value stored in YOUR_KEY"
  value       = "your-value"
  is_secret   = false
}

Secrets cannot be retrieved or edited by the Platform Orchestrator, they can only be replaced.

The new value will be added to the list of default Values and Secrets for the Application. Values referenced in the container variables section of a Workload, via the ${values.KEY} placeholder, will now be resolved to this value in the next deployment. These shared values can be overridden on the environment level.

Environment level #

Set Environment level Values or Secrets.

• Portal
• CLI
• Terraform

        
        
      humctl create value YOUR_KEY your-value-override \
  -d "The value of your-value-updated stored in YOUR_KEY" \
  --app ${APP_ID} \
  --env ${ENV_ID}

        
        
      resource "humanitec_value" "env_value" {
  app_id      = "example-app-id"
  env_id      = "example-env-id"
  key         = "YOUR_KEY"
  description = "The value of your-value-updated stored in YOUR_KEY"
  value       = "your-value-updated"
}

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. This can be referenced in the container variables section of a Workload, via the ${values.DEBUG_LOGGING} placeholder, and will now be resolved to OFF.

Use Shared Values #

Shared Application Values can be referenced using Placeholders in the variables and files properties on the Workload level using the Portal or Score.

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. For more information, see RBAC.

To apply a change in a Shared Value on the Application or Environment level to a Workload using it, it is not sufficient to Redeploy the Environment it is running in. By design, the redeploy will use the same Value Set Version as the current Deployment, thus using the same values.

To make changes in Shared Values become effective, either create a new Draft Delta through the Portal as shown in the instructions below, or redeploy your Workload via Score.

Container Environment Variables #

• Portal
• Score

        
        
      apiVersion: humanitec.org/v1b1

spec:
  containers:
    demo:
      variables:
        SOME: VARIABLE
        SHARED_VALUE: $${values.SOMETHING}

        
        
      apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    # Set by pipeline via humctl score deploy --image
    image: .
    variables:
      API_KEY: "${resources.env.API_KEY}"
resources:
  env:
    # The type "environment" is available per the Score specification.
    type: environment

File Templates #

• Portal
• Score

        
        
      {
  "key1": "value1",
  "key2": "value2",
  "key3": "value3"
}

        
        
      apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    # Set by pipeline via humctl score deploy --image
    image: .
    files:
      - target: /app/default.config
        mode: "0644"
        # The source references a locally available file
        # It is read by the humctl CLI when running "humctl score deploy"
        source: "./appsettings.json"

        
        
      apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    # Set by pipeline via humctl score deploy --image
    image: .
    files:
      - target: /app/default.config
        mode: "0644"
        # The content references the Shared Value APP_SETTINGS, available through the "env" resource declared below
        content: "${resources.env.APP_SETTINGS}"
resources:
  env:
    # The type "environment" is available per the Score specification
    type: environment

        
        
      apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    # Set by pipeline via humctl score deploy --image
    image: .
    files:
      - target: /app/default.config
        mode: "0644"
        content: |
          [config]
          key=value

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, the Platform Orchestrator 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.

A Shared Value that is Secret can only be used as a placeholder as long as it is not combined with static parts, i.e. it has to make up the entire value. The example above will therefore not work if the Shared Value PLACEHOLDER_EXAMPLE is secret. It will work if reduced to

${values.PLACEHOLDER_EXAMPLE}

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 in the secret store that is the primary secret store at the time the secret value is writen. If you did not set up another secret store for your Organization, the Platform Orchestrator uses the Humanitec-managed secret store.

Secret values are also not retrievable by the Platform Orchestrator. 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, the Platform Orchestrator 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.

Using secret references #

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

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 #

• Portal
• API
• CLI
• Terraform

Environment level #

• Portal
• API
• CLI
• Terraform

Reverting to a Previous Version #

To revert a value to a previous version:

Application level #

• Portal
• API
• CLI
• Terraform

Environment level #

• Portal
• API
• CLI
• Terraform

Purging a Version from History #

To remove a version from the history:

Application level #

• Portal
• API
• CLI
• Terraform

Environment level #

• Portal
• API
• CLI
• Terraform

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.