Docker Compose — Aliases and Links

1 minute read

Network aliases let a service respond to multiple DNS names on a network. This is useful for backward compatibility or load balancing.

Service Aliases

services:
  api:
    image: node:20-alpine
    networks:
      backend:
        aliases:
          - api-service
          - rest-api

networks:
  backend:

Now other containers on backend can reach api via:

  • api (the service name — always available)
  • api-service
  • rest-api

Verify Aliases

docker compose up -d
docker compose exec db ping rest-api

PING rest-api (172.21.0.3): 56 data bytes
64 bytes from 172.21.0.3: seq=0 ttl=64 time=0.089 ms

Network-Specific Aliases

A service can have different aliases on different networks:

services:
  api:
    image: node:20-alpine
    networks:
      frontend:
        aliases:
          - public-api
      backend:
        aliases:
          - internal-api

networks:
  frontend:
  backend:

Static IP Addresses

You can assign a fixed IP to a service (useful for testing):

services:
  db:
    image: postgres:16
    networks:
      backend:
        ipv4_address: 172.28.0.10

networks:
  backend:
    ipam:
      config:
        - subnet: 172.28.0.0/16

The links key is legacy but still supported:

services:
  web:
    image: nginx
    links:
      - "api:backend"   # 'api' reachable as 'backend' from web

Recommendation: Use custom networks with aliases instead of links.

Summary

Feature Purpose Scope
Service name Auto DNS on all networks Always
aliases Extra DNS names Per network
ipv4_address Static IP assignment Per network
links Legacy aliases Deprecated

Quick Reference

Item Detail
aliases Extra DNS names for a service
Per-network Different aliases per network
Static IP ipv4_address with IPAM subnet
Links Legacy — use aliases instead
DNS Service name always works

You may also enjoy