使用 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 密码。
目录
解决什么问题开始之前前提条件安全注意事项兼容性场景索引准备凭证和 Workspacesnexus-secret 的 Nexus 凭证为 nexus-secret 使用 basic-auth Secret为 nexus-secret 使用 Nexus Connectorkube-config 的 Kubernetes 凭证授予 apply credential Kubernetes RBAC使用 Kubernetes Secret 作为 kube-config为 kube-config 使用 Kubernetes ConnectorTask 如何解决该问题Repository 生命周期:provision 与 referenceScoped user、role 和 credential 生命周期nexusRepositories 结构provision: 条目通用字段(所有格式和类型)hosted repositoryproxy repositorygroup repository不可变字段(完整列表)reference: 条目actions 参考Task 传递原样内容与默认值的区别示例:预配项目私有 Nexus Repository示例:为现有共享 repository 赋予访问权限示例:混合预配与引用重新运行以添加 repository 或轮换 credential验证结果故障排查nexusRepositories 无法解析provision: 条目缺少 format 或 typereference: 条目在 Nexus 中不存在Nexus 针对 repository endpoint 返回 404provision: 条目在 Nexus 中已存在Nexus user 已存在,但不是 scoped role 的成员Nexus role 已存在,但其 description 不以 OWNER=connectors-operator 开头Nexus 权限不足Kubernetes 权限不足nexus-secret workspace 缺少文件nexusUrl 缺失或为空Nexus anonymous access 已启用Nexus 返回 401 UnauthorizedNexus 返回 403 Forbidden访问 Nexus 时 TLS 握手失败解决什么问题
当你需要为 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-centralproxy)。 - 仅引用:完全跳过预配,仅将 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-configworkspace 时需要 Kubernetes Connector——参见 为kube-config使用 Kubernetes Connector。) - 已在你将运行 TaskRun 的 namespace 中安装
nexus-connector-automatic-creationTask。 - Task 使用的 Nexus runtime image 可以从你的内部 registry 获取。
- (可选)TaskRun ServiceAccount 能够访问目标 Kubernetes apiserver,以便应用生成的 Connector 和 Secret。只有在
kube-configworkspace 未绑定,并且 Task 回退到集群内 ServiceAccount 时才需要这一点。当你将kube-configworkspace 绑定到指向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 版本可能可用,但未包含在测试套件覆盖范围内。
场景索引
使用下表为你的情况选择合适的起始示例:
准备凭证和 Workspaces
该方案使用两个 workspace:
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,然后将其分配给预配用户:
你可以通过以下两种方式之一提供此 workspace:
- Basic-auth Secret — 当你已经拥有 Nexus 凭证并希望直接使用它们时,这是最直接的方式。
- 挂载的 Nexus Connector — 推荐用于生产环境。Pod 侧的凭证保留在 Connectors proxy 中,Pod 仅能看到 proxy 环境变量。
为 nexus-secret 使用 basic-auth Secret
在管理 namespace 中创建一个 kubernetes.io/basic-auth Secret:
像这样绑定它:
在此模式下,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 权限要求。
然后,通过 Connectors CSI driver 将 TaskRun 的 nexus-secret workspace 绑定到该 Connector:
关于 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:
当 kube-config 已绑定时,相同的权限必须由目标 namespace 和集群中该 kubeconfig 内的用户身份持有。
使用 Kubernetes Secret 作为 kube-config
像这样绑定它:
为 kube-config 使用 Kubernetes Connector
你也可以通过 Connectors CSI driver,使用一个渲染 kubeconfig 配置的 Kubernetes Connector 提供 kube-config:
关于如何一步一步创建该 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: 和 reference: 之外的顶层键都会被拒绝,因此像 provison: 或 references: 这样的拼写错误会在前置阶段被捕获。
provision: 条目
provision: 条目与 Nexus 接受的 POST /service/rest/v1/repositories/{format}/{type} 请求体相对应。Task 会在为用户省略的字段合并合理默认值后,原样将每个条目转发给 Nexus;下文未列出的内容都会按原样转发,并由 Nexus 自行接受或拒绝。
通用字段(所有格式和类型)
hosted repository
除通用字段外,hosted repository 还接受格式特定配置。对于 maven2,具体如下:
参考: Maven Repositories — Sonatype Help。
proxy repository
Proxy repository 会按需缓存上游 registry。
有关格式特定的 proxy 字段(例如 maven2 proxy 上的 maven.versionPolicy),请参阅 Nexus Repository Formats 中相应的格式参考。权威请求体示例: Nexus Repositories REST API。
group repository
Group repository 会聚合对同一格式的一组成员 repository 的只读访问。
对于 Maven group,你可能还希望设置 maven.versionPolicy: MIXED,这样该 group 就可以作为 release 和 snapshot 成员 repository 的前端。
不可变字段(完整列表)
如果某个 provision: 条目会在现有 repository 上更改以下任一字段,Task 会使运行失败——Nexus 不接受这些字段的更新,而若静默保留旧值,会导致请求配置与实际状态漂移:
nameformattypestorage.blobStoreNamestorage.writePolicymaven.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 获得访问权限时使用。
在 reference: 模式下,Task 不会修改 repository 定义本身——只会为 scoped user 赋予 role 的 privilege。
actions 参考
provision: 或 reference: 条目上的 actions 字段可以取五种标准 Nexus repository-view action 的任意子集:
每个条目都会解析为 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:
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: 条目的契约。
TaskRun 成功后:
- Nexus 中包含 scoped role 和 user,并对
maven-public和npm-public具有read+browseaction。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 参考 以了解字段语义、默认值和不可变字段列表。
TaskRun 成功后:
- 创建两个
maven2hosted repository——一个固定为RELEASE,一个固定为SNAPSHOT——以及一个作为二者前端的grouprepository,且都使用了所请求的配置。 - scoped user 可以向
project-a-maven-releases发布 release artifact,向project-a-maven-snapshots发布 snapshot artifact,并通过project-a-maven2(group)使用单一 URL 解析依赖。 - scoped user 还可以额外读取现有的
maven-centralreference repository。
每个条目上的 actions 列表决定了授予 scoped user 的、按 repository 划分的 privilege。未在 provision: 或 reference: 中列出的 repository,scoped user 无法访问。
重新运行以添加 repository 或轮换 credential
重新运行时,Task 是幂等的。请将同一个 TaskRun(或生成它的 Pipeline / Trigger)用于两个不同目的:
Scope 变更 —— 添加 repository、移除 repository,或者更改授予现有 repository 的 actions:
- 编辑同一个 TaskRun,并在
provision:或reference:下追加、删除或修改条目。保留其他条目不变——它们会被识别为已存在并就地刷新。 - 重新应用 TaskRun。Task 会创建新的 repository,刷新授予 scoped user 的 privilege,并轮换 scoped user 的密码(见下文)。新密码会写入项目 namespace 中同一个 Connector Secret,因此读取该 Secret 的消费者会在下一次 reconcile 时获取新密码。
Credential rotation —— 在不改变 repository 集合的情况下刷新 scoped Nexus user 密码:
- 原样重新应用同一个 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 是否成功:
检查 connector namespace 中生成的 Connector 和 Secret(Secret 默认是 <connector-name>-secret,除非通过 secret 参数覆盖):
等待 Connector 进入 Ready,然后确认:
Ready=True 表示 Connector controller 已成功使用生成的 Secret 协调目标 Connector。
读取 Task result,以确认实际协调的 repository 集合和用户身份:
若要验证生成的 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 中。