SonarQube Connector
SonarQube Connector 是一种支持连接到任意 SonarQube 实例的 Connector。
您可以使用 SonarQube Connector 在 CI/CD 流水线中安全访问 SonarQube,以执行代码质量分析、安全扫描和质量门检查。
此外,该 Connector 支持集中管理跨命名空间的 SonarQube 访问配置,从而无需在每个命名空间中重复 SonarQube 令牌。
目录
概述集成要求创建简单的 SonarQube Connector字段参考SonarQube Connector 的功能身份验证所需凭证权限SonarQube Connector 代理以及使用 sonar-project.properties 文件进行配置代理地址sonar-project.properties 配置文件在 Pod 中使用 sonar-project.properties健康检查最佳实践故障排除概述
本文档涵盖:
- 集成要求:目标 SonarQube 实例的先决条件
- 创建 SonarQube Connector
- 高级功能:SonarQube Connector 的代理功能和配置功能
集成要求
SonarQube 先决条件
- SonarQube 实例必须可通过 HTTP/HTTPS 访问
- SonarQube 版本应支持 Connector 使用的 API 端点:
/api/authentication/validate- 用于身份验证验证/api/system/status- 用于存活检查
创建简单的 SonarQube Connector
以下介绍如何为自托管 SonarQube 实例创建基本的 SonarQube Connector:
字段参考
spec.connectorClassName:
sonarqube(常量),指定用于 SonarQube 集成的 ConnectorClass 名称。
spec.address:
目标 SonarQube 服务器地址,例如:
- 自托管:
https://sonarqube.example.com
spec.auth(可选):
指定 SonarQube 实例的身份验证方法。
-
spec.auth.name:对于 SonarQube Connector,应为tokenAuth。 -
spec.auth.secretRef:指定包含 SonarQube 实例身份验证令牌的 Secret。该 Secret 必须创建在与 Connector 相同的命名空间中。
可选元数据字段:
-
cpaas.io/description:SonarQube Connector 的描述信息,例如:
SonarQube Connector 的功能
身份验证
SonarQube Connector 支持以下身份验证类型:
tokenAuth:基于令牌的身份验证,对应的 Secret 类型为connectors.cpaas.io/bearer-token
例如:
SonarQube 支持多种令牌类型:
- 用户令牌:个人用户的访问令牌
- 项目分析令牌:限定于特定项目的令牌(推荐用于 CI/CD)
- 全局分析令牌:可用于分析任意项目的令牌(请谨慎使用)
对于生产环境,建议使用具有所需最小权限的项目分析令牌。
有关完整的状态信息,请参阅Connector 状态文档。
所需凭证权限
已配置凭证所需的权限取决于您计划如何在 Pod/Pipeline 中使用它。
例如:
- 代码分析:如果只需执行代码分析,令牌需要具有目标项目的“执行分析”权限。
- 质量门检查:要检查质量门状态,令牌需要具有质量门的读取权限。
- 创建项目:要在分析期间创建新项目,则需要额外权限。
出于安全最佳实践的考虑,建议创建具有所需最小权限的令牌。当需要额外权限时,请使用权限更高的令牌创建单独的 Connector,并通过命名空间隔离来控制哪些用户可以访问每个 Connector。
SonarQube Connector 代理以及使用 sonar-project.properties 文件进行配置
为了让客户端访问 SonarQube 而无需直接处理令牌,SonarQube Connector 提供了一个代理服务器,该服务器会自动注入身份验证信息。
客户端可以使用此代理服务器访问 SonarQube,而无需在客户端配置令牌。
为简化使用,SonarQube Connector 提供了一个 sonar-project.properties 文件,该文件可通过 CSI 挂载到 Pod 中。在 Pod 中执行扫描器操作时,代理服务会自动注入身份验证信息。
代理地址
创建 Connector 后,系统会自动为目标 SonarQube 实例配置代理服务。
代理端点记录在 status.proxy.httpAddress 中:
例如:
sonar-project.properties 配置文件
SonarQube Connector 提供以下配置:
sonar-project.properties:
- 提供一个
sonar-project.properties配置文件。此配置文件会通过 CSI 挂载到 Pod 中,使其能够通过代理访问 SonarQube 实例,而无需在客户端配置令牌。
在 ConfigMap 中生成的配置文件示例:
该配置包括:
sonar.host.url:实际的 SonarQube 服务器地址sonar.scanner.proxyHost:用于安全访问的代理主机名sonar.scanner.proxyPort:代理端口(HTTP 为 80,HTTPS 为 443)sonar.scanner.proxyUser:编码后的 Connector 命名空间和名称sonar.scanner.proxyPassword:身份验证令牌(自动管理)
Sonar Scanner 8.0+ 默认禁用隧道代理身份验证。要启用身份验证代理支持,需要在执行期间通过 SONAR_SCANNER_OPTS 添加参数 -Djdk.http.auth.tunneling.disabledSchemes=。
在 Pod 中使用 sonar-project.properties
Connector 会通过 CSI 挂载一个 sonar-project.properties 配置文件,其中包含带有代理 configuration.names 的扫描器设置。
要在 Pod 中使用该文件:
扫描器将使用代理配置安全访问 SonarQube,而无需直接访问令牌。
如果 SonarQube 实例使用 HTTPS,则需要将 CA 证书导入扫描器容器中的 Java 信任库:
ca.cert 由 Connector 自动挂载,其中包含 Connector Proxy 服务器的 CA 证书。更多详细信息请参阅 Connectors CSI 内置配置。
健康检查
SonarQube connector 会执行自动健康检查,以验证连接性:
存活探针:
- 端点:
/api/system/status - 预期响应:HTTP 200,包含
{"status": "UP"} - 用途:确保 SonarQube 实例正常运行
身份验证探针:
- 端点:
/api/authentication/validate - 预期响应:HTTP 200,包含
{"valid": true} - 用途:验证所提供的令牌有效
这些探针会自动运行,结果会反映在 Connector 的状态条件中。
最佳实践
- 命名空间隔离:使用命名空间隔离,为不同团队或项目创建独立的 connector
- 令牌轮换:定期轮换身份验证令牌,并相应更新 Secret
- 监控状态:监控 connector 的 Ready 条件,以检测身份验证或连接性问题
- 最小化权限:仅授予特定使用场景所需的最小权限
故障排除
如果 connector 显示非 Ready 状态:
- 检查身份验证:验证 Secret 中的令牌有效且未过期
- 验证连接性:确保 SonarQube 实例可从 Kubernetes 集群访问
- 查看日志:检查 connector-proxy-service 日志以获取详细的错误消息
- 验证地址:确认
spec.address正确,并包含协议(https://) - API 访问:确保 SonarQube 实例允许从你的集群访问 API
如需更多故障排除指导,请参阅故障排除指南。