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.

Manage Shared Values

Application level

Set Application level Values or Secrets.

  1. From the Application overview , select the Application you’d like to set shared Application Values for.
  2. Go to the Values & Secrets tab, and select + Add Variables.
  3. Enter the following information:
    1. Enter a unique key name.
    2. Enter a value.
    3. Enter a Description.
    4. (optional) Select the toggle to create a secret.
  4. Select Save to finish.

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

Optionally, you can use the --is-secret parameter if you want to save your value as secret.

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
}

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.

  1. From the Application overview , select the Application and the Environment you’d like to set shared Application Values for.
  2. Go to the Secret & value overrides tab, and edit button on the line you want to update.
  3. Enter the following information:
    1. Enter a value.
    2. Enter a Description.
  4. Select Save to finish.

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 Web UI or Score .

Container Environment Variables

  1. From the Application overview , select the name of the Application where you’d like to edit Values or Secrets.
  2. Select an Environment.
  3. Click on Create draft delta. This will create a new Deployment Delta to prepare your changes. Change its name from “Untitled Draft” to a descriptive title.
  4. Choose your Workload and Container.
  5. In the Variables section, edit any variables for that Workload as shown in Container Environment Variables .
    • 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.
  6. Click on Review and Deploy.
  7. Review your changes, enter an optional comment and click Deploy to deploy the Delta.

Define environment variables for a container. There are two ways to configure them.

  1. Via the Score file

    The Score specification supports placeholder references to the Workload metadata or Resources named in the Score file. The syntax and supported values are different in Score compared to the Platform Orchestrator, and the Platform Orchestrator will automatically convert Score references to native placeholders when deploying a Score file. Variables will be mapped into the container through a ConfigMap or Secret .

    The Platform Orchestrator supports an environment resource for accessing the shared values in the application environment:

    apiVersion: score.dev/v1b1
metadata:
  name: example
containers:
  main:
    image: example
    variables:
      KEY_ONE: hello-world
      KEY_TWO: ${resources.env.VALUE}
resources:
  env:
    type: environment

  2. Via the Score extensions file

    Score extensions files contain Platform Orchestrator specific content allowing the workload profile or deployment options to be configured along with overrides to the resulting workloads. The Score extensions file supports the use of Score placeholder references and native placeholders when escaped with a $.

    apiVersion: humanitec.org/v1b1
spec:
  containers:
    main:
      variables:
        KEY_THREE: $${values.VALUE}
        KEY_FOUR: goodbye

humanitec.score.yaml ( view on GitHub ) :

apiVersion: humanitec.org/v1b1

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

score.yaml ( view on GitHub ) :

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

containers:
  demo:
    image: registry/my-image:1.0.0
    variables:
      API_KEY: "${resources.env.API_KEY}"
resources:
  env:
    # The type "environment" is available per the Score specification.
    type: environment

File Templates

  1. From the Application overview , select the name of the Application where you’d like to edit Values or Secrets.
  2. Select an Environment.
  3. Click on Create draft delta. This will create a new Deployment Delta to prepare your changes. Change its name from “Untitled Draft” to a descriptive title.
  4. Choose your Workload and Container.
  5. Navigate to the Files section and select Add Files.
  6. 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.
  7. Click on Review and Deploy.
  8. Review your changes, enter an optional comment and click Deploy to deploy the Delta.

Add files to Containers.

Refer to the files feature for configuration details.

The examples show these variations to provide file content:

  • score.yaml: Base approach supplying the file contents as a multiline string. This approach creates the same file content across all environments.
  • score-shared-values.yaml: (Recommended) Supplying the file contents via a Shared Value via the environment resource which is available as part of the Score specification . Since Shared Values may optionally be overridden on an Environment level, this approach lets you inject environment-specific configuration managed through the Platform Orchestrator.
  • score-local-file-source.yaml: Supplying the file contents via a file available locally which is read at Score deployment time, i.e. when executing humctl score deploy.

appsettings.json ( view on GitHub ) :

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

score-local-file-source.yaml ( view on GitHub ) :

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

containers:
  demo:
    image: registry/my-image:1.0.0
    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"

score-shared-values.yaml ( view on GitHub ) :

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

containers:
  demo:
    image: registry/my-image:1.0.0
    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

score.yaml ( view on GitHub ) :

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

containers:
  demo:
    image: registry/my-image:1.0.0
    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.

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

  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.

Workloads

Container logs