企业官网建设流程全解析

• 云原生
• 容器编排
• CLI
• 开发工具

本教程基于 minikube 官方文档 local_path_provisioner.md，完整讲解如何在多节点 minikube 集群中启用storage-provisioner-rancheraddon，借助 Rancher 的 Local Path Provisioner 将每个节点的本地磁盘空间动态供应为 Kubernetes 持久化存储。读完本文，你将掌握从创建双节点集群、启用 addon、验证默认 StorageClass，到通过 PVC 与 Pod 实际写入并核验节点本地文件的全过程，并理解 addon 底层清单与默认 StorageClass 的源码级实现原理。

Local Path Provisioner 是什么

Local Path Provisioner 是一个 Kubernetes 动态存储供应器（dynamic volume provisioner），它允许集群用户直接利用每个节点上的本地存储路径。与传统依赖网络存储（如 NFS、云盘）的方案不同，它通过在节点本地目录上创建子目录来为 PersistentVolumeClaim（PVC）动态生成 PersistentVolume（PV），具有以下特点：

• 按节点本地供应：数据落盘在调度 Pod 所在节点的本地文件系统上，读写延迟低；
• 支持多节点：可以在多节点集群中为不同节点上的工作负载分别供应本地存储，教程正是基于两节点集群演示；
• 零额外存储依赖：不需要额外的网络存储设备，适合开发、测试及对数据持久性要求不高的场景。

在 minikube 中，该能力以storage-provisioner-rancheraddon 的形式提供，其维护方标注为 "3rd party (Rancher)"（见 pkg/minikube/assets/addons.go）。

前置条件

• minikube 版本高于v1.27.0（该版本起才内置storage-provisioner-rancheraddon）；
• 已安装kubectl命令行工具；
• 本机拥有可用的容器运行时或虚拟化驱动，能够启动多节点集群。

实战：在两节点集群上使用 Local Path Provisioner

第一步：创建双节点集群

使用-n参数指定节点数量，创建一个包含 1 个控制平面节点（minikube）与 1 个工作节点（minikube-m02）的两节点集群：

$ minikube start -n 2

第二步：启用 storage-provisioner-rancher addon

$ minikube addons enable storage-provisioner-rancher

启用成功后，addon 会在local-path-storage命名空间中创建一个名为local-path-provisioner的 Deployment。可通过以下命令确认 Pod 已就绪：

$ kubectl get pods -n local-path-storage NAME READY STATUS RESTARTS AGE local-path-provisioner-7f58b4649-hcbk9 1/1 Running 0 38s

第三步：确认 local-path 成为默认 StorageClass

storage-provisioner-rancheraddon 启用的同时会把名为local-path的 StorageClass 标记为集群默认存储类。查看集群中的 StorageClass 列表：

$ kubectl get sc NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE local-path (default) rancher.io/local-path Delete WaitForFirstConsumer false 107s standard k8s.io/minikube-hostpath Delete Immediate false 4m27s

注意两个关键差异：

第四步：创建 PVC 与 Pod 写入文件

下面的 YAML 同时声明了一个 64Mi 的 PVC，以及一个通过nodeSelector被调度到第二个节点minikube-m02上的 Pod。Pod 内的 busybox 容器会把内容写入挂载到/test目录的 PVC 卷中：

--- apiVersion: v1 kind: PersistentVolumeClaim metadata: name: test-pvc spec: accessModes: - ReadWriteOnce resources: requests: storage: 64Mi --- apiVersion: v1 kind: Pod metadata: name: test-local-path spec: restartPolicy: OnFailure nodeSelector: "kubernetes.io/hostname": "minikube-m02" containers: - name: busybox image: busybox:stable command: ["sh", "-c", "echo 'local-path-provisioner' > /test/file1"] volumeMounts: - name: data mountPath: /test volumes: - name: data persistentVolumeClaim: claimName: test-pvc

将其保存为local-path-test.yaml后执行：

$ kubectl apply -f local-path-test.yaml

第五步：验证 PVC 绑定与 Pod 运行状态

PVC 应很快进入Bound状态，卷名由 local-path-provisioner 自动生成：

$ kubectl get pvc NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE test-pvc Bound pvc-f07e253b-fea7-433a-b0ac-1bcea3f77076 64Mi RWO local-path 5m19s

由于 Pod 设置了restartPolicy: OnFailure且命令执行完成后即退出，Pod 会显示为Completed，并通过-o wide可以看到它被调度到了minikube-m02节点：

$ kubectl get pods -o wide NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES test-local-path 0/1 Completed 0 5m19s 10.244.1.5 minikube-m02 <none> <none>

第六步：在节点本地验证文件落盘

Local Path Provisioner 默认把卷数据存放在节点的/opt/local-path-provisioner目录下。通过minikube ssh登录第二个节点，直接读取写入的文件内容：

$ minikube ssh -n minikube-m02 "cat /opt/local-path-provisioner/pvc-f07e253b-fea7-433a-b0ac-1bcea3f77076_default_test-pvc/file1" local-path-provisioner

输出即 Pod 写入的内容，证明本地路径存储链路（PVC → PV → 节点目录）已完整打通。

源码视角：addon 到底部署了什么

启用 addon 的本质是把模板清单 storage-provisioner-rancher.yaml.tmpl 渲染后应用到集群。该清单由六部分组成：

1. Namespacelocal-path-storage：承载 provisioner 相关资源；
2. ServiceAccountlocal-path-provisioner-service-account：运行 provisioner 的账号；
3. ClusterRole / ClusterRoleBindinglocal-path-provisioner-role：授予对nodes、persistentvolumeclaims、configmaps的只读权限，对endpoints、persistentvolumes、pods的全部权限，以及对events的创建/打补丁权限；
4. Deploymentlocal-path-provisioner：以--debug start --config /etc/config/config.json参数启动控制器，并挂载配置 ConfigMap；
5. StorageClasslocal-path：provisioner: rancher.io/local-path，volumeBindingMode: WaitForFirstConsumer，reclaimPolicy: Delete；
6. ConfigMaplocal-path-config：包含 provisioner 的运行时配置。

ConfigMap 中的核心配置解读

ConfigMap 中config.json的nodePathMap定义了路径映射规则：

{ "nodePathMap":[ { "node":"DEFAULT_PATH_FOR_NON_LISTED_NODES", "paths":["/opt/local-path-provisioner"] } ] }

• DEFAULT_PATH_FOR_NON_LISTED_NODES表示该规则适用于所有未在映射中单独列出的节点，即所有节点都使用/opt/local-path-provisioner作为卷的根目录；
• 你也可以按节点名（如minikube-m02）单独指定不同的本地路径。

此外还定义了三个生命周期脚本：

• setup：创建卷目录（mkdir -m 0777 -p "$VOL_DIR"），默认权限 0777；
• teardown：删除卷目录（rm -rf "$VOL_DIR"），对应 StorageClass 的reclaimPolicy: Delete；
• helperPod.yaml：provisioner 执行 setup/teardown 时启动的辅助 Pod 模板。

为什么 local-path 会自动成为默认 StorageClass

这与 minikube 源码中的 addon 回调机制有关。在 pkg/addons/config.go 中，storage-provisioner-rancher注册了专门的回调函数enableOrDisableStorageClasses，而非普通的EnableOrDisableAddon。该回调实现在 pkg/addons/addons_storage_classes.go：

• 启用 addon 时，先应用清单，再调用storageclass.SetDefaultStorageClass把local-path标记为默认类；
• 禁用 addon 时，先通过DisableDefaultStorageClass取消默认标记，再卸载清单。

底层实现见 pkg/minikube/storageclass/storageclass.go：SetDefaultStorageClass会遍历集群中所有 StorageClass，只给指定名称的类设置storageclass.kubernetes.io/is-default-class: "true"注解，其余类统一标记为"false"，从而保证同一时刻只有一个默认 StorageClass。这就是kubectl get sc中local-path (default)的来源。

addon 的默认状态与镜像

从 pkg/minikube/assets/addons.go 可以看到该 addon 的定义：

• 默认关闭（NewAddon的布尔参数为false），需要用户显式minikube addons enable；
• provisioner 镜像固定为rancher/local-path-provisioner:v0.0.22（带 sha256 摘要校验），helper Pod 使用busybox:stable，默认从docker.io拉取；
• 支持通过--image-repository等参数覆盖镜像仓库与镜像地址（模板中使用{{.CustomRegistries.LocalPathProvisioner | default ...}}语法解析）。

集成测试如何验证该功能

仓库的集成测试 test/integration/addons_test.go 中的validateLocalPathAddon完整复刻了本教程的验证链路：启用 addon 后，应用测试清单 pvc.yaml 与 pod.yaml（Pod 通过 labelrun: test-local-path标识，无需 nodeSelector，由调度器自行选择节点），等待 Pod 运行完成后通过minikube ssh读取/opt/local-path-provisioner/<volume>_default_test-pvc/file1，断言内容为local-path-provisioner。测试同时排除了none驱动（见 tests.en.md 对validateLocalPathAddon的说明）。

清理与注意事项

• 禁用 addon：执行minikube addons disable storage-provisioner-rancher，local-path将失去默认标记并被卸载；
• 数据回收：local-pathStorageClass 的reclaimPolicy为Delete，删除 PVC 时其对应的节点本地目录会被teardown脚本清理；
• 数据位置：卷数据位于节点的/opt/local-path-provisioner目录，删除 minikube 集群前请确认是否有需要保留的数据；
• 适用场景：本地路径存储的数据与节点强绑定，Pod 重建后若被调度到其他节点，PVC 可能无法绑定到原卷，因此该方案更适合开发测试或单节点有状态服务，生产环境请结合业务对数据分布的要求评估。

相关文件速查

• 官方教程：site/content/en/docs/tutorials/local_path_provisioner.md
• addon 清单模板：deploy/addons/storage-provisioner-rancher/storage-provisioner-rancher.yaml.tmpl
• addon 注册与镜像配置：pkg/minikube/assets/addons.go
• 默认 StorageClass 回调：pkg/addons/addons_storage_classes.go
• StorageClass 注解实现：pkg/minikube/storageclass/storageclass.go
• 集成测试：test/integration/addons_test.go 与 testdata 清单

• 云原生
• 容器编排
• CLI
• 开发工具