Secure Links

Secure Links connect supported Opfield-managed resources without turning the destination into a general public endpoint.

The term covers narrowly scoped private connectivity with durable Opfield ownership. It does not imply that every private path uses the same runtime component. Ingress upstream links and managed database bindings have different owners, credentials, lifecycle records, and diagnostic signals.

Prerequisites and trust boundary

Both endpoints must be supported Opfield-managed resources with stable identities, and their owning Nodes must be online with compatible capabilities. Relay must be healthy and reachable from participating Nodes. The caller needs permission to read the target resource and mutate the resource that owns the relationship.

Select the application service or port that the process actually listens on. A published host port is not required merely to create a private link, and opening one does not repair a failed private path. Opfield does not create host firewall rules or make arbitrary networks reachable.

Database bindings

A managed database binding connects one eligible Container, Deployment, or Compose service to one managed database. Opfield creates a separate engine user or role for the binding and grants only the required database permissions. It delivers binding-specific connection material to the workload; the database owner credential is not exposed.

The workload reaches the database through the shared secure-link connector of its Docker Node, on a small private network of its own for the binding. There is no per-binding connector Container and no host listener to restart, inspect, or replace. The link and the engine identity are separate but coordinated records, so one workload’s credential rotation, permission change, or deletion does not silently alter another binding.

Recreating the workload keeps the binding available because authorization follows the stable Opfield resource identity rather than a transient Container ID. Opfield reconciles the link and injects current connection settings again. Deleting the binding removes the link and retires its engine identity through one recorded lifecycle; the normal path must not leave orphan roles or users.

For a failed database binding, check the managed database and Storage Node, then the target Docker Node and workload, binding desired state, the Node’s secure-link connector, engine identity and permissions, and finally application configuration. Do not delete the role, the link network, or the connector manually as a generic repair step. That can turn a recoverable mismatch into an orphaned identity or failed future reconciliation.

Container links

A container link gives a Container, Deployment, or Compose service private access to one port of another workload, on the same Node or another one. The consumer reaches the target as alias:port; the target needs no published port, and the link opens only that port, in one direction. Links within one Node stay on that Node; links between Nodes travel through the Relay.

Shared connector and link networks

From 2.11.1, every Docker Node runs one shared secure-link connector for all its database bindings, storage links, and container links. There are no per-link connector containers and no host listeners. Each link gets a small private network of its own, which the consumer joins; the connector answers the link’s alias there.

New link networks take their addresses from a dedicated range, 10.213.x.x (a /16) by default, one /26 per link, so links never use up the address pools Docker gives to your own networks. Networks created before 2.11.1 keep their addresses. The daemon skips subnets that Docker networks or the host’s own routes already use. If the range overlaps a network the Node reaches through its default route, such as a site network or a VPN behind a router, set another IPv4 range of /26 or larger in the Docker daemon’s configuration file, /etc/docker-daemon/config.yaml:

docker:
  secure_links:
    subnet_pool: "<IPv4 range in CIDR notation>"

Restart the Docker daemon after the change. Only new link networks use the new range; existing ones keep theirs until their link is recreated.

When the connector itself is updated, its open connections are kept for up to 30 minutes, then closed once; clients reconnect to the new connector.

Ingress upstream links

Routes and Additional Routes can target supported Docker resources through a Secure Link. Opfield validates the selected resource and application port, creates the relationship, and reconciles an Opfield-owned connector through Relay. The connector used for nginx-to-workload traffic is a real runtime component, but it remains outside ordinary user lifecycle APIs.

A link created by a managed Route belongs to that Route. It is visible for diagnosis but cannot be deleted independently; disabling the Route preserves its configuration and relationship, while deleting the Route retires the owned binding after reconciliation. Workload restart or recreation keeps the link because the Route targets the stable Opfield resource. Deployment promotion and Compose revision changes resolve the active runtime behind the same higher-level identity.

In 2.11, the Secure Link listeners on an Ingress Node keep accepting under load. Before, from 2.10.0 on, the nginx daemon checked every new connection with a full nginx configuration dump, so an Ingress Node stalled beyond roughly 100 new Secure Link connections per second and kept failing requests long after the load dropped. Now the check uses cached process information: a single-core Ingress Node handles thousands of new connections per second, connections beyond 1024 in setup are refused at once so nginx fails over quickly instead of queueing, connections a client already abandoned are dropped without opening a tunnel, and the listener recovers as soon as the load drops. A transient accept error, such as running out of file descriptors, no longer stops a listener until the daemon restarts.

Advanced nginx configurations can use separately managed additional bindings with their own lifecycle. Do not confuse those with Route-owned bindings. Before deleting a user-managed binding, identify every configuration that references it.

Normal flow and verification

For an Ingress upstream, choose the managed target in the Route or Additional Route editor, select the service or application port and protocol, save, and wait for both Secure Link reconciliation and nginx configuration validation. Then verify the target identity, connector state, Route health, and a real external request.

For a managed database, create the binding from the eligible workload and database, choose least-privilege access, wait for the engine identity and the link, apply the workload configuration when required, and execute a real application query. Confirm binding telemetry and both workload and database logs.

Verification should prove the intended path rather than only the existence of a record. For Ingress, inspect Relay availability, both Node connections, setup latency, active streams, throughput, completion health, admission rejects, nginx logs, and application behavior. For database bindings, inspect database readiness, link reconciliation, engine-principal state, application connectivity, and current workload configuration.

What Secure Links do not do

• They are not a general-purpose VPN or overlay network.
• They do not provide arbitrary TCP or SSH forwarding.
• They do not open host firewalls automatically.
• They do not remove the need for application-level authentication where the target protocol requires it.

They also do not transfer ownership of the target resource, make unsupported workloads portable, or authorize a user who lacks access to either side. A Secure Link is not a reason to expose daemon control interfaces, database owner ports, or internal connector credentials.

Failure and safe recovery

If an Ingress Route saves but traffic fails, check Route enabled and maintenance state, nginx revision, Relay, Ingress and Docker Node connectivity, target runtime and port, connector admission, then application logs and protocol behavior. Do not publish an internal workload port as an undocumented workaround.

If a Node or Relay interruption occurs, restore connectivity and wait for fresh capability and desired-state reconciliation before replacing identities. Preserve operation history and request IDs. If deletion is interrupted, keep the durable owner or binding record so Opfield can complete cleanup. Manual deletion of Opfield-owned connectors, networks, or engine principals is an exceptional recovery action requiring a coordinated procedure, not a first response.