解决actions-runner-controller中ReadWriteMany卷权限问题

在Kubernetes环境中使用actions-runner-controller时，当配置ReadWriteMany类型的存储卷作为工作目录时，可能会遇到权限问题导致工作流执行失败。本文将深入分析问题原因并提供完整的解决方案。

问题现象

在Azure Kubernetes集群中部署actions-runner-controller时，如果使用ReadWriteMany类型的存储卷作为工作目录，会出现以下两种典型错误：

1. 容器初始化阶段报错：

Error: EPERM: operation not permitted, chmod '/home/runner/_work/externals/node16/bin'

2. 当在存储类中配置了uid=1001 gid=1001的挂载选项时，工作流会无限期挂起，无法正常启动。

根本原因分析

这些问题的根本原因在于容器内用户与存储卷权限不匹配。GitHub Actions Runner容器默认以UID 1000的用户运行，而存储卷的权限配置没有正确适配这个用户。

在Kubernetes环境中，当使用持久化存储时，需要确保：

1. 容器运行用户对存储卷有读写权限
2. 文件系统权限设置正确
3. 存储类挂载选项与容器安全上下文一致

完整解决方案

1. 存储类配置

首先需要正确配置存储类，确保挂载选项包含正确的UID/GID和权限设置：

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: aks-runner-sc
provisioner: file.csi.azure.com
parameters:
  skuName: Premium_LRS
mountOptions:
  - dir_mode=0777
  - file_mode=0777
  - uid=1000
  - gid=1000
  - mfsymlinks
  - actimeo=30

关键配置说明：

• uid=1000和gid=1000：匹配Runner容器的默认用户
• dir_mode=0777和file_mode=0777：确保足够的权限
• mfsymlinks和actimeo=30：优化NFS性能

2. Runner部署配置

在Runner的部署配置中，需要设置正确的安全上下文：

template:
  spec:
    securityContext:
      fsGroup: 1000
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE
            value: /home/runner/pod-templates/default.yaml
          - name: ACTIONS_RUNNER_USE_KUBE_SCHEDULER
            value: "true"
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
    volumes:
      - name: work
        ephemeral:
          volumeClaimTemplate:
            spec:
              accessModes: [ "ReadWriteMany" ]
              storageClassName: aks-runner-sc

3. Pod模板配置

通过ConfigMap定义Pod模板，确保作业容器也有正确的安全上下文：

apiVersion: v1
kind: ConfigMap
metadata:
  name: runner-pod-template
data:
  default.yaml: |
    apiVersion: v1
    kind: PodTemplate
    metadata:
      name: runner-pod-template
    spec:
      securityContext:
        fsGroup: 1000
      containers:
      - name: $job
        resources:
          requests:
            cpu: 100m
            memory: 0.5Gi

技术原理

这个解决方案通过多层次的权限控制确保Runner容器能够正常访问存储卷：

1. 存储类级别：通过挂载选项设置底层文件系统的UID/GID和权限模式
2. Pod级别：通过fsGroup设置卷的组所有权
3. 容器级别：确保Runner以正确的用户运行

fsGroup是Kubernetes中一个特殊的安全上下文字段，它会在卷挂载时自动将卷的所有组更改为指定的GID，并应用请求的权限。这对于需要共享存储的多容器场景特别重要。

最佳实践建议

1. 对于生产环境，建议使用性能更好的存储类（如Premium_LRS）
2. 根据实际需求调整存储大小，避免资源浪费
3. 考虑使用资源限制防止单个Runner占用过多资源
4. 定期检查存储卷的回收策略，避免存储泄漏

通过以上配置，可以确保actions-runner-controller在Kubernetes环境中正确使用ReadWriteMany类型的存储卷，解决权限问题，使CI/CD流程顺利运行。