Container Links

A container link gives one workload, the consumer, private access to one TCP port of another workload, the target. The consumer reaches the target as alias:port; the target needs no published port, and nothing else is opened. Consumer and target can each be a Container, a Deployment, or a Compose service, on the same Docker Node or on different ones.

Use a container link when an application needs to call an internal service of another workload, such as an API, a queue, or a cache, without publishing that service on the host or sharing a Docker network between the two. For managed databases and managed object storage, use database bindings and storage links instead: they also deliver credentials.

Requirements

• Plan: Personal or higher. Existing links keep working after a license change; creating a link needs the current plan. See Plans and entitlements.
• Docker daemon: both Nodes, the consumer’s and the target’s, need the 2.11.1 Docker daemon or later. A link whose Node runs an older daemon shows update required until the daemon is updated.
• Permissions: on the consumer, docker:containers:edit (docker:compose:manage for a Compose service), plus docker:containers:environment when the link sets variables; on the target, docker:containers:link (docker:compose:manage for a Compose service). The target owner grants docker:containers:link to let other workloads reach it without giving them any other access. See the Scope reference.

Create a link

1. Open the consumer: the Environment tab of a Container or Deployment, or the Variables tab of a Compose Project.
2. In Container Links, select Add. For a Compose Project, choose the consumer Service.
3. Choose the Target type and the target workload, on any Docker Node, and the TCP Port of the target to open.
4. Check the Alias. It defaults to the target’s name and is the name the consumer connects to: lower-case letters, numbers, and hyphens, unique among the consumer’s links.
5. Optionally fill Environment variables for the host, the port, or a URL (http://alias:port), for example API_HOST, API_PORT, or API_URL. Setting variables recreates the consumer once so that it starts with them; a link without variables does not restart the consumer.
6. Save and wait until the link shows ready, then make a real request from the consumer to alias:port.

Incoming Links on the target lists the workloads that reach it. A link is removed from the consumer’s Container Links; removing it drops the alias and, when the link set variables, removes them with one more recreate.

API and MCP

Action	REST	MCP and assistant
List a workload’s links	GET /api/docker/container-links?nodeId=&type=&resourceId=&direction=outgoing|incoming	manage_container_link list
Create a link	POST /api/docker/container-links	manage_container_link create
Read a link and its runtime	GET /api/docker/container-links/{id} and /{id}/runtime	manage_container_link get_runtime
Delete a link	DELETE /api/docker/container-links/{id}	manage_container_link delete

A workload is identified by its Node, its type (container, deployment, or compose_service), and its resource: the container name, the Deployment ID, or <compose-project-id>:<service-name>. The runtime shows open connections, sessions, throughput, and refused connections, as for database and storage links.

Statuses

Status	Meaning	What to do
ready	The consumer reaches the target.	Nothing.
pending	The link is saved; the consumer takes it with its next start or rollout.	Start the consumer or finish its rollout.
waiting	The target does not run, or no copy of it serves.	Start the target; the link serves again on its own.
update required	The consumer’s or the target’s Node runs a Docker daemon older than 2.11.1.	Update the Docker daemon on that Node.
error	The link could not be set up; the message says why.	Fix the cause; Opfield retries the link on its own.

How traffic flows

Every Docker Node runs one shared secure-link connector for all its links. The consumer joins a small private network of its own for the link, and the connector answers the alias there. Link networks take their addresses from a dedicated range; see Shared connector and link networks.

• Same Node: the connector passes each connection straight to the target.
• Different Nodes: the connection travels through the Relay to the target’s Node, authenticated at both ends, as for any other Secure Link.

A link opens exactly one port of the target, in one direction: the consumer can reach that port, and nothing else of the target. The target cannot reach the consumer through the link, and other workloads cannot use it. The link network belongs to the link alone.

Availability targets

When the target runs under Workload Availability, the link follows the healthy copies:

• each consumer Node prefers a copy on its own Node and uses another healthy copy otherwise;
• when Availability judges a copy unhealthy, the link moves its connections to a healthy copy at once;
• a copy that recovers gets link traffic back only after Availability reports it passing its health checks again; a restarted copy whose health is not known yet does not count as passing;
• when no copy is healthy, the link stays on the copies that still serve, as Availability’s routes do.

An Availability Deployment is reached through its router, which forwards only the Deployment’s own ports. The link’s port must therefore be one of the Deployment’s ports; otherwise the link is refused when it is created, or goes to error with the reason when the Deployment’s ports change.

Troubleshooting

• The consumer cannot resolve the alias: check that the link is ready and that the application uses the alias, not the target’s container name.
• Connections are refused: check that the target listens on the link’s port inside its container, and that the link’s port is the container port, not a host port.
• update required: update the Docker daemon on the Node the message names; nothing else needs to change.
• waiting: the target is stopped, or no Availability copy serves; start or heal the target.