GitLab静态Runner调用Vault外部秘钥遇403权限拒绝问题排查

核心差异与原因 #

部署在服务器上的静态Runner和Kubernetes共享Runner，在Vault认证流程上的核心区别在于JWT令牌的生成、验证逻辑，以及所处的网络/权限环境。403错误本质是Vault拒绝了静态Runner的认证请求——静态Runner本身对拉取Vault秘钥没有固有限制，但需要针对性配置才能正常工作。

必须检查的配置项 #

1. 确认Vault的JWT认证角色配置 #

Vault的JWT角色需要允许静态Runner环境的请求，需检查：

• bound_issuer是否与GitLab实例的issuer一致（可通过GitLab实例的/.well-known/jwks.json端点确认）
• 角色是否包含静态Runner执行作业的项目路径、命名空间等bound_subject或bound_claims规则，避免仅放行K8s Runner的特定Claims
• 确保角色拥有目标秘钥路径的read权限

2. 验证静态Runner的Vault配置 #

检查静态Runnerconfig.toml中的[runners.secrets.vault]段：

• url指向正确的Vault地址，且静态Runner服务器能正常访问该地址（可通过curl https://你的Vault地址/v1/sys/health测试连通性）
• auth_method设置为jwt
• jwt_file路径正确，且Runner进程有读取权限（静态Runner的JWT令牌默认存在临时路径，需确认文件权限）

3. 网络与防火墙限制 #

• 静态Runner所在服务器的IP是否被Vault的防火墙/ACL规则拦截，导致无法发送认证请求或接收响应
• 查看Vault的审计日志，确认403错误的具体触发原因（比如Claims不匹配、权限不足、IP被拦截等）

4. GitLab Runner版本兼容性 #

确保静态Runner版本与GitLab实例版本兼容。旧版本静态Runner的JWT令牌生成逻辑可能与Vault认证不匹配，建议升级到与GitLab实例同版本或最新稳定版

验证步骤 #

1. 在静态Runner服务器上手动模拟JWT认证流程：

   # 替换为你的Runner的JWT令牌路径
   JWT_TOKEN=$(cat /var/run/gitlab-runner/jwt-token)
   # 替换为你的Vault地址和角色名
   curl --request POST \
     --data '{"jwt": "'"$JWT_TOKEN"'", "role": "你的Vault-JWT角色"}' \
     https://你的Vault实例地址/v1/auth/jwt/login
   

   根据返回的错误信息定位具体问题

2. 对比K8s Runner和静态Runner的JWT令牌Claims，检查是否存在runner_id、runner_type、namespace等Claims差异，这些差异可能被Vault角色规则限制

参考文档翻译：GitLab 使用 Vault 的 JSON Web Token（JWT）认证方法在 CI 作业中获取密钥。配置你的 Vault 和密钥，然后在 CI 作业中引用它们。

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