使用 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 前置条件Kubernetes RBAC必须允许创建 local user接入流程1. 验证 admin Connector2. 选择 tenant 的 project key pattern3. 应用 onboarding TaskRun4. 对 tenant token 做 smoke test轮换多 tenant onboardingTenant 下线故障排查另请参阅开始之前
Cluster 前置条件
- 已安装 Tekton Pipelines。请参见 Tekton Pipelines installation guide。
- 已安装 Connectors system 和 SonarQube ConnectorClass — connectors-operator 会通过
ConnectorsConfig处理二者。请参见 Connectors Installation Guide,并确保在ConnectorsConfig中启用了ConnectorsSonarQube。 sonarqube-connector-automatic-creationTask 已安装在你将运行 TaskRun 的 namespace 中。有关 apply recipe,请参见 Task reference 中的 Installation。- cluster 可以访问默认的
sonarqubeAutomationImage(或其镜像源)。
SonarQube instance 前置条件
请仅在 instance 级别配置一次这些设置,以确保 tenant 模型行为正确。这些由 SonarQube administrator 设置,而不是由 Task 设置。
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。
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 集成:
如果其中之一处于激活状态,请在接入前选择一个回退方案:
- 推荐——关闭 provisioning 集成,保留 SSO login。 SonarQube 恢复为由管理员管理 users;SSO login 集成保持不变。
- 由 IDP 预先 provision bot users。 从 IDP 预创建每个
<tenant>-bot;Task 的users/search路径会复用 IDP 已 provision 的 user,并继续执行授权 + template + token。 - 手动回退——在关闭 provisioning 的窗口内预创建。 administrator 临时禁用 provisioning,创建每个
<tenant>-botlocal 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
该 Connector 应为 Ready=True。在接入第一个 tenant 之前,还要确认 P5——admin token 必须具备全局 admin:
输出中必须出现你的 admin login。
2. 选择 tenant 的 project key pattern
projectPattern 正则表达式必须匹配所有 tenant project key,并且不能与其他 tenant 重叠。请以 tenant 前缀为锚点:
请在 tenant 目录中记录所选前缀,以便兄弟 tenant 遵守边界。
3. 应用 onboarding TaskRun
Task 会自动检测 sonarqube-config workspace 的绑定方式。请从以下模式中选择一种:
下面的示例使用 Secret-direct。该 TaskRun 假定在 connectors-management namespace 中已经预创建了 Secret admin-sonar-credentials,并且其中包含在步骤 1 中验证过的 admin token:
如果使用 Connectors CSI Driver 绑定,只需将 workspaces: 块替换为从 SonarQube sonar-scanner ConnectorClass 投影出的 CSI 配置——TaskRun 的其余部分保持不变。
执行 kubectl apply -f onboarding.yaml,然后观察 TaskRun:
成功运行后会生成以下结果:
并在 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 bravo:
这里如果返回 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。
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:
这两个 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 凭据执行:
必需的 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 仍会被删除)。
该脚本不会删除 SonarQube 上已有的 tenant 项目——administrator 仍然可以查看它们,而且(由于 P1 使其为私有)其他 tenant 无法查看。请在数据导出或迁移完成后,通过 api/projects/delete 删除这些项目。
故障排查
如果 Task 执行后出现 connector-class 侧错误,请参见 SonarQube Connector troubleshooting guide。
另请参阅
- Task reference — parameter、workspace、result 和 step 详情。
- SonarQube ConnectorClass — Task 写入 cluster 的 Connector 模型。
- Quick start — 不使用 Task 的手动 onboarding,适合一次性的 SonarQube 集成。