Kubernetes 커스텀 리소스

원문 보기 위키 갱신 2026.10.03

Kubernetes 커스텀 리소스 (Kubernetes Custom Resources)

출처: Kubernetes Custom Resources

본문

Kubernetes CRD

Traefik은 IngressRoute, Middleware 등 몇 가지 Kubernetes 커스텀 리소스(Custom Resources)를 제공해요.

프로바이더로 KubernetesCRD를 사용할 때 Traefik은 커스텀 리소스 정의(Custom Resource Definition)를 사용해 라우팅 구성을 검색합니다. Traefik 커스텀 리소스 정의는 아래에 나열되어 있어요.

Traefik을 Helm 차트로 설치하면 기본적으로 kubernetesCRD 프로바이더가 활성화됩니다.

요구 사항 (Requirements)

Helm 차트 없이 Traefik을 설치하거나, Helm으로 스택을 업그레이드하는 경우 다음 요구 사항을 충족하는지 확인하세요.

모든 Traefik 리소스 정의 추가/업데이트
Traefik 커스텀 리소스에 대한 RBAC 추가/업데이트

# Install Traefik Resource Definitions:
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

# Install RBAC for Traefik:
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml

구성 예시 (Configuration Example)

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

File (YAML)

providers:
  kubernetesCRD: {}

File (TOML)

[providers.kubernetesCRD]

CLI

--providers.kubernetescrd=true

Helm Chart Values

## Values file
providers:
  kubernetesCRD:
    enabled: true

구성 옵션 (Configuration Options)

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:
  kubernetesCRD:
    endpoint: "http://localhost:8080"
    # ...

File (TOML)

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

CLI

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

defaultTLSResourcesNamespace

default라는 이름의 TLSOption과 TLSStore는 정의된 네임스페이스와 무관하게 클러스터 전체에 걸쳐 적용돼요. 전자는 TLSOption을 명시적으로 참조하지 않는 모든 라우터의 TLS 시행 정책을 보유하고, 후자는 모든 엔트리포인트가 제공하는 기본 인증서를 보유해요. 이 옵션을 통해 클러스터 운영자는 그 정의를 자신이 제어하는 네임스페이스로 한정할 수 있어요.

옵션이 설정되지 않으면 default라는 이름의 TLSOption 또는 TLSStore는 네임스페이스와 무관하게 고려되는데, 이것이 기본이자 이전 버전과 호환되는 동작이에요. 네임스페이스로 설정하면 그 네임스페이스 안의 default 리소스만 고려됩니다.

무시되는 리소스 (Ignored resources)

구성된 네임스페이스 밖에 정의된 default라는 TLSOption 또는 TLSStore는 무시되며, 네임스페이스가 붙은 이름으로도 참조할 수 없어요. TLSStore의 경우 이는 그것이 정의하는 인증서에도 적용됩니다.

File (YAML)

providers:
  kubernetesCRD:
    defaultTLSResourcesNamespace: traefik
    # ...

File (TOML)

[providers.kubernetesCRD]
  defaultTLSResourcesNamespace = "traefik"
  # ...

CLI

--providers.kubernetesCRD.defaultTLSResourcesNamespace=traefik

safeNaming

기본적으로 Kubernetes CRD 프로바이더는 자체가 만드는 라우터, 미들웨어, 서비스의 이름을 그 객체가 비롯된 네임스페이스와 이름을 결합해 생성하는데, 이는 두 개의 서로 다른 객체에 대해 같은 이름을 만들어 하나가 다른 하나를 조용히 대체할 수 있어요.

safeNaming은 대신 충돌 방지 명명을 활성화합니다. 생성된 이름은 그 객체의 정체성에서 파생되고, 여러 부모로부터 참조되는 Kubernetes Services(여러 서비스가 있는 라우트, 또는 Weighted/Mirroring/HighestRandomWeight TraefikService)는 정체성으로 공유되는 대신 각 부모로 범위가 지정됩니다.

시작 경고 (Startup warning)

safeNaming을 설정하지 않으면 현재 명명 방식이 충돌하기 쉬우므로 시작 시 경고가 기록됩니다. 이 옵션을 명시적으로 설정하는 것을 권장하며, 새 구성에서는 true로, 현재 동작을 유지하고 경고를 없애려면 false로 설정하세요.

safeNaming이 활성화되면 생성된 이름은 더 이상 정규화되지 않아요. 그 구성 요소는 Kubernetes 네임스페이스나 이름에 나타날 수 없는 _ 구분자로 결합되고, 라우트에 대해 생성된 이름은 규칙 대신 라우트 인덱스에서 파생됩니다. 예를 들어 default 네임스페이스에 whoami라는 이름의 Kubernetes Service와 test.route라는 이름의 IngressRoute가 있을 때:

default-whoami-80                          ->    default_whoami_80
default-test-route-6b204d94623b3df4370c    ->    default_test.route_0

TraefikService(weighted, mirroring 또는 highest random weight)에 의해 또는 여러 서비스가 있는 라우트에 의해 참조되는 Kubernetes Services에 대해 생성된 서비스는, 참조를 선언하는 부모의 이름 뒤에 참조 인덱스와 참조된 Kubernetes Service의 네임스페이스·이름·포트가 붙은 이름으로 명명됩니다.

default-whoami-80    ->    default_wrr1_wrr_1_default_whoami_80

이러한 각 참조는 고유한 옵션(serversTransport, scheme, sticky, healthCheck 등)을 가지는데, 이전에는 이것이 생성된 이름의 일부가 아니었습니다. 서로 다른 옵션이 있는 같은 Kubernetes Service에 대한 두 참조는 단일 서비스로 축소되었고 마지막으로 만들어진 것이 조용히 이겼어요. safeNaming이 활성화되면 그것들은 별개의 서비스가 되며, 이는 여러 부모로부터 참조되는 Kubernetes Service의 서버가 모두를 위해 한 번 대신 참조당 한 번씩 헬스 체크된다는 뜻이기도 해요.

관측성 (Observability)

이 이름들은 사용자에게 보입니다. 대시보드와 API, 액세스 로그의 RouterName과 ServiceName 필드, 메트릭의 router와 service 라벨에 나타나요. safeNaming이 활성화되면 Kubernetes CRD 라우터, 미들웨어, 서비스 이름에 일치하는 대시보드, 알림 규칙, 로그 쿼리를 그에 맞게 갱신해야 합니다.

File (YAML)

providers:
  kubernetesCRD:
    safeNaming: true
    # ...

File (TOML)

[providers.kubernetesCRD]
  safeNaming = true
  # ...

CLI

--providers.kubernetesCRD.safeNaming=true

라우팅 구성 (Routing Configuration)

Traefik CRD는 필요에 따라 조립할 수 있는 빌딩 블록이에요.

사용 가능한 커스텀 리소스는 아래 표와 같아요.

특이 사항 (Particularities)

다른 Kubernetes 리소스를 참조하기 위해 이름과 네임스페이스를 사용.
민감한 데이터(TLS 인증서와 자격 증명)를 위해 시크릿을 사용.

전체 예시 (Full Example)

Kubernetes로 서비스를 노출하는 방법에 대한 자세한 내용은 Kubernetes 가이드를 참고하세요.

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

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

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

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

더 알아보기 (Learn more)

Traefik 공식 문서