使用 Tekton 自动创建租户 SonarQube 用户和 Connector

当新租户开始在 Alauda Container Platform 上运行 SonarQube 代码扫描时,管理员必须管理租户的 SonarQube 账户和权限,在集群上创建并维护租户的 sonarqube Connector 和认证 Secret,并在用户令牌过期前完成轮换—— 每个租户、每个轮换周期都需要执行这些操作。本指南使用单个 Tekton TaskRun 自动完成整个流程:运行一次即可预配租户,并按固定周期 调度同一 TaskRun,以便原地轮换令牌,无需人工干预。

其实现机制是 sonarqube-connector-automatic-creation Task。 本页面重点介绍 operator 工作流。有关参数、 workspace、result 和 step 的参考信息,请参阅 Task 参考。

开始之前

集群前提条件

  • 已安装 Tekton Pipelines。请参阅 Tekton Pipelines 安装指南。
  • 已安装 Connectors 系统和 SonarQube ConnectorClass—— connectors-operator 通过 ConnectorsConfig 处理这两者。请参阅 Connectors 安装指南,并确保已在 ConnectorsConfig 中启用 ConnectorsSonarQube。
  • 已在将运行 TaskRun 的命名空间中安装 sonarqube-connector-automatic-creation Task。有关应用配置的方法,请参阅 Task 参考中的 安装。
  • 集群可以访问默认的 sonarqubeAutomationImage(或其镜像)。

SonarQube 实例前提条件

在实例级别一次性配置以下设置,以确保租户模型正常运行。这些设置由 SonarQube 管理员配置,而不是由 Task 配置。

ID设置必需值原因
P1默认项目可见性Private自动创建的租户项目默认必须为私有;Public 会在首次扫描时暴露租户代码。Administration → Projects → Management → Default visibility of new projects。
P2sonar-users / Anyone 的全局权限不授予 Execute Analysis全局授予 Execute Analysis 会允许任何租户扫描到其他租户的 key 命名空间并在其中自动创建项目,从而绕过每个租户的 projectPattern。请在 Administration → Security → Global Permissions 下进行审计。
P3默认权限模板不向 sonar-users / Anyone 授予项目级权限Default Template 中的全面授权会泄露其他租户的项目,而不受租户模板限制。Administration → Security → Permission Templates → Default Template。
P4默认质量门禁 + 质量配置文件设置为组织基线自动创建的项目会继承实例默认值。请在 Quality Gates 和 Quality Profiles 下进行设置。
P5Admin Connector 的用户拥有 Administer SystemTask 会在预检阶段检查此项——如果没有该权限,针对 users/create、permissions/add_user 和 permission_templates/* 的 API 调用会失败,并返回 403 Insufficient privileges。使用 GET /api/permissions/users?permission=admin 进行验证。

Task 只会强制执行 P5。P1–P4 是租户隔离 加固措施:即使未进行这些设置,Task 仍会成功,但租户之间的边界 会减弱。在接入第一个租户之前,请先审计这些设置。

Kubernetes RBAC

TaskRun 的 ServiceAccount 在每个租户命名空间中都需要对 Secret 和 Connector 具备 get/create/patch/update/delete 权限。建议为每个租户命名空间分别使用一个 Role——在多个租户之间共享 ClusterRole 会移除用于防止配置错误的租户 TaskRun 写入其他租户命名空间的边界。

apiVersion: v1
kind: ServiceAccount
metadata:
  name: sonarqube-task-runner
  namespace: connectors-management
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: sonarqube-connector-automatic-creation
  namespace: acme-prod              # the tenant's namespace
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "create", "patch", "update", "delete"]
- apiGroups: ["connectors.alauda.io"]
  resources: ["connectors"]
  verbs: ["get", "create", "patch", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: sonarqube-connector-automatic-creation
  namespace: acme-prod
subjects:
- kind: ServiceAccount
  name: sonarqube-task-runner
  namespace: connectors-management
roleRef:
  kind: Role
  name: sonarqube-connector-automatic-creation
  apiGroup: rbac.authorization.k8s.io

Task 使用字段管理器为 connector-auto 的 Server-Side Apply, 因此当实时 spec 已经匹配时,重新运行不会执行任何操作。

跨集群变体。 当租户 Connector + Secret 位于 其他集群时,请在 TaskRun 运行时绑定 kubeconfig workspace; kubeconfig 中嵌入的身份会取代此集群端的 RBAC。

必须允许创建本地用户

Task 通过 POST /api/users/create local=true 预配租户 bot 用户。目标实例必须接受 该调用。系统不会执行预检——当本地用户创建被禁用时,只有在 Task 首次尝试 创建用户时才会出现失败,表现为 HTTP 400,响应正文会说明用户管理 已被委派。

SonarQube Community 不包含以下机制,而不使用预配的纯 SSO 登录 (SAML / OIDC / GitHub-as-login / GitLab-as-login) 不会触发此问题。已知的阻断因素是 SonarQube Enterprise / Data Center 中的预配集成:

机制所在位置错误正文大致为
SCIM 预配Administration → General → SCIM(需要 SAML)User management is delegated to your SCIM provider
GitHub 预配Administration → Authentication → GitHub → ProvisioningUser management is delegated to your GitHub organization
GitLab 预配Administration → Authentication → GitLab → ProvisioningUser management is delegated to your GitLab instance

如果其中一项已启用,请在接入前选择一种备用方案:

  1. 推荐——关闭预配集成,保留 SSO 登录。 SonarQube 会恢复为由管理员管理用户;SSO 登录 集成保持不变。
  2. 让 IDP 预配 bot 用户。 通过 IDP 预先配置每个 <tenant>-bot;Task 的 users/search 路径会复用 IDP 预配的用户,并继续执行授权 + 模板 + 令牌流程。
  3. 手动备用方案——在预配关闭的时间窗口内预先创建。 管理员暂时禁用预配,创建每个 <tenant>-bot 本地用户,然后重新启用预配并运行 Task。

在上述三种情况下,权限模板 + provisioning 授权 + 令牌签发仍会自动执行。

接入流程

本流程会将租户 acme 接入由管理员 Connector connectors-management/admin-sonar 背后的 SonarQube 实例。它会创建 acme-prod/acme-sonarqube,作为租户的 sonarqube Connector。

1. 验证管理员 Connector

kubectl -n connectors-management get connector admin-sonar -o yaml | grep -E 'address|tokenAuth|Ready'

Connector 应为 Ready=True。在接入第一个租户之前,还要确认 P5——管理员令牌必须持有全局 admin:

ADMIN_TOKEN=...  # paste once; do NOT commit
curl -fsSL -u "$ADMIN_TOKEN:" \
  "https://sonarqube.example.com/api/permissions/users?permission=admin" | jq '.users[].login'

输出中必须显示你的管理员登录名。

2. 选择租户的项目键模式

projectPattern 正则表达式必须匹配所有租户项目键,并且不得与其他租户重叠。请以租户前缀作为锚点:

租户约定projectPattern匹配项
acme:*^acme(:.*)?$acme、acme:web-frontend、acme:platform/api
acme-*^acme(-.*)?$acme、acme-api、acme-frontend

在租户目录中记录所选前缀,以便同级租户遵守边界。

3. 应用接入 TaskRun

Task 会自动检测 sonarqube-config 工作区的绑定方式。请选择一种模式:

模式适用场景方式
Connectors CSI Driver(推荐)与管理员 Connector 位于同一集群,日常接入从 SonarQube sonar-scanner ConnectorClass 配置中,通过 Connectors CSI Driver 投影的卷进行绑定。管理员令牌永远不会进入 Task pod——Connectors Proxy 会在每次 API 调用时注入该令牌。
直接使用 Secret引导、跨集群,或 CSI driver 不可用预先创建包含 token(或 username + password)的 Secret,并通过 sonarqubeUrl 参数传入 SonarQube 基础 URL。通过更改该参数,同一个 Secret 可以面向多个 SonarQube 实例。

以下示例使用直接 Secret。TaskRun 假定 connectors-management 命名空间中已预先创建 Secret admin-sonar-credentials,其中包含第 1 步验证过的管理员 token:

kubectl -n connectors-management create secret generic admin-sonar-credentials \
  --from-literal=token=$ADMIN_TOKEN
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: onboard-acme-
  namespace: connectors-management
spec:
  serviceAccountName: sonarqube-task-runner
  taskRef:
    name: sonarqube-connector-automatic-creation
  params:
  - name: connector
    value: acme-prod/acme-sonarqube
  - name: tenant
    value: acme
  - name: projectPattern
    value: '^acme(:.*)?$'
  - name: tokenDuration
    value: "30"
  - name: sonarqubeUrl
    value: https://sonarqube.example.com
  workspaces:
  - name: sonarqube-config
    secret:
      secretName: admin-sonar-credentials

如需使用 Connectors CSI Driver 绑定,请将 workspaces: 块替换为 SonarQube sonar-scanner ConnectorClass 的 CSI 投影——TaskRun 的其余部分保持不变。

使用 kubectl apply -f onboarding.yaml 应用,然后监视 TaskRun:

tkn taskrun logs -L -f -n connectors-management

成功运行后会留下以下结果:

NAME                  VALUE
tenant                acme
username              acme-bot
permission-template   acme-template
token-name            acme-prod__acme-sonarqube
connector-ref         acme-prod/acme-sonarqube

并在 acme-prod 中创建以下集群对象:

  • Secret/acme-sonarqube-secret(类型为 connectors.cpaas.io/bearer-token)
  • Connector/acme-sonarqube(Ready=True,指向上述 Secret)

4. 对租户令牌执行冒烟测试

TENANT_TOKEN=$(kubectl -n acme-prod get secret acme-sonarqube-secret \
  -o jsonpath='{.data.token}' | base64 -d)

# Should auto-create the project on first call:
curl -fsSL -u "$TENANT_TOKEN:" \
  -X POST "https://sonarqube.example.com/api/projects/create" \
  --data "project=acme:smoke-test&name=Acme%20Smoke%20Test"

# Should return the project; visibility=private (inherited from P1):
curl -fsSL -u "$TENANT_TOKEN:" \
  "https://sonarqube.example.com/api/projects/search?projects=acme:smoke-test" | jq '.components[]'

负向检查——模拟租户 bravo:

# Should return HTTP 403 with body 'Insufficient privileges'
# (the acme permission template does NOT match this key):
curl -fsSL -u "$TENANT_TOKEN:" \
  -X POST "https://sonarqube.example.com/api/projects/create" \
  --data "project=bravo:should-fail&name=Cross%20Tenant" \
  -w '\nHTTP %{http_code}\n'

此处出现 HTTP 404 意味着 projectKeyPattern 检查被绕过了——请重新验证权限模板中的模式是否与在 projectPattern 中设置的模式匹配。

确认可见性以及跨租户拒绝后,删除冒烟测试项目(api/projects/delete)。

轮换

对于租户用户、权限模板和 provisioning 授权,Task 具备幂等性。令牌则不同:每次成功运行都会撤销现有令牌(如果存在),生成新令牌,并重写租户 Secret 和 Connector。不要为同一租户运行重叠的 TaskRun,因为后运行的 TaskRun 会使前一个运行写入的令牌失效。

资源状态Task 行为
用户、权限模板和授权均存在。复用这些资源,然后撤销并生成令牌。
租户 Secret 缺失或为空。撤销并生成令牌,然后创建 Secret。
tokenDuration 或 tokenName 已更改。使用新的令牌设置撤销并生成令牌。
权限模板或用户缺失。重新创建缺失的资源,然后撤销并生成令牌。

按所需的轮换间隔调度 TaskRun(例如,为 tokenDuration=30 每 15 天运行一次)。不要先删除租户 Secret;Task 会撤销旧令牌,并使用新令牌以原子方式重写 Secret。在 Secret 更新期间运行的扫描可能会短暂失败,因此请在必要时协调轮换与工作负载调度。

确切的 cron 接线方式(Tekton-on-cron controller、TriggerSchedule,或用于 kubectl create TaskRun 的 CronJob)取决于 operator;Task 的契约仅是“使用相同参数重新运行”。

多租户接入

为第二个租户 bravo 接入服务:应用一个使用不重叠 projectPattern 的第二个 TaskRun:

params:
- name: connector
  value: bravo-prod/bravo-sonarqube
- name: tenant
  value: bravo
- name: projectPattern
  value: '^bravo(:.*)?$'

两个租户的权限模板互不重叠,因此:

  • acme-bot 可以自动创建 acme:* 项目,但不能创建 bravo:* 项目。
  • bravo-bot 可以自动创建 bravo:* 项目,但不能创建 acme:* 项目。
  • 跨租户 API 读取会返回 403 Insufficient privileges。

跨租户拒绝仅在强制执行 P3 时成立——也就是说,Default Template 在 sonar-users 或 Anyone 上没有项目级授权。否则,无论每个租户使用什么模板,默认组的授权都会泄漏到每个自动创建的项目中。在将跨租户拒绝视为安全边界之前,请审计 Default Template。

维护租户目录(项目模式 + Connector 引用),以避免未来租户选择重叠的模式。Task 本身不会强制执行不重叠。

租户下线

停用租户时,撤销 Task 创建的内容——先撤销 SonarQube 侧的构件(令牌、权限模板、provisioning 授权、机器人用户),然后再撤销集群侧的 Connector + Secret。 这种顺序可以关闭“Connector 已删除但租户令牌仍然有效”的窗口。每个调用都是幂等的:SonarQube 返回的 404 和缺失的 Kubernetes 对象都会被视为已删除,因此部分完成或中止的运行会在重新运行时自动修复。

将以下脚本保存为 sonarqube-tenant-offboard.sh,并使用租户凭据和管理员凭据运行:

TENANT=acme \
CONNECTOR_REF=acme-prod/acme-sonarqube \
SONAR=https://sonarqube.example.com \
ADMIN_TOKEN=squ_xxxxxxxxxxxxxxxxxxxx \
  bash sonarqube-tenant-offboard.sh

必需的环境变量:TENANT、CONNECTOR_REF(采用 namespace/name 格式,与传递给 Task 的 connector 参数的格式相同)、SONAR(SonarQube 基础 URL)、ADMIN_TOKEN(持有 Administer System 权限的用户所生成的 SonarQube 用户令牌——参见 P5;传入时不要带末尾的冒号,脚本会在内部为 curl Basic auth 追加冒号)。脚本会针对 /api/users/current 执行预检;如果令牌持有者缺少全局 admin 权限,脚本将拒绝继续执行。因此,配置错误的令牌会快速失败,而不是在 SonarQube 清理过程中途失败。

可选覆盖项:USERNAME(默认为 <tenant>-bot)、TEMPLATE (默认为 <tenant>-template)以及 DEACTIVATE_USER(默认为 true;设置 false 可使 SonarQube 用户保持可重新激活状态——模板和令牌仍会被删除)。

#!/usr/bin/env bash
# sonarqube-tenant-offboard.sh — symmetric undo of
# sonarqube-connector-automatic-creation. Idempotent: 404 means
# "already gone"; any other 4xx/5xx is surfaced as an error.
set -euo pipefail

: "${TENANT:?TENANT is required}"
: "${CONNECTOR_REF:?CONNECTOR_REF (namespace/name) is required}"
: "${SONAR:?SONAR base URL is required}"
: "${ADMIN_TOKEN:?ADMIN_TOKEN is required (no trailing colon)}"

USERNAME="${USERNAME:-${TENANT}-bot}"
TEMPLATE="${TEMPLATE:-${TENANT}-template}"
DEACTIVATE_USER="${DEACTIVATE_USER:-true}"

NAMESPACE="${CONNECTOR_REF%/*}"
CONNECTOR_NAME="${CONNECTOR_REF#*/}"
TOKEN_NAME="${NAMESPACE}__${CONNECTOR_NAME}"
SECRET_NAME="${CONNECTOR_NAME}-secret"

echo "Offboarding tenant=$TENANT"
echo "  SonarQube: user=$USERNAME template=$TEMPLATE token=$TOKEN_NAME"
echo "  Cluster:   $NAMESPACE/$CONNECTOR_NAME (+ secret $SECRET_NAME)"
echo

# Preflight: confirm ADMIN_TOKEN belongs to a user holding global
# `admin` (Administer System). Without it every admin-only API call
# below — user_tokens/revoke for another user, permission_templates/
# delete, permissions/remove_user, users/deactivate — would 403.
me="$(curl -sS -u "${ADMIN_TOKEN}:" "${SONAR}/api/users/current")"
case "$me" in
  *'"admin"'*) ;;
  *)
    echo "ERROR: ADMIN_TOKEN does not hold global 'admin' (Administer System)." >&2
    echo "  /api/users/current returned: $me" >&2
    echo "  Generate the token from a SonarQube user with Administer System." >&2
    exit 2 ;;
esac

# sonar <label> <path> <curl-args...>
# Prints "[label] <code>"; succeeds on 2xx / 404, fails loudly on other codes.
sonar() {
  local label="$1" path="$2"; shift 2
  local out code body
  out="$(curl -sS -u "${ADMIN_TOKEN}:" -w '\n%{http_code}' "${SONAR}${path}" "$@")"
  code="${out##*$'\n'}"
  body="${out%$'\n'*}"
  case "$code" in
    2*)    echo "  [$label] OK ($code)" ;;
    404)   echo "  [$label] already gone (404)" ;;
    *)     echo "  [$label] FAILED ($code): ${body:-<empty>}" >&2
           return 1 ;;
  esac
}

# 1. Revoke the tenant user token.
sonar revoke-token /api/user_tokens/revoke -X POST \
  --data-urlencode "login=$USERNAME" \
  --data-urlencode "name=$TOKEN_NAME"

# 2. Delete the tenant permission template.
# Endpoint moved in SonarQube 10+: /api/permissions/delete_template
# (older releases used /api/permission_templates/delete).
sonar delete-template /api/permissions/delete_template -X POST \
  --data-urlencode "templateName=$TEMPLATE"

# 3. Remove the global `provisioning` grant from the tenant user.
sonar revoke-provisioning /api/permissions/remove_user -X POST \
  --data-urlencode "login=$USERNAME" \
  --data-urlencode "permission=provisioning"

# 4. Deactivate the bot user (unless DEACTIVATE_USER=false).
if [ "$DEACTIVATE_USER" = "true" ]; then
  sonar deactivate-user /api/users/deactivate -X POST \
    --data-urlencode "login=$USERNAME"
fi

# 5. Cluster-side: delete the tenant Connector and Secret.
echo
echo "  [k8s] delete Connector $NAMESPACE/$CONNECTOR_NAME"
kubectl -n "$NAMESPACE" delete connector "$CONNECTOR_NAME" --ignore-not-found
echo "  [k8s] delete Secret    $NAMESPACE/$SECRET_NAME"
kubectl -n "$NAMESPACE" delete secret    "$SECRET_NAME"    --ignore-not-found

echo
echo "Offboarding complete."

SonarQube 上现有的租户项目不会被此脚本删除——管理员仍然可以看到这些项目,并且由于 P1 会将其 设为私有,其他租户无法看到这些项目。数据导出或迁移完成后,通过 api/projects/delete 删除这些项目。

故障排除

症状可能原因修复
ensure-tenant 在预检阶段因 403 Insufficient privileges 失败管理员 Connector 身份缺少 Administer System 权限(P5)。在 Administration → Security → Global Permissions 中向管理员用户授予 admin,然后重新运行。
users/create 返回 HTTP 400,响应正文提示用户管理已被委托(SCIM / GitHub / GitLab)Enterprise 预配集成接管了用户生命周期管理,因此阻止创建本地用户。请参见必须允许创建本地用户。
租户令牌在扫描时被拒绝(401 Unauthorized)SonarQube 侧的令牌已撤销,或租户 Secret 已轮换为过期值。重新运行 TaskRun——它会生成新令牌并重写 Secret。
apply-kubernetes-resources 因 Forbidden: User "...": connectors.alauda.io "..." is forbidden 失败TaskRun ServiceAccount 缺少对目标命名空间中 Connector / Secret 的 RBAC 权限。调整每个租户命名空间中的 Role / RoleBinding(参见 Kubernetes RBAC)——最常见的情况是从未创建该命名空间的 Role。
同级租户可以读取此租户的项目Default Template P3 授予了过于宽泛的权限;或者两个租户选择了重叠的 projectPattern。审计 Default Template(P3);选择不重叠的模式;为当前租户重新运行 Task。
Task 成功,但 Connector 保持为 Ready=False 并出现身份验证错误SonarQube 地址不匹配、Secret 中的 token 为空或错误,或者 connectors-proxy 无法访问该地址。验证:(1) Connector 的 address 与 Task 访问的 SonarQube 匹配(即 sonarqubeUrl 参数或 workspace 值);(2) Secret 的 token 键不为空;(3) 租户命名空间中的 connectors-proxy 可以向该地址发起出口连接。

对于 Task 运行后出现的 connector-class 侧错误,请参阅 SonarQube Connector 故障排除指南。

另请参阅

  • Task 参考 — 参数、工作区、结果和步骤详细信息。
  • SonarQube ConnectorClass — Task 写入集群的 Connector 模型。
  • 快速入门 — 不使用 Task 的手动入驻方式,适用于一次性的 SonarQube 集成。