使用 Tekton 自动创建并协调 JFrog Connector 资源
在 Alauda Container Platform 中创建新租户、项目或命名空间时,管理员通常需要重复执行相同的 JFrog Artifactory 接入步骤:
- 创建一个或多个 Artifactory 仓库,或为现有共享仓库附加访问权限。
- 创建一个范围受限的 Artifactory 身份,使其只能从指定仓库读取,并向这些仓库发布内容。
- 在 Kubernetes 中创建 Connector 身份验证 Secret 和 JFrog Connector。
- 将凭证复制到项目命名空间中作为镜像拉取 Secret,以便 Pod 从 Docker 仓库拉取镜像。
仓库集合和授予的操作权限会随着时间推移而变化:项目可能会新增仓库、移除旧仓库,或扩大和缩小范围受限身份可执行的操作。重新运行相同的自动化流程即可处理这些范围变更。凭证轮换是一个独立的、由安全因素驱动的周期:访问令牌具有有限的有效期,应在过期前替换,或在发生安全事件后立即替换,即使仓库集合没有任何变化。
本指南重点介绍这一运维问题。其机制是 jfrog-connector-automatic-creation Tekton Task。运行一次即可完成配置,重新运行即可协调仓库集合和授予的操作权限,再次运行则可续期或轮换令牌。
目录
此方法解决的问题开始之前先决条件安全注意事项场景索引准备凭证和工作区jfrog-secret 的 Artifactory 凭证为 jfrog-secret 使用 JFrog Connector(推荐)为 jfrog-secret 使用 basic-auth Secret(替代方式)kube-config 的 Kubernetes 凭证为应用凭证授予 Kubernetes RBAC为 kube-config 使用 Kubernetes Secret为 kube-config 使用 Kubernetes ConnectorTask 如何解决该问题仓库生命周期:provision 与 referenceTask 写入 Kubernetes 的内容jfrogRepositories Schema权限示例:配置项目专用仓库示例:向现有共享仓库授予访问权限示例:混合配置与引用重新运行以更改范围或续期凭证验证结果身份名称故障排除This REST API is available only in Artifactory Pro不存在 reference: 条目provision: 条目存在,但包类型不同运行在向 Kubernetes 写入任何内容之前失败镜像拉取 Secret 对 kubelet 有效,但在控制台中显示凭证为空成功运行后 Pod 仍然无法拉取镜像Artifactory 返回 401 或 403每次运行都会重新创建令牌此方法解决的问题
当你需要为 Alauda Container Platform 租户和命名空间自动化 Artifactory 接入及凭证生命周期管理时,可以使用此方法。
常见场景包括:
- 项目级 Artifactory 仓库:创建 Alauda Container Platform 项目所需的仓库以及一个范围受限的身份,然后在项目命名空间中实例化 Connector 和 Secret。
- 混合配置与引用:配置项目私有仓库,并在同一次运行中,将同一身份附加到 Artifactory 中已存在的共享仓库。
- 仅引用:完全跳过配置,仅将范围受限的身份附加到现有仓库,适用于通过其他渠道管理仓库的情况。
- 从 Artifactory 拉取镜像:在工作负载命名空间中生成
kubernetes.io/dockerconfigjsonSecret,并将其追加到 ServiceAccount,以便 Pod 从 Docker 仓库拉取镜像,而无需为每个工作负载单独处理凭证。 - 令牌续期和轮换:重新运行相同的自动化流程,以续期即将过期的令牌,或轮换必须立即停止工作的令牌。
开始之前
先决条件
- Tekton Pipelines 已安装。
- Connectors 系统和 JFrog Connector 组件已安装。当你通过 Kubernetes Connector 提供
kube-config工作区时,还需要 Kubernetes Connector 组件 — 参见使用 Kubernetes Connector 提供kube-config。 jfrog-connector-automatic-creationTask 已安装在你将运行 TaskRun 的命名空间中。- 集群可以访问 Task 运行时镜像。
jfrogCliImage参数默认为此 Task 发布的镜像;将其镜像到你自己的 registry 时,请针对每个 TaskRun 覆盖该参数(对于将工具镜像固定到摘要的隔离网络集群,还应考虑使用imagePullPolicy: IfNotPresent)。该镜像必须是jfrog-connector-automatic-creation镜像,或携带 Task 辅助脚本的衍生镜像 — 通用的kubectl镜像无法正常工作。 - TaskRun ServiceAccount 可以访问目标 Kubernetes apiserver,以应用生成的 Connector 和 Secret。每当
kube-config工作区为未绑定状态时,都必须满足此条件 — 这是默认状态,也是以下所有示例使用的状态。如果资源属于其他集群,请改为绑定kube-config。 - Artifactory 为 Pro 或更高版本。此 Task 驱动的仓库、组、用户和权限目标 API 都是 Pro 功能;在 OSS 上,这些 API 会返回
400 This REST API is available only in Artifactory Pro,且没有试用宽限期。
安全注意事项
- 将特权 Artifactory 凭证、Kubernetes 凭证和 TaskRun 本身保存在私有管理命名空间中。
- 限制可以触发 TaskRun 的人员:此操作可以替换访问令牌,并覆盖项目命名空间中的 Connector Secret。
- 优先将
jfrog-secret绑定到 JFrog Connector,而不是普通 Secret,这样管理员凭证会保留在 Connectors 代理中,不会进入 Pod。
场景索引
准备凭证和工作区
此 Task 使用两个工作区:
jfrog-secret 的 Artifactory 凭证
此工作区提供 Artifactory 凭证,自动化程序使用它来协调仓库、组、用户和权限目标,并创建访问令牌。
该凭证必须能够:
- 创建和读取仓库(
/artifactory/api/repositories)。 - 创建和删除组(
/artifactory/api/security/groups)——轮换时会删除该组,因为其代次已被替代。 - 创建和更新作用域用户(
/artifactory/api/security/users)。此 Task 从不删除用户。 - 读取、创建和更新权限目标(
/artifactory/api/v2/security/permissions)。 - 创建作用域限定为某个组的访问令牌(
/artifactory/api/security/token)。
Artifactory administrator 满足上述所有要求。Artifactory Pro 没有更窄的内置角色,能够创建用户并创建作用域限定为其他组的令牌,因此专用自动化账户是实际可行的最小权限选择。
请注意,该凭证在此 Task 之外还能执行的操作:Artifactory administrator 可以读取和重写实例中的每个仓库、用户、组和权限,并为任意组创建令牌。请使用带有 admin access token 的专用自动化账户,而不是人工管理员的密码;将其保存在任何项目团队都无法读取的管理命名空间中,并审计其使用情况。
你可以通过以下两种方式之一提供此工作区。
为 jfrog-secret 使用 JFrog Connector(推荐)
Pod 永远看不到管理员凭证——它通过 Connectors 代理与 Artifactory 通信,代理会在发出的请求中注入真实的身份验证标头。在生产环境中,以及凭证不应被任何能够读取 TaskRun Pod 的对象读取时,优先使用此方式。
通过 Connectors CSI driver 绑定工作区:
此 Task 会检测这种绑定形式,从挂载的 .env(其中包含代理设置)读取配置,并信任挂载的 ca.crt,然后通过代理发出每个 Artifactory 请求。有关 driver 挂载的确切文件布局,请参见 Connectors CSI driver 文档。有关创建 JFrog Connector 的操作指南,请参见 JFrog Connector 快速入门。
确保 TaskRun ServiceAccount 有权使用此 Connector。
为 jfrog-secret 使用 basic-auth Secret(替代方式)
如果你已经持有 Artifactory 凭证,但尚未为其创建 Connector,这种方式简单直接。代价是凭证会挂载到 TaskRun Pod 中,而不是保留在代理之后。
--from-file=password=/dev/stdin 可避免凭证出现在 shell 历史记录中,也不会出现在运行此命令的计算机上的 ps 输出中。--from-literal=password=… 则会使凭证出现在这两处。
按如下方式绑定:
在此模式下,Task 从挂载文件中读取 username 和 password,并直接连接到 jfrogUrl 参数指定的 URL。凭证永远不会通过命令行传递:它会被写入内存卷上的 mode-600 curl 配置文件,并在请求返回后立即删除。
kube-config 的 Kubernetes 凭证
此工作区提供 Kubernetes 凭证,用于写入 Connector 身份验证 Secret、JFrog Connector 和镜像拉取 Secret。
当 kube-config 未绑定时,Task 使用 TaskRun Pod 的集群内 ServiceAccount。当资源必须应用到其他集群,或必须使用其他身份时,请绑定此工作区。
为应用凭证授予 Kubernetes RBAC
无论由哪个凭证应用资源,它都必须能够:
getConnector 命名空间以及imagePullSecrets中列出的每个命名空间。Task 会在写入任何内容前检查每个命名空间是否存在;检查失败时,整个运行都会失败。- 在 Connector 命名空间以及
imagePullSecrets中列出的每个命名空间中,get、create和patchSecret。 - 在 Connector 命名空间中,
get、create和patchJFrog Connector 资源(connectors,API 组为connectors.alauda.io)。 - 在每个
imagePullSecrets命名空间中,get和updateServiceAccount——仅当bindImagePullSecretToSA为true时需要。
Task 使用 kubectl apply 应用资源;该操作会在修补对象前读取实时对象,因此 get 和 patch 都是必需的——仅有 create 不够。
Connector 命名空间中的最小 Role:
以及在每个接收镜像拉取 Secret 的命名空间中:
命名空间的作用域是集群级别,因此存在性检查需要 ClusterRole。使用 resourceNames 将其限制在最小范围内;对于 get,该设置会生效:
没有此权限时,运行会在第一个目标处因 namespace '<name>' does not exist; this Task does not create namespaces 失败——命名空间确实存在,只是凭证无法读取它。
使用 RoleBinding 将每个 Role 绑定到管理命名空间中的 TaskRun ServiceAccount。
为 kube-config 使用 Kubernetes Secret
为 kube-config 使用 Kubernetes Connector
有关创建该 Connector 的操作指南,请参见 Kubernetes Connector 快速入门。
Task 如何解决该问题
Artifactory 没有 robot account 概念。一个有作用域的凭证实际上由四个部分组成,Task 会协调处理其中的全部部分:
该链条的两个特性决定了 Task 的行为:
- 顺序是强制性的。权限目标不能引用尚不存在的仓库或组 — Artifactory 会拒绝写入且不保存任何内容。因此,Task 会先协调处理仓库和组,并在写入任何内容之前验证每个目标。
- 权限按请求进行评估,而不是固化到令牌中。添加仓库或扩大操作权限会对已经发放的令牌立即生效。因此,更改作用域不需要新建令牌,已经分发到其他命名空间的凭证也会继续正常工作。
仓库生命周期:provision 与 reference
provision:条目不存在时会创建。已经存在的条目会保持不变 — 现有仓库通常由客户配置,从 Task 参数重写其设置反而不如保持原样。只有packageType不匹配时才会发出警告。reference:条目必须已经存在。缺少该条目会导致运行失败,且永远不会创建:否则,共享仓库名称中的拼写错误会生成一个空的占位仓库,运行显示成功,而构建却解析不到任何内容。
两个列表都可以省略,但总体上至少需要一个条目。
Task 写入 Kubernetes 的内容
涉及两种不同类型的 Secret,且只有第一种一定会写入:
不会写入其他内容。尤其是,Task 不会为构建工具提供可读取的纯用户名/密码副本:已经采用 Connector 的项目应继续通过 Connector 使用凭证 — 由 Connectors CSI driver 挂载,并由代理注入身份验证 — 而不是让凭证直接从整个集群中的 Secret 读取。
不过,请谨慎处理 imagePullSecrets,因为它是唯一的例外。dockerconfigjson Secret 是以明文形式保存的访问令牌副本,位于项目成员通常可以读取的命名空间中,并且包含你授予的所有操作 — 如果列表中包含 delete,该令牌就可以从本次运行涉及的每个仓库中删除构件。它也无法按令牌值撤销:只有运行 tokenPolicy: refresh 才能使泄露的副本失效(请参见重新运行以更改作用域或续订凭证)。请仅列出实际运行拉取这些镜像的工作负载的命名空间。除了 auth 外,该条目还包含 username 和 password,因为 ACP 控制台会渲染这些字段;kubelet 本身只读取 auth。
当 bindImagePullSecretToSA 为 true(默认值)时,每个生成的拉取 Secret 都会追加到其所在命名空间中的 serviceAccountName ServiceAccount(默认为 default)。现有条目会保留,并发针对同一 ServiceAccount 的运行会进行重试,而不会相互覆盖。
jfrogRepositories Schema
jfrogRepositories 是一个包含两个顶层列表的 YAML 字符串:
权限
permissions 参数是一个 Artifactory 操作数组,用于授予本次运行中每个仓库的权限。其默认值为 ["read"]。
delete 这一行最容易令人意外:Artifactory 将在现有路径上进行部署视为删除操作,因此 ["read", "write"] 可以创建构件,但无法替换构件。会重新推送相同镜像标签的 CI 作业还需要 delete。
这些值会原样转发;Artifactory 不识别的操作由 Artifactory 拒绝,而不是由 Task 拒绝。
示例:配置项目专用仓库
项目 A 需要一个私有 Docker 仓库和一个私有 Maven 仓库、一个可以向这两个仓库发布内容的身份,以及工作负载命名空间中的一个镜像拉取 Secret。
TaskRun 使用内置的 jfrogCliImage 默认值;仅当您将 Task 镜像镜像到自己的 registry 时才覆盖此值。
TaskRun 成功后:
project-a-docker和project-a-maven存在于 Artifactory 中。- 一个组、一个用户和一个权限目标会在两个仓库上授予
read、write、annotate和delete。 project-a/project-a-jfrog(一个 JFrog Connector)和project-a/project-a-jfrog-secret存在于 Kubernetes 中。project-a/jfrog-pull是一个dockerconfigjsonSecret,列在defaultServiceAccount 在project-a中的imagePullSecrets内。
jfrogUrl 是 Artifactory 源地址 — 不要追加 /artifactory。相同的值会成为 Connector 的 spec.address 以及生成的拉取 Secret 的 registry authority。
示例:向现有共享仓库授予访问权限
团队 B 只使用由平台团队维护的仓库。
Task 不会创建仓库。它只会将两个现有仓库关联到权限目标,并授予读取权限。如果任一仓库不存在,运行将失败并指出该仓库,而不是创建一个空的替代仓库。
示例:混合配置与引用
无论仓库的 package type 如何,一项权限目标和一个令牌都覆盖运行中的每个仓库,并且拉取 Secret 会写入两个工作负载命名空间。
重新运行以更改范围或续期凭证
Task 具有幂等性。可以基于以下两种相互独立的意图之一重新运行它。
范围更改 — 添加或移除仓库,或更改授予的操作:
- 编辑同一个 TaskRun:在
provision:/reference:下追加、移除或修改条目,或更改permissions。 - 重新应用它。由于 Artifactory 会针对每个请求评估权限,此更改会对当前已在使用的令牌生效 — 不会创建令牌,也不会重写 Secret(
token-rotated: "false")。从列表中移除仓库会撤销对该仓库的访问权限;仓库本身会保留,因此不会丢失任何构件。
令牌续期(tokenPolicy: reuse,默认值):
Task 从 Connector Secret 中读回存储的令牌,在本地解码其过期时间,并在剩余时间超过 tokenRenewBeforeDays(默认为 7)时保留该令牌。在此时间窗口内,它会创建一个新令牌并重写每个派生 Secret,同时报告 token-rotated: "true"。
tokenExpiry 接受一个时长 — 30d(默认值)、12h、1h30m;单位可以是 s、m、h、d。不带单位的数字表示秒数。
0 会请求 Artifactory 创建一个永不过期的令牌,而它返回的正是这种令牌:创建的 JWT 完全不包含 exp 声明。(在 Artifactory 6.20.4 上,expires_in=0 会返回 expires_in: 0 以及不包含 exp 的令牌,而任何正值都会生成该声明。)选择此设置前,需要权衡以下两个后果:
- 续期没有可操作的对象。对于格式正确但没有
exp的令牌,Task 会将其视为永远不在续期窗口内,因此在tokenPolicy: reuse下,该令牌会被无限期保留,重新运行也不会替换它。 - Artifactory 无法按令牌值撤销令牌(见下文的轮换),因此唯一能使永不过期令牌停止工作的方式是执行
tokenPolicy: refresh运行,将授权移出该令牌的作用范围。
建议使用有限的生命周期。同理请注意,tokenRenewBeforeDays 是以天为单位的整数:当生命周期短于一天时,续期窗口同样永远不会打开,令牌会一直复用,直到 refresh 运行将其替换。
Task 不会按计划自动重新运行。 使用 30 天默认值时,如果 Task 在其生命周期内从未重新运行,凭证就会失效。请通过类似 cron 的 Trigger,或现有的项目协调自动化来驱动它。
令牌轮换(tokenPolicy: refresh)— 当之前的凭证必须立即停止工作时:
Artifactory 无法撤销已签发的令牌;按令牌值或令牌 ID 撤销会返回成功,但令牌仍会继续工作;删除用户也无济于事,因为系统不会重新检查实时组成员关系。有效的方法是移除令牌作用域所指向的授权。因此,该组会携带一个代次后缀(<prefix>-<n>):轮换会推进到下一个代次,将权限目标重新指向该代次,创建作用域限定于该代次的令牌,并删除已被取代的代次。随后,旧令牌的作用域不再映射到任何授权,这才是真正使其停止工作的机制。
较旧的代次不会累积 — 每次轮换都会清理它们,同时也会清理由中断运行而遗留的孤立组。
验证结果
检查 TaskRun 是否成功:
检查生成的 Connector 和 Secret:
等待 Connector 就绪:
读取 Task 结果,查看具体协调了哪些内容 — 仓库列表、Artifactory 用户和组、权限目标、写入的拉取 Secret,以及是否创建了令牌:
确认拉取 Secret 已到达 ServiceAccount:
身份名称
Artifactory 用户、组前缀和权限目标都派生自 Connector 引用:connector-<connector-namespace>-<connector-name>。
Artifactory 拒绝长度超过 58 个字符的用户名。无法容纳的派生名称会折叠为 <truncated>-<8 hex digits of its sha256>;该折叠是确定性的,因此每个步骤都会重新派生出相同的身份。组前缀会在 48 个字符处折叠,以便其代次后缀仍能容纳。
通过 jfrogUser 或 jfrogGroup 显式提供的名称绝不会被重写 — 如果名称过长,系统会明确报错拒绝,因为悄悄重命名你要求使用的名称比直接失败更糟糕。
故障排除
提示:在失败的 TaskRun 上设置
verbose: "true"。Task 随后会记录解析后的计划,以及每个 Artifactory 请求的一行信息 — 方法、路径、状态和所使用的凭证。成功响应的正文绝不会被记录,并且在包含令牌的步骤中绝不会启用 shell 跟踪。失败的调用会在其终止时的错误中报告响应正文;该正文是 Artifactory JSON 错误,而不是凭证,但请像对待任何诊断输出一样谨慎处理失败运行的日志。
This REST API is available only in Artifactory Pro
目标 Artifactory 是 OSS,或者是未安装许可证的 Pro 镜像。没有任何配置可以使这些端点以其他方式可用 — 此 Task 驱动的 API 是 Pro 功能。
不存在 reference: 条目
Task 会失败并指出该仓库。请先在 Artifactory 中创建它,或者将该条目移到 provision: 下,并使用 packageType,以便由 Task 创建它。
provision: 条目存在,但包类型不同
Task 会发出警告并继续执行,同时保留现有仓库不变。请重命名该条目,或者手动在 Artifactory 中协调该仓库 — Task 会有意避免重写已存在的仓库。
运行在向 Kubernetes 写入任何内容之前失败
命名空间和资源名称会按照 DNS-1123 标签或子域进行验证,并且每个 Kubernetes 目标都会在首次写入之前完成检查。名称被拒绝会导致整个运行失败,而不会只更新一半命名空间。
此保证仅涵盖 Kubernetes 端。在 Artifactory 端,Task 会按顺序执行协调,因此中途发生的失败会保留它此前已创建的内容 — 例如,如果运行因缺少 reference: 条目而终止,则会保留片刻前创建的 provision: 仓库。修正输入后重新运行是安全的:现有仓库会被识别并保持不变。
镜像拉取 Secret 对 kubelet 有效,但在控制台中显示凭证为空
仅适用于在此 Task 之前创建的 Secret:auths 条目除了必须包含 auth 外,还必须包含 username 和 password。重新运行 Task,以使用全部三个字段重写 Secret。
成功运行后 Pod 仍然无法拉取镜像
确认 bindImagePullSecretToSA 为 true,并确认 serviceAccountName 与工作负载实际使用的 ServiceAccount 匹配 — 自行设置 serviceAccountName 的 Pod 不会继承 default。或者直接在 Pod 规范中引用拉取 Secret。
Artifactory 返回 401 或 403
jfrog-secret 上的凭证错误,或者该凭证不属于管理员。请直接向 Artifactory 验证该凭证,并记住,此 Task 需要用户、组、权限目标和令牌 API — 不仅仅是仓库读取权限。
每次运行都会重新创建令牌
tokenRenewBeforeDays 大于或等于 tokenExpiry,因此存储的令牌始终处于续期窗口内。Task 会明确对此发出警告;请提高 tokenExpiry 或降低 tokenRenewBeforeDays。