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

Traefik TCP 라우터 규칙 및 우선순위 문서

원문 보기 위키 갱신

출처: Traefik TCP Routers Rules & Priority Documentation

본문

규칙 및 우선순위

일반

참고

  • 라우터 이름에는 @ 문자가 허용되지 않아요

  • HTTP 라우터와 TCP 라우터가 동일한 엔트리 포인트를 수신하면 TCP 라우터가 HTTP 라우터보다 먼저 적용돼요. TCP 라우터에 일치하는 경로가 없으면 HTTP 라우터가 처리하게 돼요.

규칙

규칙은 값으로 구성된 매처 집합으로, 특정 연결이 특정 기준에 맞는지 판단해요. 규칙이 검증되면 라우터가 활성화되고 미들웨어를 호출한 뒤 요청을 서비스로 전달해요.

아래 표는 사용 가능한 모든 매처를 보여줘요:

| 규칙 | 설명 | | HostSNI(domain) | 연결의 Server Name Indication이 domain 과 동일한지 확인해요. 와일드카드 서브도메인 매칭(예: *.example.com)을 지원해요. 자세한 내용은 여기에서 확인하세요. | | HostSNIRegexp(regexp) | 연결의 Server Name Indication이 regexp 와 일치하는지 확인해요. Go 스타일 문법을 사용해요. 자세한 내용은 여기에서 확인하세요. | | ClientIP(ip) | 연결의 클라이언트 IP가 ip 에 해당하는지 확인해요. IPv4, IPv6 및 CIDR 형식을 허용해요. 자세한 내용은 여기에서 확인하세요. | | ALPN(protocol) | 연결의 ALPN 프로토콜이 protocol 과 동일한지 확인해요. 자세한 내용은 여기에서 확인하세요. |

백틱 또는 따옴표?

규칙의 값을 설정하려면 백틱 ``` 또는 이스케이프된 큰따옴표 \" 를 사용해요.

값이 Go의 String Literal이므로 작은따옴표 ' 는 허용되지 않아요.

연산자와 괄호로 복잡한 규칙 표현하기

일반적인 AND(&&)와 OR(||) 논리 연산자와 괄호를 예상되는 우선순위 규칙에 따라 사용할 수 있어요.

NOT(!) 연산자로 매처를 반전시킬 수도 있어요.

다음 규칙은 다음 조건에 해당하는 연결과 일치해요:

  • Server Name Indication이 example.com 이거나,

  • Server Name Indication이 example.org 이면서 ALPN 프로토콜이 h2 가 아닌 경우

HostSNI(`example.com`) || (HostSNI(`example.org`) && !ALPN(`h2`))

HostSNI 및 HostSNIRegexp

HostSNI 와 HostSNIRegexp 매처는 특정 도메인을 대상으로 하는 연결을 매칭할 수 있게 해줘요.

이 매처들은 비-ASCII 문자를 지원하지 않으므로, 그런 도메인을 매칭하려면 punycode 인코딩 값(rfc 3492)을 사용해요.

HostSNI와 TLS

Server Name Indication은 TLS 프로토콜의 확장이라는 점에 유의해야 해요.

따라서 TLS 라우터만 그 규칙으로 도메인 이름을 지정할 수 있어요.

하지만 non-TLS 라우터에 대한 HostSNI 의 특별한 사용 사례가 하나 있어요: 모든 (non-TLS) 요청과 일치하는 non-TLS 라우터를 원한다면 HostSNI(*) 문법을 사용하면 돼요.

와일드카드 서브도메인 매칭

HostSNI 매처는 example.com 의 모든 직접 서브도메인을 매칭하는 단일 레벨 와일드카드 프리픽스(*.example.com)를 지원해요.

TLS 옵션을 연결할 수 있고 더 효율적이므로 HostSNIRegexp 매처보다 선호해야 해요.

와일드카드는 정확히 하나의 서브도메인 레이블과 일치해요: *.example.com 은 foo.example.com 과 일치하지만 foo.bar.example.com 이나 example.com 자체와는 일치하지 않아요.

이는 v3 규칙 문법(기본값)에서만 사용할 수 있어요.

예시

모든 연결 매칭:

HostSNI

HostSNI(`*`)

HostSNIRegexp

HostSNIRegexp(`^.*$`)

example.com 으로 보내지는 TCP 연결 매칭:

HostSNI(`example.com`)

example.com 의 모든 직접 서브도메인(예: foo.example.com)에서 열린 TCP 연결 매칭:

HostSNI(`*.example.com`)

example.com 의 모든 서브도메인(중첩 서브도메인 포함)에서 열린 TCP 연결을 정규 표현식을 사용해 매칭:

HostSNIRegexp(`^.+\\.example\\.com$`)

ClientIP

ClientIP 매처는 주어진 IP를 가진 클라이언트가 연 연결을 매칭할 수 있게 해줘요.

예시

주어진 IP가 연 연결 매칭:

IPv4

ClientIP(`10.76.105.11`)

IPv6

ClientIP(`::1`)

주어진 서브넷에서 오는 연결 매칭:

IPv4

ClientIP(`192.168.1.0/24`)

IPv6

ClientIP(`fe80::/10`)

ALPN

ALPN 매처는 주어진 프로토콜을 사용하는 연결을 매칭할 수 있게 해줘요.

사용자 정의 라우터가 Traefik이 이전에 시작한 ACME TLS 챌린지에 대한 응답을 가로채게 두는 것은 보안 문제가 될 거예요.

이런 이유로 ALPN 매처는 ACME-TLS/1 프로토콜을 매칭하는 것이 허용되지 않으며, 이를 시도하면 Traefik이 오류를 반환해요.

예시

ALPN 프로토콜 h2 를 사용하는 연결 매칭:

ALPN(`h2`)

우선순위 계산

기본 우선순위가 계산되는 방법

구조화 (YAML)

  tcp:
    routers:
      Router-1:
        rule: "ClientIP(`192.168.0.12`)"
        entryPoints:
        - "web"
        service: service-1
        priority: 2
      Router-2:
        rule: "ClientIP(`192.168.0.0/24`)"
        entryPoints:
        - "web"
        priority: 1
        service: service-2

구조화 (TOML)

[tcp.routers]
  [tcp.routers.Router-1]
    rule = "ClientIP(`192.168.0.12`)"
    entryPoints = ["web"]
    service = "service-1"
    priority = 2
  [tcp.routers.Router-2]
    rule = "ClientIP(`192.168.0.0/24`)"
    entryPoints = ["web"]
    priority = 1
    service = "service-2"

Labels

   labels:
    - 'traefik.tcp.routers.Router-1.rule=ClientIP(`192.168.0.12`)'
    - "traefik.tcp.routers.Router-1.entryPoints=web"
    - "traefik.tcp.routers.Router-1.service=service-1"
    - "traefik.tcp.routers.Router-1.priority=2"
    - 'traefik.tcp.routers.Router-2.rule=ClientIP(`192.168.0.0/24`)'
    - "traefik.tcp.routers.Router-2.entryPoints=web"
    - "traefik.tcp.routers.Router-2.service=service-2"
    - "traefik.tcp.routers.Router-2.priority=1"

Tags

  {
    //...
    "Tags": [
      "traefik.tcp.routers.Router-1.rule=ClientIP(`192.168.0.12`)",
      "traefik.tcp.routers.Router-1.entryPoints=web",
      "traefik.tcp.routers.Router-1.service=service-1",
      "traefik.tcp.routers.Router-1.priority=2",
      "traefik.tcp.routers.Router-2.rule=ClientIP(`192.168.0.0/24`)",
      "traefik.tcp.routers.Router-2.entryPoints=web",
      "traefik.tcp.routers.Router-2.service=service-2",
      "traefik.tcp.routers.Router-2.priority=1"
    ]
  }

위 예시에서 Router-1 이 192.168.0.12 의 요청을 처리하도록 우선순위가 구성돼 있어요.

경로 겹침을 피하기 위해 경로는 기본적으로 규칙 길이를 기준으로 내림차순 정렬돼요.

우선순위는 규칙의 길이와 정확히 같으므로, 가장 긴 규칙이 가장 높은 우선순위를 가져요.

우선순위 값 0 은 무시돼요: priority: 0 은 기본 규칙 길이 정렬이 사용됨을 의미해요.

음수 우선순위 값도 지원돼요.

Traefik은 내부 라우터를 위해 우선순위 범위를 예약해 두며, 사용자가 정의할 수 있는 최대 라우터 우선순위 값은:

  • 32비트 플랫폼의 경우 (MaxInt32 - 1000),

  • 64비트 플랫폼의 경우 (MaxInt64 - 1000).

프로바이더 우선순위

서로 다른 프로바이더의 두 경로가 같은 숫자 우선순위를 공유할 때 Traefik은 providers.precedence 설치 구성 옵션을 사용해 어떤 경로가 우선하는지 결정해요.

precedence 에 먼저 나열된 프로바이더가 동률에서 이겨요.

더 알아보기 (Learn more)