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

Traefik Kubernetes Gateway API 문서

원문 보기 위키 갱신

Traefik Kubernetes Gateway API 문서 (Traefik Kubernetes Gateway API Documentation)

출처: Traefik Kubernetes Gateway API Documentation

본문

Traefik & Kubernetes with Gateway API

Kubernetes Gateway 프로바이더는 Kubernetes 특별 관심 그룹(SIGs)의 Gateway API 사양에 대한 Traefik 구현이에요.

이 프로바이더는 Gateway API 사양의 Standard 버전 v1.6.2를 지원해요.

HTTPRoute의 모든 핵심 기능과 일부 확장 기능(Standard 채널의 BackendTLSPolicy, GRPCRoute, TLSRoute, 그리고 Experimental 채널의 TCPRoute 같은 리소스)을 완전히 지원해요.

자세한 내용은 적합성 보고서(conformance report)를 확인하세요.

Helm 차트 사용하기 (Using The Helm Chart)

Traefik Helm 차트를 사용하면 RBAC(Role-Based Access Control)이 자동으로 관리됩니다.

요구 사항 (Requirements)

Traefik은 Kubernetes 지원 정책을 따르며, 최소한 최신 마이너 3개 버전의 Kubernetes를 지원해요. 구버전에서는 일반적인 기능을 보장할 수 없습니다.

  • Kubernetes Gateway API CRD 설치/업데이트
# Install Gateway API CRDs from the Standard channel.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.2/standard-install.yaml

experimentalChannel에는 Experimental 채널 CRD가 필요해요

experimentalChannel 옵션은 Traefik이 Standard 채널 CRD가 제공하지 않는 TCPRoute와 TLSRoute 리소스를 감시하게 해요. Experimental 채널 CRD(experimental-install.yaml)를 설치하지 않고 이를 활성화하면 Kubernetes Gateway 프로바이더가 시작하지 못해요: TCPRoute와 TLSRoute뿐 아니라 Gateway API 리소스 자체도 전혀 서빙되지 않습니다. Traefik은 계속 실행되고 다른 프로바이더는 영향을 받지 않아요.

  • Helm 차트를 사용하지 않는다면 Gateway API용 Traefik RBAC 설치/업데이트
# Install Traefik RBACs for Gateway API.
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml

구성 예시 (Configuration Example)

아래에서 설명하는 것처럼 kubernetesGateway 프로바이더를 활성화할 수 있어요.

File (YAML)

providers:
  kubernetesGateway: {}
  # ...

File (TOML)

[providers.kubernetesGateway]
# ...

CLI

--providers.kubernetesgateway=true

Helm Chart Values

## Values file
providers:
  kubernetesGateway:
    enabled: true

구성 옵션 (Configuration Options)

| Field | Description | Default | Required | | providers.providersThrottleDuration | 구성 리로드 이후, 새로운 구성 갱신 이벤트를 반영하기까지 기다리는 최소 시간. 이 시간 안에 여러 이벤트가 발생하면 가장 최근 이벤트 하나만 반영되고 나머지는 모두 버려져요. 이 옵션은 프로바이더별로 설정할 수 없지만, 스로틀링 알고리즘은 각 프로바이더에 독립적으로 적용됩니다. | 2s | No | | providers.kubernetesGateway.endpoint | 서버 엔드포인트 URL. 자세한 정보는 여기. | "" | No | | providers.kubernetesGateway.experimentalChannel | Experimental 채널 리소스(Gateway API 릴리스 채널 문서)에 대한 지원을 토글해요. (예: TCPRoute) 클러스터에 Experimental 채널 CRD가 설치되어 있어야 합니다. Requirements 참고. | false | No | | providers.kubernetesGateway.token | Kubernetes 클라이언트 구성에 사용되는 Bearer 토큰. 토큰 값 자체 또는 토큰이 들어 있는 파일 경로를 모두 허용해요. | "" | No | | providers.kubernetesGateway.certAuthFilePath | 인증 기관 파일의 경로. Kubernetes 클라이언트 구성에 사용됨. | "" | No | | providers.kubernetesGateway.namespaces | 감시할 네임스페이스 배열. 비워 두면 모든 네임스페이스를 감시해요. | [] | No | | providers.kubernetesGateway.labelSelector | GatewayClass에 대해서만 필터링을 허용해요. 비워 두면 Traefik이 모든 GatewayClass 객체를 처리합니다. 자세한 내용은 label-selectors 참고. | "" | No | | providers.kubernetesGateway.gateways | 프로바이더를 특정 게이트웨이로 한정해요. | [] | No | | providers.kubernetesGateway.gateways[0].name | Gateway 이름. | "" | No | | providers.kubernetesGateway.gateways[0].namespace | Gateway 네임스페이스. | "" | No | | providers.kubernetesGateway.throttleDuration | 새 구성을 생성하기 전에 두 Kubernetes 이벤트 사이에 대기하는 최소 시간. 초당 여러 번 갱신되는 Kubernetes 클러스터가 Traefik 구성을 계속 바꾸는 것을 방지해요. 비워 두면 모든 이벤트가 포착됩니다. | 0s | No | | providers.kubernetesGateway.nativeLBByDefault | 기본적으로 네이티브 Kubernetes 로드 밸런싱 모드를 사용할지 여부를 정의해요. 자세한 내용은 traefik.io/service.nativelb 서비스 어노테이션 문서를 확인하세요. | false | No | | providers.kubernetesGateway. statusAddress.hostname | Gateway status.addresses에 복사되는 호스트 이름. | "" | No | | providers.kubernetesGateway. statusAddress.ip | Gateway status.addresses에 복사되는 IP 주소. 현재 하나의 IP 값(IPv4 또는 IPv6)만 지원해요. | "" | No | | providers.kubernetesGateway. statusAddress.service.namespace | 상태 주소를 복사할 Kubernetes 서비스의 네임스페이스. External-DNS 같은 타사 도구를 사용할 때 이 옵션으로 서비스 loadbalancer.status(서비스 엔드포인트 IP 포함)를 Gateway status.addresses에 복사할 수 있어요. | "" | No | | providers.kubernetesGateway. statusAddress.service.name | 상태 주소를 복사할 Kubernetes 서비스의 이름. External-DNS 같은 타사 도구를 사용할 때 이 옵션으로 서비스 loadbalancer.status(서비스 엔드포인트 IP 포함)를 Gateway status.addresses에 복사할 수 있어요. | "" | No | | providers.kubernetesGateway.crossProviderNamespaces | Gateway API 라우트(HTTPRoute, TCPRoute, TLSRoute)가 kind TraefikService의 backendRef를 선언할 수 있는 네임스페이스 목록. 설정하지 않으면 모든 네임스페이스가 허용돼요. []로 설정하면 그러한 backendRef가 모두 거부되고 라우트가 삭제됩니다. | [] | No | | providers.kubernetesGateway.qps | Kubernetes API 서버에 대한 최대 QPS를 정의해요. 음수 값으로 설정하면 클라이언트 측 레이트리밋이 비활성화됩니다. | 50 | No | | providers.kubernetesGateway.burst | Kubernetes API 서버에 대한 최대 요청 버스트를 정의해요. | 100 | No |

endpoint

Kubernetes 서버 엔드포인트 URL이에요.

Kubernetes에 배포될 때 Traefik은 KUBERNETES_SERVICE_HOST와 KUBERNETES_SERVICE_PORT 또는 KUBECONFIG 환경 변수를 읽어 엔드포인트를 구성해요.

액세스 토큰은 /var/run/secrets/kubernetes.io/serviceaccount/token에서, SSL CA 인증서는 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt에서 조회됩니다. 둘 다 Kubernetes 안에 배포될 때 자동으로 마운트돼요.

클러스터 안에서 환경 변수 값을 오버라이드하려면 엔드포인트를 지정할 수 있어요.

환경 변수를 찾지 못하면 Traefik은 external-cluster 클라이언트로 Kubernetes API 서버에 연결하려고 해요. 이 경우 엔드포인트가 필요합니다. 특히 관련 kubeconfig가 부여한 인증과 권한을 사용해 Kubernetes 클러스터에 연결하기 위해 kubectl proxy가 사용하는 URL로 설정할 수 있어요.

File (YAML)

providers:
  kubernetesGateway:
    endpoint: "http://localhost:8080"
    # ...

File (TOML)

[providers.kubernetesGateway]
  endpoint = "http://localhost:8080"
  # ...

CLI

--providers.kubernetesgateway.endpoint=http://localhost:8080

라우팅 구성 (Routing Configuration)

라우팅(routing) 문서의 전용 섹션을 참고하세요.

라우팅 구성 (Routing Configuration)

Kubernetes Gateway API 프로바이더를 사용할 때 Traefik은 Gateway API CRD를 사용해 라우팅 구성을 검색해요. Gateway API 개념 문서와 Traefik 문서의 전용 라우팅 섹션을 확인하세요.

프로덕션에서 Traefik OSS를 사용하고 계신가요?

직장에서 Traefik을 사용하고 있다면 기업용 API 게이트웨이 기능이나 Traefik OSS에 대한 상용 지원을 고려해 보세요.

  • API 게이트웨이 데모 영상 보기
  • 24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 추가하는 일은 빠르고 매끄러워요. 교체(rip and replace)가 필요 없고 모든 구성이 그대로 유지됩니다. 이 짧은 영상에서 실제 동작을 확인해 보세요.

더 알아보기 (Learn more)