SonarQube Connector

SonarQube Connector 是一种支持连接到任意 SonarQube 实例的 Connector。

您可以使用 SonarQube Connector 在 CI/CD 流水线中安全访问 SonarQube,以执行代码质量分析、安全扫描和质量门检查。

此外,该 Connector 支持集中管理跨命名空间的 SonarQube 访问配置,从而无需在每个命名空间中重复 SonarQube 令牌。

概述

本文档涵盖:

  • 集成要求:目标 SonarQube 实例的先决条件
  • 创建 SonarQube Connector
  • 高级功能:SonarQube Connector 的代理功能和配置功能

集成要求

SonarQube 先决条件

  • SonarQube 实例必须可通过 HTTP/HTTPS 访问
  • SonarQube 版本应支持 Connector 使用的 API 端点:
    • /api/authentication/validate - 用于身份验证验证
    • /api/system/status - 用于存活检查

创建简单的 SonarQube Connector

以下介绍如何为自托管 SonarQube 实例创建基本的 SonarQube Connector:

# SonarQube Connector for self-hosted instance
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: sonarqube-connector
spec:
  connectorClassName: sonarqube
  address: https://sonarqube.example.com
  auth:
    name: tokenAuth
    secretRef:
      name: sonarqube-token-secret

字段参考

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 的描述信息,例如:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: sonarqube-connector
      annotations:
        cpaas.io/description: "Connect to team SonarQube for code quality analysis"

SonarQube Connector 的功能

身份验证

SonarQube Connector 支持以下身份验证类型:

  • tokenAuth:基于令牌的身份验证,对应的 Secret 类型为 connectors.cpaas.io/bearer-token

例如:

apiVersion: v1
stringData:
  token: your-sonarqube-token  # User token or project analysis token
kind: Secret
metadata:
  name: sonarqube-token-secret
type: 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 中:

例如:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: sonarqube-connector
spec:
  # connector spec fields
status:
  conditions:
    # status conditions
  proxy:
    httpAddress:
      url: http://c-sonarqube-connector.default.svc.cluster.local

sonar-project.properties 配置文件

SonarQube Connector 提供以下配置:

sonar-project.properties:

  • 提供一个 sonar-project.properties 配置文件。此配置文件会通过 CSI 挂载到 Pod 中,使其能够通过代理访问 SonarQube 实例,而无需在客户端配置令牌。

在 ConfigMap 中生成的配置文件示例:

# SonarQube server configuration
sonar.host.url=https://sonarqube.example.com

# Proxy configuration (scanner properties)
sonar.scanner.proxyHost=c-sonarqube-connector.default.svc.cluster.local
sonar.scanner.proxyPort=80
sonar.scanner.proxyUser=default%2Fsonarqube-connector
sonar.scanner.proxyPassword=<connector-token>

该配置包括:

  • sonar.host.url:实际的 SonarQube 服务器地址
  • sonar.scanner.proxyHost:用于安全访问的代理主机名
  • sonar.scanner.proxyPort:代理端口(HTTP 为 80,HTTPS 为 443)
  • sonar.scanner.proxyUser:编码后的 Connector 命名空间和名称
  • sonar.scanner.proxyPassword:身份验证令牌(自动管理)
INFO

Sonar Scanner 8.0+ 默认禁用隧道代理身份验证。要启用身份验证代理支持,需要在执行期间通过 SONAR_SCANNER_OPTS 添加参数 -Djdk.http.auth.tunneling.disabledSchemes=。

在 Pod 中使用 sonar-project.properties

Connector 会通过 CSI 挂载一个 sonar-project.properties 配置文件,其中包含带有代理 configuration.names 的扫描器设置。

要在 Pod 中使用该文件:

apiVersion: batch/v1
kind: Job
metadata:
  name: sonar-scanner-job
spec:
  template:
    spec:
      containers:
        - name: sonar-scanner
          image: sonarsource/sonar-scanner-cli:latest
          command:
            - sh
            - -c
            - |
              # Use the connector configuration
              sonar-scanner -Dproject.settings=/scanner-config/sonar-project.properties
          volumeMounts:
            - name: scanner-config
              mountPath: /scanner-config
      volumes:
        - name: scanner-config
          csi:
            driver: connectors.cpaas.io
            volumeAttributes:
              connectorName: sonarqube-connector
              connectorNamespace: connectors-sonarqube-demo
              configuration.names: "sonar-scanner"

扫描器将使用代理配置安全访问 SonarQube,而无需直接访问令牌。

如果 SonarQube 实例使用 HTTPS,则需要将 CA 证书导入扫描器容器中的 Java 信任库:

keytool -importcert -noprompt \
    -trustcacerts \
    -keystore $JAVA_HOME/lib/security/cacerts \
    -storepass changeit \
    -alias corp-ca \
    -file /<mount-path>/ca.cert

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 的状态条件中。

最佳实践

  1. 命名空间隔离:使用命名空间隔离,为不同团队或项目创建独立的 connector
  2. 令牌轮换:定期轮换身份验证令牌,并相应更新 Secret
  3. 监控状态:监控 connector 的 Ready 条件,以检测身份验证或连接性问题
  4. 最小化权限:仅授予特定使用场景所需的最小权限

故障排除

如果 connector 显示非 Ready 状态:

  1. 检查身份验证:验证 Secret 中的令牌有效且未过期
  2. 验证连接性:确保 SonarQube 实例可从 Kubernetes 集群访问
  3. 查看日志:检查 connector-proxy-service 日志以获取详细的错误消息
  4. 验证地址:确认 spec.address 正确,并包含协议(https://)
  5. API 访问:确保 SonarQube 实例允许从你的集群访问 API

如需更多故障排除指导,请参阅故障排除指南。