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

当在 Alauda Container Platform 中创建新的租户、项目或 namespace 时,管理员通常需要一遍又一遍地完成相同的 Nexus 上线步骤:

  • 创建一个或多个 Nexus repository,或者为现有的共享 repository 赋予访问权限。
  • 创建一个仅作用于这些 repository 的 Nexus 本地用户和角色。
  • 在 Kubernetes 中创建 Connector authentication Secret 和 Nexus Connector。

repository 集合以及授予的 action 范围会随着时间演进——项目会新增 repository、移除旧 repository,或者扩大/缩小 scoped user 被允许执行的操作。重新运行相同的自动化可以处理这些 scope 变化。Credential rotation 是一个单独的、由安全驱动的周期:即使 repository 集合和 action scope 没有变化,scoped Nexus user 密码也应定期轮换(或在事件响应后轮换),以避免在下游消费者中积累长期有效的凭证。Task 会从同一个 TaskRun 驱动这两种流程,但二者的意图是彼此独立的。

本指南聚焦于这一运维问题。这里使用的实现机制是 nexus-connector-automatic-creation Tekton Task。你可以先运行一次用于初始预配,之后再次运行以协调 repository 配置和 scope,也可以按计划定期运行以轮换 scoped user 密码。

解决什么问题

当你需要为 Alauda Container Platform 的租户和 namespace 自动化 Nexus 上线和 credential 刷新时,可以使用此方法。

常见场景包括:

  • 项目级 Nexus repository:为一个 Alauda Container Platform 项目创建一个或多个 Nexus repository(hosted、proxy 或 group),以及一个 scoped user,然后在项目 namespace 中生成 Connector 和 Secret。
  • 混合预配与引用:在预配项目私有 repository 的同时,将同一个 scoped user 关联到 Nexus 中已存在的共享上游 repository(例如内置的 maven-central proxy)。
  • 仅引用:完全跳过预配,仅将 scoped user 关联到现有 repository,适用于 repository 由其他渠道管理的情况。
  • Credential 刷新与协调:重新运行相同的自动化以更新 repository 配置、刷新 Nexus user 密码,并更新生成的 Connector Secret。

本指南旨在解决 Nexus 初始化和 credential 生命周期问题。Tekton Task 是实现该工作流所使用的方案。

开始之前

前提条件

  • 已安装 Tekton Pipelines。
  • 已安装 Connectors system、Nexus Connector 组件和 Kubernetes Connector 组件。(当你通过 Kubernetes Connector 提供 kube-config workspace 时需要 Kubernetes Connector——参见 为 kube-config 使用 Kubernetes Connector。)
  • 已在你将运行 TaskRun 的 namespace 中安装 nexus-connector-automatic-creation Task。
  • Task 使用的 Nexus runtime image 可以从你的内部 registry 获取。
  • (可选)TaskRun ServiceAccount 能够访问目标 Kubernetes apiserver,以便应用生成的 Connector 和 Secret。只有在 kube-config workspace 未绑定,并且 Task 回退到集群内 ServiceAccount 时才需要这一点。当你将 kube-config workspace 绑定到指向 kubeconfig 风格凭证的 Kubernetes Connector 时,Task 会通过该 Connector 访问目标集群,而 TaskRun ServiceAccount 不需要在本地集群上拥有 apiserver 权限。

安全注意事项

  • 使用私有管理 namespace 存放特权 Nexus credential、Kubernetes credential 以及执行预配或 credential 刷新的 TaskRun。
  • 限制谁可以触发 TaskRun,因为该操作可能会轮换 scoped Nexus user 密码并覆盖 Connector Secret。
  • 如果需要严格部署,请在运行此 Task 之前,在 Nexus 控制台中禁用 Nexus anonymous access(Settings → Security → Anonymous Access)。当 anonymous access 已启用时,Task 仅会发出警告;它不会更改集群级别的 Nexus 配置。

兼容性

已在 Nexus Repository Manager 3.76 OSS 上测试。

其他 Nexus 3.x 版本可能可用,但未包含在测试套件覆盖范围内。

场景索引

使用下表为你的情况选择合适的起始示例:

场景真实世界示例从这里开始
仅预配 — 一个项目,一个或多个专用 Nexus repo“Project A 需要一个专属的私有 Maven hosted repo 和一个 scoped user,以便其 CI 可以发布 release artifact,而不影响共享基础设施。”示例:预配项目私有 Nexus Repository
仅引用 — repo 已存在;只需关联 scoped user“Team B 的 CI 需要从平台团队维护的现有共享 maven-public 和 npm-public proxy 中解析依赖;这些 repo 不由我们拥有。”示例:为现有共享 repository 赋予访问权限
混合 — 预配少量私有 repo,并引用共享上游“Project A 需要自己的私有 Maven hosted + proxy + group repo 用于内部发布,同时同一个 scoped user 还应能够从平台共享的 maven-central proxy 中读取。”示例:混合预配与引用
跨格式 — 在一个 TaskRun 中同时包含 Maven + npm + raw(或任意组合)“一个多语言项目拥有一个用于 Java 服务的 Maven hosted repo,以及一个用于前端包的 npm hosted repo——二者都应一并协调。”示例:预配项目私有 Nexus Repository(通过混合格式扩展 provision[])

准备凭证和 Workspaces

该方案使用两个 workspace:

Workspace必需用途预期内容
nexus-secret是用于 Nexus 侧操作的 Nexus credential。Basic-auth Secret(username + password 文件),或通过 Connectors CSI driver 挂载的 Nexus Connector。
kube-config否用于 Kubernetes 侧操作的 kubeconfig。未绑定时使用集群内 ServiceAccount。kubeconfig

nexus-secret 的 Nexus 凭证

该 workspace 提供自动化用于创建或更新 Nexus repository、创建 scoped user 和 role,以及将标准 repository-view privilege 关联到该 role 的 Nexus credential。

此处使用的 Nexus credential 必须能够:

  • 创建和更新 Nexus repository。
  • 创建和更新 Nexus 本地用户。
  • 创建和更新 Nexus role。
  • 读取现有的 nx-repository-view-<format>-<repo>-<action> privilege,并将它们关联到一个 role。
  • 重置 Task 创建的 scoped Nexus user 的密码。

Nexus 内置的 nx-admin role 满足以上全部要求。如果你更倾向于最小权限预配,请创建一个专用的 Nexus role,并授予以下 privilege,然后将其分配给预配用户:

Privilege所需原因
nx-repository-admin-*-*-*创建、读取并更新 Task 可能预配的所有格式和类型的 repository。若预配用户只管理某些格式,可缩小这些通配符范围。
nx-userschangepw每次运行时重置 scoped Nexus user 的密码。
nx-users-create, nx-users-read, nx-users-update管理 Task 创建的 scoped Nexus user。
nx-roles-create, nx-roles-read, nx-roles-update管理 scoped Nexus role。
nx-privileges-read查找 Nexus 在创建 repository 时自动生成的 nx-repository-view-<format>-<repo>-<action> privilege。Task 只读取这些 privilege——不会创建自定义 privilege。

你可以通过以下两种方式之一提供此 workspace:

  • Basic-auth Secret — 当你已经拥有 Nexus 凭证并希望直接使用它们时,这是最直接的方式。
  • 挂载的 Nexus Connector — 推荐用于生产环境。Pod 侧的凭证保留在 Connectors proxy 中,Pod 仅能看到 proxy 环境变量。

为 nexus-secret 使用 basic-auth Secret

在管理 namespace 中创建一个 kubernetes.io/basic-auth Secret:

kubectl create secret generic nexus-provisioner-auth \
  -n <management-namespace> \
  --type=kubernetes.io/basic-auth \
  --from-literal=username=<nexus-provisioner-username> \
  --from-literal=password=<nexus-provisioner-password> \
  --dry-run=client -o yaml | kubectl apply -f -

像这样绑定它:

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

在此模式下,Task 会从挂载文件中读取 username 和 password,并直接连接到 nexusUrl Task 参数指定的 URL。

为 nexus-secret 使用 Nexus Connector

当你希望将 Nexus credential 保持在 Pod 外时,推荐使用此模式——Pod 通过 Connectors proxy 与 Nexus 通信,而 proxy 会在出站请求中注入真实的 basic-auth header。该 Connector 可以位于与 TaskRun 相同的集群中,也可以位于集群外;两种形式都是有效选择。

首先,在管理 namespace 中创建一个 Nexus Connector。该 Connector 后面的 credential 应满足上文列出的相同 Nexus 权限要求。

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

然后,通过 Connectors CSI driver 将 TaskRun 的 nexus-secret workspace 绑定到该 Connector:

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

关于 Connectors CSI driver 会挂载到 workspace 中的精确文件布局,请参见 Connectors CSI driver 文档。关于如何一步一步创建可在此挂载的 Nexus Connector,请参见 Nexus Connector 快速开始。

引用的 Connector 必须使用 connectorClassName: nexus。Task 会拒绝其他 ConnectorClass,以保持 proxy 认证路由的一致性。请确保 TaskRun ServiceAccount 被允许使用此 Nexus Connector。

kube-config 的 Kubernetes 凭证

该 workspace 提供自动化用于在 connector namespace 中创建或更新 Connector Secret 和 Nexus Connector 的 Kubernetes credential。

此处使用的 Kubernetes credential 必须能够:

  • 在 connector namespace 中创建和更新 Secret。
  • 在 connector namespace 中创建和更新 Nexus Connector 资源。

当 kube-config workspace 未绑定时,Task 使用 TaskRun Pod 的集群内 ServiceAccount。仅当你需要使用与 TaskRun ServiceAccount 不同的 kubeconfig 来应用 Connector 和 Secret 时才绑定它,例如目标是外部集群时。

授予 apply credential Kubernetes RBAC

无论你使用集群内 ServiceAccount 还是已绑定的 kubeconfig,该 credential 都必须被允许在 connector namespace 中对 Secrets 和 Nexus Connector 资源(connectors.connectors.alauda.io,group connectors.alauda.io)执行 get、create 和 patch。Task 使用 Server-Side Apply,而 apiserver 会将其授权为 patch 动作,因此仅有 create 不够。

下面是在 connector namespace 中的最小 Role + RoleBinding,绑定到 management namespace 中的 TaskRun ServiceAccount:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: nexus-connector-automatic-creation
  namespace: <project-namespace>
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "patch", "create"]
  - apiGroups: ["connectors.alauda.io"]
    resources: ["connectors"]
    verbs: ["get", "patch", "create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: nexus-connector-automatic-creation
  namespace: <project-namespace>
subjects:
  - kind: ServiceAccount
    name: <taskrun-service-account>
    namespace: <management-namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: nexus-connector-automatic-creation

当 kube-config 已绑定时,相同的权限必须由目标 namespace 和集群中该 kubeconfig 内的用户身份持有。

使用 Kubernetes Secret 作为 kube-config

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

你也可以通过 Connectors CSI driver,使用一个渲染 kubeconfig 配置的 Kubernetes Connector 提供 kube-config:

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

关于如何一步一步创建该 Kubernetes Connector,请参见 Kubernetes Connector 快速开始。背景信息: 在 Tekton Task 中使用 Kubernetes Connector 和 Kubernetes Connector。

Task 如何解决该问题

nexus-connector-automatic-creation Task 有两种用法:

  • 初始预配:创建列出的 Nexus repository,创建 scoped user 和 role,关联标准 repository-view privilege,然后在 connector namespace 中创建 Connector Secret 和 Nexus Connector。
  • 重复协调:使用相同的 Task 重新运行,传入期望的 repository 集合、格式和 actions,以刷新现有 repository 中可更新的字段,重新关联 privilege 集,轮换 scoped user 密码,并更新生成的 Secret。

Repository 生命周期:provision 与 reference

nexusRepositories 参数是一个 YAML map,包含两个顶层列表,用于显式表达生命周期意图:

  • provision: 条目由 Task 拥有。当它们不存在时,Task 会创建它们,并在每次运行时刷新可更新字段。如果某个不可变字段(例如 storage.blobStoreName、storage.writePolicy 或 maven.versionPolicy)需要在现有 repository 上发生变化,Task 会使运行失败。暴露出来的错误可能会指出具体的 diff 字段,也可能直接透传 Nexus 的原始拒绝(即使 diff 位于其他不可变字段,通常也会出现总括性消息 "You cannot change a repository's blob store through the API")——请参见 不可变字段完整列表 进行完整对照。可通过删除 Nexus repository 后重新运行,或者将该条目移到 reference: 下以便 Task 只关联 privilege 而不触碰定义来解决。
  • reference: 条目不由 Task 拥有。它们必须已经存在于 Nexus 中。Task 只会将 scoped user 的 privilege 关联到这些 repository。如果某个 reference: 条目不存在,Task 会快速失败,并提示你将其移到 provision: 下并提供 format 和 type。

两个列表都可以省略,但至少必须存在一个。

Scoped user、role 和 credential 生命周期

对于每个 TaskRun,Task 会在 Nexus 内确保存在一个 role 和一个 user:

  • role 默认命名为 <connector-namespace>-<connector-name>-role,并由 Task 拥有。重新运行 Task 时,总会刷新 role 的 privilege 列表,以匹配当前的 nexusRepositories 和 actions。
  • user 默认命名为 connector-<connector-namespace>-<connector-name>,或者在设置了 nexusUser 时使用其值。每次成功运行都会轮换该用户的密码,并将其写入生成的 Connector Secret。运行结束后,旧密码将失效。

如果你使用相同的 nexusRepositories 和 actions 重新运行 Task,则 role 上的 privilege 集合不会变化,但用户密码仍会轮换。可利用此行为按计划刷新 Connector Secret,或在 Nexus user 事件后刷新。

有关完整参数参考和精确的 Task 定义,请参见 nexus-connector-automatic-creation Task 参考。

nexusRepositories 结构

nexusRepositories Task 参数包含一个单一 YAML 字符串,其中有两个顶层列表:

provision:           # repos this Task creates and idempotently manages
  - name: ...
    format: ...
    type: ...
    # type-specific subfields go here
reference:           # repos that already exist (Task only attaches privileges)
  - name: ...
    actions: [...]   # optional; narrows the granted privilege subset

两个列表都可以省略,但至少必须存在一个。除 provision: 和 reference: 之外的顶层键都会被拒绝,因此像 provison: 或 references: 这样的拼写错误会在前置阶段被捕获。

provision: 条目

provision: 条目与 Nexus 接受的 POST /service/rest/v1/repositories/{format}/{type} 请求体相对应。Task 会在为用户省略的字段合并合理默认值后,原样将每个条目转发给 Nexus;下文未列出的内容都会按原样转发,并由 Nexus 自行接受或拒绝。

通用字段(所有格式和类型)

FieldRequiredTypeDefaultNotes
nameyesstring—Repository 名称。创建后 不可变。
formatyesstring—maven2、npm、raw、pypi、docker、helm 等之一。请参阅 Nexus Repository Formats 以获取你的 Nexus 实例支持的完整列表。不可变。
typeyesstring—hosted(你推送)、proxy(缓存上游)、或 group(聚合只读)。不可变。
onlineoptionalbooleantruerepository 是否接受传入请求。
storage.blobStoreNameoptionalstringdefault底层 blob store。不可变——若要迁移 blob store,需删除 repository 后重新创建。
storage.strictContentTypeValidationoptionalbooleantrue拒绝声明的 content type 与实际 payload 不匹配的上传。
storage.writePolicyoptional (hosted)stringALLOW (on hosted)ALLOW、ALLOW_ONCE、DENY 之一。在现有 repository 上不可变。
cleanup.policyNamesoptionallist of strings—要关联的预先存在的 Nexus cleanup policy 名称。
maven.contentDispositionoptional (maven2 only)stringNexus-defaultINLINE、ATTACHMENT 之一。控制 Nexus 在 artifact 响应中设置的 Content-Disposition header。可在现有 maven2 repository 上更新。
actionsoptionallist of strings[read, browse, add, edit, delete]授予 scoped user 在该 repository 上的五种 Nexus repository-view action 的子集。

hosted repository

除通用字段外,hosted repository 还接受格式特定配置。对于 maven2,具体如下:

FieldRequiredTypeDefaultNotes
maven.versionPolicyoptionalstringRELEASERELEASE、SNAPSHOT、MIXED 之一。在创建时设置——Nexus 会静默忽略对此字段的更新,因此 Task 将其视为不可变,并在发现差异时快速失败,以避免静默无操作。请在 release repository 上设置 RELEASE,在 snapshot repository 上设置 SNAPSHOT,以强制匹配的版本契约。
maven.layoutPolicyoptionalstringSTRICTSTRICT、PERMISSIVE 之一。可在重新运行时更新。

参考: Maven Repositories — Sonatype Help。

proxy repository

Proxy repository 会按需缓存上游 registry。

FieldRequiredTypeDefaultNotes
proxy.remoteUrlyesstring—上游 URL,例如 https://repo.maven.apache.org/maven2/。
proxy.contentMaxAgeoptionalint1440 (minutes)缓存 artifact 保持新鲜的时长。
proxy.metadataMaxAgeoptionalint1440缓存 metadata 保持新鲜的时长。
negativeCache.enabledoptionalbooleantrue缓存负面(404)响应以减轻上游负载。
negativeCache.timeToLiveoptionalint1440negative-cache 条目的 TTL。
httpClient.blockedoptionalbooleanfalse设为 true 时,proxy 拒绝发起任何上游请求。
httpClient.autoBlockoptionalbooleantrue在连续上游故障时自动阻断。

有关格式特定的 proxy 字段(例如 maven2 proxy 上的 maven.versionPolicy),请参阅 Nexus Repository Formats 中相应的格式参考。权威请求体示例: Nexus Repositories REST API。

group repository

Group repository 会聚合对同一格式的一组成员 repository 的只读访问。

FieldRequiredTypeDefaultNotes
group.memberNamesyesordered list of strings—成员 repository 名称,按解析顺序排列。可在重新运行时更新。

对于 Maven group,你可能还希望设置 maven.versionPolicy: MIXED,这样该 group 就可以作为 release 和 snapshot 成员 repository 的前端。

不可变字段(完整列表)

如果某个 provision: 条目会在现有 repository 上更改以下任一字段,Task 会使运行失败——Nexus 不接受这些字段的更新,而若静默保留旧值,会导致请求配置与实际状态漂移:

  • name
  • format
  • type
  • storage.blobStoreName
  • storage.writePolicy
  • maven.versionPolicy

用户可见的错误可能有以下两种形式,具体取决于哪个 Nexus REST 调用暴露了拒绝:

  • 名为“<field> is IMMUTABLE in Nexus”的消息,指出具体的 diff 字段(当 Task 的 pre-PUT 检查触发时)。
  • Nexus 的原始 HTTP 400 body,通常是总括性消息 "You cannot change a repository's blob store through the API",即使实际 diff 位于另一个不可变字段(当 Nexus 自身的 validator 先拒绝 PUT 时)。请将 diff 与上表交叉对照;仅凭消息文本并不总能识别出有问题的字段。

处理不可变 diff 的方法是删除 Nexus repository 后重新运行,或者将该条目移到 reference: 下,以便 Task 只关联 privilege 而不触碰定义。

reference: 条目

当 repository 已经存在于 Nexus 中(由其他渠道管理),而你只想让 scoped user 获得访问权限时使用。

FieldRequiredTypeDefaultNotes
nameyesstring—现有 Nexus repository 的名称。如果不存在,Task 会快速失败。
actionsoptionallist of strings[read, browse, add, edit, delete]要授予的五种 Nexus repository-view action 的子集。

在 reference: 模式下,Task 不会修改 repository 定义本身——只会为 scoped user 赋予 role 的 privilege。

actions 参考

provision: 或 reference: 条目上的 actions 字段可以取五种标准 Nexus repository-view action 的任意子集:

Action含义
read下载已发布的 artifact。
browse列出目录并查询 metadata。
edit覆盖现有版本并修改 metadata。
add上传新的 artifact 版本。
delete删除 artifact。

每个条目都会解析为 Nexus 在创建 repository 时生成的相应 nx-repository-view-<format>-<repo>-<action> privilege,并附加到 scoped role 上。

Task 传递原样内容与默认值的区别

  • 原样传递:你在 provision: 条目下设置的每个字段,在创建(POST)和幂等刷新(PUT)时都会原样转发给 Nexus。Task 不会悄悄重写你提供的值。
  • 仅在省略时填充默认值:上表中带默认值的字段,会在用户省略时补齐,然后再转发给 Nexus。用户显式提供的值——包括布尔字段上的 false——都会被保留。

示例:预配项目私有 Nexus Repository

最常见的场景使用此模式——一个项目拥有一个或多个专用 Nexus repository,且只有该项目会消费它们。

查看 schema 参考 以了解每个 provision: 条目接受的完整字段集。

在运行示例之前,请替换这些占位符:

  • <management-namespace>:包含 Task 和 credential Secret 的私有 namespace。
  • <project-namespace>:Connector 和 Secret 应放置到的 namespace。

然后应用此 TaskRun:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: project-a-nexus-setup
  namespace: <management-namespace>
spec:
  taskRef:
    kind: Task
    name: nexus-connector-automatic-creation
  params:
    # The Task uses its built-in `nexusCliImage` default; override only when mirroring the image.
    - name: connector
      value: <project-namespace>/project-a-nexus
    - name: nexusUrl
      value: <your-nexus-address>  # e.g. https://nexus.example.com
    - name: nexusRepositories
      value: |
        provision:
          - name: project-a-maven-hosted
            format: maven2
            type: hosted
          - name: project-a-npm-internal
            format: npm
            type: hosted
  workspaces:
    - name: nexus-secret
      secret:
        secretName: nexus-provisioner-auth
    # `kube-config` is optional; bind it only when SSA must target a
    # different cluster — see the Workspaces section for details. The
    # subsequent mixed / reference examples below bind it to show the
    # out-of-cluster shape.

TaskRun 成功后:

  • Nexus 中包含所请求的两个 repository,并为未设置字段应用了合理默认值(storage.blobStoreName=default、hosted repository 上的 storage.writePolicy=ALLOW、maven2 上的 maven.versionPolicy=RELEASE)。
  • Nexus 中包含 scoped role 和 user,并且这两个 repository 都具有完整的 repository-view action。
  • 项目 namespace 中包含生成的 Connector Secret 和指向你在 nexusUrl 中提供地址的 Nexus Connector。

示例:为现有共享 repository 赋予访问权限

当 repository 已经存在于 Nexus 中、由其他渠道管理,且你只需要为 Alauda Container Platform 项目授予一个 scoped credential 时,使用此模式。

查看 schema 参考 以了解 reference: 条目的契约。

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: team-a-nexus-readonly
  namespace: <management-namespace>
spec:
  taskRef:
    kind: Task
    name: nexus-connector-automatic-creation
  params:
    # The Task uses its built-in `nexusCliImage` default; override only when mirroring the image.
    - name: connector
      value: <team-a-namespace>/team-a-nexus
    - name: nexusUrl
      value: <your-nexus-address>  # e.g. https://nexus.example.com
    - name: nexusRepositories
      value: |
        reference:
          - name: maven-public
            actions: [read, browse]
          - name: npm-public
            actions: [read, browse]
  workspaces:
    - name: nexus-secret
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connectors: <management-namespace>/nexus-provisioner
    - name: kube-config
      secret:
        secretName: target-kubeconfig

TaskRun 成功后:

  • Nexus 中包含 scoped role 和 user,并对 maven-public 和 npm-public 具有 read + browse action。Task 不会修改 repository 本身。
  • team namespace 中包含生成的 Connector Secret 和 Nexus Connector。该 namespace 中的 workload 可以通过 Connector proxy 从共享 repository 解析依赖,而无需持有直接的 Nexus credential。

示例:混合预配与引用

当一个 scoped user 既要向项目私有 repository 发布,又要从共享上游 repository 拉取时,使用此模式。所预配的集合遵循 Maven 最佳实践——使用一个 group repository 作为前端,将分离的 releases 和 snapshots hosted repository 统一起来,这样消费者只需通过一个 URL 即可解析。

查看 schema 参考 以了解字段语义、默认值和不可变字段列表。

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: project-a-nexus-mixed
  namespace: <management-namespace>
spec:
  taskRef:
    kind: Task
    name: nexus-connector-automatic-creation
  params:
    # The Task uses its built-in `nexusCliImage` default; override only when mirroring the image.
    - name: connector
      value: <project-namespace>/project-a-nexus
    - name: nexusUrl
      value: <your-nexus-address>  # e.g. https://nexus.example.com
    - name: nexusRepositories
      value: |
        provision:
          - name: project-a-maven-releases
            format: maven2
            type: hosted
            maven:
              versionPolicy: RELEASE
              layoutPolicy: STRICT
            actions: [read, browse, add, edit, delete]
          - name: project-a-maven-snapshots
            format: maven2
            type: hosted
            maven:
              versionPolicy: SNAPSHOT
              layoutPolicy: STRICT
            actions: [read, browse, add, edit, delete]
          - name: project-a-maven2
            format: maven2
            type: group
            group:
              memberNames:
                - project-a-maven-releases
                - project-a-maven-snapshots
            maven:
              versionPolicy: MIXED
            actions: [read, browse, add, edit, delete]
        reference:
          - name: maven-central
            actions: [read, browse]
  workspaces:
    - name: nexus-secret
      secret:
        secretName: nexus-provisioner-auth
    - name: kube-config
      secret:
        secretName: target-kubeconfig

TaskRun 成功后:

  • 创建两个 maven2 hosted repository——一个固定为 RELEASE,一个固定为 SNAPSHOT——以及一个作为二者前端的 group repository,且都使用了所请求的配置。
  • scoped user 可以向 project-a-maven-releases 发布 release artifact,向 project-a-maven-snapshots 发布 snapshot artifact,并通过 project-a-maven2(group)使用单一 URL 解析依赖。
  • scoped user 还可以额外读取现有的 maven-central reference repository。

每个条目上的 actions 列表决定了授予 scoped user 的、按 repository 划分的 privilege。未在 provision: 或 reference: 中列出的 repository,scoped user 无法访问。

重新运行以添加 repository 或轮换 credential

重新运行时,Task 是幂等的。请将同一个 TaskRun(或生成它的 Pipeline / Trigger)用于两个不同目的:

Scope 变更 —— 添加 repository、移除 repository,或者更改授予现有 repository 的 actions:

  1. 编辑同一个 TaskRun,并在 provision: 或 reference: 下追加、删除或修改条目。保留其他条目不变——它们会被识别为已存在并就地刷新。
  2. 重新应用 TaskRun。Task 会创建新的 repository,刷新授予 scoped user 的 privilege,并轮换 scoped user 的密码(见下文)。新密码会写入项目 namespace 中同一个 Connector Secret,因此读取该 Secret 的消费者会在下一次 reconcile 时获取新密码。

Credential rotation —— 在不改变 repository 集合的情况下刷新 scoped Nexus user 密码:

  1. 原样重新应用同一个 TaskRun。每次成功运行都会轮换 scoped user 的密码,并将其重新写入同一个 Connector Secret。这是周期性轮换和事件驱动轮换的推荐机制。

以下内容在重复运行之间保持不变(除非你通过相应的 Task 参数显式覆盖):Connector 资源名称(connector 参数中的 <connector-name> 部分)、Secret 名称(默认是 <connector-name>-secret,除非通过 secret 参数覆盖)、以及 Nexus role 名称(<connector-namespace>-<connector-name>-role)。Nexus user 名称也保持不变,除非通过 nexusUser 覆盖。

移除 repository 时——从 nexusRepositories 中删除该条目并重新应用。Task 不会删除 Nexus repository 本身(因此历史 artifact 不会丢失);它只会撤销 scoped user 对该 repository 的权限。

验证结果

检查 TaskRun 是否成功:

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

检查 connector namespace 中生成的 Connector 和 Secret(Secret 默认是 <connector-name>-secret,除非通过 secret 参数覆盖):

kubectl get connector project-a-nexus -n <project-namespace>
kubectl get secret project-a-nexus-secret -n <project-namespace>

等待 Connector 进入 Ready,然后确认:

kubectl wait --for=condition=Ready connector/project-a-nexus \
  -n <project-namespace> --timeout=120s
kubectl get connector project-a-nexus -n <project-namespace> \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'

Ready=True 表示 Connector controller 已成功使用生成的 Secret 协调目标 Connector。

读取 Task result,以确认实际协调的 repository 集合和用户身份:

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

若要验证生成的 Connector 是否确实能够消费 Nexus,请将其挂载到项目 namespace 中的 workload,并针对 proxy 运行一次依赖解析。有关 Connectors CSI driver 提供的配置挂载(settings.xml、.npmrc、pip.conf),请参见 Nexus Connector。

故障排查

提示:在失败的 TaskRun 上将 Task 参数 verbose: "true" 设置为 true,可为非敏感步骤启用 shell tracing。即使启用了 verbose tracing,Secret 值仍会被抑制。跟踪到的命令有助于更容易定位 401 / 403 / SSL / yq-parse 错误。

nexusRepositories 无法解析

该参数必须是一个有效的 YAML map,并且至少包含顶层键 provision: 或 reference: 之一。顶层裸 list 会被拒绝。Task 会在第 2 步日志中暴露底层 yq 错误。

provision: 条目缺少 format 或 type

每个 provision: 条目都需要 name、format 和 type。Task 会快速失败并指出缺少字段的条目。请补充缺失字段,或者如果 repository 已经存在于 Nexus 中,则将该条目移到 reference: 下。

reference: 条目在 Nexus 中不存在

Task 会以如下形式失败:reference mode: repo '<name>' does not exist; move the entry under provision: (with format + type) to create it. 要么先在 Nexus 中创建该 repository,要么将该条目移到 provision: 下并提供 format 和 type。

Nexus 针对 repository endpoint 返回 404

当请求的 format 不被该 Nexus 实例支持时,Nexus 会在 POST /service/rest/v1/repositories/<slug>/<type> 上返回 404。Task 会暴露 format 名称,并提醒你唯一非 1:1 的 slug 映射是 maven2 → maven——其他所有 format 名称都与其 endpoint slug 相同。

provision: 条目在 Nexus 中已存在

Task 会刷新 Nexus 允许更新的字段(例如 online、storage.strictContentTypeValidation、cleanup.policyNames)。如果不可变字段(name、format、type、storage.blobStoreName、storage.writePolicy 或 maven.versionPolicy)的提供值与现有值不同,Task 会使运行失败——Nexus 不接受这些字段的更新,因此必须先删除现有 repository 才能应用所请求的配置。暴露出来的错误可能会指出具体的 diff 字段(“<field> is IMMUTABLE in Nexus”),也可能透传 Nexus 的原始 HTTP 400 body,而该 body 通常会显示“You cannot change a repository's blob store through the API”,即使实际 diff 位于另一个不可变字段——请将 diff 与 不可变字段列表 交叉对照,而不要只依赖消息文本。可通过删除现有 Nexus repository 后重新运行,或者将该条目移到 reference: 下以便 Task 只关联 privilege 而不触碰定义来解决。

Nexus user 已存在,但不是 scoped role 的成员

Task 拒绝刷新一个 foreign user——即其 userId 与 Task 派生名称匹配,但其 roles 列表不包含 Task 管理的 role。该步骤会以 Refusing to refresh foreign user (would replace existing roles and rotate the password). Override the user name via the nexusUser Task param if a different identity is needed. 失败。可通过显式设置 nexusUser 值,让 Task 拥有自己的用户身份,或者在下一次运行前,手动将 Task 管理的 role 添加到现有用户在 Nexus 中的 roles 列表中来解决。Task 刻意不会接管现有用户,以避免替换其他系统设置的 role,并轮换另一个集成所依赖的 credential。

Nexus role 已存在,但其 description 不以 OWNER=connectors-operator 开头

这表示与某个非 Task 拥有的 role 发生了名称冲突——例如手工创建了一个同名 Nexus role。Task 会以 squatter 错误失败。你可以删除或重命名冲突 role,或者选择不同的 connector 名称,以避免派生出的 role 名称发生冲突。

Nexus 权限不足

nexus-secret 使用的 Nexus credential 必须满足上文 nexus-secret 的 Nexus 凭证 中列出的权限集合。请在 Nexus 控制台(Security → Roles)中检查分配给预配用户的 role。

如果你为 nexus-secret 使用的是 Nexus Connector,请同时检查:

  • Connector 后面的 Nexus user 拥有所列权限。
  • TaskRun ServiceAccount 被允许使用该 Connector。

Kubernetes 权限不足

Task 在应用 Connector 和 Secret 之前会运行一次 kubectl auth can-i 预检。该预检是建议性的:如果某个 verb 被拒绝,Task 会记录一条指明缺失 verb 的警告,但不会快速失败——随后 Server-Side-Apply 调用会直接从 Kubernetes apiserver 暴露同样的缺失权限错误。调试 RBAC 时,请同时查看两条日志:预检中建议性的 kubectl auth can-i ... reports forbidden 警告,以及 SSA 调用返回的 apiserver 错误。

kube-config 所使用的 Kubernetes credential(或者在 kube-config 未绑定时使用的集群内 ServiceAccount)必须被允许在 connector namespace 中对 Secrets 和 Nexus Connector 资源(group connectors.alauda.io)执行 get、create 和 patch。Task 使用 Server-Side Apply,而 apiserver 会将其授权为 patch 动作,因此仅有 create 不够。请参见 授予 apply credential Kubernetes RBAC 获取可直接复制粘贴的 Role 和 RoleBinding。

nexus-secret workspace 缺少文件

在 basic-auth Secret 模式下,workspace 必须包含 username 和 password 文件。若任一文件缺失,Task 会快速失败并给出提示。在 Nexus Connector 模式下,workspace 必须包含 Connectors CSI driver 的挂载输出。Task 会通过检查 workspace 自动检测模式,而 basic-auth 文件优先:如果同时存在 username/password 文件 以及 Connectors CSI mount,Task 会选择 basic-auth,且不会发出警告。一次只挂载一种形态,以便你期望的认证模式是明确无歧义的。

nexusUrl 缺失或为空

nexusUrl 参数在两种 workspace 模式下都必需。Task 从不从 Secret 或 Connector 推导 URL——它始终只使用 nexusUrl 作为唯一目标。请将该参数设置为 Nexus base URL(末尾不要带斜杠),例如 https://nexus.example.com,或者类似 http://nexus.nexus-system.svc 的集群内 Service URL。

Nexus anonymous access 已启用

当 Nexus anonymous access 已启用时,Task 会在第 1 步发出警告,但不会失败,也不会修改集群级别的 Nexus 设置。如果需要严格部署,请在 Nexus 控制台(Settings → Security → Anonymous Access)中禁用 anonymous access。

Nexus 返回 401 Unauthorized

步骤日志中会包含某个 Nexus REST 调用返回的 HTTP_CODE=401。常见原因包括:

  • 已绑定 Secret 的 username / password 文件有误、为空,或者末尾多了一个换行符。请使用 kubectl create secret generic ... --from-literal= 重新创建 basic-auth Secret(这样不会像编辑器保存的文件通过 --from-file= 那样插入换行符)。
  • nexusUrl 所指向的 host 与创建该 credential 时所针对的 Nexus 实例不匹配(例如 https://nexus.example.com 指向了另一个 Nexus 3.x 部署)。
  • 在 Nexus Connector 模式(CSI 挂载)下,workspace 未正确绑定,导致 Task 回退到 basic-auth 模式并尝试从挂载中读取 username / password。检查第 1 步的模式检测日志行,确认选择的是哪种模式(A 或 B)。

Nexus 返回 403 Forbidden

步骤日志中会包含 HTTP_CODE=403。credential 认证成功,但其后面的 Nexus role 缺少失败操作所需的某个 privilege。请将 nexus-secret 的 Nexus 凭证 privilege 表与日志行中提到的具体 REST endpoint 进行交叉对照——例如,POST /v1/repositories/maven/hosted 返回 403,表示该 role 缺少 nx-repository-admin-maven-*-create。

访问 Nexus 时 TLS 握手失败

步骤日志中会包含 SSL_ERROR 或 curl: (60) SSL certificate problem。nexusUrl 是 HTTPS,但 Task runtime image 不信任 Nexus 提供的证书链。如果你使用自定义 CA 代理 Nexus,请通过 Nexus Connector workspace 挂载 CA bundle(Connectors CSI driver 会注入 Connector 的 caBundle 中的 CA);如果你直接绑定 basic-auth Secret,请将 Secret 类型重新创建为 kubernetes.io/tls,以便 Task image 从标准路径获取 CA,或者在构建时将 CA 安装到 image 的 trust store 中。