# longhorn 배포 가이드

## 개요

분산 블록 스토리지. **Rancher 패키징 차트**(업스트림 longhorn/longhorn 이 아님)로,
Rancher 2.14 계열과 짝을 이루는 109.x 라인을 쓴다. `longhorn-crd` 를 먼저 설치해야 한다
(`catalog.cattle.io/auto-install: longhorn-crd=match`).

## custom-values 로 오버라이드하는 항목

차트 기본값이 `resources: ~` 라 manager·CSI 컴포넌트가 BestEffort QoS 가 되는 문제를
실측 기반 request 로 보정한다. 상세 근거는 custom-values.yaml 주석 참고.

| 항목 | 요지 |
|---|---|
| `longhornManager.resources.requests` | request 만 부여. CPU limit 은 attach/detach throttling, 메모리 limit 은 OOM 루프(=모든 CR 쓰기 차단) 위험 |
| `defaultSettings.guaranteedInstanceManagerCPU` | 기본 12% → v1 만 5%. 32코어 노드에서 3840m 과다 예약(실측 ~100m) |
| `defaultSettings.systemManagedCSIComponentsResourceLimits` | CSI 사이드카 request/limit. **JSON 문자열 필수**(차트가 toJson 없이 quote 만 함) |

## 소비 측(dipup)에서 주입하는 항목

`persistence.defaultClassReplicaCount`·`csi.*ReplicaCount`·`longhornUI.replicas` 는
노드 수에 따라 [1,3] 으로 클램프하므로 소비 측에서 계산해 주입한다.
`defaultSettings.defaultDataPath` 도 환경 의존 값이다.

## ⚠️ 운영 주의

- **CSI 리소스 변경이 보류된 PV 삭제를 flush 한다.** `systemManagedCSIComponentsResourceLimits`
  를 바꾸면 csi-provisioner 가 재시작하고, 재시작 직후 resync 에서 reclaimPolicy=Delete 인
  Released PV 의 대기 중 DeleteVolume 이 실행된다(dev 실측: 재시작 4분 뒤 볼륨 12개 삭제).
  **prod 적용 전 Released/Failed PV 목록을 반드시 먼저 확인할 것.**
- **IM CPU 는 즉시 반영되지 않는다.** running engine instance 가 있으면 Longhorn 이
  `applied=false` 로 staged 하고("It will be eventually applied"), 해당 노드의 볼륨이
  전부 detach 될 때 실현된다.
- `guaranteedInstanceManagerCPU` 는 **비율**이라 저코어 노드에서 절대값이 작아진다
  (8코어 → 400m). 고객 클러스터 배포 시 코어 수를 확인할 것.