使用 Tekton 自动创建并协调 JFrog Connector 资源

在 Alauda Container Platform 中创建新租户、项目或命名空间时,管理员通常需要重复执行相同的 JFrog Artifactory 接入步骤:

  • 创建一个或多个 Artifactory 仓库,或为现有共享仓库附加访问权限。
  • 创建一个范围受限的 Artifactory 身份,使其只能从指定仓库读取,并向这些仓库发布内容。
  • 在 Kubernetes 中创建 Connector 身份验证 Secret 和 JFrog Connector。
  • 将凭证复制到项目命名空间中作为镜像拉取 Secret,以便 Pod 从 Docker 仓库拉取镜像。

仓库集合和授予的操作权限会随着时间推移而变化:项目可能会新增仓库、移除旧仓库,或扩大和缩小范围受限身份可执行的操作。重新运行相同的自动化流程即可处理这些范围变更。凭证轮换是一个独立的、由安全因素驱动的周期:访问令牌具有有限的有效期,应在过期前替换,或在发生安全事件后立即替换,即使仓库集合没有任何变化。

本指南重点介绍这一运维问题。其机制是 jfrog-connector-automatic-creation Tekton Task。运行一次即可完成配置,重新运行即可协调仓库集合和授予的操作权限,再次运行则可续期或轮换令牌。

此方法解决的问题

当你需要为 Alauda Container Platform 租户和命名空间自动化 Artifactory 接入及凭证生命周期管理时,可以使用此方法。

常见场景包括:

  • 项目级 Artifactory 仓库:创建 Alauda Container Platform 项目所需的仓库以及一个范围受限的身份,然后在项目命名空间中实例化 Connector 和 Secret。
  • 混合配置与引用:配置项目私有仓库,并在同一次运行中,将同一身份附加到 Artifactory 中已存在的共享仓库。
  • 仅引用:完全跳过配置,仅将范围受限的身份附加到现有仓库,适用于通过其他渠道管理仓库的情况。
  • 从 Artifactory 拉取镜像:在工作负载命名空间中生成 kubernetes.io/dockerconfigjson Secret,并将其追加到 ServiceAccount,以便 Pod 从 Docker 仓库拉取镜像,而无需为每个工作负载单独处理凭证。
  • 令牌续期和轮换:重新运行相同的自动化流程,以续期即将过期的令牌,或轮换必须立即停止工作的令牌。

开始之前

先决条件

  • Tekton Pipelines 已安装。
  • Connectors 系统和 JFrog Connector 组件已安装。当你通过 Kubernetes Connector 提供 kube-config 工作区时,还需要 Kubernetes Connector 组件 — 参见使用 Kubernetes Connector 提供 kube-config。
  • jfrog-connector-automatic-creation Task 已安装在你将运行 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。

场景索引

场景实际示例从以下内容开始
仅配置 — 一个项目及其专属仓库“项目 A 需要一个私有 Docker 仓库和一个私有 Maven 仓库,以及一个供其 CI 发布内容使用的身份。”示例:配置项目私有仓库
仅引用 — 仓库已存在“团队 B 从平台团队维护的共享仓库解析依赖项;这些仓库不归我们所有。”示例:为现有共享仓库附加访问权限
混合 — 私有仓库和共享上游仓库“项目 A 将内容发布到自己的仓库,同时从共享 Maven 虚拟仓库读取内容。”示例:混合配置与引用
在多个命名空间中从 Artifactory 拉取镜像“三个命名空间运行的工作负载所使用的镜像位于项目的 Docker 仓库中。”示例:混合配置与引用(其中的 imagePullSecrets 已涵盖两个命名空间)

准备凭证和工作区

此 Task 使用两个工作区:

工作区必需用途预期内容
jfrog-secret是用于所有 Artifactory 端操作的 Artifactory 凭证。Basic-auth Secret(username + password 文件),或通过 Connectors CSI driver 挂载的 JFrog Connector。
kube-config否用于所有 Kubernetes 端操作的 kubeconfig。未绑定时使用集群内 ServiceAccount。kubeconfig

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 的对象读取时,优先使用此方式。

apiVersion: v1
kind: Secret
metadata:
  name: jfrog-provisioner-auth
  namespace: <management-namespace>
type: kubernetes.io/basic-auth
stringData:
  username: <artifactory-admin-username>
  password: <artifactory-admin-password-or-token>
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: jfrog-provisioner
  namespace: <management-namespace>
spec:
  connectorClassName: jfrog
  address: <your-artifactory-address>  # e.g. https://jfrog.example.com
  auth:
    name: basicAuth
    secretRef:
      name: jfrog-provisioner-auth

通过 Connectors CSI driver 绑定工作区:

workspaces:
  - name: jfrog-secret
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connectors: <management-namespace>/jfrog-provisioner

此 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 中,而不是保留在代理之后。

read -rs -p 'Artifactory admin password or token: ' JFROG_PASSWORD

printf '%s' "$JFROG_PASSWORD" | kubectl create secret generic jfrog-provisioner-auth \
  -n <management-namespace> \
  --type=kubernetes.io/basic-auth \
  --from-literal=username=<artifactory-admin-username> \
  --from-file=password=/dev/stdin \
  --dry-run=client -o yaml | kubectl apply -f -

unset JFROG_PASSWORD

--from-file=password=/dev/stdin 可避免凭证出现在 shell 历史记录中,也不会出现在运行此命令的计算机上的 ps 输出中。--from-literal=password=… 则会使凭证出现在这两处。

按如下方式绑定:

workspaces:
  - name: jfrog-secret
    secret:
      secretName: jfrog-provisioner-auth

在此模式下,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

无论由哪个凭证应用资源,它都必须能够:

  • get Connector 命名空间以及 imagePullSecrets 中列出的每个命名空间。Task 会在写入任何内容前检查每个命名空间是否存在;检查失败时,整个运行都会失败。
  • 在 Connector 命名空间以及 imagePullSecrets 中列出的每个命名空间中,get、create 和 patch Secret。
  • 在 Connector 命名空间中,get、create 和 patch JFrog Connector 资源(connectors,API 组为 connectors.alauda.io)。
  • 在每个 imagePullSecrets 命名空间中,get 和 update ServiceAccount——仅当 bindImagePullSecretToSA 为 true 时需要。

Task 使用 kubectl apply 应用资源;该操作会在修补对象前读取实时对象,因此 get 和 patch 都是必需的——仅有 create 不够。

Connector 命名空间中的最小 Role:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: jfrog-connector-automatic-creation
  namespace: <project-namespace>
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "patch", "create"]
  - apiGroups: ["connectors.alauda.io"]
    resources: ["connectors"]
    verbs: ["get", "patch", "create"]

以及在每个接收镜像拉取 Secret 的命名空间中:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: jfrog-connector-automatic-creation-pull
  namespace: <workload-namespace>
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "patch", "create"]
  # Only needed when bindImagePullSecretToSA is "true"
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "update"]

命名空间的作用域是集群级别,因此存在性检查需要 ClusterRole。使用 resourceNames 将其限制在最小范围内;对于 get,该设置会生效:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: jfrog-connector-automatic-creation-namespaces
rules:
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get"]
    resourceNames: ["<project-namespace>", "<workload-namespace>"]

没有此权限时,运行会在第一个目标处因 namespace '<name>' does not exist; this Task does not create namespaces 失败——命名空间确实存在,只是凭证无法读取它。

使用 RoleBinding 将每个 Role 绑定到管理命名空间中的 TaskRun ServiceAccount。

为 kube-config 使用 Kubernetes Secret

kubectl create secret generic target-kubeconfig \
  -n <management-namespace> \
  --from-file=kubeconfig=/path/to/kubeconfig \
  --dry-run=client -o yaml | kubectl apply -f -
workspaces:
  - name: kube-config
    secret:
      secretName: target-kubeconfig

为 kube-config 使用 Kubernetes Connector

workspaces:
  - name: kube-config
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connectors: <management-namespace>/<k8s-connector-name>
        configuration.names: kubeconfig

有关创建该 Connector 的操作指南,请参见 Kubernetes Connector 快速入门。

Task 如何解决该问题

Artifactory 没有 robot account 概念。一个有作用域的凭证实际上由四个部分组成,Task 会协调处理其中的全部部分:

repository ──┐
             ├── permission target ── grants actions to ── group ── contains ── user
             │                                               │
             └── access token   scope=member-of-groups:<group> ┘

该链条的两个特性决定了 Task 的行为:

  • 顺序是强制性的。权限目标不能引用尚不存在的仓库或组 — Artifactory 会拒绝写入且不保存任何内容。因此,Task 会先协调处理仓库和组,并在写入任何内容之前验证每个目标。
  • 权限按请求进行评估,而不是固化到令牌中。添加仓库或扩大操作权限会对已经发放的令牌立即生效。因此,更改作用域不需要新建令牌,已经分发到其他命名空间的凭证也会继续正常工作。

仓库生命周期:provision 与 reference

  • provision: 条目不存在时会创建。已经存在的条目会保持不变 — 现有仓库通常由客户配置,从 Task 参数重写其设置反而不如保持原样。只有 packageType 不匹配时才会发出警告。
  • reference: 条目必须已经存在。缺少该条目会导致运行失败,且永远不会创建:否则,共享仓库名称中的拼写错误会生成一个空的占位仓库,运行显示成功,而构建却解析不到任何内容。

两个列表都可以省略,但总体上至少需要一个条目。

Task 写入 Kubernetes 的内容

涉及两种不同类型的 Secret,且只有第一种一定会写入:

是否写入用途
Connector 认证 Secret(secret 参数,默认值为 <connector-name>-secret)始终写入Connector 用于进行身份验证的内容。一个包含作用域用户名和访问令牌的 kubernetes.io/basic-auth Secret。
镜像拉取 Secret(imagePullSecrets 参数)仅在列出时写入供 kubelet 使用的 kubernetes.io/dockerconfigjson 副本,以便 Pod 可以从 Docker 仓库拉取镜像。每个条目都包含 username、password 和 auth。

不会写入其他内容。尤其是,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 字符串:

provision:                        # created when absent, left untouched when present
  - name: project-a-docker
    packageType: docker           # docker | maven | npm | pypi | generic | ...
    rclass: local                 # default: local
  - name: project-a-maven
    packageType: maven
reference:                        # must already exist; only linked into the permission target
  - name: shared-maven-virtual
字段适用对象必填说明
name两者是Artifactory 仓库键。
packageTypeprovision是原样转发至 Artifactory;Artifactory 接受的任何 package type 均可使用。
rclassprovision否默认为 local。

权限

permissions 参数是一个 Artifactory 操作数组,用于授予本次运行中每个仓库的权限。其默认值为 ["read"]。

操作授予的权限
read拉取 / 解析。
write部署新构件。
annotate设置属性和元数据。
delete删除构件 — 并覆盖已经存在的构件。
manage编辑仓库自身的权限 — 持有 manage 的令牌可以在该仓库上授予自身任何其他权限,因此应将其视为权限提升路径,仅在项目确实管理自己的仓库时授予。

delete 这一行最容易令人意外:Artifactory 将在现有路径上进行部署视为删除操作,因此 ["read", "write"] 可以创建构件,但无法替换构件。会重新推送相同镜像标签的 CI 作业还需要 delete。

这些值会原样转发;Artifactory 不识别的操作由 Artifactory 拒绝,而不是由 Task 拒绝。

示例:配置项目专用仓库

项目 A 需要一个私有 Docker 仓库和一个私有 Maven 仓库、一个可以向这两个仓库发布内容的身份,以及工作负载命名空间中的一个镜像拉取 Secret。

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: project-a-jfrog-setup
  namespace: <management-namespace>
spec:
  taskRef:
    name: jfrog-connector-automatic-creation
  params:
    - name: jfrogUrl
      value: https://jfrog.example.com
    - name: connector
      value: project-a/project-a-jfrog
    - name: jfrogRepositories
      value: |
        provision:
          - name: project-a-docker
            packageType: docker
          - name: project-a-maven
            packageType: maven
    - name: permissions
      value:
        - read
        - write
        - annotate
        - delete
    - name: imagePullSecrets
      value:
        - project-a/jfrog-pull
    - name: bindImagePullSecretToSA
      value: "true"
  workspaces:
    - name: jfrog-secret
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connectors: <management-namespace>/jfrog-provisioner

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 是一个 dockerconfigjson Secret,列在 default ServiceAccount 在 project-a 中的 imagePullSecrets 内。

jfrogUrl 是 Artifactory 源地址 — 不要追加 /artifactory。相同的值会成为 Connector 的 spec.address 以及生成的拉取 Secret 的 registry authority。

示例:向现有共享仓库授予访问权限

团队 B 只使用由平台团队维护的仓库。

  params:
    - name: jfrogUrl
      value: https://jfrog.example.com
    - name: connector
      value: team-b/team-b-jfrog
    - name: jfrogRepositories
      value: |
        reference:
          - name: shared-maven-virtual
          - name: shared-npm-virtual
    - name: permissions
      value:
        - read

Task 不会创建仓库。它只会将两个现有仓库关联到权限目标,并授予读取权限。如果任一仓库不存在,运行将失败并指出该仓库,而不是创建一个空的替代仓库。

示例:混合配置与引用

  params:
    - name: jfrogUrl
      value: https://jfrog.example.com
    - name: connector
      value: project-a/project-a-jfrog
    - name: jfrogRepositories
      value: |
        provision:
          - name: project-a-docker
            packageType: docker
          - name: project-a-generic
            packageType: generic
        reference:
          - name: shared-maven-virtual
    - name: permissions
      value:
        - read
        - write
        - annotate
        - delete
    - name: imagePullSecrets
      value:
        - project-a/jfrog-pull
        - project-a-staging/jfrog-pull

无论仓库的 package type 如何,一项权限目标和一个令牌都覆盖运行中的每个仓库,并且拉取 Secret 会写入两个工作负载命名空间。

重新运行以更改范围或续期凭证

Task 具有幂等性。可以基于以下两种相互独立的意图之一重新运行它。

范围更改 — 添加或移除仓库,或更改授予的操作:

  1. 编辑同一个 TaskRun:在 provision: / reference: 下追加、移除或修改条目,或更改 permissions。
  2. 重新应用它。由于 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 是否成功:

kubectl get taskrun project-a-jfrog-setup -n <management-namespace>

检查生成的 Connector 和 Secret:

kubectl get connector project-a-jfrog -n project-a
kubectl get secret project-a-jfrog-secret -n project-a

等待 Connector 就绪:

kubectl wait --for=condition=Ready connector/project-a-jfrog \
  -n project-a --timeout=120s

读取 Task 结果,查看具体协调了哪些内容 — 仓库列表、Artifactory 用户和组、权限目标、写入的拉取 Secret,以及是否创建了令牌:

kubectl get taskrun project-a-jfrog-setup -n <management-namespace> \
  -o jsonpath='{.status.results}'

确认拉取 Secret 已到达 ServiceAccount:

kubectl get serviceaccount default -n project-a \
  -o jsonpath='{.imagePullSecrets}'

身份名称

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。