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

Traefik Kubernetes Ingress 문서

원문 보기 위키 갱신

Traefik Kubernetes Ingress 문서 (Traefik Kubernetes Ingress Documentation)

출처: Traefik Kubernetes Ingress Documentation

본문

Traefik & Kubernetes

Traefik Kubernetes Ingress 프로바이더는 Kubernetes Ingress 컨트롤러예요. 즉 Ingress 사양을 지원하여 클러스터 서비스에 대한 액세스를 관리합니다.

Ingress 백엔드 리소스 미지원

specific.rules.http.paths.backend.resource를 사용해 백엔드 서비스 엔드포인트를 참조하는 것은 지원되지 않아요. 대신 spec.rules.http.paths.backend.service를 사용하세요.

Ingress API 동결

Kubernetes Ingress API는 동결되었으며 더 이상 변경이나 업데이트가 없을 거예요. 대신 Kubernetes Gateway 프로바이더 사용을 권장합니다.

구성 예시 (Configuration Example)

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

File (YAML)

providers:
  kubernetesIngress: {}

File (TOML)

[providers.kubernetesIngress]

CLI

--providers.kubernetesingress=true

Helm Chart Values

## Values file
providers:
  kubernetesIngress:
    enabled: true

그런 다음 프로바이더는 아래 예시와 같은 들어오는 인그레스 이벤트를 감시하고, 그로부터 해당 동적 구성을 파생하여 결과적으로 라우터, 서비스, 핸들러 등을 만들게 됩니다.

구성 옵션 (Configuration Options)

| Field | Description | Default | Required | | providers.providersThrottleDuration | 구성 리로드 이후, 새로운 구성 갱신 이벤트를 반영하기까지 기다리는 최소 시간. 이 시간 안에 여러 이벤트가 발생하면 가장 최근 이벤트 하나만 반영되고 나머지는 모두 버려져요. 이 옵션은 프로바이더별로 설정할 수 없지만, 스로틀링 알고리즘은 각 프로바이더에 독립적으로 적용됩니다. | 2s | No | | providers.kubernetesIngress.endpoint | 서버 엔드포인트 URL. 자세한 정보는 여기. | "" | No | | providers.kubernetesIngress.token | Kubernetes 클라이언트 구성에 사용되는 Bearer 토큰. 토큰 값 자체 또는 토큰이 들어 있는 파일 경로를 모두 허용해요. | "" | No | | providers.kubernetesIngress.certAuthFilePath | 인증 기관 파일의 경로. Kubernetes 클라이언트 구성에 사용됨. | "" | No | | providers.kubernetesIngress.namespaces | 감시할 네임스페이스 배열. 비워 두면 모든 네임스페이스를 감시해요. | | No | | providers.kubernetesIngress.labelSelector | 라벨 셀렉터를 사용해 Ingress 객체에만 필터링을 허용해요. Kubernetes Secrets, EndpointSlices, Services에는 영향 없음. 자세한 내용은 label-selectors 참고. | "" | No | | providers.kubernetesIngress.ingressClass | 처리할 리소스 객체를 식별하는 IngressClass 리소스 이름 또는 kubernetes.io/ingress.class 어노테이션 값. 비워 두면 해당 어노테이션이 없거나, 빈 값이거나, traefik 값인 리소스가 처리됩니다. | "" | No | | providers.kubernetesIngress.disableIngressClassLookup | 더 이상 사용되지 않음: 대신 disableClusterScopeResources를 사용하세요. 클러스터에서 IngressClasses 발견을 방지해요. Traefik에 IngressClasses 조회 권한을 부여해야 하는 요구가 완화됩니다. IngressClass가 있는 Ingress를 무시해요. 어노테이션은 이 옵션의 영향을 받지 않아요. | false | No | | providers.kubernetesIngress. ingressEndpoint.hostname | Kubernetes Ingress 엔드포인트에 사용되는 호스트 이름. | "" | No | | providers.kubernetesIngress. ingressEndpoint.ip | 이 IP는 Ingress status.loadbalancer.ip에 복사되며, 현재 하나의 IP 값(IPv4 또는 IPv6)만 지원해요. | "" | No | | providers.kubernetesIngress. ingressEndpoint.publishedService | 상태를 복사할 Kubernetes 서비스. 자세한 내용은 여기. | "" | No | | providers.kubernetesIngress.throttleDuration | 새 구성을 생성하기 전에 두 Kubernetes 이벤트 사이에 대기하는 최소 시간. 초당 여러 번 갱신되는 Kubernetes 클러스터가 Traefik 구성을 계속 바꾸는 것을 방지해요. 비워 두면 모든 이벤트가 포착됩니다. | 0s | No | | providers.kubernetesIngress.allowEmptyServices | 사용 가능한 엔드포인트가 없는 서비스에 도달하는 라우트를 만들 수 있게 해요. Traefik이 503 HTTP 상태를 반환하기 전에 이 서비스를 대상으로 하는 요청과 응답을 처리(미들웨어 적용 또는 관측성 작업)할 수 있게 합니다. | false | No | | providers.kubernetesIngress.allowExternalNameServices | Ingress가 ExternalName 서비스를 참조할 수 있게 해요. | false | No | | providers.kubernetesIngress.crossProviderNamespaces | Ingress 또는 Services가 traefik.ingress.kubernetes.io/router.middlewares, traefik.ingress.kubernetes.io/router.tls.options, traefik.ingress.kubernetes.io/service.middlewares, traefik.ingress.kubernetes.io/service.serverstransport 어노테이션을 사용할 수 있는 네임스페이스 목록. 설정하지 않으면 모든 네임스페이스가 허용돼요. []로 설정하면 모든 크로스 프로바이더 참조가 거부됩니다. | [] | No | | providers.kubernetesIngress.nativeLBByDefault | 모든 Ingress에 대해 기본적으로 Traefik이 제공하는 것 대신 Kubernetes Service 로드 밸런싱을 팟들 사이에서 사용할 수 있게 해요. Service에서 오버라이드할 수 있어요. | false | No | | providers.kubernetesIngress.disableClusterScopeResources | 클러스터 범위 리소스(IngressClass, Nodes) 발견을 방지해요. 이렇게 하면 Traefik에 클러스터 리소스 조회 권한을 부여해야 하는 요구가 완화됩니다. 또한 Traefik은 IngressClass 참조가 있는 Ingress를 처리하지 않으므로 그러한 Ingress는 무시됩니다(어노테이션은 이 옵션의 영향을 받지 않는다는 점을 유의하세요). 이는 서비스에서 NodePortLB 옵션 사용도 방지해요. | false | No | | providers.kubernetesIngress.strictPrefixMatching | 접두어 매칭을 Kubernetes Ingress 사양(문자 단위 문자열 매칭 대신 경로 요소 단위 매칭)에 엄격히 따르게 해요. 예를 들어 /foo의 PathPrefix는 /foo, /foo/, /foo/bar와 일치하지만 /foobar와는 일치하지 않아요. | false | 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:
  kubernetesIngress:
    endpoint: "http://localhost:8080"
    # ...

File (TOML)

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

CLI

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

ingressEndpoint.publishedService

형식: namespace/servicename.

상태를 복사할 Kubernetes 서비스로, 서비스 유형에 따라 달라요.

  • ClusterIP: 서비스의 ExternalIPs가 인그레스 상태로 전파됩니다.
  • NodePort: 클러스터 노드의 ExternalIP 주소가 인그레스 상태로 전파됩니다.
  • LoadBalancer: 서비스의 loadBalancer.status 필드(로드 밸런서가 제공하는 엔드포인트 포함)의 IP가 인그레스 상태로 전파됩니다.
  • ExternalName: 서비스의 spec.externalName 필드의 호스트 이름이 인그레스 상태로 전파됩니다.

External-DNS 같은 타사 도구를 사용할 때 이 옵션은 외부 서비스 IP를 인그레스 리소스로 복사할 수 있게 해줘요.

File (YAML)

providers:
  kubernetesIngress:
    ingressEndpoint:
      publishedService: "namespace/foo-service"
    # ...

File (TOML)

[providers.kubernetesIngress.ingressEndpoint]
  publishedService = "namespace/foo-service"
  # ...

CLI

--providers.kubernetesingress.ingressendpoint.publishedservice=namespace/foo-service

라우팅 구성 (Routing Configuration)

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

더 알아보기 (Further)

Traefik이 지원하는 Ingress 사양의 다양한 측면을 더 알아보려면, Traefik 저장소의 테스트 예시에 많은 Ingress 정의 예시가 있습니다.

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

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

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

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

더 알아보기 (Learn more)