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.

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.

Placeholder name Description
context.app.id The id of the App in Humanitec.
context.deploy.id The id of the current deployment.
context.deploy.set.id The id of the deployment set used for the current deployment.
context.env.id The id of the Environment.
context.org.id The id of the organization.

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.

Placeholder name Description
values.{valueId} App-wide shared Values and Secrets - optionally overridden by the Environment.

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.

Placeholder name Description
externals.{resourceId}.{outputName} The output value provided by a private resource.
shared.{resourceId}.{outputName} The output value provided by a shared resource.

Each resource type defines the set of output Names that can be used as placeholders.

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

Placeholder name Description
modules.{workloadId}.service.name The in-cluster DNS name of the Workload.
modules.{workloadId}.service.external-name The DNS name of the Workload, which is generated if you expose the Workload externally.

Pod

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

Placeholder name Description
pod.metadata.name The name of the current pod.
pod.metadata.namespace The namespace that the pod is deployed in.
pod.hostIP The IP address of the Host that the Pod is running on.

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.

Placeholder name Description
containers.main.limits.cpu The maximum number of CPU cores the container may use.
containers.main.limits.ram The maximum RAM (in GiB) the container may use.
Top