在 Nexus Raw 仓库中上传和下载构件
需要与 Nexus 交换二进制文件、tarball、文档包或测试报告的流水线,通常需要从托管的 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 上传和下载 Tasks 所需的输入。
目录
此方案解决的问题开始之前先决条件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,以及可选的sha256校验和清单——这些功能均由平台附带的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 仓库具有读取和写入权限。
- 目标 raw 仓库已存在于 Nexus 中。本指南不会创建仓库——有关该流程,请参阅 Nexus Connector Automatic Creation。
Connector 路径的差异
上传使用 HTTP PUT,下载则在 <address>/repository/<repo>/<path> 上使用 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 展示了该编辑器时映射之后的等效
运行时绑定。它直接引用 Connector,因为 TaskRun 不会引用 ResourceInterface 对象:
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 应原样返回该构件。
- 在 Nexus 控制台的 Browse → Components 下查看目标 raw 仓库,确认上传内容已显示在那里。
步骤 4 — 选择并下载 Raw 文件
在 Pipeline 编辑器中,基于
nexus-raw-repository ResourceInterface 添加 Pipeline Integration,然后:
- 选择 Nexus Connector。
- 选择仓库。列表中仅包含 Nexus 格式为
raw且类型为hosted的仓库。 - 选择 文件路径。表单会针对所选仓库调用 Nexus asset search 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 会自动完成此配置;旧版本可能需要显式步骤。
参考
nexus-upload和nexus-downloadTekton Tasks — 使用此 RI 的 Task。- Nexus ConnectorClass 概念 — 底层 ConnectorClass,包括正向代理 URL 的派生方式以及为其他格式公开的配置。