在 Nexus Raw 仓库中上传和下载构件

需要与 Nexus 交换二进制文件、tarball、文档包或测试报告的流水线,通常需要从托管的 raw 仓库中下载或向其中上传,而不是使用 Maven、npm 或 PyPI 软件包格式。 如果没有 Connector,这意味着流水线作者必须:

  1. 在 Nexus 控制台中找到确切的 Nexus raw 仓库名称;对于下载,还要找到完整的文件路径,然后将其粘贴到 TaskRun 中。
  2. 在用户命名空间中创建并维护一个 kubernetes.io/basic-auth Secret,其中包含长期有效的用户名和密码。
  3. 在使用 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 所需的输入。

此方案解决的问题

在以下场景中使用此方案:

  • 从 Tekton TaskRun 上传构件到托管的 raw 仓库(单个文件、目录树、glob 展开、可选地打包为 tarball,以及可选的 sha256 校验和清单——这些功能均由平台附带的 nexus-upload Tekton Task 提供)。
  • 通过选择完整路径下载现有的 raw 构件,而不是从 Nexus 控制台复制路径。
  • 移除用户命名空间中手动管理的 Secret,由平台 Connector 负责凭证生命周期管理。
  • 从过滤为 raw 格式和 hosted 类型的列表中选择仓库,然后在配置下载时搜索其中的文件。

开始之前

先决条件

以下示例假定默认的安装命名空间为 connectors-system。 如果你的平台将 Connectors 组件安装到其他命名空间,请在看到 connectors-system 的位置替换为该命名空间。

  • 已安装 Tekton Pipelines。
  • 已安装 Connectors 系统和 Nexus Connector 组件(ConnectorsCore 和 ConnectorsNexus CR 已协调为 Ready)。
  • 已在运行 TaskRun 的命名空间中安装 nexus-upload 或 nexus-download Tekton Task。该 Task 必须使用支持 nexus-raw-repository ResourceInterface 的版本。有关引入 Connector 支持的 Task 版本,请参阅平台 release notes。
  • 指向目标 Nexus 实例的 Nexus Connector,并且其中的 Secret 包含一个 Nexus 用户:对于下载,该用户对所选托管 raw 仓库具有读取权限;对于上传,该用户对所选托管 raw 仓库具有读取和写入权限。
  • 目标 raw 仓库已存在于 Nexus 中。本指南不会创建仓库——有关该流程,请参阅 Nexus Connector Automatic Creation。

Connector 路径的差异

方面手动管理的 Secret通过 nexus-raw-repository RI 使用 Connector
凭证存储位置用户命名空间中的明文 Secret平台命名空间中由 Connector 所有的 Secret
仓库名称输入由流水线作者输入从过滤为 raw + hosted 的下拉列表中选择
下载文件输入从 Nexus 复制完整路径从仓库的文件列表中选择完整路径
凭证轮换在每个命名空间中手动编辑并重新部署只需轮换一次 Connector Secret;新的 TaskRun 会获取更新后的凭证
Pod 环境调用方将 Secret 挂载为 auth 工作区CSI driver 注入 .env(包含正向代理 URL)和 ca.crt
数据路径curl 使用 --user $u:$p 直接连接 NexusTask 通过 HTTPS_PROXY 连接;正向代理使用 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。

apiVersion: v1
kind: Secret
metadata:
  name: my-nexus-cred
  namespace: connectors-system
type: kubernetes.io/basic-auth
stringData:
  username: <nexus-user-with-write-on-target-raw-repo>
  password: <password>
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: my-nexus
  namespace: connectors-system
spec:
  connectorClassName: nexus
  address: https://nexus.example.com
  auth:
    name: basicAuth
    secretRef:
      name: my-nexus-cred

等待 Connector 报告 Ready=True:

kubectl -n connectors-system get connector my-nexus -w

步骤 2 — 使用 ResourceInterface 上传

nexus-upload Task 声明了一个 auth 工作区和一个 repository 参数,这两者都由 nexus-raw-repository ResourceInterface 在 Pipeline 编辑器中进行映射。以下手写的 TaskRun 展示了该编辑器时映射之后的等效 运行时绑定。它直接引用 Connector,因为 TaskRun 不会引用 ResourceInterface 对象:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: upload-dist-
spec:
  taskRef:
    name: nexus-upload
  params:
  # In a UI-driven TaskRun, both nexusServerURL and repository are
  # auto-filled from the Connector via the RI's `address` and
  # `repository` attributes. In a hand-written YAML you pass the
  # values directly; they must agree with the chosen Connector
  # (nexusServerURL = the Connector's spec.address).
  - name: nexusServerURL
    value: https://nexus.example.com
  - name: repository
    value: my-raw-hosted              # filled from the RI dropdown in the UI
  - name: targetPath
    value: releases/$(context.taskRun.name)
  - name: sources
    value: ["dist/*.tar.gz"]
  workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: build-output
  - name: auth
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connectors: connectors-system/my-nexus
        # Empty configuration.names tells the CSI driver to mount only the
        # builtin configuration: .env (HTTPS_PROXY with the connector
        # context token embedded) and ca.crt (the forward-proxy CA bundle).
        configuration.names: ""
        token.expiration: 30m

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 成功后:

  1. 在 TaskRun 上列出 result;nexus-upload 会为每个上传的文件公开一个结果,其中包含最终绝对 URL。
  2. 打开上一步中的某个 URL。Nexus 应原样返回该构件。
  3. 在 Nexus 控制台的 Browse → Components 下查看目标 raw 仓库,确认上传内容已显示在那里。

步骤 4 — 选择并下载 Raw 文件

在 Pipeline 编辑器中,基于 nexus-raw-repository ResourceInterface 添加 Pipeline Integration,然后:

  1. 选择 Nexus Connector。
  2. 选择仓库。列表中仅包含 Nexus 格式为 raw 且类型为 hosted 的仓库。
  3. 选择 文件路径。表单会针对所选仓库调用 Nexus asset search API,并显示每个文件的完整路径。
  4. 要缩小较大第一页的范围,请在文件选择器的搜索框中输入文本。 表单会将该文本作为 q 查询参数发送到 Nexus。Nexus 会应用 自己的全文搜索语义;这并不保证是简单的文件名 contains 匹配。

Raw 仓库不会为文件分配 Maven 风格的版本。所选值是完整的仓库相对路径,例如:

releases/app/v1/package.tar.gz

某些 Nexus 版本会返回带前导 / 的相同路径。 ResourceInterface 会在将该值传递给 Task 之前移除这个前导斜杠,因为 nexus-download 需要的是仓库相对的 sourcePath,而不是 绝对路径或下载 URL。

按如下方式将 Integration 映射到 nexus-download Task:

ResourceInterface 输出nexus-download 输入
address 属性nexusServerURL 参数
repository 属性repository 参数
path 属性sourcePath 参数
auth 工作区auth 工作区

当 Task 声明其 RawRepository Integration contract 时,Pipeline 编辑器可以推荐这些映射。你也可以手动选择每个 Integration 属性。path 参数是可选的,默认值为空,因此在引入文件选择功能之前保存的 Pipeline Integration 仍可加载。

选择器目前仅公开 Nexus 返回的第一页,不会自动加载后续页面。有效仓库在没有匹配文件时会返回包含空 items 数组的成功响应;这不是身份验证错误或系统错误。

步骤 5 — 验证下载

TaskRun 成功后:

  1. 确认 Task 接收到的是不带前导斜杠的仓库相对 sourcePath。
  2. 检查 Task 结果或输出工作区中是否存在已下载的文件。
  3. 将其校验和或内容与 Nexus 中的源资产进行比较。

凭证轮换

要轮换所有引用此 Connector 的命名空间中所有 TaskRun 使用的 Nexus 用户密码:

kubectl -n connectors-system patch secret my-nexus-cred \
  --type=strategic \
  -p '{"stringData":{"password":"<new-password>"}}'

之后的 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-download Tekton Tasks — 使用此 RI 的 Task。
  • Nexus ConnectorClass 概念 — 底层 ConnectorClass,包括正向代理 URL 的派生方式以及为其他格式公开的配置。