在 Nexus Raw Repository 中上传和下载制品
与 Nexus 交换二进制文件、tarball、文档包或测试报告的流水线,通常需要向托管的 raw 仓库上传,或从托管的 raw 仓库下载,而不是使用 Maven、npm 或 PyPI 包格式。 如果没有 Connector,这意味着流水线作者必须:
- 在 Nexus 控制台中找到确切的 Nexus raw 仓库名称,以及下载所需的完整文件路径,然后将其粘贴到
TaskRun中。 - 在用户命名空间中创建并维护一个
kubernetes.io/basic-authSecret,其中包含长期有效的用户名和密码。 - 在每个使用 Nexus 的命名空间中重新创建该 Secret,并在 Nexus 凭证发生变化时在所有位置轮换该 Secret。
本指南介绍另一种方式:通过 nexus-raw-repository ResourceInterface 引用平台 Nexus Connector,并让 connectors CSI driver 在 TaskRun 运行时注入代理 URL 和 CA 证书。用户命名空间从不存储明文 Nexus Secret,凭证轮换过程透明完成。
ResourceInterface(RI)是可复用的 Connector-to-Task 绑定模板。平台提供 nexus-raw-repository,用于将 Nexus Connector、选定的 raw 仓库以及可选的文件路径映射到 raw 上传和下载 Task 所需的输入。
目录
此方法解决的问题开始之前前提条件Connector 路径的差异步骤 1 — 创建 Nexus Connector步骤 2 — 使用 ResourceInterface 上传步骤 3 — 验证上传步骤 4 — 选择并下载 Raw 文件步骤 5 — 验证下载凭证轮换故障排除来自 Nexus 的401 Unauthorized上传时发生 403 Forbidden文件选择器不返回任何选项下拉查询时发生 403 Forbidden由于找不到路径而导致下载失败sourcePath must not be absolutePod 卡在 ContainerCreatingx509: certificate signed by unknown authority参考此方法解决的问题
在以下情况下使用此方法:
- 从 Tekton
TaskRun向托管的 raw 仓库上传制品(单个文件、目录树、glob 扩展、可选的 tarball 打包、可选的sha256checksum manifest——这些都是平台附带的nexus-uploadTekton Task 提供的功能)。 - 通过选择完整路径下载现有的 raw 制品,而不是从 Nexus 控制台复制路径。
- 移除用户命名空间中由人工管理的 Secret,并让平台 Connector 负责凭证生命周期管理。
- 从列表中选择仓库,将列表过滤为
raw格式和hosted类型,然后在配置下载时搜索其中的文件。
开始之前
前提条件
以下示例假定默认安装命名空间为
connectors-system。 如果你的平台将 Connectors 组件安装到其他命名空间,请在看到connectors-system的位置替换为该命名空间。
- 已安装 Tekton Pipelines。
- 已安装 Connectors 系统和 Nexus Connector 组件(
ConnectorsCore和ConnectorsNexusCR 已协调为 Ready)。 - 已在运行
TaskRun的命名空间中安装nexus-upload或nexus-downloadTekton Task。该 Task 必须使用能够消费nexus-raw-repositoryResourceInterface 的版本。有关引入 Connector 支持的 Task 版本,请参阅平台 release notes。 - 一个指向目标 Nexus 实例的 Nexus Connector,并且其中的 Secret 包含一个 Nexus 用户:对选定的托管 raw 仓库具有读取权限(用于下载),以及读取和写入权限(用于上传)。
- 目标 raw 仓库已存在于 Nexus 中。本指南不会创建仓库——有关该流程,请参阅 Nexus Connector 自动创建。
Connector 路径的差异
在 <address>/repository/<repo>/<path> 上,上传使用 HTTP PUT,下载使用 HTTP GET。
Connector 路径会改变 curl 的身份验证方式:它不再看到 Nexus 用户,而是看到正向代理 URL,并由代理使用 Connector 存储的凭证对上游连接进行身份验证。
步骤 1 — 创建 Nexus Connector
如果你已经为 mvn、npm 或 pypi
工作流创建了 Nexus Connector,则同一个 Connector 也可用于 raw 上传和下载——跳转到
步骤 2。
等待 Connector 报告 Ready=True:
步骤 2 — 使用 ResourceInterface 上传
nexus-upload Task 声明了一个 auth 工作区和一个 repository
参数,nexus-raw-repository ResourceInterface 会在 Pipeline 编辑器中映射这两者。下面手写的
TaskRun 展示了编辑器时映射完成后的等效运行时绑定。由于
TaskRun 不引用 ResourceInterface 对象,因此该示例直接引用 Connector:
Pod 启动时,CSI driver 会将两个文件写入 auth
工作区:
.env— 导出HTTPS_PROXY、HTTP_PROXY、https_proxy、http_proxy、no_proxy,这些变量全部指向平台正向 代理。代理 URL 包含根据 Connector 身份和 TaskRun ServiceAccount 令牌派生的短期凭证。ca.crt— 用于签发正向代理 TLS 证书的 CA bundle。
Task 会在内部加载 .env 以获取 HTTPS_PROXY,然后运行
curl -X PUT --cacert <auth_workspace>/ca.crt --upload-file <file> <address>/repository/<repository>/<path>。正向代理会验证
TaskRun 作用域内的凭证,查找 Nexus Connector,将代理身份验证替换为 Connector 的真实 Nexus 用户名和密码,
并将 PUT 转发到 Nexus。
步骤 3 — 验证上传
TaskRun 成功后:
- 在
TaskRun上列出result—nexus-upload会为每个上传的文件公开一个结果,其中包含最终绝对 URL。 - 打开上一步中的某个 URL。Nexus 应返回未发生变化的 artifact。
- 在 Nexus 控制台的 Browse → Components 下查找目标 raw 仓库,确认上传内容已显示在那里。
步骤 4 — 选择并下载 Raw 文件
在 Pipeline 编辑器中,添加一个基于
nexus-raw-repository ResourceInterface 的 Pipeline Integration,然后:
- 选择 Nexus Connector。
- 选择仓库。列表仅包含 Nexus 格式为
raw且类型为hosted的仓库。 - 选择 File Path。表单会调用所选仓库的 Nexus asset 搜索 API,并显示每个文件的完整路径。
- 若第一页结果较多,可在文件选择器的搜索框中输入文本以缩小范围。
表单会将该文本作为
q查询参数发送给 Nexus。Nexus 会应用自身的全文搜索语义;这不保证是简单的文件名contains匹配。
Raw 仓库不会为文件分配 Maven 风格的版本。选中的值是完整的仓库相对路径,例如:
某些 Nexus 版本会返回带前导 / 的相同路径。
ResourceInterface 会在将该值传递给 Task 前移除这个前导斜杠,因为
nexus-download 需要的是仓库相对的 sourcePath,而不是
绝对路径或下载 URL。
按如下方式将 Integration 映射到 nexus-download Task:
当 Task 声明其
RawRepository Integration contract 时,Pipeline 编辑器可以推荐这些映射。你也可以手动选择每个 Integration
属性。path 参数是可选的,默认值为空,因此在引入文件选择功能之前保存的
Pipeline Integration 仍可加载。
选择器目前只显示 Nexus 返回的第一页,不会自动加载后续页面。存在但没有匹配文件的有效仓库会返回成功响应,其中
items 数组为空;这不属于身份验证或系统错误。
步骤 5 — 验证下载
TaskRun 成功后:
- 确认 Task 收到的是不带前导斜杠的仓库相对
sourcePath。 - 检查 Task 结果或输出工作区,确认已下载文件。
- 将其校验和或内容与 Nexus 中的源资产进行比较。
凭证轮换
要轮换所有引用此 Connector 的命名空间中所有 TaskRun 使用的 Nexus 用户密码:
后续的 TaskRun 会自动获取新凭证。无需重新部署 Pipeline,也无需编辑用户命名空间 Secret — 此路径上不存在这些 Secret。
故障排除
来自 Nexus 的 401 Unauthorized
Connector 的 Secret 中缺少 Nexus 凭证,或凭证无效。更正用户名或密码,并等待 Connector 恢复为 Ready=True。
上传时发生 403 Forbidden
Connector 的 Nexus 用户有效,但对目标 raw 仓库没有写入权限。调整 Nexus 用户的角色,使其包含 nx-repository-view-raw-<repo>-add 和 nx-repository-view-raw-<repo>-edit,然后重试。
文件选择器不返回任何选项
当仓库为空或搜索文本与任何资产都不匹配时,选择器为空是有效结果。清除搜索文本,然后重试。如果仍然缺少文件,请确认 Connector 的 Nexus 用户对该仓库具有浏览和读取权限。
下拉查询时发生 403 Forbidden
首先检查当前配置 Pipeline Integration 的用户的平台权限。该用户必须对 connectors/apis/nexus/service/rest/v1/repositories 和 connectors/apis/nexus/service/rest/v1/search/assets 具有 get。向该用户授予在命名空间中聚合了 cpaas:connectors-nexus-apis:view 或更高权限的平台角色。
如果平台权限已具备,则上游 Nexus 账户可能缺少所选仓库的浏览或读取权限。更新该账户的 Nexus 角色,然后重试。
由于找不到路径而导致下载失败
Pipeline Integration 保存后,所选资产可能已被删除或移动。重新打开文件选择器并选择当前路径。对于没有匹配项的情况,列表 API 可以返回空的成功响应;而后续对特定缺失路径的下载会因 Nexus HTTP 404 语义而失败。
sourcePath must not be absolute
不要在所选路径前添加 /。重新打开并保存 Pipeline Integration,以便 ResourceInterface 规范化 Nexus 路径;或者输入类似 releases/app/v1/package.tar.gz 的仓库相对值。
Pod 卡在 ContainerCreating
CSI 驱动程序报告了挂载错误。kubectl describe pod 将显示底层消息 — 常见原因包括错误的 volumeAttributes.connectors 命名空间/名称、从未达到 Ready=True 状态的 Connector,或 TaskRun 中未绑定的 auth 工作区。
x509: certificate signed by unknown authority
curl 在未将 --cacert 指向工作区 ca.crt 的情况下被调用。CA bundle 存在于 auth 工作区中,但未告知 curl 信任它。最新版本的上传和下载 Task 会自动完成此配置;较旧版本可能需要显式步骤。
参考
- 使用此 RI 的
nexus-upload和nexus-downloadTekton Tasks。 - Nexus ConnectorClass 概念 — 底层 ConnectorClass,包括正向代理 URL 的派生方式以及为其他格式公开的配置。