Traefik 시작 FAQ

원문 보기 위키 갱신 2026.10.03

출처: Traefik 시작 FAQ (Traefik Getting Started FAQ)

본문

FAQ

왜 Traefik이 XXX HTTP 응답 상태 코드로 응답하나요?

Traefik은 동적 리버스 프록시예요. 문서는 흔히 구성 옵션을 파일 예시로 보여주지만, Traefik의 핵심 기능은 동적 구성 가능성, 즉 시간에 따라 프로바이더의 변화에 직접 반응하는 것이에요.

특히 설치 구성은 정적이며 시작 시 파일로 제공될 수 있는 반면, 파일 프로바이더 같은 다양한 프로바이더는 Traefik 인스턴스의 수명 내내 라우팅 구성 변화에 동적으로 기여합니다.

게다가 구성은 EntryPoint 같은 개념을 포함해요. EntryPoint는 전송 계층(TCP)의 리스너로 볼 수 있고, 그에 반해 Router는 프레젠테이션(TLS)과 애플리케이션 계층(HTTP)에 더 가깝죠. 그리고 주어진 EntryPoint에 라우터는 원하는 만큼 많이 존재할 수 있어요.

다시 말해서, 주어진 EntryPoint에 대해 어떤 순간에도 보이는 트래픽이 반드시 하나의 프로토콜에만 묶이지는 않아요. HTTP일 수도 있고 다른 것일 수도 있죠. TLS 위일 수도 있고 아닐 수도 있고요. 동적 구성 변화가 그런 트래픽을 시간에 따라 변하게 만들 수도 있다는 건 말할 것도 없어요.

따라서 이 동적 맥락에서 entryPoint의 정적 구성은 그 entryPoint를 지나는 트래픽이 어떻게 라우팅될지에 대해 어떤 힌트도 주지 않아요. 아예 라우팅될지조차도요. 즉, 그곳을 지나는 트래픽 종류와 매칭되는 Router가 있는지에 대한 정보가 없는 거예요.

404 Not found

Traefik은 다음 상황에서 404 응답 코드를 반환해요:

Router가 없는 EntryPoint로 도달한 요청
HTTP Router가 없는 EntryPoint로 도달한 HTTP 요청
HTTPS Router가 없는 EntryPoint로 도달한 HTTPS 요청
매칭할 수 없는 HTTP/HTTPS Router가 있는 EntryPoint로 도달한 요청

Traefik의 관점에서 보면, 요청이 라우터와 매칭될 수 없을 때마다 올바른 응답 코드는 404 Not found예요.

이 상황에서 응답 코드는 503 Service Unavailable이 아니에요. Traefik이 요청에 매칭되는 라우터가 없다는 것이 일시적인지 확신할 수 없기 때문이죠. Traefik의 라우팅 구성은 동적이고 서로 다른 프로바이더로부터 집계되므로, 어느 순간에 특정 라우트가 처리되어야 하는지 아닌지를 가정하는 건 불가능해요.

이 동작은 rfc7231과 일치해요

The server is currently unable to handle the request due to a
temporary overloading or maintenance of the server. The implication
is that this is a temporary condition which will be alleviated after
some delay. If known, the length of the delay MAY be indicated in a
Retry-After header. If no Retry-After is given, the client SHOULD
handle the response as it would for a 500 response.

    Note: The existence of the 503 status code does not imply that a
    server must use it when becoming overloaded. Some servers may wish
    to simply refuse the connection.

rfc7231#section-6.6.4에서 발췌.

502 Bad Gateway

Traefik은 업스트림 서비스에 접촉하는 동안 오류가 발생하면 502 응답 코드를 반환해요.

503 Service Unavailable

Traefik은 Router가 매칭됐는데 요청을 처리할 준비가 된 서버가 없을 때 503 응답 코드를 반환해요.

이 상황은 서비스가 서버 없이 명시적으로 구성됐을 때, 또는 서비스에 헬스체크가 켜져 있고 모든 서버가 비정상(unhealthy)일 때 발생해요.

404 대신 XXX

때로는 404 응답 코드가 다른 당사자나 서비스(예: CDN)와 잘 맞지 않을 수 있어요.

이런 상황에서는 404 대신 항상 503 응답 코드로 응답하게 하고 싶을 거예요.

이 동작을 얻으려면, 가능한 가장 낮은 우선순위를 갖고 서버가 없는 서비스로 라우팅하는 catchall 라우터가, 다른 라우터가 매칭되지 않을 때 모든 요청을 처리할 수 있어요.

아래 예시는 그런 구성이 어떤 모습인지 보여주는 파일 프로바이더 전용(yaml) 버전이에요:

정적 구성

# traefik.yml

entryPoints:
  web:
    address: :80

providers:
  file:
    filename: dynamic.yaml

동적 구성

# dynamic.yaml

http:
  routers:
    catchall:
      # attached only to web entryPoint
      entryPoints:
        - "web"
      # catchall rule
      rule: "PathPrefix(`/`)"
      service: unavailable
      # lowest possible priority
      # evaluated when no other router is matched
      priority: 1

  services:
    # Service that will always answer a 503 Service Unavailable response
    unavailable:
      loadBalancer:
        servers: {}

전용 서비스

503이 아닌 응답 코드와/또는 맞춤 메시지가 필요하다면, 위 예시의 원리(catchall 라우터)는 그대로 유효하지만, unavailable 서비스를 그런 요구에 맞게 조정해야 해요.

콘텐츠가 바뀌어도 내 TLS 인증서가 리로드되지 않는 이유는 무엇인가요?

파일 프로바이더에서 구성 업데이트는 감시 중인 구성 파일 중 하나가 수정됐을 때만 촉발돼요.

그래서 인증서가 경로로 정의됐는데 실제 인증서 내용이 바뀌어도 구성 업데이트가 촉발되지 않는 거예요.

새 인증서 내용을 반영하려면 동적 구성의 업데이트를 강제해야 해요. 이를 위한 방법 중 하나는 파일 알림을 촉발하는 것, 예를 들어 구성 파일에 touch 명령을 쓰는 거예요.

HTTP 요청을 프록시할 때 전달되는 헤더는 무엇인가요?

기본적으로 요청을 프록시할 때 다음 헤더가 자동으로 추가돼요:

자세한 내용은 전달 헤더(forwarded header) 문서를 확인해 주세요.

Traefik은 TLS 인증서를 어떻게 저장하고 제공하나요?

TLS 인증서 저장

TLS 인증서는 라우팅 구성이 직접 제공하거나 인증서 리졸버가 제공해요.

각 TLS 인증서에 대해 Traefik은 저장에 쓰는 키 역할을 하는 식별자를 만들어요. 이 식별자는 TLS 인증서의 SAN인 DNSNames와 IPAddresses를 알파벳순으로 연결해서 구성됩니다.

예시:

식별자는 나중에 TLS 연결 처리에 쓰기 위해 TLS 인증서를 저장하는 데 사용돼요. 이 작업은 구성이 바뀔 때마다 일어납니다.

같은 SAN 정의(같은 식별자)로 여러 TLS 인증서가 제공되면, 먼저 처리된 것만 유지돼요. 동적 구성이 모든 프로바이더에서 집계되므로, TLS 인증서를 모으기 위해 처리할 때 그 순서가 보장되지 않아요. 즉 적용된 구성에 따라 특정 식별자에 대해 유지되는 TLS 인증서가 달라질 수 있다는 뜻이에요.

TLS 인증서 제공

들어오는 각 연결에 대해 Traefik은 제공된 서버 이름에 대해 "가장 잘 맞는" TLS 인증서를 제공해요.

TLS 인증서 선택 과정은 서버 이름과 매칭되는 TLS 인증서 목록을 좁힌 다음, 그 목록을 식별자 순으로 정렬한 뒤 마지막 TLS 인증서를 선택해요.

예시:

TLS 인증서 캐싱

Traefik이 들어오는 각 연결에 대해 가장 잘 맞는 TLS 인증서를 제공하는 동안, 연결마다 드는 선택 과정 비용은 캐시 메커니즘 덕분에 피할 수 있어요.

서버 이름에 대해 "가장 잘 맞는" TLS 인증서가 한 번 선택되면, 한 시간 동안 캐시되어 이후 연결에서 선택 과정을 건너뜁니다.

그래도 새 구성이 적용되면 캐시는 재설정돼요.

"field not found" 오류는 무엇을 의미하나요?

error: field not found, node: -badField-

"field not found" 오류는 동적 또는 정적 구성에서 알 수 없는 속성을 만났을 때 발생해요.

구성 파일이 제대로 만들어졌는지 확인하는 한 가지 방법은 다음으로 검증하는 거예요:

정적 구성의 JSON Schema
동적 구성의 JSON Schema

왜 일부 리소스(라우터, 미들웨어, 서비스 등)가 생성/적용되지 않나요?

흔한 팁으로, 동적 구성이 평가된 후 Traefik이 리소스를 버리거나 만들지 않았다면, 로그에서 오류를 찾아보세요.

오류를 찾았다면 그 오류가 리소스를 만드는 중에 문제가 있었다는 걸 확인해 주고, 메시지는 구성의 실수를 파악하고 고치는 방법을 알려줘요.

파일 프로바이더를 쓸 때 동적 구성이 제대로 만들어졌는지 확인하는 한 가지 방법은 동적 구성의 JSON Schema로 검증하는 거예요.

왜 Let's Encrypt 와일드카드 인증서 갱신/생성이 DNS 챌린지로 실패하나요?

DNS 챌린지로 와일드카드 인증서를 갱신하려는데 다음과 같은 오류가 난다면:

msg="Error renewing certificate from LE: {example.com [*.example.com]}"
providerName=letsencrypt.acme error="error: one or more domains had a problem:
[example.com] acme: error presenting token: gandiv5: unexpected authZone example.com. for fqdn example.com."

CNAME 지원 때문일 수 있어요.

그렇다면, CNAME에 의존하지 않는 DNS 챌린지에 맞게 인프라가 제대로 구성되어 있는지 확인하고, 다음으로 CNAME 지원을 비활성화해 보세요:

LEGO_DISABLE_CNAME_SUPPORT=true

프로덕션에서 Traefik OSS를 쓰고 있나요?

직장에서 Traefik을 쓰고 있다면, 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS용 상업 지원을 추가하는 걸 고려해 보세요.

API Gateway 데모 영상 보기
24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 더하는 건 빠르고 매끄러워요. 갈아엎을 필요도 없고 모든 구성이 그대로 유지됩니다. 짧은 영상으로 직접 확인해 보세요.

더 알아보기 (Learn more)

Traefik 공식 문서