Traefik Headers 미들웨어

원문 보기 위키 갱신 2026.10.03

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

본문

Headers

Headers 미들웨어는 요청과 응답의 헤더를 관리해요.

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

설정 예시

요청과 응답에 헤더 추가하기

다음 예시는 프록시된 요청에 X-Script-Name 헤더를, 응답에 X-Custom-Response-Header 헤더를 추가해요.

구조화 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test"
        customResponseHeaders:
          X-Custom-Response-Header: "value"

구조화 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test"
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "value"

Labels

labels:
  - "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"

Tags

{
  //...
  "Tags": [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
  ]

}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test"
    customResponseHeaders:
      X-Custom-Response-Header: "value"

헤더 추가와 제거

다음 예시에서, 요청은 추가 X-Script-Name 헤더와 함께 프록시되는 반면 X-Custom-Request-Header 헤더는 제거되고, 응답은 X-Custom-Response-Header 헤더가 제거돼요.

구조화 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test" # Adds
          X-Custom-Request-Header: "" # Removes
        customResponseHeaders:
          X-Custom-Response-Header: "" # Removes

구조화 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test" # Adds
        X-Custom-Request-Header = "" # Removes
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "" # Removes

Labels

labels:
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header="
  - "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header=",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test" # Adds
      X-Custom-Request-Header: "" # Removes
    customResponseHeaders:
      X-Custom-Response-Header: "" # Removes

보안 헤더 사용하기

보안 관련 헤더(HSTS 헤더, 브라우저 XSS 필터 등)는 위에서 보여준 것처럼 커스텀 헤더와 유사하게 관리할 수 있어요. 이 기능을 사용하면 헤더를 추가하는 것만으로 보안 기능을 쉽게 사용할 수 있게 돼요.

구조화 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        frameDeny: true
        browserXssFilter: true

구조화 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    frameDeny = true
    browserXssFilter = true

Labels

labels:
  - "traefik.http.middlewares.testHeader.headers.framedeny=true"
  - "traefik.http.middlewares.testHeader.headers.browserxssfilter=true"

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.framedeny=true",
    "traefik.http.middlewares.testheader.headers.browserxssfilter=true"
  ]

}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    frameDeny: true
    browserXssFilter: true

CORS 헤더

CORS (Cross-Origin Resource Sharing) 헤더는 위의 커스텀 헤더와 유사한 방식으로 추가하고 구성할 수 있어요. 이 기능은 더 고급 보안 기능을 빠르게 설정할 수 있게 해줘요. CORS 헤더가 설정되면, 미들웨어는 preflight 요청을 어떤 서비스로도 전달하지 않고, 대신 응답을 생성해 클라이언트에게 직접 보내요. 아래 예시는 결코 권위적이거나 완전한 것이 아니며, 그대로 프로덕션에 사용해서는 안 된다는 점을 참고하세요.

구조화 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        accessControlAllowMethods:
          - GET
          - OPTIONS
          - PUT
        accessControlAllowHeaders:
          - "*"
        accessControlAllowOriginList:
          - https://foo.bar.org
          - https://example.org
        accessControlMaxAge: 100
        addVaryHeader: true

구조화 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    accessControlAllowMethods = ["GET", "OPTIONS", "PUT"]
    accessControlAllowHeaders = [ "*" ]
    accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
    accessControlMaxAge = 100
    addVaryHeader = true

Labels

labels:
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*"
  - "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
  - "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
  - "traefik.http.middlewares.testheader.headers.addvaryheader=true"

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT",
     "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*",
    "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org",
    "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100",
    "traefik.http.middlewares.testheader.headers.addvaryheader=true"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    accessControlAllowMethods:
      - "GET"
      - "OPTIONS"
      - "PUT"
    accessControlAllowHeaders:
      - "*"
    accessControlAllowOriginList:
      - "https://foo.bar.org"
      - "https://example.org"
    accessControlMaxAge: 100
    addVaryHeader: true

설정 옵션

경고

커스텀 헤더는 이름이 동일하면 기존 헤더를 덮어써요.

보안 헤더에 대한 자세한 문서는 unrolled/secure에서 확인할 수 있어요.

| 필드 | 설명 | 기본값 | 필수 | | customRequestHeaders | 요청에 대한 헤더 이름과 값을 나열해요. | [] | 아니요 | | customResponseHeaders | 응답에 대한 헤더 이름과 값을 나열해요. | [] | 아니요 | | accessControlAllowCredentials | 요청에 사용자 자격 증명을 포함할 수 있는지 여부를 나타내요. | false | 아니요 | | accessControlAllowHeaders | 허용된 요청 헤더 이름을 지정해요. | [] | 아니요 | | accessControlAllowMethods | 허용된 요청 메서드를 지정해요. | [] | 아니요 | | accessControlAllowOriginList | 허용된 출처를 지정해요. 자세한 내용은 여기 | [] | 아니요 | | accessControlAllowOriginListRegex | 정규식과 일치하는 출처를 허용해요. 자세한 내용은 여기 | [] | 아니요 | | accessControlExposeHeaders | CORS API 사양의 API에 노출해도 안전한 헤더를 지정해요. | [] | 아니요 | | accessControlMaxAge | preflight 요청을 캐시하는 시간(초)이에요. | 0 | 아니요 | | addVaryHeader | accessControlAllowOriginList와 함께 사용되어, 서버 응답이 origin 헤더의 값에 따라 달라질 수 있음을 보여주기 위해 Vary 헤더를 추가하거나 수정할지 여부를 결정해요. | false | 아니요 | | allowedHosts | 허용된 도메인 이름을 나열해요. | [] | 아니요 | | hostsProxyHeaders | 프록시된 호스트명을 위한 헤더 키를 지정해요. | [] | 아니요 | | sslProxyHeaders | 유효한 HTTPS 요청임을 나타낼 헤더 키와 연관 값의 집합을 정의해요. 다른 프록시를 사용할 때 유용할 수 있어요 (예: "X-Forwarded-Proto": "https"). | {} | 아니요 | | stsSeconds | Strict-Transport-Security 헤더의 Max age예요. | - | 아니요 | | stsIncludeSubdomains | true로 설정하면 includeSubDomains 지시어가 Strict-Transport-Security 헤더에 추가돼요. | false | 아니요 | | stsPreload | STS 헤더에 preload 플래그를 추가해요. | false | 아니요 | | forceSTSHeader | HTTP 연결에 STS 헤더를 추가해요. | false | 아니요 | | frameDeny | frameDeny를 true로 설정하면 값이 DENY인 X-Frame-Options 헤더가 추가돼요. | false | 아니요 | | customFrameOptionsValue | X-Frame-Options 헤더 값을 커스텀 값으로 설정할 수 있어요. 이 값은 FrameDeny 옵션을 덮어써요. | "" | 아니요 | | contentTypeNosniff | contentTypeNosniff를 true로 설정하면 값이 nosniff인 X-Content-Type-Options 헤더가 추가돼요. | false | 아니요 | | browserXssFilter | browserXssFilter를 true로 설정하면 값이 1; mode=block인 X-XSS-Protection 헤더가 추가돼요. | false | 아니요 | | customBrowserXSSValue | X-XSS-Protection 헤더 값을 커스텀 값으로 설정할 수 있어요. 이 값은 BrowserXssFilter 옵션을 덮어써요. | "" | 아니요 | | contentSecurityPolicy | Content-Security-Policy 헤더 값을 커스텀 값으로 설정할 수 있어요. | "" | 아니요 | | contentSecurityPolicyReportOnly | Content-Security-Policy-Report-Only 헤더 값을 커스텀 값으로 설정할 수 있어요. | "" | 아니요 | | publicKey | 인증서 고정(pinning)을 위한 HPKP를 구현해요. | "" | 아니요 | | referrerPolicy | Referer 헤더의 전달을 제어해요. | "" | 아니요 | | permissionsPolicy | 사이트가 브라우저 기능을 제어할 수 있게 해요. | "" | 아니요 | | isDevelopment | 개발 중에는 AllowedHosts, SSL, STS 옵션의 원치 않는 영향을 완화하기 위해 true로 설정해요. 보통 테스트는 프로덕션 도메인이 아닌 localhost에서, HTTPS가 아닌 HTTP로 진행돼요. | false | 아니요 |

accessControlAllowOriginList

accessControlAllowOriginList는 서로 다른 값을 반환함으로써 리소스를 공유할 수 있는지 나타내요.

와일드카드 출처 *도 설정할 수 있고, 모든 요청과 일치해요. 이 값이 백엔드 서비스에 의해 설정되면 Traefik이 덮어써요.

이 값은 허용된 출처 목록을 담을 수 있어요.

설정을 사용하는 방법을 포함한 자세한 내용은 다음에서 확인할 수 있어요:

Mozilla.org
w3
IETF

Traefik은 더 이상 null 값을 지원하지 않아요. 더 이상 반환 값으로 권장되지 않기 때문이에요.

accessControlAllowOriginListRegex

accessControlAllowOriginListRegex 옵션은 origin 값 대신 정규식을 사용한다는 점을 제외하면 accessControlAllowOriginList 옵션의 대응 항목이에요. accessControlAllowOriginList의 정규식과 일치하는 부분을 포함하는 모든 출처를 허용해요.

팁

정규식과 대체는 Go Playground나 Regex101 같은 온라인 도구로 테스트할 수 있어요.

YAML에서 정규식을 정의할 때, 이스케이프된 문자는 두 번 이스케이프해야 해요: example\.com은 example\\\\.com으로 작성해야 해요.

프로덕션에서 Traefik OSS를 사용 중이신가요?

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

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

Traefik OSS에 API 게이트웨이 기능을 추가하는 건 빠르고 매끄러워요. rip-and-replace 방식이 없고 모든 구성이 그대로 유지돼요. 짧은 영상으로 직접 확인해 보세요.

더 알아보기 (Learn more)

Traefik 공식 문서