Placeholders

What are placeholders? #

Humanitec uses Placeholders as a means to inject values known only at deployment time into the Application Configuration. They resemble Template literals  in JavaScript or variable substitution in shell scripting languages such as Bash and PowerShell.

Placeholders are primarily used to dynamically reference values in Files and Environment Variables, and are supported in the labels, variables, and files properties of workloads in Deployment Sets, and driver_inputs in Resource Definitions.

Syntax #

Placeholders follow the syntax: ${path}, where path is composed of . separated tokens or JSON strings enclosed in []. For example:

${shared.users-db.name}
${["shared"]["users-db"]["name"]}
${shared['users-db'].name}

A literal ${ can be inserted by escaping the { with a backslash, as in $\{path}, which evaluates to ${path}.

You can use multiple placeholders in a string, for instance when specifying a database connection string:

postgresql://${shared.users-db.username}:${shared.users-db.password}@${shared.users-db.host}:${shared.users-db.port}/${shared.users-db.name}

Placeholders and Secrets #

If a placeholder refers to a secret value (like a database password), its parent string will be treated as a secret by Humanitec. However, some placeholders cannot be used as secrets. If these are included in a string containing other secret placeholders, an error will occur.

Placeholders and types #

Most placeholder represent string values. However, placeholders expand a little differently based on types.

Placeholder expansion follows these rules:

• If a string only contains a placeholder, then it will resolve to the type that the value has.
• If the string contains more than a placeholder, then it will resolve to a JSON representation of that value except if the value is a string when it will just resolve to the raw string.

For example, if the outputs of a config resource has the following outputs:

str: "Hello world!"
num: 42
bool: true
obj:
  msg: "Hello world!"
arr:
  - "one"
  - "two"

Then the following placeholders would resolve as follows:

Usage #

Placeholders can be utilized in certain fields in the Platform Orchestrator. These include:

• The driver_inputs property in Resource Definitions, e.g. like this:

entity:
  driver_inputs:
    values:
      namespace: "${context.app.id}-${context.env.id}"

• The driver_account property in Resource Definitions, e.g. like this:

entity:
  # Obtain the Cloud Account from a config resource
  driver_account: ${resources['config.default#aws-account'].account}

• The variables and files properties in Score files, e.g like this:

containers:
  hello:
    image: .
    variables:
      MYVAR: ${context.app.id}-${context.env.id}
    files:
      - target: /app/default.config
        mode: "0644"
        content: "${context.app.id}-${context.env.id}"

• labels, variables, and files in Deployment Sets

In the Humanitec Portal, inputs for labels, variables, and files support placeholder autocompletion. Type ${ in the input area to see a complete list of available placeholders.

See the list of Placeholders on this page for the supported usage of each Placeholder.

Containers #

Containers running in pods on Kubernetes provide placeholders that enable you to retrieve information about the Kubernetes resource limits (CPU, RAM, etc) that are placed on the container.

Example: ${containers.main.limits.cpu} - The maximum number of CPU cores the container may use.

Context #

The App and Deployment context is useful for configuring logging for your Deployments as it enables you to record exactly which version of which software was running on which Environment at the time an issue occurred.

Example: ${context.app.id} - The id of the App in Humanitec.

Pod #

Pods running on Kubernetes provide placeholders that can be helpful in logging.

Example: ${pod.metadata.name} - The name of the current Pod.

Resource References #

Drivers can provide various outputs that may be required by the App. The outputs of Resources that are private to a workload are accessible under the externals. path prefix, whereas the outputs of Resources that are shared across the App can be accessed via the shared. path prefix.

Each Resource Type defines the set of output names that can be used as placeholders.

Example: ${externals.users-db.username} - The username output of the users-db private Resource.

Example: ${shared.my-dns.host} - The host output of the my-dns Shared Resource.

Some limitations apply when using the Humanitec Operator.

Values and Secrets #

Humanitec provides a hierarchical solution to storing and managing fixed values and secrets. This is particularly helpful for feature flags, API credentials for third-party platforms (for example, analytics, social media, monitoring, billing, etc.), and setting log-levels.

Example: ${values.myvariable} - The value of the Application variable myvariable.

Workload References #

Workloads in a microservice Application frequently need to communicate, to enable this Humanitec provides placeholders that can be used to inject URIs from the Workload’s SVC (a Kubernetes service object).

Example: ${modules.myworkload.service.name} - The in-cluster DNS name of the Workload myworkload.

List of placeholders #

In the following table, <someId> is used to indicate an ID and <value...> is used to indicate a value that may have additional sub properties. Do not include the <> characters in the actual placeholder.