Traefik Docker 라우팅 문서

원문 보기 위키 갱신 2026.10.03

출처: Traefik Docker Routing Documentation

본문

Traefik & Docker

Traefik의 가장 좋은 기능 중 하나는 라우팅 구성을 애플리케이션 레벨에 위임하는 것이에요. Docker에서는 Traefik이 컨테이너에 붙은 라벨을 활용해 라우팅 규칙을 생성할 수 있어요.

라벨과 민감 데이터

라벨에 민감 데이터(인증서, 자격 증명 등)를 저장하지 않는 것을 권장해요. 대신 민감 데이터는 더 안전한 저장소(secret, 파일 등)에 보관하는 것을 권장해요.

설정 예시

Docker 구성 & 서비스 하나 배포/노출하기 docker 프로바이더 활성화하기

Structured (YAML)

providers:
  docker: {}

Structured (TOML)

[providers.docker]

CLI

--providers.docker=true

컨테이너에 라벨 붙이기 (docker compose 파일에서)

services:
  my-container:
    # ...
    labels:
      - traefik.http.routers.my-container.rule=Host(`example.com`)

컨테이너에 사용자 지정 포트 지정하기 http://example.com 에 대한 요청을 http://:12345 로 전달해요:

services:
  my-container:
    # ...
    labels:
      - traefik.http.routers.my-container.rule=Host(`example.com`)
      # Tell Traefik to use the port 12345 to connect to `my-container`
      - traefik.http.services.my-service.loadbalancer.server.port=12345

Traefik이 잘못된 포트에 연결: HTTP/502 Gateway Error

기본적으로 Traefik은 컨테이너의 첫 번째 노출된 포트를 사용해요.

traefik.http.services.xxx.loadbalancer.server.port 라벨을 설정하면 그 동작이 재정의돼요.

컨테이너당 여러 개의 라우터와 서비스 지정하기 컨테이너의 둘 이상의 포트로 요청을 전달하려면 라우터의 service 매개변수를 사용해 서비스 로드밸런서 포트 정의를 참조해야 해요.

이 예시에서는 http://example-a.com 요청을 http://:8000 으로, http://example-b.com 요청을 http://:9000 으로 전달해요:

services:
  my-container:
    # ...
    labels:
      - traefik.http.routers.www-router.rule=Host(`example-a.com`)
      - traefik.http.routers.www-router.service=www-service
      - traefik.http.services.www-service.loadbalancer.server.port=8000
      - traefik.http.routers.admin-router.rule=Host(`example-b.com`)
      - traefik.http.routers.admin-router.service=admin-service
      - traefik.http.services.admin-service.loadbalancer.server.port=9000

설정 옵션

라벨

라벨 are case-insensitive.

TLS 기본 생성 인증서

Traefik 기본 생성 인증서를 구성하는 방법은 TLS 인증서 페이지를 참고하세요.

일반

Traefik은 각 컨테이너에 대해 해당하는 서비스와 라우터를 생성해요.

서비스는 컨테이너의 인스턴스마다 자동으로 서버를 가지며, 라우터에는 defaultRule 이 정의한 규칙이 자동으로 적용돼요 (라벨에 그 규칙이 정의되지 않은 경우).

Service 정의

일반적으로 Traefik 프로바이더를 구성할 때, 라우팅이 동작하려면 하나(또는 여러 개)의 라우터에 할당된 서비스도 정의되어 있어야 해요.

하지만 라벨 기반 구성을 사용할 때는 예외가 있어요:

라벨이 라우터를 정의하고(예: router Rule을 통해) 라벨이 서비스를 정의하는데(예: 로드밸런서 서버 포트 값을 통해 암시적으로), 라우터가 어떤 서비스도 지정하지 않으면, 그 서비스가 라우터에 자동으로 할당돼요.
라벨이 라우터를 정의하고(예: router Rule을 통해) but no service is defined, 서비스가 자동으로 생성되어 라우터에 할당돼요.

예상할 수 있듯이 이 두 경우 모두에서 라우터에 서비스가 추가로 지정되어 있으면, 실제로 정의되어 있는지 다른 서비스가 정의되어 있는지와 무관하게 그 서비스가 할당돼요.

서비스 하나로 자동 할당 compose 파일의 라벨로

labels:
  - "traefik.http.routers.myproxy.rule=Host(`example.net`)"
  # service myservice gets automatically assigned to router myproxy
  - "traefik.http.services.myservice.loadbalancer.server.port=80"

라우터 하나로 자동 서비스 생성 compose 파일의 라벨로

labels:
  # no service specified or defined and yet one gets automatically created
  # and assigned to router myproxy.
  - "traefik.http.routers.myproxy.rule=Host(`example.net`)"

서비스 하나로 명시적 정의 compose 파일의 라벨로

labels:
  - traefik.http.routers.www-router.rule=Host(`example-a.com`)
  # Explicit link between the router and the service
  - traefik.http.routers.www-router.service=www-service
  - traefik.http.services.www-service.loadbalancer.server.port=8000

Router

컨테이너에 자동으로 연결된 Router의 구성을 업데이트하려면, traefik.http.routers.. 으로 시작하고 변경할 옵션이 뒤따르는 라벨을 추가하세요.

예를 들어 규칙을 변경하려면 traefik.http.routers.my-container.rule=Host(example.com) 라벨을 추가하면 돼요.

라우터 이름 ** 에는 @ 문자가 허용되지 않아요.

설정 옵션

Service

컨테이너에 자동으로 연결된 Service의 구성을 업데이트하려면, traefik.http.services.. 으로 시작하고 변경할 옵션이 뒤따르는 라벨을 추가하세요.

예를 들어 passHostHeader 동작을 변경하려면, traefik.http.services..loadbalancer.passhostheader=false 라벨을 추가하면 돼요.

서비스 이름 ** 에는 @ 문자가 허용되지 않아요.

설정 옵션

Middleware

traefik.http.middlewares.. 으로 시작하는 라벨을 사용해 미들웨어를 선언할 수 있어요. 그 뒤에 미들웨어 타입/옵션이 이어져요.

예를 들어 my-redirect 라는 이름의 redirectscheme 미들웨어를 선언하려면, traefik.http.middlewares.my-redirect.redirectscheme.scheme=https 라고 쓰면 돼요.

사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션을 참고하세요.

미들웨어 이름에는 @ 문자가 허용되지 않아요.

미들웨어 선언 및 참조하기

   services:
     my-container:
       # ...
       labels:
         # Declaring a middleware
         - traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
         # Referencing a middleware
         - traefik.http.routers.my-container.middlewares=my-redirect

선언 충돌

이름은 같은데 매개변수가 다른 미들웨어를 여러 개 선언하면 미들웨어 선언이 실패해요.

TCP

라벨을 사용해 TCP Router 및/또는 Service를 선언할 수 있어요.

서비스 하나로 TCP Router 선언하기

   services:
     my-container:
       # ...
       labels:
         - "traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)"
         - "traefik.tcp.routers.my-router.tls=true"
         - "traefik.tcp.services.my-service.loadbalancer.server.port=4123"

TCP와 HTTP

TCP Router/Service를 선언하면 Traefik이 HTTP Router/Service를 자동으로 생성하는 것을 막아요 (TCP Router/Service가 정의되지 않으면 기본적으로 생성하듯이요). 같은 컨테이너에 TCP Router/Service와 HTTP Router/Service를 모두 선언할 수 있어요 (단, 수동으로 해야 해요).

TCP Router

TCP Service

TCP Middleware

You can declare pieces of middleware using tags starting with traefik.tcp.middlewares.{name-of-your-choice}., 그 뒤에 미들웨어 타입/옵션이 이어져요.

예를 들어 test-inflightconn 이라는 이름의 InFlightConn 미들웨어를 선언하려면 traefik.tcp.middlewares.test-inflightconn.inflightconn.amount=10 이라고 쓰면 돼요.

사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션을 참고하세요.

미들웨어 선언 및 참조하기

# ...
# Declaring a middleware
traefik.tcp.middlewares.test-inflightconn.inflightconn.amount=10
# Referencing a middleware
traefik.tcp.routers.my-service.middlewares=test-inflightconn

선언 충돌

이름은 같은데 매개변수가 다른 미들웨어를 여러 개 선언하면 미들웨어 선언이 실패해요.

UDP

라벨을 사용해 UDP Router 및/또는 Service를 선언할 수 있어요.

서비스 하나로 UDP Router 선언하기

   services:
     my-container:
       # ...
       labels:
         - "traefik.udp.routers.my-router.entrypoints=udp"
         - "traefik.udp.services.my-service.loadbalancer.server.port=4123"

UDP와 HTTP

UDP Router/Service를 선언하면 Traefik이 HTTP Router/Service를 자동으로 생성하는 것을 막아요 (UDP Router/Service가 정의되지 않으면 기본적으로 생성하듯이요). 같은 컨테이너에 UDP Router/Service와 HTTP Router/Service를 모두 선언할 수 있어요 (단, 수동으로 해야 해요).

UDP Router

UDP Service

특정 프로바이더 옵션

| Label | Description | Value | | traefik.enable | traefik.enable 을 true 또는 false로 설정해 Traefik이 컨테이너를 고려할지(또는 하지 않을지) 지정할 수 있어요. 이 옵션은 exposedByDefault 값을 재정의해요. | true | | traefik.docker.allownonrunning | 기본적으로 Traefik은 "running" 상태의 컨테이너만 고려해요. 이 옵션은 "running" 상태가 아닌 컨테이너(예: stopped, paused, exited)가 서비스 발견을 위해 Traefik에 여전히 보여야 하는지 제어해요. 이 라벨을 true로 설정하면 Traefik은: - 컨테이너가 실행 중이 아니어도 라우터와 서비스 구성을 유지하고 - 빈 백엔드 서버 목록으로 서비스를 만들며 - 중지된 컨테이너에 대한 요청에 (404 Not Found 대신) 503 Service Unavailable을 반환하고 - 전체 미들웨어 체인을 실행해 미들웨어가 요청을 가로챌 수 있게 해요. traefik.docker.allownonrunning 은 이 옵션을 노출하는 모든 컨테이너를 상태와 무관하게 발견하게 하므로, 중지된 여러 컨테이너가 같은 라우터를 노출하는데 구성이 서로 다르면 라우터가 드롭돼요. | true | | traefik.docker.network | 컨테이너에 대한 연결에 사용할 기본 docker 네트워크를 재정의해요. 컨테이너가 여러 네트워크에 연결되어 있다면 올바른 네트워크 이름을 설정해야 해요 (docker inspect 로 확인할 수 있어요). 그렇지 않으면 (docker가 반환하는 방식에 따라) 임의로 하나를 선택할 거예요. compose 파일에서 스택을 배포할 때 정의된 네트워크에는 stack 프리픽스가 붙어요. | mynetwork |

더 알아보기 (Learn more)

Traefik 공식 문서