portainer

starlightBlog.tags.count

彻底清理并重新部署 Portainer：解决存储与权限冲突

starlightBlog.post.date

在通过 Helm 将 Portainer 的底层存储从 local-path 更改为 longhorn 时，直接执行 helm upgrade 通常会导致升级失败。这主要由以下三个原因造成：

1. PVC Immutable 报错：Kubernetes 规范限制了已绑定 PVC 的 storageClassName 是不可变的，不能直接修改覆盖。
2. 全局权限冲突：Helm 尝试创建全局的 ClusterRoleBinding 时，会因为系统中存在历史安装遗留的同名资源而报错。
3. 手动资源残留：通过 kubectl apply 手动创建的 Service（例如手动配置的 LoadBalancer）不在 Helm 的管理范围内，helm uninstall 不会自动将其回收。

为了保证新配置能够顺利应用，必须先彻底清理命名空间下的所有关联资源，然后执行干净的重装。以下是完整的操作步骤。

---

第一阶段：彻底清理残留资源

注意： 执行以下清理命令将删除该节点上 Portainer 的所有历史数据。请在操作前确认数据已备份或不再需要。

1. 卸载 Helm 发布版本

首先，通过 Helm 卸载现有的 Portainer 实例：

helm uninstall portainer -n portainer

2. 删除命名空间下的所有资源及 PVC

由于 Helm 卸载操作会保留 PVC 以及未被其管理的手动资源，需要使用以下命令强制清空 portainer 命名空间：

kubectl delete all --all -n portainer
kubectl delete pvc --all -n portainer

3. 清理全局权限绑定

ClusterRole 和 ClusterRoleBinding 是集群级别的资源，不包含在特定命名空间内。需要手动删除它们以解决后续的权限冲突报错：

kubectl delete clusterrolebinding portainer
kubectl delete clusterrole portainer

4. 验证清理结果

执行以下命令检查命名空间，确认环境已完全清空：

kubectl get all,pvc -n portainer

正常情况下，终端应返回：No resources found in portainer namespace.

---

第二阶段：执行全新安装

环境清理完毕后，使用配置好 Longhorn 存储的 portainer-values.yaml 文件重新执行 Helm 安装命令：

helm install portainer portainer/portainer \
  -n portainer \
  --create-namespace \
  --set persistence.storageClass=longhorn \
  --set nodeSelector=null \
  -f portainer-values.yaml

---

第三阶段：验证部署与恢复服务

1. 检查集群资源状态

安装完成后，检查 Pod 和 PVC 的状态。确认 PVC 已经绑定到 longhorn，并且 Pod 处于 Running 状态：

kubectl get pods,pvc,svc -n portainer -o wide

2. 恢复手动创建的 Service (视情况执行)

如果你之前的外网访问依赖于手动创建的 Service（例如名为 portainer-lb-manual 的资源），并且该配置没有整合进 Helm 的 values.yaml 中，你需要重新应用该配置文件来恢复服务的对外暴露：

# 请将文件名替换为你实际使用的 yaml 文件
kubectl apply -f portainer-lb-manual.yaml

执行完毕后，即可通过分配的 IP 地址访问 Portainer 并完成初始管理员密码的设置。

starlightBlog.post.tags

• k3s
• kubernetes
• helm
• portainer
• longhorn