본문으로 건너뛰기

Headlamp

Headlamp는 Lumie k3s 클러스터를 위한 경량 Kubernetes 웹 대시보드입니다. 네임스페이스, 파드, 디플로이먼트, 서비스 등 클러스터 리소스를 시각적으로 탐색하고 관리할 수 있습니다.

배포 구성​

  • 네임스페이스: headlamp
  • 차트: headlamp v0.39.0 (https://kubernetes-sigs.github.io/headlamp)
  • 이미지: zot.lumie-infra.com/headlamp-k8s/headlamp:v0.40.1
  • 복제본: 1개
  • 접근: Teleport 앱 프록시 경유 (직접 Ingress 없음)

ArgoCD Multi-Source 배포​

Headlamp는 ArgoCD의 Multi-Source 기능을 활용합니다. Helm 차트와 공통 values 파일을 서로 다른 소스에서 가져옵니다:

spec:
  sources:
  # 소스 1: 공식 Headlamp Helm 차트
  - repoURL: https://kubernetes-sigs.github.io/headlamp
    chart: headlamp
    targetRevision: 0.39.0
    helm:
      valueFiles:
      - $values/applications/headlamp/helm-values.yaml

  # 소스 2: lumie-infra 저장소 (values 파일 참조용)
  - repoURL: https://github.com/Lumie-Edu/lumie-infra.git
    targetRevision: main
    ref: values
    path: charts/common
    helm:
      valueFiles:
      - $values/applications/headlamp/common-values.yaml

$values는 두 번째 소스(ref: values)를 참조하는 ArgoCD Multi-Source 변수입니다.

Helm 설정​

helm-values.yaml​

replicaCount: 1

image:
  registry: zot.lumie-infra.com
  repository: headlamp-k8s/headlamp
  tag: v0.40.1
  pullPolicy: IfNotPresent

serviceAccount:
  create: true
  name: headlamp

# 클러스터 전체 읽기 권한 바인딩 생성
clusterRoleBinding:
  create: true

service:
  type: ClusterIP
  port: 80

# Ingress 비활성화 — Teleport를 통해서만 접근
ingress:
  enabled: false

config:
  baseURL: ""

리소스 설정​

resources:
  requests:
    cpu: 15m
    memory: 100Mi
  limits:
    memory: 100Mi  # CPU 제한 없음

파드 분산 배치 (Soft Anti-Affinity)​

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: headlamp
          topologyKey: kubernetes.io/hostname

Common 차트 설정​

공통 차트(common-values.yaml)에서는 Headlamp Helm 차트가 이미 생성하는 리소스와 중복되지 않도록 배포, 서비스, Ingress를 모두 비활성화합니다:

common:
  name: headlamp

  deployment:
    enabled: false  # 외부 차트가 생성

  service:
    enabled: false  # 외부 차트가 생성

  ingress:
    enabled: false

접근 방법​

Teleport를 통한 접근​

# Teleport CLI로 앱 로그인
tsh app login headlamp

# 앱 URI 확인
tsh app config headlamp --format=uri

포트 포워딩 (개발/디버깅용)​

kubectl port-forward -n headlamp svc/headlamp 8080:80
# http://localhost:8080 에서 접근

운영 확인​

파드 상태 확인​

kubectl get pods -n headlamp
kubectl describe pod -n headlamp -l app.kubernetes.io/name=headlamp

로그 확인​

kubectl logs -n headlamp -l app.kubernetes.io/name=headlamp

ServiceAccount 및 RBAC 확인​

# ClusterRoleBinding 확인
kubectl get clusterrolebinding | grep headlamp

# ServiceAccount 확인
kubectl get serviceaccount -n headlamp headlamp

문제 해결​

대시보드에서 리소스가 보이지 않는 경우​

Headlamp는 clusterRoleBinding.create: true로 설정 시 기본 ClusterRole(cluster-admin 또는 view)을 바인딩합니다. RBAC 문제라면 다음을 확인합니다:

# ClusterRoleBinding 상세 확인
kubectl describe clusterrolebinding headlamp

# 권한 테스트
kubectl auth can-i list pods --all-namespaces \
  --as=system:serviceaccount:headlamp:headlamp

이미지 풀 실패​

# Zot 레지스트리 미러 상태 확인
kubectl get pods -n zot
kubectl describe pod -n headlamp <pod-name> | grep -A5 Events

ArgoCD 동기화 오류​

Multi-Source App에서 $values 참조 오류가 발생하면:

# ArgoCD App 상태 확인
kubectl get application -n argocd headlamp -o yaml | grep -A20 status

# 소스 별 동기화 상태
argocd app get headlamp

관련 문서​