Traefik KV 스토어를 이용한 라우팅 구성

원문 보기 위키 갱신 2026.10.03

출처: Traefik Routing Configuration with KV stores

본문

Traefik & KV 스토어

설정 예시

KV 스토어 구성하기 & 서비스 하나 배포/노출하기 KV 스토어 프로바이더 활성화하기 (예: Consul)

구조화 (YAML)

providers:
  consul:
    endpoints:
      - "127.0.0.1:8500"

구조화 (TOML)

[providers.consul]
  endpoints = ["127.0.0.1:8500"]

CLI

--providers.consul.endpoints=127.0.0.1:8500

KV 스토어에 키 설정하기 (예: Consul)

consul kv put traefik/http/routers/my-router/rule "Host(`example.com`)"
consul kv put traefik/http/routers/my-router/service "my-service"
consul kv put traefik/http/services/my-service/loadbalancer/servers/0/url "http://127.0.0.1:8080"

서비스에 사용자 지정 포트 지정하기 http://example.com 에 대한 요청을 http://127.0.0.1:12345 로 전달하려면:

consul kv put traefik/http/routers/my-router/rule "Host(`example.com`)"
consul kv put traefik/http/routers/my-router/service "my-service"
consul kv put traefik/http/services/my-service/loadbalancer/servers/0/url "http://127.0.0.1:12345"

라우터와 서비스를 여러 개 지정하기 둘 이상의 서비스로 요청을 전달하려면 여러 라우터와 서비스를 정의해야 해요.

이 예시에서는 http://example-a.com 요청을 http://127.0.0.1:8000 으로, http://example-b.com 요청을 http://127.0.0.1:9000 으로 전달해요:

consul kv put traefik/http/routers/www-router/rule "Host(`example-a.com`)"
consul kv put traefik/http/routers/www-router/service "www-service"
consul kv put traefik/http/services/www-service/loadbalancer/servers/0/url "http://127.0.0.1:8000"

consul kv put traefik/http/routers/admin-router/rule "Host(`example-b.com`)"
consul kv put traefik/http/routers/admin-router/service "admin-service"
consul kv put traefik/http/services/admin-service/loadbalancer/servers/0/url "http://127.0.0.1:9000"

설정 옵션

키

키는 대소문자를 구분하지 않아요.

HTTP

Router

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

Service

서비스 이름 ** 에는 @ 문자가 허용되지 않아요.

| 키 (경로) | 설명 | 값 | | traefik/http/services//loadbalancer/servers/0/url | 서버에 대한 자세한 내용은 서버를 참고하세요. | http://:/ |

traefik/http/services//loadbalancer/servers/0/preservePath 서버에 대한 자세한 내용은 서버를 참고하세요. true

traefik/http/services//loadbalancer/servers/0/weight 서버에 대한 자세한 내용은 서버를 참고하세요. 1

traefik/http/services//loadbalancer/serverstransport 파일 프로바이더나 Kubernetes CRD 프로바이더로 정의된 ServersTransport 리소스를 참조할 수 있게 해줘요. serverstransport에 대한 자세한 내용은 serverstransport를 참고하세요. foobar@file

traefik/http/services//loadbalancer/passhostheader 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//loadbalancer/healthcheck/headers/X-Foo 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. foobar

traefik/http/services//loadbalancer/healthcheck/hostname 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. example.org

traefik/http/services//loadbalancer/healthcheck/interval 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. 10

traefik/http/services//loadbalancer/healthcheck/path 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. /foo

traefik/http/services//loadbalancer/healthcheck/method 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. foobar

traefik/http/services//loadbalancer/healthcheck/status 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. 42

traefik/http/services//loadbalancer/healthcheck/port 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. 42

traefik/http/services//loadbalancer/healthcheck/scheme 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. http

traefik/http/services//loadbalancer/healthcheck/timeout 헬스 체크에 대한 자세한 내용은 헬스 체크를 참고하세요. 10

traefik/http/services//loadbalancer/sticky 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//loadbalancer/sticky/cookie/httponly 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//loadbalancer/sticky/cookie/name 서비스에 대한 자세한 내용은 서비스를 참고하세요. foobar

traefik/http/services//loadbalancer/sticky/cookie/path 서비스에 대한 자세한 내용은 서비스를 참고하세요. /foobar

traefik/http/services//loadbalancer/sticky/cookie/secure 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//loadbalancer/sticky/cookie/samesite 서비스에 대한 자세한 내용은 서비스를 참고하세요. none

traefik/http/services//loadbalancer/sticky/cookie/maxage 서비스에 대한 자세한 내용은 서비스를 참고하세요. 42

traefik/http/services/myservice/loadbalancer/responseforwarding/flushinterval 서비스에 대한 자세한 내용은 서비스를 참고하세요. 10

traefik/http/services//mirroring/service 서비스에 대한 자세한 내용은 서비스를 참고하세요. foobar

traefik/http/services//mirroring/mirrors//name 서비스에 대한 자세한 내용은 서비스를 참고하세요. foobar

traefik/http/services//mirroring/mirrors//percent 서비스에 대한 자세한 내용은 서비스를 참고하세요. 42

traefik/http/services//weighted/services//name 서비스에 대한 자세한 내용은 서비스를 참고하세요. foobar

traefik/http/services//weighted/services//weight 서비스에 대한 자세한 내용은 서비스를 참고하세요. 42

traefik/http/services//weighted/sticky/cookie/name 서비스에 대한 자세한 내용은 서비스를 참고하세요. foobar

traefik/http/services//weighted/sticky/cookie/secure 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//weighted/sticky/cookie/samesite 서비스에 대한 자세한 내용은 서비스를 참고하세요. none

traefik/http/services//weighted/sticky/cookie/httpOnly 서비스에 대한 자세한 내용은 서비스를 참고하세요. true

traefik/http/services//weighted/sticky/cookie/maxage 서비스에 대한 자세한 내용은 서비스를 참고하세요. 42

traefik/http/services//failover/fallback Failover에 대한 자세한 내용은 Failover를 참고하세요. backup

traefik/http/services//failover/healthcheck Failover에 대한 자세한 내용은 Failover를 참고하세요. {}

traefik/http/services//failover/service Failover에 대한 자세한 내용은 Failover를 참고하세요. main

Middleware

설정 옵션

키 (경로) 설명 값

traefik/http/middlewares//middleware_type/middleware_option middleware_type 은 미들웨어의 타입(예: forwardAuth, headers 등)이고, middleware_option 은 설정할 미들웨어 옵션이에요(예: addPrefix 미들웨어의 경우 prefix). 사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션을 참고하세요. foobar

미들웨어 이름에는 @ 문자가 허용되지 않아요.

선언 충돌

이름은 같은데 매개변수가 다른 미들웨어를 여러 개 선언하면 미들웨어 선언이 실패해요.

ServerTransport

설정 옵션

키 (경로) | 설명 | 값 | | traefik/http/serversTransports//st_option | st_option 은 설정할 ServerTransport 옵션이에요(예: maxIdleConnsPerHost). 사용 가능한 옵션에 대한 자세한 내용은 전용 ServerTransport 섹션을 참고하세요. | ServerTransport 옵션 |

TCP

KV를 사용해 TCP 라우터 및/또는 서비스를 선언할 수 있어요.

Router

Service

Middleware

설정 옵션 traefik/tcp/middlewares/{원하는 이름}. 으로 시작하는 태그로 미들웨어를 선언하고, 그 뒤에 미들웨어 타입/옵션을 이어 붙여요.

예를 들어 이름이 test-inflightconn 인 InFlightConn 미들웨어를 선언하려면 traefik/tcp/middlewares/test-inflightconn/inflightconn/amount=10 이라고 쓰면 돼요.

사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션을 참고하세요.

| 키 (경로) | 설명 | 값 | | traefik/tcp/middlewares//middleware_type/middleware_option | middleware_type 은 미들웨어의 타입(예: inflightconn)이고, middleware_option 은 설정할 미들웨어 옵션이에요(예: inflightconn 미들웨어의 경우 amount). 사용 가능한 미들웨어에 대한 자세한 내용은 전용 미들웨어 섹션을 참고하세요. | foobar |

선언 충돌

이름은 같은데 매개변수가 다른 미들웨어를 여러 개 선언하면 미들웨어 선언이 실패해요.

ServerTransport

설정 옵션 | 키 (경로) | 설명 | 값 | | traefik/tcp/serversTransports//st_option | st_option 은 설정할 ServerTransport 옵션이에요(예: maxIdleConnsPerHost). 사용 가능한 옵션에 대한 자세한 내용은 전용 ServerTransport 섹션을 참고하세요. | ServerTransport 옵션 |

UDP

KV를 사용해 UDP 라우터 및/또는 서비스를 선언할 수 있어요.

Router

Service

TLS

TLS 옵션

KV 프로바이더를 사용하면 tls/options 키로 TLS 연결의 일부 매개변수를 구성할 수 있어요.

예를 들어 다음과 같은 기본 설정을 정의할 수 있어요:

TLS 기본 생성 인증서

Traefik이 기본 인증서를 생성하도록 ACME 프로바이더(예: Let's Encrypt)를 사용하도록 구성할 수 있어요.

기본 인증서를 해석하는 구성은 TLS 스토어에 정의해야 해요.

더 알아보기 (Learn more)

Traefik 공식 문서