#SonarQube Connector

SonarQube Connector 是一个用于连接任意 SonarQube 实例的连接器。

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

此外，该连接器支持跨命名空间集中管理 SonarQube 访问配置，避免在每个命名空间中重复配置 SonarQube 令牌。

#Overview

本文档涵盖：

• 集成要求：目标 SonarQube 实例的前置条件
• 创建 SonarQube 连接器
• 高级功能：关于 SonarQube 连接器的代理能力和配置能力

#Integration Requirements

SonarQube 前置条件

• SonarQube 实例必须能通过 HTTP/HTTPS 访问
• SonarQube 版本应支持连接器使用的 API 端点：
  • /api/authentication/validate - 用于认证验证
  • /api/system/status - 用于存活检测

#Creating a Simple SonarQube Connector

以下是为自托管 SonarQube 实例创建基础 SonarQube Connector 的示例：

# 自托管实例的 SonarQube Connector
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

#Fields Reference

spec.connectorClassName：

sonarqube（常量），指定 SonarQube 集成的 ConnectorClass 名称。

spec.address：

目标 SonarQube 服务器地址，例如：

• 自托管：https://sonarqube.example.com

spec.auth（可选）：

指定 SonarQube 实例的认证方式。

• spec.auth.name：SonarQube 连接器应为 tokenAuth。

• spec.auth.secretRef：指定包含 SonarQube 实例认证令牌的 Secret。该 Secret 必须创建在与连接器相同的命名空间中。

可选元数据字段：

• cpaas.io/description：SonarQube 连接器的描述信息，例如：

  apiVersion: connectors.alauda.io/v1alpha1
  kind: Connector
  metadata:
    name: sonarqube-connector
    annotations:
      cpaas.io/description: "连接团队 SonarQube 进行代码质量分析"

#Capabilities of SonarQube Connector

#Authentication

SonarQube 连接器支持以下认证类型：

• tokenAuth：基于令牌的认证，对应的 Secret 类型为 connectors.cpaas.io/bearer-token

例如：

apiVersion: v1
stringData:
  token: your-sonarqube-token  # 用户令牌或项目分析令牌
kind: Secret
metadata:
  name: sonarqube-token-secret
type: connectors.cpaas.io/bearer-token

有关完整状态信息，请参见 Connector Status Documentation。

#Credential Permissions Required

配置凭证所需权限取决于您在 Pod/流水线中的使用场景。

例如：

• 代码分析：仅需对目标项目拥有“执行分析”权限的令牌。
• 质量门检查：需要对质量门拥有读取权限的令牌。
• 创建项目：分析时若需创建新项目，则需额外权限。

为安全起见，建议创建权限最小的令牌。如需额外权限，请创建权限更高的连接器，并通过命名空间隔离控制用户访问。

#SonarQube Connector Proxy and Configuration with sonar-project.properties File

为了让客户端无需直接处理令牌即可访问 SonarQube，SonarQube 连接器提供了一个代理服务器，自动注入认证信息。

客户端可通过该代理服务器访问 SonarQube，无需在客户端配置令牌。

为简化使用，SonarQube 连接器提供了一个 sonar-project.properties 文件，可通过 CSI 挂载到 Pod 中。在 Pod 内执行扫描器操作时，代理服务会自动注入认证信息。

#Proxy Address

创建连接器时，系统会自动为目标 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 Configuration File

SonarQube 连接器提供如下配置：

sonar-project.properties：

• 提供一个 sonar-project.properties 配置文件。该配置文件通过 CSI 挂载到 Pod 中，使得通过代理访问 SonarQube 时无需在客户端配置令牌。

配置文件示例（生成于 ConfigMap）：

# SonarQube 服务器配置
sonar.host.url=https://sonarqube.example.com

# 代理配置（扫描器属性）
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：编码后的连接器命名空间和名称
• sonar.scanner.proxyPassword：认证令牌（自动管理）

#Using sonar-project.properties in Pods

连接器通过 CSI 挂载包含代理配置的 sonar-project.properties 配置文件。

在 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
            - |
              # 使用连接器配置
              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 由连接器自动挂载，包含连接器代理服务器的 CA 证书。详情请参见 Connectors CSI Built-in Configurations。

#Health Checks

SonarQube 连接器执行自动健康检查以验证连通性：

存活探针：

• 端点：/api/system/status
• 预期响应：HTTP 200，内容为 {"status": "UP"}
• 目的：确保 SonarQube 实例正常运行

认证探针：

• 端点：/api/authentication/validate
• 预期响应：HTTP 200，内容为 {"valid": true}
• 目的：验证提供的令牌有效

探针自动运行，结果反映在连接器的状态条件中。

#Best Practices

1. 命名空间隔离：为不同团队或项目创建独立连接器，利用命名空间隔离
2. 令牌轮换：定期轮换认证令牌并更新 Secret
3. 监控状态：监控连接器的 Ready 条件，及时发现认证或连通性问题
4. 最小权限原则：仅授予特定用例所需的最小权限

#Troubleshooting

若连接器显示非 Ready 状态：

1. 检查认证：确认 Secret 中的令牌有效且未过期
2. 验证连通性：确保 Kubernetes 集群能访问 SonarQube 实例
3. 查看日志：检查 connector-proxy-service 日志获取详细错误信息
4. 确认地址：确认 spec.address 正确且包含协议（https://）
5. API 访问：确保 SonarQube 实例允许来自集群的 API 访问

更多故障排查指南，请参见 Troubleshooting Guide。