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.

Usage

Placeholders can be utilized in certain fields in Humanitec. These include:

  • labels, variables, and files in Deployment Sets.
  • driver_inputs in Resource Definitions.

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.

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

Placeholder name Location Description
containers.<containerId>.<value...> variables Metadata about a particular container in a Pod retrieved via the Kubernetes Downward API. This placeholder cannot be combined with other values that are secrets.
context.app.id labels, variables, files, driver_inputs The id of the current Application.
context.deploy.id labels, variables, files The id of the current Deployment.
⚠️ Use with care: the id will change in between Deployments and might cause unexpected Pod restarts.
context.deploy.set.id labels, variables, files The id of the Deployment Set used for the current Deployment.
⚠️ Use with care: the id will change in between Deployments and might cause unexpected Pod restarts.
context.env.id labels, variables, files, driver_inputs The id of the current Environment.
context.org.id labels, variables, files, driver_inputs The id of the current Organization.
context.res.id driver_inputs The fully qualified ID of the current Resource.
context.res.class driver_inputs The Resource Class of the current Resource.
context.res.type driver_inputs The Resource Type of the current Resource.
externals.<resourceId>.<outputName> labels, variables, files The output value provided by a private Resource.
modules.<workloadId>.service.name labels,variables, files The in-cluster DNS name of the Service exposing the Workload.
modules.<workloadId>.service.external-name labels, variables, files The DNS name of the Workload, which is generated if you expose the Workload externally.
pod.<value...> variables Metadata and Status information about the current Pod retrieved via the Kubernetes Downward API. This placeholder cannot be combined with other values that are secrets.
resources.<type#id>.outputs.<value...> driver_inputs A Resource Reference placeholder. Resolves to the output of another resource defined by type#id (#id is optional).
shared.<resourceId>.<outputName> variables, files The output value provided by a shared Resource.
values.<sharedValueId> labels, variables, files App-wide shared Values and Secrets - optionally overridden by the Environment.
Top