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

Kubernetes에서 Traefik 설정하기

원문 보기 위키 갱신

출처: Setup Traefik on Kubernetes

본문

Kubernetes

이 가이드는 공식 Helm 차트를 사용해 Kubernetes 클러스터 안에 Traefik Proxy를 설치하고 구성하는 과정을 깊이 있게 안내해요. 이 가이드에서 다룰 내용은 다음과 같아요:

  • 표준 HTTP(web)와 HTTPS(websecure) 엔트리포인트 구성하기

  • HTTP에서 HTTPS로의 자동 리다이렉션 구현하기

  • Basic Authentication으로 Traefik 대시보드 보호하기

  • 설정을 테스트할 데모 애플리케이션 배포하기

  • 다른 주요 구성 옵션 살펴보기

사전 요구 사항

  • Kubernetes 클러스터

  • Helm v3

  • Kubectl

클러스터 만들기

아직 Kubernetes 클러스터가 없다면 K3d로 하나를 만들 수 있어요:

k3d cluster create traefik \
  --port 80:80@loadbalancer \
  --port 443:443@loadbalancer \
  --port 8000:8000@loadbalancer \
  --k3s-arg "--disable=traefik@server:0"

포트 80과 443은 호스트에서 Traefik으로 도달하고, 포트 8000은 나중 데모를 위해 남겨둬요. k3s와 함께 제공되는 내장 Traefik은 충돌을 피하기 위해 비활성화해요.

컨텍스트를 확인하세요:

kubectl cluster-info --context k3d-traefik

다음과 같은 결과를 볼 수 있어야 해요:

Kubernetes control plane is running at https://0.0.0.0:56049
CoreDNS is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

차트 저장소와 네임스페이스 추가하기

Helm은 Kubernetes 애플리케이션 배포를 간소화해요. Helm은 애플리케이션을 "차트"로 패키징하는데, 차트는 Kubernetes 리소스를 설명하는 템플릿 파일 모음이에요. 우리는 관리되고 커스터마이즈 가능한 설치를 위해 공식 Traefik Helm 차트를 사용해요.

helm repo add traefik https://traefik.github.io/charts
helm repo update
kubectl create namespace traefik

첫 번째 명령은 공식 차트 위치를 가리키는 traefik 저장소 별칭을 등록해요. 두 번째 명령은 로컬 캐시를 새로고침해 구성된 모든 저장소에서 사용 가능한 최신 차트와 버전 목록을 확보해요.

로컬 자체 서명 TLS 시크릿 만들기

Traefik의 Gateway 리스너는 리스너가 protocol: HTTPS를 사용할 때마다 인증서를 요구해요.

로컬 개발을 위해 일회용 자체 서명 인증서를 만들고 이를 local-selfsigned-tls라는 Kubernetes Secret에 저장하세요. Gateway는 이 시크릿을 참조해 websecure 리스너에서 TLS를 종료해요.

# 1) Generate a self‑signed certificate valid for *.docker.localhost
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=*.docker.localhost"

# 2) Create the TLS secret in the traefik namespace
kubectl create secret tls local-selfsigned-tls \
  --cert=tls.crt --key=tls.key \
  --namespace traefik

왜 이걸 해야 하나요?

Gateway의 HTTPS 리스너는 certificateRefs를 통해 이 시크릿을 참조해요. 없으면 helm 차트 검증이 실패하고 HTTP→HTTPS 리다이렉트 체인이 깨져요.

프로덕션 팁

위의 자체 서명 인증서는 로컬 개발 전용이에요. 프로덕션에서는 조직의 CA가 발급한 인증서를 Secret에 저장하거나 cert-manager나 Traefik의 ACME(Let's Encrypt) 같은 자동 발급기가 인증서를 필요할 때 생성하게 하세요. websecure 리스너의 certificateRefs를 갱신하거나 traefik.io/tls.certresolver를 사용해서 클라이언트가 신뢰할 수 있는 인증서를 받아 브라우저 경고가 더 이상 뜨지 않게 하세요.

Helm 차트 구성 값 준비하기

다음 내용으로 values.yaml 파일을 만드세요:

# Configure Network Ports and EntryPoints
# EntryPoints are the network listeners for incoming traffic.
ports:
  # Defines the HTTP entry point named 'web'
  web:
    port: 80
    nodePort: 30000
    # Instructs this entry point to redirect all traffic to the 'websecure' entry point
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true

  # Defines the HTTPS entry point named 'websecure'
  websecure:
    port: 443
    nodePort: 30001

# Enables the dashboard in Secure Mode
api:
  dashboard: true
  insecure: false

ingressRoute:
  dashboard:
    enabled: true
    matchRule: Host(`dashboard.docker.localhost`)
    entryPoints:
      - websecure
    middlewares:
      - name: dashboard-auth

# Creates a BasicAuth Middleware and Secret for the Dashboard Security
extraObjects:
  - apiVersion: v1
    kind: Secret
    metadata:
      name: dashboard-auth-secret
    type: kubernetes.io/basic-auth
    stringData:
      username: admin
      password: "P@ssw0rd"      # Replace with an Actual Password
  - apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
    spec:
      basicAuth:
        secret: dashboard-auth-secret

# We will route with Gateway API instead.
ingressClass:
  enabled: false

# Enable Gateway API Provider & Disables the KubernetesIngress provider
# Providers tell Traefik where to find routing configuration.
providers:
  kubernetesIngress:
    enabled: false
  kubernetesGateway:
    enabled: true

## Gateway Listeners
gateway:
  listeners:
    web:           # HTTP listener that matches entryPoint `web`
      port: 80
      protocol: HTTP
      namespacePolicy:
        from: All

    websecure:         # HTTPS listener that matches entryPoint `websecure`
      port: 443
      protocol: HTTPS  # TLS terminates inside Traefik
      namespacePolicy:
        from: All
      mode: Terminate
      certificateRefs:    
        - kind: Secret
          name: local-selfsigned-tls  # the Secret we created before the installation
          group: ""

# Enable Observability
log:
  level: INFO
# This enables access logs, outputting them to Traefik's standard output by default. The [Access Logs Documentation](https://doc.traefik.io/traefik/observability/access-logs/) covers formatting, filtering, and output options.
accessLog:
  enabled: true

# Enables Prometheus for Metrics
metrics:
  prometheus:
    enabled: true

Helm 값으로 Traefik 설치하기

이제 Helm 클라이언트로 구성을 적용하세요.

# Install the chart into the 'traefik' namespace
helm install traefik traefik/traefik \
  --namespace traefik \
  --values values.yaml

명령 분석:

  • helm install traefik: Helm에 traefik이라는 새 릴리스를 설치하라고 지시해요.

  • traefik/traefik: 사용할 차트를 지정해요(앞서 추가한 traefik 저장소의 traefik 차트).

  • --namespace traefik: 설치할 Kubernetes 네임스페이스를 지정해요. 전용 네임스페이스를 사용하는 것이 권장되는 관행이에요.

  • --values values.yaml: values.yaml 파일의 커스텀 구성을 적용해요.

대시보드 접근하기

이제 Traefik이 배포됐으니 https://dashboard.docker.localhost/에서 대시보드에 접근할 수 있어요. 이 링크에 접근하면 브라우저가 사용자 이름과 비밀번호를 요구할 거예요. values.yaml 파일에 설정한 자격 증명을 사용해 로그인하세요. 로그인에 성공하면 아래와 같이 대시보드가 표시돼요:

데모 애플리케이션 배포하기

설정을 테스트하려면 Kubernetes 클러스터에 Traefik whoami 애플리케이션을 배포하세요. whoami.yaml이라는 파일을 만들고 다음을 붙여넣으세요:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  namespace: traefik
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: traefik
spec:
  selector:
    app: whoami
  ports:
    - port: 80

매니페스트를 적용하세요:

kubectl apply -f whoami.yaml

애플리케이션을 배포한 후 Gateway API HTTPRoute를 만들어 애플리케이션을 노출할 수 있어요. 그러려면 whoami-route.yaml이라는 파일을 만들고 다음을 붙여넣으세요:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
  namespace: traefik
spec:
  parentRefs:
    - name: traefik-gateway # Name of the Gateway that Traefik creates when you enable the Gateway API provider
  hostnames:
    - "whoami.docker.localhost"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: whoami
          port: 80

매니페스트를 적용하세요:

kubectl apply -f whoami-route.yaml

매니페스트를 적용한 후 Traefik 대시보드의 Routes로 이동하면 https://whoami.docker.localhost 라우트가 생성된 것을 볼 수 있어요.

curl로 애플리케이션을 테스트할 수 있어요:

curl -k https://whoami.docker.localhost/

Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1

브라우저를 열고 https://whoami.docker.localhost로 이동해 서비스의 JSON 덤프를 볼 수도 있어요.

기타 주요 구성 영역

위 설정은 안전한 기반을 제공하지만, Traefik은 훨씬 더 많은 기능을 제공해요. 여기서는 Helm values.yaml 오버라이드를 사용한 최소 예시와 함께 다른 필수 구성에 대한 간략한 개요를 다룰게요.

이 예시들은 기능을 활성화하는 방법을 보여주는 것이므로, 자세한 옵션은 메인 문서를 참고하세요.

TLS 인증서 관리 (Let's Encrypt)

websecure 엔트리포인트에서는 TLS가 기본적으로 활성화돼 있어요. 하지만 현재 유효한 인증서가 없어요. Traefik은 ACME 프로토콜을 사용해 Let's Encrypt에서 TLS 인증서를 자동으로 획득하고 갱신할 수 있어요.

values.yaml 추가 예시:

additionalArguments:
  - "[email protected]"
  - "--certificatesresolvers.le.acme.storage=/data/acme.json"
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
  # - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Requires provider-specific config, adjust if you control your DNS provider

# Enable persistence for ACME data (certificates, account) to ensure it survives pod restarts:
persistence:
  enabled: true
  name: data
  size: 1Gi
  storageClass: ""

이것은 le라는 인증서 리졸버를 활성화하고, 필수 이메일과 저장 파일을 구성하며, HTTP 챌린지를 설정해요(포트 80 접근 필요). 전체 내용(DNS 챌린지 구성 포함)은 HTTPS/TLS 문서와 Let's Encrypt 문서를 참고하세요.

프로덕션의 Let's Encrypt

Let's Encrypt는 포트 80(HTTP-01) 또는 DNS 프로바이더 API(DNS-01)를 통해 접근 가능한 공개 IP 주소를 가리키는 호스트 이름에 대해서만 인증서를 발급할 수 있어요. *.docker.localhost 예시를 여러분이 제어하는 실제 도메인으로 바꾸고, DNS 레코드를 만든 뒤, 검증이 성공할 수 있도록 클러스터로 포트 80/443을 열어 두세요.

Gateway API와 ACME

Traefik의 내장 ACME/Let's Encrypt 통합은 IngressRoute와 Ingress 리소스에서 동작하지만, Gateway API 리스너에는 인증서를 발급하지 않아요. Gateway API를 사용한다면 cert-manager(또는 다른 인증서 컨트롤러)를 설치하고, 그것이 만든 시크릿을 gateway.listeners.websecure.certificateRefs에서 참조하세요.

메트릭 (Prometheus)

Traefik은 성능과 처리하는 트래픽 모니터링에 필수적인 세부 메트릭을 Prometheus 형식으로 노출할 수 있어요.

values.yaml 추가 예시:

# Enable metrics endpoint
metrics:
  prometheus:
    # The entry point metrics will be available on (usually internal/admin)
    entryPoint: metrics
    # Add standard Prometheus metrics
    addRoutersLabels: true
    addServicesLabels: true
    # ... other options available

이것은 전용 metrics 엔트리포인트(포트 9100)에서 Prometheus 엔드포인트를 활성화해요. 구성 세부 사항과 사용 가능한 메트릭은 Metrics 문서를 참고하세요.

트레이싱 (OTel)

분산 트레이싱은 시스템(그리고 Traefik 자체)을 통한 요청 지연 시간과 흐름을 이해하는 데 도움을 줘요.

values.yaml 추가 예시:

additionalArguments:
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector.observability:4317" # Adjust endpoint as needed
  - "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed

이것은 OTel 트레이싱을 활성화하고 컬렉터 엔드포인트를 지정해요. OTel 트레이싱에 대한 자세한 내용은 Tracing 문서를 참고하세요.

결론

이 설정은 보안 대시보드 접근과 HTTPS 리다이렉션을 갖춘 Traefik을 구축하고, 관측 가능성과 TLS 활성화에 대한 안내도 포함해요.

프로덕션에서 Traefik OSS를 사용 중인가요?

업무에서 Traefik을 사용한다면 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS용 상용 지원을 고려해 보세요.

  • API Gateway 데모 영상 보기

  • 24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 추가하는 건 빠르고 매끄러워요. 대체(rip and replace)가 필요 없고 모든 구성이 그대로 유지돼요. 이 짧은 영상으로 직접 확인해 보세요.

더 알아보기