본문 바로가기
WIKI 기술 지식 베이스

Traefik TLS 문서

원문 보기 위키 갱신

출처: Traefik TLS Documentation

본문

TLS

일반

TCP 라우터가 TLS 트래픽을 처리하도록 구성할 때는 정의에 tls 필드를 포함하세요. 이 필드는 Traefik에 라우터가 TLS 연결만 처리하고 non-TLS 트래픽은 무시해야 한다는 것을 알려줘요.

기본적으로 TLS 필드가 있는 라우터는 TLS 연결을 종료(terminate)해요. 즉, 복호화된 데이터를 서비스로 보낸다는 뜻이에요.

설정 예시

구조화 (YAML)

tcp:
  routers:
    my-tls-router:
      rule: "HostSNI(`example.com`)"
      service: "my-tcp-service"
      tls:
        passthrough: true
        options: "my-tls-options"
        domains:
          - main: "example.com"
            sans:
              - "www.example.com"
              - "api.example.com"
        certResolver: "myresolver"

구조화 (TOML)

[tcp.routers.my-tls-router]
  rule = "HostSNI(`example.com`)"
  service = "my-tcp-service"

  [tcp.routers.my-tls-router.tls]
    passthrough = true
    options = "my-tls-options"
    certResolver = "myresolver"

    [[tcp.routers.my-tls-router.tls.domains]]
      main = "example.com"
      sans = ["www.example.com", "api.example.com"]

Labels

labels:
  - "traefik.tcp.routers.my-tls-router.tls=true"
  - "traefik.tcp.routers.my-tls-router.rule=HostSNI(`example.com`)"
  - "traefik.tcp.routers.my-tls-router.service=my-tcp-service"
  - "traefik.tcp.routers.my-tls-router.tls.passthrough=true"
  - "traefik.tcp.routers.my-tls-router.tls.options=my-tls-options"
  - "traefik.tcp.routers.my-tls-router.tls.certResolver=myresolver"
  - "traefik.tcp.routers.my-tls-router.tls.domains[0].main=example.com"
  - "traefik.tcp.routers.my-tls-router.tls.domains[0].sans=www.example.com,api.example.com"

Tags

{
  //...
  "Tags": [
    "traefik.tcp.routers.my-tls-router.tls=true",
    "traefik.tcp.routers.my-tls-router.rule=HostSNI(`example.com`)",
    "traefik.tcp.routers.my-tls-router.service=my-tcp-service",
    "traefik.tcp.routers.my-tls-router.tls.passthrough=true",
    "traefik.tcp.routers.my-tls-router.tls.options=my-tls-options",
    "traefik.tcp.routers.my-tls-router.tls.certResolver=myresolver",
    "traefik.tcp.routers.my-tls-router.tls.domains[0].main=example.com",
    "traefik.tcp.routers.my-tls-router.tls.domains[0].sans=www.example.com,api.example.com"
  ]
}

Postgres STARTTLS Traefik은 Postgres STARTTLS 프로토콜을 지원하며,

이를 통해 Postgres 연결에 대한 TLS 라우팅이 가능해요.

그렇게 하기 위해 Traefik은 Postgres 클라이언트가 보낸 첫 바이트를 읽어

STARTTLS 협상의 메시지에 해당하는지 식별하고,

해당하면 이를 확인하고 클라이언트에게 TLS 핸드셰이크를 시작할 수 있다고 신호를 보내요.

연결이 결국 TLS 연결이 되는지 여부에는 STARTTLS 고유의 미묘한 점들이 있다는 점을 유의하세요.

이 미묘한 점들은 클라이언트 구성의 sslmode 값(그리고 서버 인증 규칙)에 따라 달라져요.

따라서 sslmode 에는 require 값을 사용하는 것이 권장돼요.

이후에는 TLS 핸드셰이크와 TLS 기반 라우팅이 예상대로 진행될 수 있어요.

TCP TLS PassThrough 라우터가 있는 Postgres STARTTLS

위에서 언급했듯이 sslmode 구성 매개변수는 STARTTLS 세션이 성공할지 여부에 영향을 미쳐요.

특히 TCP TLS PassThrough 맥락에서는 allow 같은 일부 값은 의미가 없기까지 해요.

그래서 다시 한번 require 값을 사용하는 것이 권장돼요.

설정 옵션

| 필드 | 설명 | 기본값 | 필수 | | passthrough | 요청을 "그대로" 전달해 모든 데이터를 암호화된 상태로 유지할지 여부를 정의해요. | false | 아니요 | | options | TLS 매개변수를 세밀하게 제어할 수 있게 해줘요. TLS 옵션을 참조하며 HostSNI 규칙이 정의된 경우에만 적용돼요. HTTP 라우터와 달리 여러 TCP 라우터가 서로 다른 TLS 옵션으로 동일한 HostSNI 를 제공할 수 있어요. 자세한 내용은 TLS 옵션 및 HostSNI를 참고하세요. | "" | 아니요 | | certResolver | ACME 프로바이더(예: Let's Encrypt)를 통한 자동 인증서 생성을 위해 사용할 인증서 리졸버의 이름이에요. 자세한 내용은 인증서 리졸버 섹션을 참고하세요. | "" | 아니요 | | domains | 명시적 인증서 도메인 지정을 위한 도메인 및 Subject Alternative Names(SAN) 목록이에요. 자세한 내용은 사용자 지정 도메인 섹션을 참고하세요. | [] | 아니요 |

TLS 옵션 및 HostSNI

HTTP 라우터와 달리

여러 TCP 라우터가 서로 다른 TLS 옵션으로 동일한 HostSNI 를 제공할 수 있으며,

이것은 충돌이 아니에요.

TCP 라우터 규칙은 HostSNI 매처에만 국한되지 않고, TCP muxer는 TLS 핸드셰이크가 발생하기 전에 어떤 경로가 연결과 일치하는지 결정할 수 있어요.

따라서 TLS 옵션은 호스트 이름별이 아니라 경로별로 선택되며,

이로 인해 다음과 같은 구성이 유효하게 돼요:

구조화 (YAML)

# Dynamic configuration

tcp:
  routers:
    routerfoo:
      rule: "HostSNI(`example.com`) && ClientIP(`192.168.0.11`)"
      tls:
        options: foo

    routerbar:
      rule: "HostSNI(`example.com`) && ClientIP(`192.168.0.12`)"
      tls:
        options: bar

구조화 (TOML)

# Dynamic configuration

[tcp.routers]
  [tcp.routers.routerfoo]
    rule = "HostSNI(`example.com`) && ClientIP(`192.168.0.11`)"
    [tcp.routers.routerfoo.tls]
      options = "foo"

  [tcp.routers.routerbar]
    rule = "HostSNI(`example.com`) && ClientIP(`192.168.0.12`)"
    [tcp.routers.routerbar.tls]
      options = "bar"

인증서 리졸버

tls.certResolver 옵션을 사용하면 ACME 프로바이더(예: Let's Encrypt)를 통한 자동 인증서 생성을 위한 인증서 리졸버를 지정할 수 있어요.

라우터에 인증서 리졸버가 구성되면

Traefik은 라우터 규칙(HostSNI 매처)에 지정된 도메인이나 tls.domains 구성(tls.domains 가 우선)에 지정된 도메인에 대한 TLS 인증서를 자동으로 획득하고 관리해요.

전제 조건

  • 인증서 리졸버는 정적 구성에 정의되어 있어야 해요

  • 라우터에 tls가 활성화되어 있어야 해요

  • 인증서 리졸버에 ACME 챌린지 유형이 구성되어 있어야 해요

사용자 지정 도메인

ACME 인증서 리졸버를 사용할 때 도메인은 라우터 규칙에서 자동으로 추출되지만,

tls.domains 옵션을 사용하면 인증서를 생성할 도메인과 Subject Alternative Names(SAN)를 명시적으로 지정할 수 있어요.

이렇게 하면 인증서 생성을 세밀하게 제어할 수 있고 라우터 규칙에서 자동으로 추출된 도메인보다 우선해요.

모든 도메인에는 Traefik을 가리키는 A/AAAA 레코드가 있어야 해요.

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

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

  • API 게이트웨이 데모 영상 보기

  • 24/7/365 OSS 지원 요청하기

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

더 알아보기 (Learn more)