按官方指南无法部署Jenkins到Kubernetes的排查求助

操作步骤 #

我在Linux/Minikube环境中，按照官方「使用Helm v3安装Jenkins」步骤部署，操作如下：

• 创建Jenkins命名空间
• 通过官方YAML创建Persistent Volume（PV）
• 创建ServiceAccount（SA）
• 执行命令 helm install jenkins -n jenkins -f jenkins-values.yaml jenkinsci/jenkins 安装，仅修改官方values文件中以下配置：

storageClass: jenkins-pv
...
serviceAccount:
  create: false

问题现象 #

Jenkins Pod始终无法启动，报错：

0/1 nodes are available: 1 node(s) didn’t find available persistent volumes to bind. preemption: 0/1 nodes are available: 1 Preemption is not helpful for scheduling…

资源状态信息 #

PV状态 #

rage@ubuntu-virtual:~$ kubectl describe pv jenkins -n jenkins
Name:            jenkins-pv
Labels:          <none>
Annotations:     pv.kubernetes.io/bound-by-controller: yes
Finalizers:      [kubernetes.io/pv-protection]
StorageClass:    jenkins-pv
Status:          Released
Claim:           default/jenkins
Reclaim Policy:  Retain
Access Modes:    RWO
VolumeMode:      Filesystem
Capacity:        5Gi
Node Affinity:   <none>
Message:         
Source:
    Type:          HostPath (bare host directory volume)
    Path:          /data/jenkins-volume/
    HostPathType:  
Events:            <none>

PVC状态 #

$ kubectl describe pvc jenkins -n jenkins
Name:          jenkins
Namespace:     jenkins
StorageClass:  jenkins-pv
Status:        Pending
Volume:        
Labels:        app.kubernetes.io/component=jenkins-controller
               app.kubernetes.io/instance=jenkins
               app.kubernetes.io/managed-by=Helm
               app.kubernetes.io/name=jenkins
               helm.sh/chart=jenkins-4.3.23
Annotations:   meta.helm.sh/release-name: jenkins
               meta.helm.sh/release-namespace: jenkins
Finalizers:    [kubernetes.io/pvc-protection]
Capacity:      
Access Modes:  
VolumeMode:    Filesystem
Used By:       jenkins-0
Events:
  Type    Reason               Age                   From                         Message
  ----    ------               ----                  ----                         -------
  Normal  WaitForPodScheduled  38m (x481 over 160m)  persistentvolume-controller  waiting for pod jenkins-0 to be scheduled
  Normal  WaitForPodScheduled  28m (x26 over 34m)    persistentvolume-controller  waiting for pod jenkins-0 to be scheduled
  Normal  WaitForPodScheduled  2m35s (x81 over 22m)  persistentvolume-controller  waiting for pod jenkins-0 to be scheduled

Pod事件 #

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  37s   default-scheduler  0/1 nodes are available: 1 node(s) didn't find available persistent volumes to bind. preemption: 0/1 nodes are available: 1 Preemption is not helpful for scheduling..

已尝试的操作 #

我尝试为PersistentVolume添加nodeAffinity，但未解决问题，配置如下：

nodeAffinity:
required:
  nodeSelectorTerms:
  - matchExpressions:
    - key: kubernetes.io/hostname
      operator: In
      values:
      - minikube

同时添加了claimRef，指定Helm创建的PVC名称：

claimRef:
  name: jenkins
  namespace: jenkins

排查方案 #

1. 修复PV状态冲突
   当前PV状态为Released，绑定的是default/jenkins PVC，但现在使用的PVC在jenkins命名空间。由于PV回收策略是Retain，Released状态的PV不会自动重新绑定新PVC，需手动处理：

   • 删除现有PV，重新创建不带旧claimRef的PV
   • 或执行kubectl edit pv jenkins-pv，将status改为Available，并删除spec.claimRef字段

2. 验证存储类匹配
   确认jenkins-pv存储类是否存在，且PV与PVC的存储类名称完全一致（注意大小写）。若自定义存储类未正确配置，可改用Minikube默认的standard存储类。

3. 修复HostPath权限与存在性
   进入Minikube节点检查目录状态：

   minikube ssh
   # 确认目录存在并设置正确权限（Jenkins容器默认用uid 1000）
   sudo mkdir -p /data/jenkins-volume
   sudo chown 1000:1000 /data/jenkins-volume
   

4. 移除手动添加的claimRef
   手动指定的claimRef会限制PV只能绑定特定PVC，且与之前的绑定记录冲突。建议创建PV时不设置该字段，让Kubernetes自动匹配符合条件的PVC。

内容的提问来源于stack exchange，提问作者Dec0de