在 Nexus Raw Repository 中上传和下载制品

与 Nexus 交换二进制文件、tarball、文档包或测试报告的流水线,通常需要向托管的 raw 仓库上传,或从托管的 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 上传和下载 Task 所需的输入。

此方法解决的问题

在以下情况下使用此方法:

  • 从 Tekton TaskRun 向托管的 raw 仓库上传制品(单个文件、目录树、glob 扩展、可选的 tarball 打包、可选的 sha256 checksum manifest——这些都是平台附带的 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 仓库已存在于 Nexus 中。本指南不会创建仓库——有关该流程,请参阅 Nexus Connector 自动创建。

Connector 路径的差异

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

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 展示了编辑器时映射完成后的等效运行时绑定。由于 TaskRun 不引用 ResourceInterface 对象,因此该示例直接引用 Connector:

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 应返回未发生变化的 artifact。
  3. 在 Nexus 控制台的 Browse → Components 下查找目标 raw 仓库,确认上传内容已显示在那里。

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

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

  1. 选择 Nexus Connector。
  2. 选择仓库。列表仅包含 Nexus 格式为 raw 且类型为 hosted 的仓库。
  3. 选择 File Path。表单会调用所选仓库的 Nexus asset 搜索 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 会自动完成此配置;较旧版本可能需要显式步骤。

参考

  • 使用此 RI 的 nexus-upload 和 nexus-download Tekton Tasks。
  • Nexus ConnectorClass 概念 — 底层 ConnectorClass,包括正向代理 URL 的派生方式以及为其他格式公开的配置。