Traefik EntryPoints 문서

원문 보기 위키 갱신 2026.10.03

Traefik EntryPoints 문서 (Traefik EntryPoints Documentation)

출처: Traefik EntryPoints Documentation

본문

EntryPoints (엔트리포인트)

들어오는 연결/요청을 수신하기 (Listening for Incoming Connections/Requests)

설정 예시 (Configuration Example)

파일 (YAML)

entryPoints:
  web:
    address: :80
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true
    observability:
      accessLogs: false
      metrics: false
      tracing: false

  websecure:
    address: :443
    http:
      tls: {}
      middlewares:
        - default-auth@kubernetescrd
        - default-strip@kubernetescrd

파일 (TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"
    [entryPoints.web.http]
      [entryPoints.web.http.redirections.entryPoint]
        to = "websecure"
        scheme = "https"
        permanent = true
    [entryPoints.web.observability]
      accessLogs = false
      metrics = false
      tracing = false

  [entryPoints.websecure]
    address = ":443"
    [entryPoints.websecure.http]
      middlewares = ["default-auth@kubernetescrd", "default-strip@kubernetescrd"]
      [entryPoints.websecure.http.tls]

Helm 차트 값 (Helm Chart Values)

## Values file
ports:
  web:
    port: :80
  websecure:
    port: :443
    tls:
      enabled: true
    middlewares:
      - default-auth@kubernetescrd
      - default-strip@kubernetescrd
additionalArguments:
  - --entryPoints.web.http.redirections.entryPoint.to=websecure
  - --entryPoints.web.http.redirections.entryPoint.scheme=https
  - --entryPoints.web.http.redirections.entryPoint.permanent=true
  - --entryPoints.web.observability.accessLogs=false
  - --entryPoints.web.observability.metrics=false
  - --entryPoints.web.observability.tracing=false

팁 (Tip)

Helm 차트에서 엔트리포인트 web(포트 80), websecure(포트 443), traefik(포트 8080), metrics(포트 9100)는 기본적으로 생성돼요. 엔트리포인트 web, websecure는 기본적으로 Service로 노출돼요.

기본 동작은 Helm 차트에서 덮어쓸 수 있어요.

설정 옵션 (Configuration Options)

asDefault

asDefault 옵션이 true로 설정된 엔트리포인트가 없으면, 기본 엔트리포인트 목록에는 모든 HTTP/TCP 엔트리포인트가 포함돼요.

asDefault 옵션이 true로 설정된 엔트리포인트가 하나라도 있으면, 기본 엔트리포인트 목록에는 asDefault 옵션이 true로 설정된 엔트리포인트만 포함돼요.

내장 엔트리포인트 중 traefik은 항상 목록에서 제외돼요.

asDefault 옵션은 UDP 엔트리포인트에는 효과가 없어요. UDP 라우터가 엔트리포인트 옵션을 정의하지 않으면, 사용 가능한 모든 UDP 엔트리포인트에 연결돼요.

allowACMEByPass

기본적으로 Traefik은 ACME HTTP와 TLS 챌린지를 처리하기 위해 가능한 최고 우선순위(MaxInt)의 내부 라우터를 만들어요. 이는 인증서 챌린지가 항상 성공하도록 보장하지만, 같은 엔트리포인트에서 사용자 정의 라우터가 챌린지 요청을 가로채는 것도 막아요.

엔트리포인트에서 allowACMEByPass가 true로 설정되면:

내부 ACME HTTP 챌린지 라우터가 명시적인 높은 우선순위 없이 만들어져서, 사용자 정의 라우터가 챌린지 요청을 대신 처리할 수 있어요.
엔트리포인트에서 TLS-ALPN 챌린지 통과(passthrough)가 활성화되어, 사용자 정의 TLS 라우터가 TLS 챌린지를 처리할 수 있어요.

이는 ACME 챌린지를 커스텀 처리해야 할 때 유용해요. 예를 들어 전용 서비스로 HTTP-01이나 TLS-ALPN-01 챌린지를 해결할 때요.

참고 (Note)

TLS 챌린지 리졸버가 설정되지 않으면, allowACMEByPass는 모든 엔트리포인트의 TLS 통과에 대해 암시적으로 활성화돼요.

참고 (Note)

allowACMEByPass가 활성화되고 엔트리포인트에 HTTP 리다이렉트가 설정되어 있으면(http.redirections.entryPoint로), 리다이렉트 라우터는 자동으로 ACME 챌린지 경로(/.well-known/acme-challenge/)를 제외해요. 이렇게 하면 사용자 정의 ACME 챌린지 라우터가 리다이렉트에 덮어쓰여지지 않고 챌린지 요청을 처리할 수 있어요.

파일 (YAML)

entryPoints:
  web:
    address: ":80"
    allowACMEByPass: true

파일 (TOML)

[entryPoints.web]
  address = ":80"
  allowACMEByPass = true

CLI

--entryPoints.web.address=:80
--entryPoints.web.allowACMEByPass=true

http.middlewares

각 엔트리포인트에 미들웨어 목록을 붙일 수 있어요.
미들웨어는 규칙이 일치할 때만, 그리고 요청을 서비스로 전달하기 전에 효과를 발휘해요.
미들웨어는 선언된 순서와 같은 순서로 적용돼요.
미들웨어는 기본적으로 EntryPoint를 통해 노출되는 모든 라우터에 적용돼요 (IngressRoute나 Ingress에 선언된 미들웨어는 Entrypoint에 선언된 것 이후에 적용돼요).
미들웨어는 provider 네임스페이스 접미사(@)를 포함한 완전히 정규화된 이름으로 참조해야 해요. 정확한 값은 미들웨어를 선언하는 프로바이더에 따라 달라져요:

파일 (YAML)

entryPoints:
  web:
    address: :80
    http:
      middlewares:
        - default-auth@kubernetescrd
        - strip@file

Helm 차트 값 (Helm Chart Values)

ports:
  web:
    port: :80
    http:
      middlewares:
        - default-auth@kubernetescrd
        - strip@file

encodeQuerySemicolons

동작 예시:

aliasHeadersStrategy

선택 사항, 기본값=keep

aliasHeadersStrategy 옵션은 다른 헤더 이름을 별칭으로 하는 이름을 가진 요청 헤더를 라우팅 전에 어떻게 처리할지 정의해요:

keep: 별칭 이름을 가진 요청 헤더는 그대로 전달돼요 (기본값).
delete: 이름에 문자, 숫자, 대시가 아닌 문자가 포함된 요청 헤더는 요청에서 조용히 제거돼요.
reject: 이름에 문자, 숫자, 대시가 아닌 문자가 포함된 헤더를 가진 요청은 400 Bad Request 응답으로 거부돼요.

Go는 대시에서만 헤더 이름을 정규화하므로 X-Auth-User, X_Auth_User, X.Auth.User를 세 개의 서로 다른 헤더로 처리해요. 반면 헤더 이름에서 변수 이름을 파생하는 백엔드(CGI, WSGI, PHP, NGINX, ...)는 셋을 모두 같은 HTTP_X_AUTH_USER 변수로 읽어요.

언더스코어와 점만 관련된 것이 아니에요. HTTP가 헤더 이름에서 허용하는 문자 중 문자, 숫자, 대시를 제외한 모든 문자는 그런 별칭을 만들어요. 즉 !, #, $, %, &, ', *, +, ., ^, _, `, |, ~예요. 자세한 내용은 별칭 이름을 가진 헤더(Headers with Aliasing Names) 보안 문서를 참고하세요.

요청 헤더를 관리하는 미들웨어(예: ForwardAuth authResponseHeaders 옵션)는 자신이 설정한 헤더의 정규 형태만 관리하고, 별칭 이름으로 스푸핑되지 않도록 이 옵션에 의존해요. Traefik은 이 옵션 없이 남겨진 모든 엔트리포인트에 대해 시작 시 경고를 기록해요.

보안 (Security)

헤더 이름을 정규화하는 백엔드는 자신이 신뢰하는 헤더의 별칭 이름으로 스푸핑될 수 있어요. 그런 백엔드가 노출될 때 aliasHeadersStrategy 옵션을 delete나 reject로 설정하는 것을 권장해요.

delete와 reject 전략은 모든 요청 헤더에 적용돼요. 이름에 그런 문자가 포함된 합법적인 헤더(예: X_Request_Id)도 제거되거나 거부돼요.

파일 (YAML)

entryPoints:
  websecure:
    address: ':443'
    http:
      aliasHeadersStrategy: delete

파일 (TOML)

[entryPoints.websecure]
  address = ":443"

  [entryPoints.websecure.http]
    aliasHeadersStrategy = "delete"

CLI

--entryPoints.websecure.address=:443
--entryPoints.websecure.http.aliasHeadersStrategy=delete

예시 (Examples)

sanitizePath

sanitizePath 옵션은 요청 경로 위생화를 활성화할지 정의해요. 비활성화하면 들어오는 요청 경로는 그대로 백엔드에 전달돼요. 이것은 요청 경로의 데이터를 URL 인코딩하지 않는 레거시 클라이언트를 다룰 때 유용할 수 있어요. 예를 들어 base64는 내부적으로 "/" 문자를 사용하는데, 그것이 url로 인코딩되지 않으면 sanitizePath 옵션이 false로 설정되었을 때 안전하지 않은 라우팅으로 이어질 수 있어요.

보안 (Security)

sanitizePath 옵션을 false로 설정하는 것은 안전하지 않아요. 모든 요청이 제대로 url 인코딩되도록 하세요.

예시 (Examples)

인코딩된 문자 (Encoded Characters)

보안 목적으로 요청 경로의 인코딩된 문자 처리를 제어하도록 Traefik을 설정할 수 있어요. 기본적으로 Traefik은 경로 탐색(path traversal)이나 다른 보안 공격에 사용될 수 있는 특정 인코딩된 문자를 경로에 포함한 요청을 거부하지 않아요.

정보 (Info)

이 검사는 요청 쿼리 파라미터에 대해서는 하지 않고, RFC3986 section-3에 정의된 요청 경로에 대해서만 해요.

보안 고려 사항 (Security Considerations)

백엔드가 RFC 3986을 완전히 준수하지 않고 특히 요청 경로의 인코딩된 예약 문자를 디코딩한다면, 이 옵션들을 false로 설정해 split-view 상황을 피하고 경로 탐색 공격이나 보안 통제를 우회하려는 다른 악의적 시도를 막는 것을 권장해요.

기본적으로 허용되는 인코딩된 문자 목록은 다음과 같아요:

| 인코딩된 문자 (Encoded Character) | 문자 (Character) | | %2f 또는 %2F | / (슬래시) | | %5c 또는 %5C | \ (백슬래시) | | %00 | NULL (널 문자) | | %3b 또는 %3B | ; (세미콜론) | | %25 | % (퍼센트) | | %3f 또는 %3F | ? (물음표) | | %23 | # (해시) |

전달된 헤더 (Forwarded Headers)

Traefik이 전달된 헤더 정보(X-Forwarded-*)를 신뢰하도록 설정할 수 있어요.

forwardedHeaders.trustedIPs 특정 IP에서 온 전달된 헤더 신뢰하기 (Trusting Forwarded Headers from specific IPs)

파일 (YAML)

## Static configuration
entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      trustedIPs:
        - "127.0.0.1/32"
        - "192.168.1.7"

파일 (TOML)

## Static configuration
[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      trustedIPs = ["127.0.0.1/32", "192.168.1.7"]

CLI

## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7

forwardedHeaders.insecure Insecure 모드 (전달된 헤더 항상 신뢰하기) (Insecure Mode (Always Trusting Forwarded Headers))

파일 (YAML)

## Static configuration
entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      insecure: true

파일 (TOML)

## Static configuration
[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      insecure = true

CLI

## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.insecure

forwardedHeaders.connection RFC7230에 따라 Traefik은 클라이언트 요청의 Connection 옵션을 존중해요. 그렇게 함으로써 요청 Connection 헤더에 나열된 모든 헤더 필드와, 비어 있을 때 Connection 헤더 필드 자체를 제거해요. 제거는 요청이 Traefik에 의해 처리되는 즉시 일어나므로, 제거된 헤더는 요청이 미들웨어 체인을 통과할 때 사용할 수 없어요. connection 옵션은 제거되기 전에 미들웨어 체인을 통과할 수 있는 Connection 헤더를 나열해요.

파일 (YAML)

## Static configuration
entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      connection:
        - foobar

파일 (TOML)

## Static configuration
[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      connection = ["foobar"]

CLI

## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.connection=foobar

HTTP3

HTTP/3는 실제로 UDP를 사용하므로, Traefik이 HTTP/3가 활성화된 포트 N의 TCP entryPoint로 설정되면, 시작되는 기본 HTTP/3 서버는 자동으로 UDP 포트 N에서도 수신해요. 결과적으로, 포트 N은 다른 UDP entryPoint가 사용할 수 없어요. HTTP/3는 TLS 사용을 요구하므로, TLS가 활성화된 라우터만 HTTP/3와 함께 사용할 수 있어요.

ProxyProtocol과 로드 밸런서

원격 클라이언트 주소의 교체는 trustedIPs에 나열된 IP 주소에 대해서만 발생해요. 여기에 로드 밸런서 IP나 CIDR 범위를 지정하면 돼요.

Traefik을 다른 로드 밸런서 뒤에 둘 때는, 양쪽 모두에 PROXY 프로토콜을 설정해야 해요. 그렇게 하지 않으면 시스템에 보안 위험(요청 위조 가능)이 생길 수 있어요.

reusePort

예시 (Examples)

같은 EntryPoint의 여러 프로세스:

파일 (YAML)

  entryPoints:
    web:
      address: ":80"
      reusePort: true

Helm 차트 값 (Helm Chart Values)

  ## Values file
  additionalArguments:
    - --entryPoints.web.reusePort=true

다른 호스트에서 같은 EntryPoint의 여러 프로세스:

파일 (YAML)

entryPoints:
  web:
    address: ":80"
    reusePort: true
  privateWeb:
    address: "192.168.1.2:80"
    reusePort: true

Helm 차트 값 (Helm Chart Values)

additionalArguments:
  - --entryPoints.web.reusePort=true
  - --entryPoints.privateWeb.address=192.168.1.2:80
  - --entryPoints.privateWeb.reusePort=true

지원 플랫폼 (Supported platforms)

reusePort 옵션은 현재 Linux, FreeBSD, OpenBSD, Darwin에서만 동작해요. 다른 플랫폼에서는 무시돼요.

reusePort 옵션을 사용할 때 의도하지 않은 TCP 연결 실패를 일으킬 수 있는 알려진 Linux 커널 버그가 있어요. 자세한 내용은 여기를 참고하세요.

카나리 배포 (Canary deployment)

reusePort 옵션과 다른 옵션 transport.lifeCycle.gracetimeout을 함께 사용해 Traefik 자체에 대해 카나리 배포를 할 수 있어요. 예를 들어 Traefik 버전을 업그레이드하거나 정적 설정을 서비스 다운타임 없이 리로드하는 것처럼요.

traceVerbosity

observability.traceVerbosity는 이 EntryPoint에 연결된 라우터의 추적 세부 수준을 정의해요. 라우터는 자체 관찰성 설정에서 이 값을 덮어쓸 수 있어요.

가능한 값은:

minimal: 라우터가 처리하는 각 요청에 대해 서버 스팬 하나와 클라이언트 스팬 하나를 생성해요.
detailed: 라우터가 처리하는 각 요청에 대해 실행되는 각 미들웨어에 대한 추가 스팬 생성을 활성화해요.

Systemd 소켓 활성화 (Systemd Socket Activation)

Traefik은 systemd 소켓 활성화를 지원해요.

소켓 활성화 파일 디스크립터 이름이 EntryPoint 이름과 일치하면, 해당 파일 디스크립터가 일치하는 EntryPoint의 TCP/UDP 리스너로 사용돼요.

systemd-socket-activate -l 80 -l 443 --fdname web:websecure  ./traefik --entrypoints.web --entrypoints.websecure

EntryPoint 주소 (EntryPoint Address)

소켓 활성화 파일 디스크립터 이름이 EntryPoint 이름과 일치하면, 그것의 주소 설정은 무시돼요. UDP 라우팅을 지원하려면 주소에 /udp 접미사가 있어야 해요(--entrypoints.my-udp-entrypoint.address=/udp).

Docker 지원 (Docker Support)

소켓 활성화는 Docker에서 지원되지 않지만 Podman 컨테이너에서는 동작해요.

소켓 파일의 여러 리스너 (Multiple listeners in socket file)

각 systemd 소켓 파일은 HTTP/3의 경우를 제외하고 Listen 지시문을 하나만 포함해야 해요. HTTP/3에서는 파일이 ListenStream과 ListenDatagram 지시문을 모두 포함해야 해요. 같은 포트에 TCP와 UDP 리스너를 설정하려면 서로 다른 entrypoint 이름을 가진 여러 소켓 파일을 사용하세요.

더 알아보기 (Learn more)

Traefik 공식 문서