Jenkins Kubernetes插件配置workspaceVolume不生效 Pod启动报错

问题现象 #

参照Jenkins Kubernetes插件官方文档配置podTemplate，目标为启用Docker-on-Docker模式、修改Jenkins默认工作目录，将workspaceVolume设置为hostPathWorkspaceVolume，指定宿主机路径为/opt/workspace（宿主机已提前创建该目录）。Pod启动时jnlp容器异常终止（退出码: 1，原因: Error），流水线最终执行失败。

原podTemplate配置 #

podTemplate(
    workspaceVolume: hostPathWorkspaceVolume(hostPath: "/opt/workspace"),
    yaml: '''
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: base-container
    image: python:2.7
    command: ['sleep', '99d']
    volumeMounts:
    - name: dockersock
      mountPath: /var/run/docker.sock
    - name: dockerbin
      mountPath: /usr/bin/docker
  volumes:
  - name: dockersock
    hostPath:
      path: /var/run/docker.sock
  - name: dockerbin
    hostPath:
      path: /usr/bin/docker
''')

运行报错日志 #

23:10:52  jenkins-demo-253-pwlzb-qt66s-678gm Container jnlp was terminated (Exit Code: 1, Reason: Error)
23:10:52  [Pipeline] // node
23:10:52  [Pipeline] }
23:10:52  [Pipeline] // podTemplate
23:10:52  [Pipeline] End of Pipeline
23:10:52  ERROR: Queue task was cancelled
23:10:52  Finished: FAILURE

故障根因 #

核心问题是宿主机/opt/workspace目录权限配置错误：

• jnlp容器默认以UID为1000的jenkins用户运行，启动时需要在挂载的工作目录下写入代理临时文件、拉取代码，必须拥有目录的读写权限
• 宿主机上root用户创建的/opt/workspace目录默认权限为drwxr-xr-x，属主为root，UID 1000的用户属于其他用户范畴，没有写入权限，直接导致jnlp进程启动失败退出
• 原配置中直接挂载宿主机/usr/bin/docker二进制的方式存在兼容性隐患，不同宿主机的docker二进制依赖的动态库版本不一致，会导致后续容器内docker命令执行报错

修复步骤 #

• 配置宿主机目录权限
  在所有Kubernetes工作节点执行以下命令，给工作目录配置可访问权限，二选一即可：

  # 测试环境快速验证：开放目录读写权限
  chmod 777 /opt/workspace
  
  # 生产环境推荐：将目录属主设置为与jnlp容器运行用户一致的UID 1000
  chown -R 1000:1000 /opt/workspace
  

  如果集群启用了SELinux，还需要执行以下命令配置安全上下文，允许容器访问该hostPath目录：

  chcon -Rt svirt_sandbox_file_t /opt/workspace
  

• 调整podTemplate配置
  显式声明hostPathWorkspaceVolume为可读写模式，移除存在兼容性问题的docker二进制直接挂载，改为在业务镜像中预装匹配版本的docker客户端，同时给docker.sock挂载配置双向传播策略适配Docker-on-Docker场景：

  podTemplate(
      workspaceVolume: hostPathWorkspaceVolume(
          hostPath: "/opt/workspace",
          readOnly: false
      ),
      yaml: '''
  

apiVersion: v1
kind: Pod
spec:
containers:

• name: base-container
  image: python:2.7 # 需提前在该镜像内安装docker客户端
  command: ['sleep', '99d']
  volumeMounts:
  • name: dockersock
    mountPath: /var/run/docker.sock
    mountPropagation: Bidirectional
    volumes:
• name: dockersock
  hostPath:
  path: /var/run/docker.sock
  type: Socket
  ''')

## 验证方法
重新触发流水线，查看jnlp容器日志，若无Permission denied类报错，可正常连接Jenkins控制器、拉取代码并执行流水线步骤，即修复生效。

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