使用 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 配置到 admin Connector connectors-management/admin-sonar 后面的 SonarQube 实例中。它会创建 acme-prod/acme-sonarqube,作为租户的 sonarqube Connector。
1. 验证 admin Connector
kubectl -n connectors-management get connector admin-sonar -o yaml | grep -E 'address|tokenAuth|Ready'
Connector 应为 Ready=True。在接入第一个租户之前,还要确认 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'
输出中必须显示你的管理员登录名。
2. 选择租户项目键模式
projectPattern 正则表达式必须匹配所有租户项目键,并且不得重叠。请以租户前缀作为锚点:
在租户目录中记录所选前缀,以便同级租户遵守边界。
3. 应用接入 TaskRun
Task 会自动检测 sonarqube-config workspace 的绑定方式。请选择一种模式:
下面的示例使用 Secret 直接绑定。TaskRun 假定 connectors-management 命名空间中已预先创建 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 中留下以下集群对象:
Secret/acme-sonarqube-secret(类型为 connectors.cpaas.io/bearer-token)
Connector/acme-sonarqube(Ready=True,指向上述 Secret)
4. 对租户 token 执行冒烟测试
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 具有幂等性。Token 则不同:每次成功运行都会撤销现有 token(如果存在)、铸造新 token,并重写租户 Secret 和 Connector。不要为同一租户运行重叠的 TaskRun,因为后一次运行会使前一次运行写入的 token 失效。
按所需的轮换间隔调度 TaskRun(例如,每 15 天为 tokenDuration=30 运行一次)。不要先删除租户 Secret;Task 会撤销旧 token,并使用新 token 原子地重写 Secret。在 Secret 更新期间运行的扫描可能会短暂失败,因此请在必要时协调轮换与工作负载的调度。
确切的 cron 配置方式(Tekton-on-cron controller、TriggerSchedule,或对 TaskRun 执行 kubectl create 的 CronJob)取决于 operator;Task 的契约仅是“使用相同参数重新运行我”。
多租户接入
通过应用第二个 TaskRun 为第二个租户 bravo 接入,并使用不重叠的 projectPattern:
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 ref),以确保未来的租户不会选择重叠的模式。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 故障排除指南。
另请参阅