K3s配置Local Path Provisioner回收策略

发表于

在K3s集群中，Local Path Provisioner是默认的本地存储供应器，负责为Pod动态分配宿主机本地目录作为持久化存储，其核心配置之一便是存储回收策略（Reclaim Policy）。默认情况下，Local Path的回收策略为Delete，即删除PVC（PersistentVolumeClaim）时，对应的PV（PersistentVolume）及宿主机上的存储数据会被自动清理。但在生产环境中，为避免误删数据、便于数据恢复，通常需要将回收策略修改为Retain（保留），同时需确保修改后的配置不会被K3s升级覆盖，保障集群稳定性。本文将结合实践，详细讲解Local Path Provisioner回收策略的配置方法、升级兼容要点及常见问题解决方案。

一、核心前提：理解Local Path回收策略的作用与默认行为

Local Path Provisioner的回收策略由StorageClass资源定义，直接决定了PV在PVC被删除后的生命周期：

  • Delete（默认）：PVC删除后，PV自动被删除，同时宿主机上对应的存储目录（默认路径为/var/lib/rancher/k3s/storage）会被清理，数据彻底丢失，适用于测试环境或临时存储场景。

  • Retain（推荐生产环境）：PVC删除后，PV会变为Released状态，保留宿主机上的存储数据，需手动删除PV和对应目录才能释放资源，有效避免误删数据，便于故障排查和数据恢复。

  • Recycle（已废弃）：PVC删除后，PV会被清理并重新变为Available状态，可被新的PVC复用，但该策略已被Kubernetes废弃，不建议使用。

需要注意的是，K3s默认的Local Path相关资源（StorageClass、ConfigMap、Deployment）是通过静态清单（/var/lib/rancher/k3s/server/manifests/local-path-provisioner.yaml）创建的，直接修改该清单会在K3s升级时被官方镜像覆盖，导致配置丢失。因此，持久化修改回收策略的核心原则是：不修改原生静态清单，通过自定义资源覆盖实现配置生效。

二、正确配置：Local Path回收策略的持久化实现方案

要实现回收策略的持久化修改（不被K3s升级覆盖），核心方案是「删除原生StorageClass + 创建自定义同名StorageClass」，同时保证与原有Local Path Provisioner的兼容性，具体步骤如下。

2.1 前提准备：确认集群环境与核心资源

首先执行以下命令，确认Local Path Provisioner的运行状态及默认StorageClass配置：

1
2
3
4
5
6
7
8
# 查看Local Path Provisioner部署状态
kubectl get deployment local-path-provisioner -n kube-system

# 查看默认StorageClass（默认名称为local-path）
kubectl get sc local-path -o yaml

# 查看默认存储路径（确认宿主机目录）
kubectl get cm local-path-config -n kube-system -o jsonpath='{.data.config\.json}' | jq .

确认资源正常运行后，即可开始配置修改。

2.2 步骤1：删除原生StorageClass，避免冲突

K3s原生的local-path StorageClass是集群级资源，直接删除后，后续创建的自定义同名StorageClass会自动成为默认存储类，且K3s升级时不会重建已手动删除的StorageClass（仅重建静态清单中的Deployment和ConfigMap）。执行删除命令：

1
kubectl delete storageclass local-path

2.3 步骤2：创建自定义StorageClass，修改回收策略

创建自定义StorageClass配置文件（命名为custom-local-path-sc.yaml），核心是将reclaimPolicy设为Retain，同时保留与原生配置一致的关键参数（确保兼容性）：

1
2
3
4
5
6
7
8
9
10
11
12
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-path  # 与原生名称一致，兼容原有PVC/PV
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"  # 保持为默认存储类
provisioner: rancher.io/local-path  # 必须与Provisioner名称一致，否则无法绑定PV
parameters:
  pathPattern: "${DEFAULT_STORAGE_PATH}/${namespace}/${pvc}"  # 复用原生路径规则，确保数据存储位置不变
reclaimPolicy: Retain  # 核心修改：将回收策略改为保留
volumeBindingMode: WaitForFirstConsumer  # 延迟绑定，避免节点调度冲突（与原生配置一致）
allowVolumeExpansion: false  # Local Path不支持扩容，保持默认配置

应用配置文件，创建自定义StorageClass：

1
kubectl apply -f custom-local-path-sc.yaml

2.4 步骤3：验证配置生效

配置完成后，通过以下命令验证回收策略是否生效，确保与预期一致：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 查看自定义StorageClass的配置，确认reclaimPolicy为Retain
kubectl get sc local-path -o yaml | grep reclaimPolicy

# 测试PVC创建，验证PV继承回收策略
# 1. 创建测试PVC
cat > test-pvc.yaml << EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-local-path-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
EOF

# 2. 应用PVC并创建测试Pod（触发PV创建）
kubectl apply -f test-pvc.yaml
kubectl run test-pod --image=nginx -v test-local-path-pvc:/data

# 3. 查看PV的回收策略，确认为Retain
kubectl get pv -o jsonpath='{.items[?(@.spec.claimRef.name=="test-local-path-pvc")].spec.persistentVolumeReclaimPolicy}'

若输出结果为Retain，说明配置生效，PV已成功继承自定义StorageClass的回收策略。

2.5 步骤4：清理测试资源（可选）

测试完成后，清理测试资源，注意回收策略为Retain时，删除PVC后PV不会自动删除，需手动清理：

1
2
3
4
5
6
7
8
9
10
# 删除测试Pod和PVC
kubectl delete pod test-pod
kubectl delete pvc test-local-path-pvc

# 查看Released状态的PV，手动删除
kubectl get pv
kubectl delete pv <对应的PV名称>

# 手动删除宿主机上的存储目录（避免占用空间）
rm -rf /var/lib/rancher/k3s/storage/default/test-local-path-pvc/

三、关键要点：确保配置不被K3s升级覆盖

很多用户在修改回收策略后，会遇到K3s升级后配置丢失的问题，核心原因是修改了原生静态清单。要避免该问题，需牢记以下4个核心要点：

3.1 不修改K3s原生静态清单

/var/lib/rancher/k3s/server/manifests/local-path-provisioner.yaml是K3s的核心静态清单，升级时会被官方镜像覆盖，任何直接修改（如修改清单中的StorageClass回收策略）都会在升级后丢失，这是最常见的踩坑点。

3.2 保留自定义资源的同名特性

自定义的StorageClass名称必须与原生一致（均为local-path），一方面可以保证原有使用默认存储类的PVC/PV无需修改配置，完全兼容；另一方面，K3s升级时不会重建已删除的StorageClass，自定义资源会被保留。

3.3 核心参数与原生配置保持一致

自定义StorageClass的provisioner字段必须为rancher.io/local-path，与Local Path Provisioner的名称一致，否则无法正常创建PV；volumeBindingMode、parameters等参数建议与原生配置保持一致，避免出现调度或路径匹配问题。

3.4 升级后验证配置

K3s升级完成后，建议执行以下命令验证回收策略是否保留：

1
2
3
4
5
# 查看StorageClass的回收策略
kubectl get sc local-path -o yaml | grep reclaimPolicy

# 查看Local Path Provisioner运行状态
kubectl get deployment local-path-provisioner -n kube-system

若回收策略仍为Retain，且Provisioner正常运行，说明配置未被覆盖。

四、扩展：同步修改存储路径（可选，同样持久化）

很多场景下，用户除了修改回收策略，还需要调整Local Path的默认存储路径（原生路径为/var/lib/rancher/k3s/storage）。同样，不建议直接修改原生ConfigMap，推荐通过K3s全局配置文件实现持久化修改：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 创建/编辑K3s全局配置文件（若不存在）
mkdir -p /etc/rancher/k3s/
vi /etc/rancher/k3s/config.yaml

# 2. 添加自定义存储路径参数（优先级高于ConfigMap）
local-storage-path: /data/k3s/storage  # 替换为自定义路径

# 3. 重启K3s生效
systemctl restart k3s

# 4. 验证路径修改生效
kubectl get cm local-path-config -n kube-system -o jsonpath='{.data.config\.json}' | jq .

该方式修改的存储路径，会被Local Path Provisioner自动读取，且K3s升级时不会覆盖/etc/rancher/k3s/config.yaml，实现存储路径与回收策略的双重持久化。

五、常见问题与解决方案

问题1：修改回收策略后，PV创建失败

原因：自定义StorageClass的provisioner字段与Provisioner名称不匹配，或路径模板错误。

解决方案：确认provisioner: rancher.io/local-path，检查pathPattern参数与原生配置一致，重启Local Path Provisioner：

1
kubectl rollout restart deployment local-path-provisioner -n kube-system

问题2：K3s升级后，回收策略恢复为默认Delete

原因：直接修改了原生静态清单，升级时被覆盖；或删除原生StorageClass后，未创建自定义StorageClass，K3s升级时重建了原生StorageClass。

解决方案：按本文2.2-2.3步骤，重新删除原生StorageClass，创建自定义StorageClass，确保不修改原生静态清单。

问题3：删除PVC后，宿主机数据未清理（Retain策略）

原因：Retain策略的设计就是保留数据，需手动清理PV和宿主机目录。

解决方案：按2.5步骤，手动删除Released状态的PV，再删除宿主机上对应的存储目录，避免占用空间。

六、总结

K3s中Local Path Provisioner回收策略的持久化配置，核心是「不修改原生静态清单，通过自定义同名StorageClass覆盖配置」，既实现了回收策略的修改（推荐改为Retain），又保证了K3s升级时配置不丢失。关键在于把握3个核心：一是删除原生StorageClass避免冲突，二是自定义StorageClass保持与原生参数的兼容性，三是通过K3s全局配置文件实现存储路径等参数的持久化。

该方案适用于生产环境，既能避免误删数据，又能保障集群升级后的稳定性，同时兼容原有PVC/PV资源，无需大规模修改现有配置。在实际部署中，建议结合自身业务场景，同步配置存储路径、权限等参数，进一步优化Local Path Provisioner的使用体验。

（注：文档部分内容可能由 AI 生成）