26Z21f

package.json과 main.js를 넣었는데도 incomplete plugins disabled 경고가 계속 뜬다면, Headlamp가 플러그인을 검증하는 세부 규칙 3가지 중 하나에 걸린 것입니다.

Headlamp의 플러그인 로더는 다음 조건을 엄격하게 체크합니다:

1. package.json 안에 headlamp: { ... } 메타데이터 블록이 없으면 유효한 플러그인으로 인식하지 않습니다.
2. 개별 파일 subPath 마운트 시 리눅스 파일 시스템에서 디렉터리 inode가 꼬여 로더가 폴더 스캔을 건너뛰는 현상이 발생합니다.
3. UI 우측 상단 Settings -> Plugins에서 플러그인이 Disabled(비활성화) 상태로 잠겨 있는 경우가 있습니다.

가장 깔끔하고 확실하게 해결하는 방법입니다.

---

1. package.json에 Headlamp 필수 메타데이터 추가

Headlamp 플러그인은 package.json에 아래와 같이 headlamp 전용 섹션이 명시되어 있어야 합니다.

kubectl create configmap headlamp-lakehouse-plugin \
  --from-file=main.js=./dist/main.js \
  --from-literal=package.json='{
    "name": "lakehouse-monitor",
    "version": "0.1.0",
    "main": "main.js",
    "description": "Lakehouse Monitoring Plugin",
    "headlamp": {
      "name": "lakehouse-monitor",
      "version": "0.1.0",
      "description": "Lakehouse Monitoring Plugin"
    }
  }' \
  -n headlamp \
  --dry-run=client -o yaml | kubectl apply -f -

---

2. subPath 대신 디렉터리 전체 마운트 방식으로 변경

파일 2개를 각각 subPath로 쪼개서 마운트하면 Headlamp 백엔드(Node.js fs.readdir)가 해당 디렉터리를 스캔할 때 파일 메타데이터를 불완전하게 읽는 버그가 있습니다.

ConfigMap 전체를 디렉터리로 한 번에 마운트합니다.

kubectl patch deployment headlamp -n headlamp --type='strategic' -p '{
  "spec": {
    "template": {
      "spec": {
        "containers": [
          {
            "name": "headlamp",
            "volumeMounts": [
              {
                "name": "lakehouse-plugin-vol",
                "mountPath": "/headlamp/plugins/lakehouse-monitor"
              }
            ]
          }
        ],
        "volumes": [
          {
            "name": "lakehouse-plugin-vol",
            "configMap": {
              "name": "headlamp-lakehouse-plugin"
            }
          }
        ]
      }
    }
  }
}'

---

3. Pod 재기동 및 내부 검증

1. Pod 롤아웃 대기:

kubectl rollout status deployment/headlamp -n headlamp

2. Pod 내부 파일 구조 및 권한 확인:

POD_NAME=$(kubectl get pod -n headlamp -l app.kubernetes.io/name=headlamp -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD_NAME -n headlamp -- ls -la /headlamp/plugins/lakehouse-monitor/

• 아래와 같이 main.js와 package.json이 링크 형태로 깔끔하게 조회되어야 합니다.

lrwxrwxrwx 1 root root ... main.js -> ..data/main.js
lrwxrwxrwx 1 root root ... package.json -> ..data/package.json

3. Headlamp Pod 로그 확인:

kubectl logs -n headlamp $POD_NAME | grep -i plugin

• Loaded plugin: lakehouse-monitor 메시지가 찍히는지 확인합니다.

---

4. UI 설정에서 플러그인 활성화 토글 확인

서버에서 로드가 정상이어도 브라우저 LocalStorage에 비활성화 플래그가 남아있을 수 있습니다.

1. Headlamp 웹 화면 우측 상단 설정 아이콘(톱니바퀴 / Settings) 클릭
2. Plugins 탭으로 이동
3. 목록에 lakehouse-monitor가 보인다면 오른쪽 스위치를 ON(Enabled)으로 켜고 페이지 새로고침(Ctrl + F5)