Traefik 파일 라우팅 구성

원문 보기 위키 갱신 2026.10.03

출처: Traefik File Routing Configuration

본문

Traefik 파일 라우팅 구성

파일 프로바이더는 YAML 또는 TOML로 라우팅 구성을 정의할 수 있게 해줘요.

이를 사용해 Traefik이 파일이나 디렉토리에서 로드해야 하는 라우터, 서비스, 미들웨어, TCP·UDP 라우팅, TLS 옵션을 선언할 수 있어요.

파일 프로바이더 자체를 구성하는 방법은 파일 프로바이더 설치 구성 페이지를 참고하세요.

설정 예시

파일 프로바이더 구성하고 HTTP 서비스 하나 노출하기 파일 프로바이더 활성화하기:

구조화 (YAML)

providers:
  file:
    filename: /etc/traefik/dynamic.yml

구조화 (TOML)

[providers.file]
  filename = "/etc/traefik/dynamic.toml"

CLI

--providers.file.filename=/etc/traefik/dynamic.yml

동적 HTTP 구성 선언하기:

구조화 (YAML)

http:
  routers:
    app:
      rule: Host(`example.com`)
      entryPoints:
        - websecure
      service: app
      tls: {}

  services:
    app:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:8080

구조화 (TOML)

[http.routers.app]
  rule = "Host(`example.com`)"
  entryPoints = ["websecure"]
  service = "app"

  [http.routers.app.tls]

[http.services.app.loadBalancer]
  [[http.services.app.loadBalancer.servers]]
    url = "http://127.0.0.1:8080"

라우터와 서비스를 여러 개 지정하기 각 라우터를 정의하고 일치하는 요청을 처리할 서비스에 명시적으로 연결하세요.

구조화 (YAML)

http:
  routers:
    app:
      rule: Host(`example-a.com`)
      service: app
    admin:
      rule: Host(`example-b.com`)
      service: admin

  services:
    app:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:8000
    admin:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:9000

구조화 (TOML)

[http.routers.app]
  rule = "Host(`example-a.com`)"
  service = "app"

[http.routers.admin]
  rule = "Host(`example-b.com`)"
  service = "admin"

[http.services.app.loadBalancer]
  [[http.services.app.loadBalancer.servers]]
    url = "http://127.0.0.1:8000"

[http.services.admin.loadBalancer]
  [[http.services.admin.loadBalancer.servers]]
    url = "http://127.0.0.1:9000"

미들웨어 선언 및 참조하기 파일 프로바이더가 선언한 미들웨어는 파일 프로바이더의 라우터나 다른 프로바이더의 라우터가 사용할 수 있어요.

다른 프로바이더가 이를 참조할 때는 @file 프로바이더 접미사를 사용해요.

구조화 (YAML)

http:
  routers:
    app:
      rule: Host(`secure.example.com`)
      entryPoints:
        - websecure
      middlewares:
        - secure-headers
      service: app
      tls:
        options: modern

  middlewares:
    secure-headers:
      headers:
        stsSeconds: 31536000
        forceSTSHeader: true

  services:
    app:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:8080

tls:
  options:
    modern:
      minVersion: VersionTLS12
      sniStrict: true

구조화 (TOML)

[http.routers.app]
  rule = "Host(`secure.example.com`)"
  entryPoints = ["websecure"]
  middlewares = ["secure-headers"]
  service = "app"

  [http.routers.app.tls]
    options = "modern"

[http.middlewares.secure-headers.headers]
  stsSeconds = 31536000
  forceSTSHeader = true

[http.services.app.loadBalancer]
  [[http.services.app.loadBalancer.servers]]
    url = "http://127.0.0.1:8080"

[tls.options.modern]
  minVersion = "VersionTLS12"
  sniStrict = true

여러 동적 구성 파일 로드하기 동적 구성을 여러 파일로 나누고 싶다면 디렉토리로 파일 프로바이더를 구성하세요.

구조화 (YAML)

providers:
  file:
    directory: /etc/traefik/dynamic
    watch: true

구조화 (TOML)

[providers.file]
  directory = "/etc/traefik/dynamic"
  watch = true

CLI

--providers.file.directory=/etc/traefik/dynamic
--providers.file.watch=true

/etc/traefik/dynamic/http.yml 예시:

http:
  routers:
    app:
      rule: Host(`example.com`)
      service: app

  services:
    app:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:8080

/etc/traefik/dynamic/tls.yml 예시:

tls:
  certificates:
    - certFile: /certs/example.crt
      keyFile: /certs/example.key

설정 옵션

일반

파일 프로바이더는 서비스를 자동으로 발견하지 않아요.

모든 라우터, 서비스, 미들웨어, TLS 리소스를 라우팅 구성 파일에 명시적으로 정의하세요.

다른 프로바이더가 파일 프로바이더가 선언한 리소스를 참조할 때는 @file 프로바이더 접미사를 추가하세요.

예를 들어 Docker 라벨은 secure-headers@file 로 파일 프로바이더 미들웨어를 참조할 수 있어요.

아래 예시들은 YAML 스타일 필드 경로를 사용해요.

TOML에서는 동등한 테이블·배열 문법을 사용하세요. 예: [http.routers.] 및 [[http.services..loadBalancer.servers]].

HTTP

Router

http.routers. 아래에 HTTP 라우터를 정의하세요.

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

| 필드 | 설명 | 값 | | http.routers..rule | rule에 대한 자세한 내용은 rule을 참고하세요. | Host(example.com) | | http.routers..ruleSyntax | ruleSyntax에 대한 자세한 내용은 ruleSyntax를 참고하세요. RuleSyntax는 더 이상 사용되지 않으며 다음 메이저 버전에서 제거될 예정이에요. | v3 | | http.routers..entryPoints[n] | 엔트리 포인트에 대한 자세한 내용은 엔트리 포인트를 참고하세요. | websecure | | http.routers..middlewares[n] | 미들웨어 개요에 대한 자세한 내용은 미들웨어 개요를 참고하세요. | secure-headers | | http.routers..service | 서비스에 대한 자세한 내용은 서비스를 참고하세요. | app | | http.routers..parentRefs[n] | 다중 레이어 라우팅에 대한 자세한 내용은 다중 레이어 라우팅을 참고하세요. | parent-router@file | | http.routers..tls | TLS에 대한 자세한 내용은 TLS를 참고하세요. | {} | | http.routers..tls.certResolver | certResolver에 대한 자세한 내용은 certResolver를 참고하세요. | myresolver | | http.routers..tls.domains[n].main | 도메인에 대한 자세한 내용은 도메인을 참고하세요. | example.org | | http.routers..tls.domains[n].sans[n] | 도메인에 대한 자세한 내용은 도메인을 참고하세요. | www.example.org | | http.routers..tls.options | TLS 옵션에 대한 자세한 내용은 TLS 옵션을 참고하세요. | modern | | http.routers..observability.accessLogs | 라우터에 대한 액세스 로그를 활성화하거나 비활성화해요. | true | | http.routers..observability.metrics | 라우터에 대한 메트릭을 활성화하거나 비활성화해요. | true | | http.routers..observability.tracing | 라우터에 대한 트레이싱을 활성화하거나 비활성화해요. | true | | http.routers..observability.traceVerbosity | 트레이스 상세도에 대한 자세한 내용은 트레이스 상세도를 참고하세요. | minimal | | http.routers..priority | 우선순위에 대한 자세한 내용은 우선순위를 참고하세요. | 42 |

Service

http.services. 아래에 HTTP 서비스를 정의하세요.

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

| 필드 | 설명 | 값 | | http.services..loadBalancer.servers[n].url | 서버에 대한 자세한 내용은 서버를 참고하세요. | http://127.0.0.1:8080 | | http.services..loadBalancer.servers[n].weight | 서버에 대한 자세한 내용은 서버를 참고하세요. | 1 | | http.services..loadBalancer.servers[n].preservePath | 서버에 대한 자세한 내용은 서버를 참고하세요. | true | | http.services..loadBalancer.strategy | 로드 밸런싱 전략에 대한 자세한 내용은 로드 밸런싱 전략을 참고하세요. | wrr | | http.services..loadBalancer.passHostHeader | 서비스 로드 밸런서에 대한 자세한 내용은 서비스 로드 밸런서를 참고하세요. | true | | http.services..loadBalancer.healthCheck.* | 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. | path: /health | | http.services..loadBalancer.passiveHealthCheck.* | 수동 헬스 체크에 대한 자세한 내용은 수동 헬스 체크를 참고하세요. | maxFailedAttempts: 3 | | http.services..loadBalancer.sticky.cookie.* | 스티키 세션에 대한 자세한 내용은 스티키 세션을 참고하세요. | name: app-cookie | | http.services..loadBalancer.responseForwarding.flushInterval | 서비스 로드 밸런서에 대한 자세한 내용은 서비스 로드 밸런서를 참고하세요. | 100ms | | http.services..loadBalancer.serversTransport | ServersTransport에 대한 자세한 내용은 ServersTransport를 참고하세요. | secure-transport | | http.services..weighted.services[n].name | 가중 라운드 로빈에 대한 자세한 내용은 가중 라운드 로빈을 참고하세요. | app-v1 | | http.services..weighted.services[n].weight | 가중 라운드 로빈에 대한 자세한 내용은 가중 라운드 로빈을 참고하세요. | 3 | | http.services..weighted.sticky.cookie.* | 스티키 세션에 대한 자세한 내용은 스티키 세션을 참고하세요. | name: app-cookie | | http.services..weighted.healthCheck | 가중 서비스 헬스 체크에 대한 자세한 내용은 가중 서비스 헬스 체크를 참고하세요. | {} | | http.services..highestRandomWeight.services[n].name | highest random weight에 대한 자세한 내용은 highest random weight를 참고하세요. | app-v1 | | http.services..highestRandomWeight.services[n].weight | highest random weight에 대한 자세한 내용은 highest random weight를 참고하세요. | 3 | | http.services..highestRandomWeight.healthCheck | highest random weight에 대한 자세한 내용은 highest random weight를 참고하세요. | {} | | http.services..mirroring.service | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | app-main | | http.services..mirroring.mirrorBody | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | true | | http.services..mirroring.maxBodySize | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | 1048576 | | http.services..mirroring.mirrors[n].name | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | app-shadow | | http.services..mirroring.mirrors[n].percent | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | 10 | | http.services..mirroring.healthCheck | 미러링에 대한 자세한 내용은 미러링을 참고하세요. | {} | | http.services..failover.service | 장애 조치에 대한 자세한 내용은 장애 조치를 참고하세요. | app-main | | http.services..failover.fallback | 장애 조치에 대한 자세한 내용은 장애 조치를 참고하세요. | app-backup | | http.services..failover.healthCheck | 장애 조치에 대한 자세한 내용은 장애 조치를 참고하세요. | {} |

Middleware

http.middlewares. 아래에 HTTP 미들웨어를 정의하세요.

예를 들어 add-api 라는 이름의 AddPrefix 미들웨어를 선언하려면 http.middlewares.add-api.addPrefix.prefix=/api 로 설정하세요.

사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션에서 찾을 수 있어요.

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

선언 충돌

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

| 필드 | 설명 | 값 | | http.middlewares... | middleware_type 은 addPrefix 나 headers 같은 미들웨어 타입이고, middleware_option 은 설정할 옵션이에요. | prefix: /api |

ServersTransports

http.serversTransports. 아래에 HTTP ServersTransports를 정의하세요.

| 필드 | 설명 | 값 | | http.serversTransports..* | ServersTransport에 대한 자세한 내용은 ServersTransport를 참고하세요. | serverName: example.org |

TCP

파일 프로바이더로 TCP 라우터, 서비스, 미들웨어, ServersTransports를 선언할 수 있어요.

TCP Router

tcp.routers. 아래에 TCP 라우터를 정의하세요.

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

| 필드 | 설명 | 값 | | tcp.routers..entryPoints[n] | 엔트리 포인트에 대한 자세한 내용은 엔트리 포인트를 참고하세요. | websecure | | tcp.routers..rule | rule에 대한 자세한 내용은 rule을 참고하세요. | HostSNI(example.com) | | tcp.routers..ruleSyntax | 라우터별로 규칙을 파싱하는 데 사용할 규칙 문법을 구성해요. RuleSyntax는 더 이상 사용되지 않으며 다음 메이저 버전에서 제거될 예정이에요. | v3 | | tcp.routers..middlewares[n] | TCP 미들웨어 개요에 대한 자세한 내용은 TCP 미들웨어 개요를 참고하세요. | ip-allowlist | | tcp.routers..service | 서비스에 대한 자세한 내용은 서비스를 참고하세요. | tcp-app | | tcp.routers..tls | TLS에 대한 자세한 내용은 TLS를 참고하세요. | {} | | tcp.routers..tls.certResolver | certResolver에 대한 자세한 내용은 certResolver를 참고하세요. | myresolver | | tcp.routers..tls.domains[n].main | TLS에 대한 자세한 내용은 TLS를 참고하세요. | example.org | | tcp.routers..tls.domains[n].sans[n] | TLS에 대한 자세한 내용은 TLS를 참고하세요. | www.example.org | | tcp.routers..tls.options | TLS에 대한 자세한 내용은 TLS를 참고하세요. | modern | | tcp.routers..tls.passthrough | Passthrough에 대한 자세한 내용은 Passthrough를 참고하세요. | true | | tcp.routers..priority | 우선순위에 대한 자세한 내용은 우선순위를 참고하세요. | 42 |

TCP Service

tcp.services. 아래에 TCP 서비스를 정의하세요.

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

| 필드 | 설명 | 값 | | tcp.services..loadBalancer.servers[n].address | servers 로드 밸런서에 대한 자세한 내용은 servers 로드 밸런서를 참고하세요. | 127.0.0.1:9000 | | tcp.services..loadBalancer.servers[n].tls | 백엔드 서버에 다이얼할 때 TLS를 사용할지 여부를 결정해요. | true | | tcp.services..loadBalancer.serversTransport | TCP ServersTransport에 대한 자세한 내용은 TCP ServersTransport를 참고하세요. | secure-tcp | | tcp.services..loadBalancer.proxyProtocol.version | 백엔드 연결에 대해 Proxy Protocol을 활성화해요. | 2 | | tcp.services..loadBalancer.terminationDelay | 연결 종료 전 지연을 정의해요. | 100 | | tcp.services..loadBalancer.healthCheck.* | TCP 서비스 헬스 체크에 대한 자세한 내용은 TCP 서비스 헬스 체크를 참고하세요. | interval: 10s | | tcp.services..weighted.services[n].name | 가중 라운드 로빈에 대한 자세한 내용은 가중 라운드 로빈을 참고하세요. | tcp-v1 | | tcp.services..weighted.services[n].weight | 가중 라운드 로빈에 대한 자세한 내용은 가중 라운드 로빈을 참고하세요. | 3 | | tcp.services..weighted.healthCheck | 가중 라운드 로빈에 대한 자세한 내용은 가중 라운드 로빈을 참고하세요. | {} |

TCP Middleware

tcp.middlewares. 아래에 TCP 미들웨어를 정의하세요.

예를 들어 limit 이라는 이름의 InFlightConn 미들웨어를 선언하려면 tcp.middlewares.limit.inFlightConn.amount=10 으로 설정하세요.

사용 가능한 미들웨어에 대한 자세한 내용은 전용 TCP 미들웨어 섹션에서 확인할 수 있어요.

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

선언 충돌

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

| 필드 | 설명 | 값 | | tcp.middlewares... | middleware_type 은 inFlightConn 같은 미들웨어 타입이고, middleware_option 은 설정할 옵션이에요. | amount: 10 |

TCP ServersTransports

tcp.serversTransports. 아래에 TCP ServersTransports를 정의하세요.

| 필드 | 설명 | 값 | | tcp.serversTransports..* | TCP ServersTransport에 대한 자세한 내용은 TCP ServersTransport를 참고하세요. | dialTimeout: 30s |

UDP

파일 프로바이더로 UDP 라우터와 서비스를 선언할 수 있어요.

UDP Router

udp.routers. 아래에 UDP 라우터를 정의하세요.

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

| 필드 | 설명 | 값 | | udp.routers..entryPoints[n] | UDP 라우터 엔트리 포인트에 대한 자세한 내용은 UDP 라우터 엔트리 포인트를 참고하세요. | dns | | udp.routers..service | UDP 라우터 구성에 대한 자세한 내용은 UDP 라우터 구성을 참고하세요. | dns-service |

UDP Service

udp.services. 아래에 UDP 서비스를 정의하세요.

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

| 필드 | 설명 | 값 | | udp.services..loadBalancer.servers[n].address | UDP 서비스에 대한 자세한 내용은 UDP 서비스를 참고하세요. | 127.0.0.1:5353 | | udp.services..weighted.services[n].name | UDP 서비스에 대한 자세한 내용은 UDP 서비스를 참고하세요. | dns-v1 | | udp.services..weighted.services[n].weight | UDP 서비스에 대한 자세한 내용은 UDP 서비스를 참고하세요. | 3 |

TLS

파일 프로바이더로 TLS 인증서, 옵션, 스토어를 선언할 수 있어요.

인증서

TLS 옵션

TLS 스토어

Go 템플릿

경고

Go 템플릿은 전용 동적 구성 파일에서만 작동해요.

템플릿은 Traefik 메인 정적 구성 파일에서는 작동하지 않아요.

Traefik은 Go 템플릿을 사용해 구성 파일의 반복적인 섹션을 자동으로 생성하는 것을 지원해요.

이 섹션들은 유효한 Go 템플릿이어야 하며, sprig 템플릿 함수를 사용할 수 있어요.

예를 들어 다음 예시들에서 설명한 대로 여러 라우터, 서비스, TLS 인증서를 쉽게 정의할 수 있어요:

템플릿을 사용한 구성

YAML

http:
  routers:
    {{range $i, $e := until 100 }}
    router{{ $e }}-{{ env "MY_ENV_VAR" }}:
      # ...
    {{end}}

  services:
    {{range $i, $e := until 100 }}
    application{{ $e }}:
      # ...
    {{end}}

tcp:
  routers:
    {{range $i, $e := until 100 }}
    router{{ $e }}:
      # ...
    {{end}}

  services:
    {{range $i, $e := until 100 }}
    service{{ $e }}:
      # ...
    {{end}}

tls:
  certificates:
  {{ range $i, $e := until 10 }}
  - certFile: "/etc/traefik/cert-{{ $e }}.pem"
    keyFile: "/etc/traefik/cert-{{ $e }}.key"
    stores:
    - "my-store-foo-{{ $e }}"
    - "my-store-bar-{{ $e }}"
  {{end}}

TOML

# template-rules.toml
[http]

  [http.routers]
  {{ range $i, $e := until 100 }}
    [http.routers.router{{ $e }}-{{ env "MY_ENV_VAR" }}]
    # ...
  {{ end }}

  [http.services]
  {{ range $i, $e := until 100 }}
      [http.services.service{{ $e }}]
      # ...
  {{ end }}

[tcp]

  [tcp.routers]
  {{ range $i, $e := until 100 }}
    [tcp.routers.router{{ $e }}]
    # ...
  {{ end }}

  [tcp.services]
  {{ range $i, $e := until 100 }}
      [tcp.services.service{{ $e }}]
      # ...
  {{ end }}

{{ range $i, $e := until 10 }}
[[tls.certificates]]
  certFile = "/etc/traefik/cert-{{ $e }}.pem"
  keyFile = "/etc/traefik/cert-{{ $e }}.key"
  stores = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
{{ end }}

[tls.options]
{{ range $i, $e := until 10 }}
  [tls.options.TLS{{ $e }}]
  # ...
{{ end }}

더 알아보기 (Learn more)

Traefik 공식 문서