Skip to content

Multiple public IPs per container

Assigning more than one public IPv4 / IPv6 address to a single container on Stack Harbor PaaS — typical use cases, the primary-IP rule, and the API methods that drive it.

A single container on the platform can hold multiple public IP addresses — any mix of IPv4 and IPv6. Each address is independently routable from the public internet, so one container can serve multiple production-grade endpoints with different DNS names and TLS certificates.

When you need this

The two common patterns:

  • Multi-tenant hosting on one node. Several websites on the same container, each with its own custom domain and its own SSL certificate.
  • Network appliances with multiple addresses. A load balancer or front-end that needs an IP on each of several upstream segments.

If your application can do it with one IP, do it with one IP — multiple IPs is a tool for cases where you genuinely need address-level separation.

Attaching IPs from the dashboard

Use the topology wizard. When creating an environment or editing its topology, the per-node panel exposes two spinners — Public IPv4 and Public IPv6. Set each to the number of addresses you want on the node.

If you hit a quota limit, contact your hosting administrator about raising it.

How attached IPs appear

On the main dashboard, each node shows:

LabelWhat it is
Private IPAuto-attached internal address, always listed first
Public IPv4Single address or expandable list of all v4 addresses
Public IPv6Single address or expandable list of all v6 addresses

Per-address actions:

  • Copy to clipboard — copies the address
  • Detach — removes the address

Per-node action:

  • Attach / Detach IP(s) — adjusts the total count of attached IPs of one version

Apply commits the change.

The primary-IP rule

The first IPv4 attached is the primary IPv4. The first IPv6 attached is the primary IPv6. Per version:

  • Outbound traffic from the container goes out the primary IP.
  • Inbound traffic can arrive on any of the attached IPs.
  • The primary IP can only be detached when no other IP of the same version is attached.

This is the rule that keeps outbound traffic stable while you rotate or grow the set of inbound addresses.

Connecting over SSH

When you SSH into the environment, the container’s full network view is printed in the topology details:

  • LAN IP column — the container’s internal address
  • WAN IP column — the public addresses, IPv4 first then IPv6

The order matches what the dashboard shows.

API reference

Setting the IP count

The SetExtIpCount method attaches or detaches public IPs:

https://{platform-api-host}/1.0/environment/control/rest/setextipcount
  ?envname={envname}
  &session={session}
  &type={ipv4|ipv6}
  &count={count}
  &nodegroup={nodegroup}
  &nodeid={nodeid}
ParameterDescription
envnameSource environment name
sessionCurrent user session ID
typeipv4 or ipv6
countThe desired number of IPs on the node
nodegroupOne of bl, cp, sqldb, nosqldb, storage, vps, build
nodeidDestination node ID

count is the absolute target, not a delta. To increase or reduce, pass the new total.

The older AttachExtIp / DetachExtIp methods are deprecated but kept for backward compatibility.

Swapping IPs between nodes

SwapExtIps exchanges IPs between two nodes (same environment or different environments):

https://{platform-api-host}/1.0/environment/control/rest/swapextips
  ?envname={envname}
  &session={session}
  &sourcenodeid={sourcenodeid}
  &destnodeid={destnodeid}
  &sourceip={sourceip}
  &destip={destip}
ParameterDescription
envnameSource environment name
sessionCurrent user session ID
sourcenodeidSource node ID
destnodeidDestination node ID (may belong to a different environment)
sourceipPublic IP on the source node to swap (optional)
destipPublic IP on the destination node to swap (optional)

Omit sourceip / destip to swap all public IPs between the two nodes.

SwapExtIps works with IPv4 only.

See also