26Z03c

Kubernetes 클러스터(RHEL 10, Vanilla K8s 등)에서 각 노드의 로컬 디스크/디렉토리를 영구 스토리지(Persistent Storage)로 사용할 수 있게 해주는 Rancher Local Path Provisioner 설치 및 설정 방법입니다.

설치가 매우 간단하고 오버헤드가 적어, 단일 노드 스토리지나 로컬 SSD/NVMe를 활용해야 하는 워크로드(예: Kafka, StarRocks BE, MinIO 등)에 널리 사용됩니다.

---

1. Quick Start (공식 배포 매니페스트 적용)

kubectl 명령어로 공식 저장소의 배포 매니페스트를 적용하는 것만으로 즉시 설치가 완료됩니다.

# 최신 안정 버전 적용 (v0.0.31 기준)
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.31/deploy/local-path-storage.yaml

설치 상태 확인

kubectl get pods -n local-path-storage

local-path-provisioner-xxxx 파드가 Running 상태이면 정상 동작 중입니다.

---

2. StorageClass 확인 및 기본(Default) 설정

설치가 완료되면 local-path라는 이름의 StorageClass가 자동으로 생성됩니다.

kubectl get storageclass

local-path를 기본 StorageClass로 지정하고 싶은 경우

PersistentVolumeClaim(PVC) 생성 시 storageClassName을 지정하지 않아도 자동으로 local-path를 사용하게 하려면 아래 명령어로 annotaiton을 설정합니다.

kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

---

3. 데이터 저장 경로(Path) 변경 방법

기본 설정으로 생성되는 PV 볼륨 데이터는 각 노드의 /opt/local-path-provisioner 경로에 저장됩니다.

만약 디스크 용량이 큰 별도 마운트 포인트(예: /data, /mnt/nvme 등)로 저장 경로를 변경하려면 ConfigMap을 수정해야 합니다.

ConfigMap 수정

kubectl edit configmap local-path-config -n local-path-storage

config.json 부분을 찾아 paths 배열 경로를 원하는 마운트 경로로 변경합니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: local-path-config
  namespace: local-path-storage
data:
  config.json: |-
    {
            "nodePathMap":[
            {
                    "node":"DEFAULT_PATH_FOR_NON_LISTED_NODES",
                    "paths":["/data/local-path-provisioner"]  # <--- 원하는 경로로 변경 (예: /data/...)
            }
            ]
    }

팁: ConfigMap을 수정하면 Provisioner 파드가 설정 변경을 자동으로 감지하므로 파드를 재시작할 필요가 없습니다.

---

4. 동작 테스트 (PVC & Pod 생성)

정상적으로 PVC가 생성되고 노드 로컬 디렉토리에 마운트되는지 검증합니다.

① 테스트용 PVC 및 Pod 생성 (test-local-path.yaml)

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: local-path-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 2Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: volume-test-pod
spec:
  containers:
  - name: test-container
    image: nginx:alpine
    volumeMounts:
    - name: my-vol
      mountPath: /usr/share/nginx/html
  volumes:
  - name: my-vol
    persistentVolumeClaim:
      claimName: local-path-pvc

kubectl apply -f test-local-path.yaml

② PVC 및 PV 상태 확인

kubectl get pvc,pv

Status가 Bound 상태가 되었는지 확인합니다.

③ 실제 노드의 로컬 디렉토리 데이터 확인

Pod가 배포된 해당 노드로 접속하여 저장 경로(예: /opt/local-path-provisioner/pvc-xxxx...)로 이동하면 PV 디렉토리가 생성되어 있는 것을 확인할 수 있습니다.

---

5. RHEL 10 / SELinux 환경 주의사항

RHEL 10 환경에서 SELinux가 Enforcing 모드인 경우, 호스트 디렉토리를 Pod에 마운트할 때 권한 문제가 발생할 수 있습니다.

1. SELinux 볼륨 플래그 고려:
   Pod 매니페스트에서 호스트 경로 마운트 시 권한 이슈가 생기면 해당 노드의 볼륨 저장 경로 디렉토리에 SELinux 컨텍스트를 부여합니다.

# 저장 경로에 container_file_t 컨텍스트 부여
chcon -Rt container_file_t /opt/local-path-provisioner

2. Node Affinity (노드 고정):
   Local Path Provisioner로 만들어진 PV는 특정 노드의 로컬 디스크에 바인딩됩니다. 따라서 해당 PVC를 사용하는 Pod가 재시작되면 K8s 스케줄러가 자동으로 데이터가 위치한 동일한 노드로 Pod를 스케줄링합니다 (nodeAffinity 자동 추가됨).