Runtime templates

Added in v0.21.0

Runtime templates let service configuration use metadata that is only known when Uncloud creates a container. They use Go template syntax.

Uncloud renders runtime templates on the destination machine before it creates each container. This means that every replica can receive a value based on its own container metadata.

Available metadata

Runtime templates currently expose the following fields:

Field	Description	Example
`.Container.Name`	Name assigned to the container	`app-c1zd`

Supported template locations

You can currently use runtime templates in these locations of a service definition:

Location	Compose attribute
Host path of a bind mount	`volumes[].source` or `volumes` short-syntax `- /host/path:/container/path`
Mount path inside the container	`volumes[].target` or `volumes` short-syntax `- /host/path:/container/path`

:::tip Want other locations or metadata fields?

If you want to use runtime templates in other locations, such as environment variable, or use other metadata fields, add a 👍 reaction or comment with your use case on the issue #431.

:::

Use runtime templates in a Compose file

The following service gets a separate host path for every replica:

services:
  app:
    image: app:latest
    volumes:
      - "/var/lib/app/{{.Container.Name}}:/data"
    scale: 2

If Uncloud names the containers app-c1zd and app-f7kx, their host paths are /var/lib/app/app-c1zd and /var/lib/app/app-f7kx.

You can combine runtime templates with Compose environment interpolation:

volumes:
  - "${DATA_ROOT:-/var/lib/app}/{{.Container.Name}}:/data"

Uncloud expands the DATA_ROOT environment variable on the local machine first and renders .Container.Name later on the destination machine.

Use runtime templates with `uc run`

Quote the volume argument so your shell passes the template through unchanged:

uc run --replicas 2 \
  --volume "/var/lib/app/{{.Container.Name}}:/data" \
  app:latest

:::warning Clean up templated host directories

Uncloud does not remove host directories created for bind mounts when it replaces a container or removes a service. If a runtime template gives each container a unique host directory, you are responsible for cleaning up directories that are no longer needed.

If you only need per-container ephemeral storage, consider a tmpfs mount. An anonymous volume declared by the Docker image can also provide Docker-managed disk storage for each container. Use a named volume or a stable bind mount path for data that must remain available across container replacements.

:::