Traefik Errors 미들웨어

출처: Traefik Errors 미들웨어 (Errors Documentation)

본문

Errors

errors 미들웨어는 구성된 HTTP 상태 코드 범위에 따라, 기본 페이지 대신 커스텀 페이지를 반환해요.

설정 예시

구조화 (YAML)

# 502와 504를 제외한 5XX 상태 코드용 동적 커스텀 오류 페이지
http:
  middlewares:
    test-errors:
      errors:
        status:
          - "500"
          - "501"
          - "503"
          - "505-599"
        statusRewrites:
          "418": 404
          "502-504": 500
        service: error-handler-service
        query: "/{status}.html"

  services:
    # ... error-handler-service의 정의

구조화 (TOML)

# 502와 504를 제외한 5XX 상태 코드용 동적 커스텀 오류 페이지
[http.middlewares]
  [http.middlewares.test-errors.errors]
    status = ["500","501","503","505-599"]
    service = "error-handler-service"
    query = "/{status}.html"

    [http.middlewares.test-errors.errors.statusRewrites]
      "418" = 404
      "502-504" = 500

[http.services]
  # ... error-handler-service의 정의

Labels

# 5XX 상태 코드용 동적 커스텀 오류 페이지
labels:
  - "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
  - "traefik.http.middlewares.test-errors.errors.statusRewrites.418=404"
  - "traefik.http.middlewares.test-errors.errors.statusRewrites.502-504=500"
  - "traefik.http.middlewares.test-errors.errors.service=error-handler-service"
  - "traefik.http.middlewares.test-errors.errors.query=/{status}.html"

Tags

// 502와 504를 제외한 5XX 상태 코드용 동적 커스텀 오류 페이지
{
  // ...
  "Tags": [
    "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599",
    "traefik.http.middlewares.test-errors.errors.statusRewrites.418=404",
    "traefik.http.middlewares.test-errors.errors.statusRewrites.502-504=500",
    "traefik.http.middlewares.test-errors.errors.service=error-handler-service",
    "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
  ]

}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-errors
spec:
  errors:
    status:
      - "500"
      - "501"
      - "503"
      - "505-599"
    statusRewrites:
      "418": 404
      "502-504": 500
    query: /{status}.html
    service:
      name: error-handler-service
      port: 80

설정 옵션

| 필드 | 설명 | 기본값 | 필수 | | status | 어떤 상태 또는 상태 범위가 오류 페이지를 표시할지 정의해요. 상태 코드 범위는 포함(inclusive) 방식이에요 (505-599는 505와 599를 포함해 그 사이의 모든 코드에서 트리거돼요). 상태 코드를 숫자(500)로, 쉼표로 구분된 여러 숫자(500,502)로, 대시로 두 코드를 구분한 범위(505-599)로, 또는 이 둘의 조합(404,418,505-599)으로 정의할 수 있어요. | [] | 아니요 | | statusRewrites | 다시 쓰여질 상태 코드의 선택적 매핑이에요. 자세한 내용은 여기. | [] | 아니요 | | service | 새로운 요청된 오류 페이지를 제공할 서비스예요. 자세한 내용은 여기. | "" | 예 | | query | 오류 페이지의 URL이에요 (service가 호스팅). 자세한 내용은 여기 | "" | 아니요 | | errorRequestHeaders | 오류 페이지 서비스로 전달되는 원래 요청 헤더 목록을 정의해요. 자세한 내용은 여기 | [] | 아니요 |

service와 HostHeader

기본적으로 클라이언트 Host 헤더 값은 구성된 오류 서비스로 전달돼요. 구성된 오류 서비스 URL에 대응하는 Host 값을 전달하려면 passHostHeader 옵션을 false로 설정해야 해요.

Kubernetes

Kubernetes에서 서비스를 지정할 때(예: IngressRoute에서), Kubernetes Service 리소스의 name, namespace, port를 참조해야 해요. 예를 들어 my-service.my-namespace@kubernetescrd (또는 my-service.my-namespace@kubernetescrd:80)는 요청이 올바른 서비스와 포트로 가도록 보장해요.

ServersTransport (Kubernetes)

Traefik이 오류 페이지 서비스에 연결하는 방식을 커스터마이징하려면(예: 백엔드에 TLS를 구성하려면), 미들웨어의 service에 serversTransport를 설정하세요. Kubernetes Service의 traefik.ingress.kubernetes.io/service.serverstransport 어노테이션은 여기 적용되지 않아요. 이 어노테이션은 Ingress 백엔드로 사용되는 Service에만 영향을 주고, 미들웨어가 참조하는 Service에는 영향을 주지 않아요.

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-errors
spec:
  errors:
    status:
      - "500"
      - "501"
    service:
      name: error-handler-service
      port: 80
      serversTransport: mytransport

statusRewrites

statusRewrites는 다시 쓰여질 상태 코드의 선택적 매핑이에요.

예를 들어, 서비스가 418을 반환한다면 404로 다시 쓰고 싶을 수 있어요. 개별 상태 코드나 심지어 범위를 다른 상태 코드로 매핑할 수 있어요. 범위의 구문은 status 옵션과 같은 규칙을 따라요.

query

query 옵션에는 URL에 값을 삽입하기 위해 넣을 수 있는 여러 변수가 있어요.

아래 표는 사용 가능한 모든 변수와 그에 대응하는 값을 나열해요.

| 변수 | 값 | | {status} | 응답 상태 코드. | | {originalStatus} | statusRewrites 옵션에 의해 수정된 경우의 원래 응답 상태 코드. | | {url} | 이스케이프된 요청 URL. |

errorRequestHeaders

오류 페이지 서비스로 전달되는 원래 요청 헤더 목록을 정의해요.

기본적으로(errorRequestHeaders 미설정 시) Authorization과 Cookie 같은 인증 자료를 포함한 모든 요청 헤더가 전달돼요. 오류 페이지 서비스가 별도의 신뢰 도메인에 있다면, 이 옵션을 사용해 어떤 헤더가 서비스 경계를 넘는지 제한하세요.

명시적 목록으로 설정하면 해당 헤더만 전달하고, 빈 목록(errorRequestHeaders: [])으로 설정하면 어떤 헤더도 전달하지 않아요.

더 알아보기 (Learn more)

• Traefik 공식 문서