26Z21c

이 에러(failed to create: Request entity too large: limit is 3145728)는 쿠버네티스 etcd의 단일 리소스 크기 제한(약 1MB~3MB) 및 Helm 릴리즈 시크릿(Secret) 크기 제한(약 3MB)을 초과해서 발생하는 문제입니다.

Webpack 등으로 번들링된 main.js 파일 크기가 수 MB 이상으로 커진 상태에서, 이를 Helm values.yaml에 인라인 텍스트로 직접 집어넣거나 Helm이 릴리즈 매니페스트로 통째로 관리하려 할 때 발생합니다.

---

해결 방법: Helm values에 JS를 넣지 말고 분리하기

플러그인 파일(main.js)을 Helm 템플릿/values에 포함하지 않고, 독립 리소스(ConfigMap)로 먼저 클러스터에 배포한 뒤 Helm에서는 볼륨 이름(existingConfigMap)만 참조하도록 변경해야 합니다.

---

1단계: 플러그인을 독립 ConfigMap으로 직접 생성

Helm을 거치지 않고 kubectl로 직접 ConfigMap을 생성합니다.

# dist/main.js 파일로부터 ConfigMap 직접 생성
kubectl create configmap headlamp-lakehouse-plugin \
  --from-file=main.js=./dist/main.js \
  -n headlamp \
  --dry-run=client -o yaml | kubectl apply -f -

만약 main.js 파일 자체가 1MB를 초과하여 위 명령에서도 Request entity too large가 발생하는 경우:
아래 3번 항목(Init Container 이미지 방식)을 사용해야 합니다.

---

2단계: Helm values.yaml 수정 및 배포

Helm values.yaml에는 JS 내용을 넣지 말고, 생성해 둔 ConfigMap의 이름만 마운트하도록 지정합니다.

# values.yaml
config:
  pluginsDir: /headlamp/plugins

extraVolumes:
  - name: lakehouse-plugin-vol
    configMap:
      name: headlamp-lakehouse-plugin

extraVolumeMounts:
  - name: lakehouse-plugin-vol
    mountPath: /headlamp/plugins/lakehouse-monitor/main.js
    subPath: main.js

# Helm 업그레이드 실행
helm upgrade headlamp headlamp/headlamp \
  --namespace headlamp \
  -f values.yaml

---

3단계: 플러그인 번들 용량이 너무 클 때의 근본 해결책 (Init Container 방식)

React 및 의존성 라이브러리가 포함되어 main.js 파일 자체가 1.5MB 이상으로 비대해진 경우 K8s ConfigMap 자체에 담기지 않습니다. 이 때는 플러그인을 담은 경량 도커 이미지를 사내 레지스트리에 푸시하고 Init Container로 주입하는 방식을 사용합니다.

1. 플러그인 배포용 Dockerfile 생성 및 빌드:

FROM busybox
COPY dist/main.js /plugins/lakehouse-monitor/main.js
CMD ["sh", "-c", "cp -r /plugins/* /target/"]

docker build -t registry.internal.example.com/headlamp-lakehouse-plugin:v1 .
docker push registry.internal.example.com/headlamp-lakehouse-plugin:v1

2. Helm values.yaml에 Init Container 설정:

initContainers:
  - name: install-lakehouse-plugin
    image: registry.internal.example.com/headlamp-lakehouse-plugin:v1
    command: ["sh", "-c", "mkdir -p /target/lakehouse-monitor && cp /plugins/lakehouse-monitor/main.js /target/lakehouse-monitor/main.js"]
    volumeMounts:
      - name: plugin-storage
        mountPath: /target

extraVolumes:
  - name: plugin-storage
    emptyDir: {}

extraVolumeMounts:
  - name: plugin-storage
    mountPath: /headlamp/plugins

용량이 1MB 미만이라면 1단계(수동 ConfigMap 생성 + Helm에서는 이름만 참조)로 즉시 해결되며, 1MB를 넘는 대형 플러그인이라면 3단계(Init Container 방식)가 가장 표준적인 해결책입니다.