Traefik Kubernetes Services

원문 보기 위키 갱신 2026.10.03

Traefik Kubernetes Services (TraefikService)

출처: Traefik Kubernetes Services Documentation

본문

TraefikService

TraefikService는 Kubernetes Service 위에 놓이는 커스텀 리소스예요. Kubernetes Service 사이의 가중치 라운드 로빈 로드 밸런싱, Highest Random Weight 로드 밸런싱, 미러링, 페일오버 같은 고급 로드 밸런싱 기능을 활성화해 줘요.

서비스는 들어오는 요청을 실제로 처리할 엔드포인트에 도달하는 방법을 구성해요. Traefik에서 대상 서비스는 파드를 노출하는 표준 Kubernetes service이거나 TraefikService일 수 있어요. 후자를 사용하면 다음과 같은 고급 로드 밸런싱 옵션을 결합할 수 있어요:

가중치 라운드 로빈 로드 밸런싱.
Highest Random Weight 로드 밸런싱.
미러링.
페일오버.

Weighted Round Robin (가중치 라운드 로빈)

WRR은 가중치를 기반으로 여러 서비스 사이에서 요청을 로드 밸런싱할 수 있어요. WRR TraefikService를 사용하면 Kubernetes Service와 다른 TraefikService 인스턴스(다른 WRR 서비스 또는 미러링 서비스) 사이에서 트래픽을 로드 밸런싱할 수 있어요.

Configuration Example (설정 예시)

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test-name
  namespace: apps

spec:
  entryPoints:
  - websecure
  routes:
  - match: Host(`example.com`) && PathPrefix(`/foo`)
    kind: Rule
    services:
    # Set a WRR TraefikService
    - name: wrr1
      namespace: apps
      kind: TraefikService
  tls:
    # Add a TLS certificate from a Kubernetes Secret
    secretName: supersecret

TraefikService WRR Level#1

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: wrr1
  namespace: apps

spec:
  weighted:
    services:
        # Kubernetes Service
      - name: svc1
        namespace: apps
        port: 80
        weight: 1
        # Second level WRR service
      - name: wrr2
        namespace: apps
        kind: TraefikService
        weight: 1
        # Mirroring service
        # The service is described in the Mirroring example
      - name: mirror1
        namespace: apps
        kind: TraefikService
        weight: 1

TraefikService WRR Level#2

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: wrr2
  namespace: apps

spec:
  weighted:
    services:
      # Kubernetes Service
      - name: svc2
        namespace: apps
        port: 80
        weight: 1
      # Kubernetes Service
      - name: svc3
        namespace: apps
        port: 80
        weight: 1

Kubernetes Services

apiVersion: v1
kind: Service
metadata:
  name: svc1
  namespace: apps

spec:
  ports:
  - name: http
      port: 80
  selector:
    app: traefiklabs
    task: app1
---
apiVersion: v1
kind: Service
metadata:
  name: svc2
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app2
---
apiVersion: v1
kind: Service
metadata:
  name: svc3
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app3

Secret

apiVersion: v1
kind: Secret
metadata:
  name: supersecret
  namespace: apps

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Configuration Options (설정 옵션)

Stickiness on multiple levels (여러 레벨에서의 고정 세션)

로드 밸런서를 연결하거나 혼합할 때(예: 서버 로드 밸런서가 서비스 로드 밸런서의 "자식" 중 하나인 경우), 고정 세션이 끝까지 동작하려면 필요한 모든 레벨에서 옵션을 지정해야 해요. 즉 클라이언트는 고정 레벨 수만큼 많은 key/value 쌍을 가진 쿠키를 보내야 해요.

고정 세션은 끝까지 동작하려면 각 로드 밸런싱 레벨에서 지정되어야 해요.

예를 들어 아래 예시에는, 두 whoami 서비스의 (가중치 라운드 로빈) 로드 밸런싱이 있으므로 첫 번째 레벨의 로드 밸런싱이 있고, 각 whoami 서비스는 replicaset이므로 서버 로드 밸런서로 처리되는 두 번째 레벨이 있어요.

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutebar
  namespace: apps

spec:
  entryPoints:
  - web
  routes:
  - match: Host(`example.com`) && PathPrefix(`/foo`)
    kind: Rule
    services:
    - name: wrr1
      namespace: apps
      kind: TraefikService

TraefikService WRR with 2 level of stickiness

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: wrr1
  namespace: apps

spec:
  weighted:
    services:
    - name: whoami1
      kind: Service
      port: 80
      weight: 1
      # Stickiness level2 (on the Kubernetes service)
      sticky:
        cookie:
        name: lvl2
    - name: whoami2
      kind: Service
      weight: 1
      port: 80
      # Stickiness level2 (on the Kubernetes service)
      sticky:
        cookie:
        name: lvl2
  # Stickiness level2 (on the WRR service)
  sticky:
    cookie:
    name: lvl1

위 예시에서, 같은 서버로 세션을 유지하려면 클라이언트가 매 요청에서 쿠키 안에 두 레벨을 지정해야 해요. 예를 들어 curl로:

# Assuming `10.42.0.6` is the IP address of one of the replicas (a pod then) of the `whoami1` service.
curl -H Host:example.com -b "lvl1=default-whoami1-80; lvl2=http://10.42.0.6:80" http://localhost:8000/foo

Highest Random Weight

HRW(Highest Random Weight) 로드 밸런서는 일관된 해싱(consistent hashing)을 사용해서 같은 클라이언트 IP에서 온 요청이 항상 같은 서비스로 라우팅되도록 보장해요. 가중치를 기반으로 요청을 분산하는 가중치 라운드 로빈과 달리, HRW는 클라이언트의 원격 주소를 기반으로 일관된 라우팅을 제공해요.

이는 고정 쿠키 없이 세션 선호도(session affinity)를 유지하는 데 특히 유용해요. 클라이언트가 자신의 IP 주소를 기반으로 일관되게 같은 백엔드 서비스에 도달할 수 있기 때문이에요.

Configuration Example (설정 예시)

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test-hrw
  namespace: apps

spec:
  entryPoints:
  - websecure
  routes:
  - match: Host(`example.com`) && PathPrefix(`/app`)
    kind: Rule
    services:
    # Set an HRW TraefikService
    - name: hrw1
      namespace: apps
      kind: TraefikService
  tls:
    secretName: supersecret

TraefikService HRW

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: hrw1
  namespace: apps

spec:
  highestRandomWeight:
    services:
      # Kubernetes Service with weight 10
      - name: svc1
        namespace: apps
        port: 80
        weight: 10
      # Kubernetes Service with weight 20
      - name: svc2
        namespace: apps
        port: 80
        weight: 20
      # Another TraefikService
      - name: wrr1
        namespace: apps
        kind: TraefikService
        weight: 15

Kubernetes Services

apiVersion: v1
kind: Service
metadata:
  name: svc1
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app1
---
apiVersion: v1
kind: Service
metadata:
  name: svc2
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app2

Configuration Options (설정 옵션)

How HRW Works (HRW 동작 방식)

Highest Random Weight 알고리즘은 일관된 해싱과 가중치 로드 밸런싱을 결합해요:

일관된 해싱: 각 수신 요청에 대해 클라이언트의 원격 주소가 해시되어 일관된 라우팅을 보장해요.
가중치 기반 선택: 각 서비스는 클라이언트 IP의 해시와 서비스 가중치를 모두 기반으로 한 난수 값을 할당받아요.
최고 선택: 계산된 값이 가장 높은 서비스가 요청을 받아요.

이 접근 방식은 몇 가지 이점을 제공해요:

세션 선호도: 클라이언트가 일관되게 같은 백엔드 서비스에 도달해요.
가중치 분산: 가중치가 높은 서비스가 선택될 가능성이 더 높아요.
상태 불필요: 고정 쿠키와 달리 클라이언트 측이나 서버 측 상태가 필요 없어요.
내결함성: 서비스가 사용 불가능해지면 요청은 남은 서비스 사이에 일관되게 재분산돼요.

Mirroring (미러링)

미러링은 서비스로 보내진 요청을 다른 서비스로 미러링할 수 있어요.

미러링 서비스를 사용하면 여러 서비스에 함께 트래픽을 보낼 수 있어요:

메인 서비스는 트래픽의 100%를 받아요.
미러 서비스들은 트래픽의 일정 비율을 받아요.

예를 들어 애플리케이션의 버전을 업그레이드할 때, 현재 버전을 타깃으로 하는 서비스를 메인 서비스로, 새 버전의 서비스를 미러 서비스로 설정할 수 있어요. 이렇게 하면 현재 버전에 계속 접근하면서 새 버전의 동작을 테스트할 수 있어요.

미러링 TraefikService는 Kubernetes Service와 다른 TraefikService 인스턴스(다른 WRR 서비스 또는 미러링 서비스)를 참조할 수 있게 해 줘요.

기본적으로 미러링되는 동안 전체 요청이 메모리에 버퍼링된다는 점에 유의하세요. 이 동작을 수정하는 방법은 아래 예시의 maxBodySize 옵션을 참고해 주세요.

Configuration Example (설정 예시)

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutebar
  namespace: default

spec:
  entryPoints:
    - web
  routes:
  - match: Host(`example.com`) && PathPrefix(`/foo`)
    kind: Rule
    services:
    - name: mirror1
      namespace: default
      kind: TraefikService

Mirroring from a Kubernetes Service

# Mirroring from a k8s Service
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: mirror1
  namespace: default

spec:
  mirroring:
    name: svc1                      # svc1 receives 100% of the traffic
    port: 80
    mirrorBody: true                # Default: true
    maxBodySize: 1048576
    mirrors:
      - name: svc2                  # svc2 receives a copy of 20% of this traffic
        port: 80
        percent: 20
      - name: svc3                  # svc3 receives a copy of 15% of this traffic
        kind: TraefikService
        percent: 15

Mirroring from a TraefikService (WRR)

# Mirroring from a Traefik Service
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: mirror1
  namespace: default

spec:
  mirroring:
    name: wrr1                      # wrr1 receives 100% of the traffic
    kind: TraefikService
    mirrors:
      - name: svc2                  # svc2 receives a copy of 20% of this traffic
        port: 80
        percent: 20
      - name: svc3                  # svc3 receives a copy of 10% of this traffic
        kind: TraefikService
        percent: 10

Kubernetes Services

apiVersion: v1
kind: Service
metadata:
  name: svc1
  namespace: default

spec:
  ports:
    - name: http
      port: 80
  selector:
    app: traefiklabs
    task: app1
---
apiVersion: v1
kind: Service
metadata:
  name: svc2
  namespace: default

spec:
  ports:
    - name: http
      port: 80
  selector:
    app: traefiklabs
    task: app2

Configuration Options (설정 옵션)

Main Service Options (메인 서비스 옵션)

메인 서비스 속성은 옵션의 루트 레벨로 설정돼요.

메인 서비스는 Service와 동일한 옵션을 제공해요.

서비스 옵션의 전체 목록은 Service 문서에 설명되어 있어요. 미러 메인 서비스 전용 옵션은 아래에 설명돼요.

Mirrored Services Options (미러링된 서비스 옵션)

미러링된 서비스 속성은 mirrors 목록에 설정돼요.

미러링된 서비스는 Service와 동일한 옵션을 제공해요.

서비스 옵션의 전체 목록은 Service 문서에 설명되어 있어요. 미러링된 서비스 전용 옵션은 아래에 설명돼요.

Failover (페일오버)

페일오버 서비스는 메인 서비스가 errors 구성에서 정의된 특정 HTTP 상태 코드로 응답할 때 모든 요청을 폴백(fallback) 서비스로 전달해요.

Failover

Failover 서비스에 대한 HealthCheck는 현재 File provider에서만 정의할 수 있어요.

Configuration Examples (설정 예시)

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test-name
  namespace: apps

spec:
  entryPoints:
  - websecure
  routes:
  - match: Host(`example.com`) && PathPrefix(`/foo`)
    kind: Rule
    services:
    # Set a Failover TraefikService
    - name: failover1
      namespace: apps
      kind: TraefikService

Failover from Kubernetes Services

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: failover1
  namespace: apps

spec:
  failover:
    service:
      name: svc1
      port: 80
    fallback:
      name: svc2
      port: 80
    errors:
      status:
        - "500-503"
        - "429"

Failover from TraefikService (WRR)

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: failover1
  namespace: apps

spec:
  failover:
    service:
      name: wrr1
      kind: TraefikService
    fallback:
      name: wrr2
      kind: TraefikService
    errors:
      status:
        - "500-503"

Failover with maxRequestBodyBytes

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: failover1
  namespace: apps

spec:
  failover:
    service:
      name: svc1
      port: 80
    fallback:
      name: svc2
      port: 80
    errors:
      status:
        - "500-503"
        - "429"
      maxRequestBodyBytes: 1048576

Kubernetes Services

apiVersion: v1
kind: Service
metadata:
  name: svc1
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app1
---
apiVersion: v1
kind: Service
metadata:
  name: svc2
  namespace: apps

spec:
  ports:
  - name: http
    port: 80
  selector:
    app: traefiklabs
    task: app2

Configuration Options (설정 옵션)

Main Service and Fallback Options (메인 서비스와 폴백 옵션)

service와 fallback 필드는 각각 Service와 동일한 옵션을 사용해 대상 서비스를 정의해요.

서비스 옵션의 전체 목록은 Service 문서에 설명되어 있어요.

Failover Dedicated Options (페일오버 전용 옵션)

더 알아보기 (Learn more)

Traefik 공식 문서