Skip to content

Containers Updated 2026-05-27

Container links

Link containers across layers of a Stack Harbor PaaS environment to propagate environment variables and resolve DNS aliases between tiers.

The Stack Harbor PaaS exposes a Links mechanism that wires two layers of a single environment together. Once a layer is linked, containers in the source layer receive a curated set of environment variables from the target layer’s image, prefixed with the link alias, and gain a DNS name they can use to reach individual target containers or the layer as a whole.

This is the recommended way to pass connection details between application tiers — an app server discovering a database layer, a load balancer discovering an app tier — without exposing ports externally and without hard-coding addresses.

Container links are configured per layer through the topology wizard or the layer settings panel:

  1. Open the layer that should receive the link (the consumer side).
  2. In the Links section, click Add.
  3. Pick the target layer from the Node dropdown.
  4. Provide an Alias — a short identifier that becomes the prefix for imported variables and the DNS alias for the layer. For example, an alias of db exposes db_HOST, db_PORT (depending on what the source image declares as variables) and registers db_1, db_2, … as DNS names for individual target containers.
  5. Click Save, then Apply the topology change.

A layer can hold any number of links, each with its own alias. The same target layer can be linked from multiple consumer layers — every link gets its own DNS namespace.

Applying a link restarts the consumer-layer containers so the new environment variables and DNS records take effect. Plan around the short downtime.

When a link is applied, the platform registers DNS entries that resolve only between the linked layers — they are not visible to the rest of the platform or the internet. For a link with alias db:

  • db_1, db_2, db_N resolve to specific target containers. The master container is always db_1. The remaining containers are sorted by nodeID ascending and assigned db_2, db_3, and so on.
  • db (without an index suffix) resolves through round-robin to any container in the target layer. Useful for even load distribution against stateless targets.

You can confirm the records resolve using ping, host, or dig from a container in the source layer.

Updating environment variables on linked layers

Editing a variable on the target layer propagates automatically to every consumer that is linked to it — there is no need to re-apply the link. The target image’s variable schema is the contract; consumers pick up changes on the next variable refresh.

Unlinking, on the other hand, removes the imported variables and DNS records from the consumer layer and again restarts the consumer containers.

If two containers just need to talk to each other and you already know the target’s hostname, you can skip the link mechanism — the platform’s internal DNS resolves layer and container hostnames natively (see DNS hostnames for direct connection to containers).

Use links when:

  • the source image expects connection details as environment variables (the typical pattern for Docker Hub stack images),
  • you want round-robin DNS across a target layer without standing up a separate service,
  • you want the source layer to restart automatically when target topology changes warrant it.

See also