使用 Tekton 自动创建 Tenant SonarQube User 和 Connector

当新的 tenant 开始在 Alauda Container Platform 上运行 SonarQube 代码扫描时,administrator 必须管理该 tenant 的 SonarQube 账户和权限,在 cluster 上创建并维护该 tenant 的 sonarqube Connector 以及认证 Secret,并且在 user token 过期前持续完成轮换——对每个 tenant、在每个轮换周期都要如此。本文档通过单个 Tekton TaskRun 将整个流程自动化:运行一次即可为 tenant 完成初始化,并可按固定周期调度同一个 TaskRun,在不需要人工介入的情况下原地轮换 token。

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

开始之前

Cluster 前置条件

SonarQube instance 前置条件

请仅在 instance 级别配置一次这些设置,以确保 tenant 模型行为正确。这些由 SonarQube administrator 设置,而不是由 Task 设置。

IDSettingRequired value为什么
P1默认项目可见性Private自动创建的 tenant 项目默认必须是私有的;如果是 Public,第一次扫描时就会暴露 tenant 代码。Administration → Projects → Management → Default visibility of new projects。
P2sonar-users / Anyone 上的全局权限未授予 Execute Analysis如果全局授予 Execute Analysis,任何 tenant 都可以扫描到同级 tenant 的 key namespace 并在其中自动创建项目,从而绕过按 tenant 划分的 projectPattern。请在 Administration → Security → Global Permissions 下审计。
P3默认 permission template不向 sonar-users / Anyone 授予项目级权限Default Template 中的全局授予会泄漏到同级项目,无论 tenant template 如何设置。Administration → Security → Permission Templates → Default Template。
P4默认 quality gate + quality profile设置为组织基线自动创建的项目会继承 instance 默认值。请在 Quality Gates 和 Quality Profiles 下设置。
P5Admin Connector 的 user持有 Administer SystemTask 会先检查这一点——如果没有该权限,针对 users/create、permissions/add_user 和 permission_templates/* 的 API 调用都会以 403 Insufficient privileges 失败。可通过 GET /api/permissions/users?permission=admin 验证。

Task 只强制要求 P5。P1–P4 是 tenant 隔离加固措施:即使不配置,Task 也能成功执行,但 tenant 之间的边界会变弱。请在接入第一个 tenant 之前完成审计。

Kubernetes RBAC

TaskRun 的 ServiceAccount 需要在每个 tenant namespace 中对 Secret 和 Connector 具备 get/create/patch/update/delete 权限。推荐的做法是为每个 tenant namespace 单独配置一个 Role——在多个 tenant 之间共享 ClusterRole 会移除边界,使配置错误的 tenant TaskRun 可能写入兄弟 namespace。

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 使用 field manager connector-auto 进行 Server-Side Apply,因此当当前 spec 已经匹配时,重复运行不会产生实际变更。

跨 cluster 变体。 当 tenant Connector + Secret 位于不同的 cluster 上时,请在 TaskRun 执行时绑定 kubeconfig workspace;kubeconfig 中嵌入的身份会替代此 cluster 侧 RBAC。

必须允许创建 local user

Task 通过 POST /api/users/create local=true 为 tenant provision bot user。目标 instance 必须允许该调用。这里没有预检查——当 local user creation 被禁用时,失败会在 Task 第一次尝试创建 user 时显现,返回 HTTP 400,并在 body 中说明 user management 已被委派。

SonarQube Community 不包含下面这些机制,而且纯 SSO login(SAML / OIDC / GitHub-as-login / GitLab-as-login,不带 provisioning)不会触发这一限制。已知的阻碍来自以下 SonarQube Enterprise / Data Center provisioning 集成:

机制所在位置错误 body 大致内容
SCIM provisioningAdministration → General → SCIM(需要 SAML)User management is delegated to your SCIM provider
GitHub provisioningAdministration → Authentication → GitHub → ProvisioningUser management is delegated to your GitHub organization
GitLab provisioningAdministration → Authentication → GitLab → ProvisioningUser management is delegated to your GitLab instance

如果其中之一处于激活状态,请在接入前选择一个回退方案:

  1. 推荐——关闭 provisioning 集成,保留 SSO login。 SonarQube 恢复为由管理员管理 users;SSO login 集成保持不变。
  2. 由 IDP 预先 provision bot users。 从 IDP 预创建每个 <tenant>-bot;Task 的 users/search 路径会复用 IDP 已 provision 的 user,并继续执行授权 + template + token。
  3. 手动回退——在关闭 provisioning 的窗口内预创建。 administrator 临时禁用 provisioning,创建每个 <tenant>-bot local user,然后重新启用 provisioning 并运行 Task。

在这三种情况下,permission template + provisioning 授权 + token mint 仍会自动执行。

接入流程

下面的流程会将 tenant acme provision 到位于 admin Connector connectors-management/admin-sonar 后面的 SonarQube instance。它会在 acme-prod 中创建 acme-sonarqube 作为 tenant 的 sonarqube Connector。

1. 验证 admin Connector

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

该 Connector 应为 Ready=True。在接入第一个 tenant 之前,还要确认 P5——admin token 必须具备全局 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'

输出中必须出现你的 admin login。

2. 选择 tenant 的 project key pattern

projectPattern 正则表达式必须匹配所有 tenant project key,并且不能与其他 tenant 重叠。请以 tenant 前缀为锚点:

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

请在 tenant 目录中记录所选前缀,以便兄弟 tenant 遵守边界。

3. 应用 onboarding TaskRun

Task 会自动检测 sonarqube-config workspace 的绑定方式。请从以下模式中选择一种:

模式适用场景方式
Connectors CSI Driver(推荐)与 admin Connector 同一个 cluster,day-2 onboarding绑定到由 Connectors CSI Driver 从 SonarQube sonar-scanner ConnectorClass 配置投影出来的 volume。admin token 不会进入 Task pod——Connectors Proxy 会在每次 API 调用时注入它。
Secret-directbootstrap、跨 cluster,或无法使用 CSI driver预先创建一个包含 token(或 username + password)的 Secret,并通过 sonarqubeUrl 参数传入 SonarQube base URL。通过调整参数,同一个 Secret 可以面向多个 SonarQube instance。

下面的示例使用 Secret-direct。该 TaskRun 假定在 connectors-management namespace 中已经预创建了 Secret admin-sonar-credentials,并且其中包含在步骤 1 中验证过的 admin 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 中留下以下 cluster 对象:

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

4. 对 tenant token 做 smoke test

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[]'

负向检查——假装自己是 tenant 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 检查被绕过了——请重新确认 permission template 的 pattern 与你在 projectPattern 中设置的内容一致。

在验证完可见性以及跨 tenant 拒绝后,请删除 smoke-test project(api/projects/delete)。

轮换

该 Task 是幂等的:使用相同参数重新运行时,会复用 tenant user、template 和 provisioning 授权;当 token 仍被 SonarQube 跟踪且 tenant Secret 中持有非空 token 时,会复用该 token。最简单的轮换方式是在 cron 上重新运行同一个 TaskRun——但有一个细节(见下文),即 Task 何时实际 mint 新 token。

cron 执行时的状态Task 行为
user_tokens/search 找到了 token 且 Secret 中有非空 token。复用——不会写入 SonarQube,也不会重写 Secret。
user_tokens/search 未命中(token 被撤销 / 在该 Secret 生命周期内从未 mint)。mint——生成新的 token,expirationDate = today UTC + tokenDuration;使用 SSA 重写 Secret。
tenant Secret 在外部被删除。mint——同上。
自上次运行以来 tokenDuration 或 tokenName 已更改。revoke + mint——影响身份的输入变更会强制重新发放。
permission template / user 丢失(被 operator 删除)。recreate——与全新接入时相同。

Task 不会检查 expirationDate。SonarQube 没有 token-renew API;如果某个 token 仍存在于 user_tokens/search 中,但已经过期,Task 会将其视为复用,而过期问题会在扫描时以 401 的形式暴露。operator 需要决定如何弥补这一点:

  • 按时间轮换(推荐)。 以短于 tokenDuration 的周期运行 TaskRun(例如 tokenDuration=30 时每 15 天一次),并在每次运行前删除 tenant Secret。Task 的下一次运行会发现 Secret 为空,mint 一个新的、有效期为 tokenDuration 天的 token,并重写 Secret。线上 token 始终至少还剩 ≥ tokenDuration/2 天。
  • 惰性轮换。 按 tokenDuration/2 的周期调度 TaskRun,不做其他操作。Task 会复用该 token,直到 SonarQube 在 expirationDate 上撤销它;随后下一次扫描时的 401 会在下一个 cron tick 后得到新的 token。简单,但会留下一个短暂的 401 窗口。
  • 无需 cron——在出现 401 时手动轮换。 仅当 operator 在扫描时收到 401 后才重新运行 Task。适合低吞吐 tenant。

具体的 cron 编排方式(Tekton-on-cron controller、TriggerSchedule,或通过 CronJob 执行 kubectl create 创建 TaskRun)由 operator 自行决定;Task 的契约仅为:“删除 tenant Secret 后,使用相同参数重新运行我”。

多 tenant onboarding

通过应用第二个 TaskRun,并使用一个不重叠的 projectPattern,即可接入第二个 tenant bravo:

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

这两个 tenant 的 permission template 不会重叠,因此:

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

只有在启用了 P3 时,跨 tenant 拒绝才成立——也就是说,Default Template 不能在 sonar-users 或 Anyone 上授予任何项目级权限。否则,不论 per-tenant template 如何配置,默认 group 的授权都会泄漏到每个自动创建的项目中。在将跨 tenant 拒绝视为安全边界之前,请先审计 Default Template。

请维护 tenant 目录(project pattern + connector ref),以避免后续 tenant 选择重叠的 pattern。Task 本身不会强制检查是否重叠。

Tenant 下线

当某个 tenant 被停用时,请按相反顺序撤销 Task 创建的内容——先撤销 SonarQube 侧的工件(token、permission template、provisioning 授权、bot user),再删除 cluster 侧的 Connector + Secret。这个顺序可以关闭“Connector 已删除但 tenant token 仍然有效”的窗口。所有调用都是幂等的:来自 SonarQube 的 404 和缺失的 Kubernetes object 都会被视为已不存在,因此部分执行或中止的操作可以在重新运行时自愈。

将下面的脚本保存为 sonarqube-tenant-offboard.sh,并使用 tenant + admin 凭据执行:

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

必需的 env vars:TENANT、CONNECTOR_REF(格式为 namespace/name,与 Task 的 connector 参数传入值一致)、SONAR(SonarQube base URL)、ADMIN_TOKEN(来自持有 Administer System 的 user 的 SonarQube user token —— 见 P5;传入时不要带末尾冒号,脚本会在内部为 curl Basic auth 自动补上)。脚本会先对 /api/users/current 执行 preflight;当 token 持有者缺少全局 admin 权限时会拒绝继续,因此配置错误的 token 会快速失败,而不会在 SonarQube 清理过程进行到一半时才暴露问题。

可选覆盖项:USERNAME(默认值为 <tenant>-bot)、TEMPLATE(默认值为 <tenant>-template)、以及 DEACTIVATE_USER(默认值为 true;如设置为 false,可保留 SonarQube user 以便后续重新激活——但 template 和 token 仍会被删除)。

#!/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 上已有的 tenant 项目——administrator 仍然可以查看它们,而且(由于 P1 使其为私有)其他 tenant 无法查看。请在数据导出或迁移完成后,通过 api/projects/delete 删除这些项目。

故障排查

症状可能原因解决方法
ensure-tenant 在 preflight 阶段失败并返回 403 Insufficient privilegesAdmin Connector 身份缺少 Administer System(P5)。在 Administration → Security → Global Permissions 中为 admin user 授予 admin,然后重新运行。
users/create 返回 HTTP 400,body 中提到 user management 被委派(SCIM / GitHub / GitLab)某个 Enterprise provisioning 集成拥有 user 生命周期管理权限,并阻止了 local user creation。参见 必须允许创建 local user。
tenant token 在扫描时被拒绝(401 Unauthorized)token 在 SonarQube 侧被撤销,或者 tenant Secret 已轮换为过期值。重新运行 TaskRun——它会 mint 新 token 并重写 Secret。
apply-kubernetes-resources 失败并报 Forbidden: User "...": connectors.alauda.io "..." is forbiddenTaskRun ServiceAccount 缺少目标 namespace 中 Connector / Secret 的 RBAC。调整 per-tenant-namespace Role / RoleBinding(参见 Kubernetes RBAC)——最常见的情况是该 namespace 的 Role 从未创建。
兄弟 tenant 可以读取此 tenant 的项目Default Template P3 授予了全局权限;或者两个 tenant 选择了重叠的 projectPattern。审计 Default Template(P3);选择不重叠的 pattern;然后为当前 tenant 重新运行 Task。
Task 成功但 Connector 仍保持 Ready=False 并出现认证错误SonarQube 地址不匹配、Secret 中的 token 为空或错误,或者 connectors-proxy 无法访问该地址。验证:(1) Connector 的 address 与 Task 实际访问的 SonarQube 一致(sonarqubeUrl 参数或 workspace 值);(2) Secret 的 token 键非空;(3) tenant namespace 中的 connectors-proxy 可以访问该地址。

如果 Task 执行后出现 connector-class 侧错误,请参见 SonarQube Connector troubleshooting guide。

另请参阅