Helm을 활용한 Traefik 쿠버네티스 설치하기

🔔 알림: 이 게시글은 Google의 AI 모델인 Gemini를 통해 원본 문서를 번역하고 기술적인 내용을 바탕으로 정리한 글입니다.
원본 출처: Traefik 공식 문서 (Kubernetes Setup) https://doc.traefik.io/traefik/setup/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

 

클러스터 문제를 추가로 디버깅하고 진단하려면 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의 게이트웨이 리스너가 HTTPS 프로토콜을 사용할 때마다 인증서가 필요합니다. 로컬 개발을 위해 일회용 자체 서명 인증서를 생성하고 이를 local-selfsigned-tls라는 이름의 Kubernetes 시크릿에 저장합니다. 게이트웨이는 이 시크릿을 참조하여 websecure 리스너에서 TLS를 종료(terminate)합니다.

# 1) *.docker.localhost에 유효한 자체 서명 인증서 생성
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=*.docker.localhost"

# 2) traefik 네임스페이스에 TLS 시크릿 생성
kubectl create secret tls local-selfsigned-tls \
  --cert=tls.crt --key=tls.key \
  --namespace traefik

 

이 작업이 필요한 이유 게이트웨이의 HTTPS 리스너는 certificateRefs를 통해 이 시크릿을 참조합니다. 이것이 없으면 Helm 차트 검증이 실패하고 HTTP→HTTPS 리다이렉션 체인이 끊어집니다.

 

운영 환경 팁 위의 자체 서명 인증서는 로컬 개발용으로만 사용해야 합니다. 운영 환경에서는 조직의 CA에서 발급한 인증서를 시크릿에 저장하거나, cert-manager 또는 Traefik의 ACME(Let's Encrypt)와 같은 자동 발급 도구를 사용하여 필요할 때 인증서를 생성하세요. 클라이언트가 신뢰할 수 있는 인증서를 받고 브라우저 경고가 표시되지 않도록 websecure 리스너의 certificateRefs를 업데이트하거나 traefik.io/tls.certresolver를 사용하세요.

---

Helm 차트 설정 값(Values) 준비

다음 내용을 포함하는 values.yaml 파일을 생성합니다.

# 네트워크 포트 및 엔트리포인트 구성
# 엔트리포인트는 들어오는 트래픽을 위한 네트워크 리스너입니다.
ports:
  # 'web'이라는 이름의 HTTP 엔트리포인트 정의
  web:
    port: 80
    nodePort: 30000
    # 이 엔트리포인트의 모든 트래픽을 'websecure' 엔트리포인트로 리다이렉트하도록 지시
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true

  # 'websecure'라는 이름의 HTTPS 엔트리포인트 정의
  websecure:
    port: 443
    nodePort: 30001

# 보안 모드에서 대시보드 활성화
api:
  dashboard: true
  insecure: false

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

# 대시보드 보안을 위한 BasicAuth 미들웨어 및 시크릿 생성
extraObjects:
  - apiVersion: v1
    kind: Secret
    metadata:
      name: dashboard-auth-secret
    type: kubernetes.io/basic-auth
    stringData:
      username: admin
      password: "P@ssw0rd" # 실제 비밀번호로 교체하세요
  - apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
    spec:
      basicAuth:
        secret: dashboard-auth-secret

# 대신 Gateway API로 라우팅합니다.
ingressClass:
  enabled: false

# Gateway API 프로바이더 활성화 및 KubernetesIngress 프로바이더 비활성화
# 프로바이더는 Traefik에 라우팅 설정을 찾을 위치를 알려줍니다.
providers:
  kubernetesIngress:
    enabled: false
  kubernetesGateway:
    enabled: true

## 게이트웨이 리스너
gateway:
  listeners:
    web: # 엔트리포인트 `web`과 일치하는 HTTP 리스너
      port: 80
      protocol: HTTP
      namespacePolicy:
        from: All
    websecure: # 엔트리포인트 `websecure`와 일치하는 HTTPS 리스너
      port: 443
      protocol: HTTPS # TLS는 Traefik 내부에서 종료됨
      namespacePolicy:
        from: All
      mode: Terminate
      certificateRefs:
        - kind: Secret
          name: local-selfsigned-tls # 설치 전 생성한 시크릿
          group: ""

# 관측성(Observability) 활성화
logs:
  general:
    level: INFO
  # 액세스 로그를 활성화하여 기본적으로 Traefik의 표준 출력으로 내보냅니다.
  access:
    enabled: true

# 메트릭을 위한 Prometheus 활성화
metrics:
  prometheus:
    enabled: true

---

Helm 설정을 사용한 Traefik 설치

이제 Helm 클라이언트를 사용하여 구성을 적용합니다.

# 'traefik' 네임스페이스에 차트 설치
helm install traefik traefik/traefik \
  --namespace traefik \
  --values values.yaml

 

명령어 설명:

• helm install traefik: traefik이라는 이름의 새 릴리스를 설치하도록 Helm에 지시합니다.
• 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 # Gateway API 프로바이더 활성화 시 Traefik이 생성하는 게이트웨이 이름
  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/

브라우저에서 https://whoami.docker.localhost로 접속하여 서비스의 JSON 덤프를 확인할 수도 있습니다.

---

기타 주요 구성 영역

위의 설정은 안전한 기반을 제공하지만, Traefik은 훨씬 더 많은 기능을 제공합니다. 다음은 Helm values.yaml 재정의를 사용한 몇 가지 필수 구성의 요약입니다.

 

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

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

values.yaml 추가 예시:

additionalArguments:
  - "--certificatesresolvers.le.acme.email=your-email@example.com"
  - "--certificatesresolvers.le.acme.storage=/data/acme.json"
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"

persistence:
  enabled: true
  name: data
  size: 1Gi
  storageClass: ""

 

운영 환경에서의 Let's Encrypt
Let's Encrypt는 80번 포트(HTTP-01) 또는 DNS 프로바이더의 API(DNS-01)를 통해 접근 가능한 공인 IP 주소를 가리키는 호스트 이름에 대해서만 인증서를 발급할 수 있습니다. *.docker.localhost 예시를 실제 소유한 도메인으로 바꾸고 DNS 레코드를 생성하세요.

 

Gateway API 및 ACME

Traefik의 내장 ACME 통합은 IngressRoute 및 Ingress 리소스에서 작동하지만, Gateway API 리스너에 대해서는 인증서를 발급하지 않습니다. Gateway API를 사용하는 경우 cert-manager를 설치하고 gateway.listeners.websecure.certificateRefs에서 생성된 시크릿을 참조하세요.

 

메트릭 (Prometheus)

Traefik은 성능 및 트래픽 모니터링에 필수적인 Prometheus 형식의 상세 메트릭을 노출할 수 있습니다.

values.yaml 추가 예시:

metrics:
  prometheus:
    entryPoint: metrics
    addRoutersLabels: true
    addServicesLabels: true

 

트레이싱 (OTel)

분산 트레이싱은 Traefik 자체를 포함하여 시스템을 통과하는 요청의 지연 시간과 흐름을 이해하는 데 도움이 됩니다.

values.yaml 추가 예시:

additionalArguments:
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector.observability:4317"

 

결론

이 구성을 통해 안전한 대시보드 액세스, HTTPS 리다이렉션, 그리고 관측성 및 TLS 활성화를 위한 기반이 갖추어진 Traefik이 설정되었습니다.