使用 Tekton 自动创建租户 SonarQube 用户和 Connector
当新租户开始在 Alauda
Container Platform 上运行 SonarQube 代码扫描时,管理员必须管理租户的
SonarQube 账户和权限,在集群上创建并维护租户的
sonarqube Connector 和认证 Secret,并在用户令牌过期前完成轮换——
每个租户、每个轮换周期都需要执行这些操作。本指南使用单个
Tekton TaskRun 自动完成整个流程:运行一次即可预配租户,并按固定周期
调度同一 TaskRun,以便原地轮换令牌,无需人工干预。
其实现机制是
sonarqube-connector-automatic-creation Task。
本页面重点介绍 operator 工作流。有关参数、
workspace、result 和 step 的参考信息,请参阅
Task 参考。
开始之前
集群前提条件
SonarQube 实例前提条件
在实例级别一次性配置以下设置,以确保租户模型正常运行。这些设置由 SonarQube 管理员配置,而不是由 Task 配置。
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
中的预配集成:
如果其中一项已启用,请在接入前选择一种备用方案:
- 推荐——关闭预配集成,保留 SSO
登录。 SonarQube 会恢复为由管理员管理用户;SSO 登录
集成保持不变。
- 让 IDP 预配 bot 用户。 通过 IDP 预先配置每个
<tenant>-bot;Task 的 users/search 路径会复用
IDP 预配的用户,并继续执行授权 + 模板 + 令牌流程。
- 手动备用方案——在预配关闭的时间窗口内预先创建。
管理员暂时禁用预配,创建每个
<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 正则表达式必须匹配所有租户项目键,并且不得与其他租户重叠。请以租户前缀作为锚点:
在租户目录中记录所选前缀,以便同级租户遵守边界。
3. 应用接入 TaskRun
Task 会自动检测 sonarqube-config 工作区的绑定方式。请选择一种模式:
以下示例使用直接 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 会使前一个运行写入的令牌失效。
按所需的轮换间隔调度 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 删除这些项目。
故障排除
对于 Task 运行后出现的 connector-class 侧错误,请参阅
SonarQube Connector 故障排除指南。
另请参阅