Nexus Connector

Nexus connector 是一种与平台无关的连接器,可用于连接 Nexus 仓库。

您可以使用 Nexus Connector 在 CICD 流水线或 Kubernetes 工作负载中安全地执行 Maven、NPM 和 PyPI 操作,而无需凭证。

此外,您可以集中管理跨命名空间的 Nexus 访问配置,避免在每个命名空间中重复配置 Nexus 凭证。

概述

本文档介绍:

  • 集成要求:目标 Nexus 仓库的先决条件
  • 创建 Nexus connector
  • 高级功能:Maven、NPM 和 PyPI 的代理功能与配置文件

集成要求

Nexus Repository 先决条件

  • Nexus 服务器必须可从集群访问。
  • 支持的仓库类型:Maven(hosted/proxy/group)、NPM(hosted/proxy/group)、PyPI(hosted/proxy/group)。

客户端先决条件

对于 Maven 客户端,您必须在执行 mvn 操作之前信任 connector 代理服务器的证书:

keytool -importcert -noprompt \
  -trustcacerts \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit \
  -alias corp-ca \
  -file /opt/maven/ca.cert

mvn 客户端还必须使用 wagon 传输:

MAVEN_OPTS=-Dmaven.resolver.transport=wagon

创建 Nexus Connector

以下介绍如何创建基本的 Nexus Connector:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: nexus-connector
spec:
  connectorClassName: nexus
  address: https://nexus.example.com
  auth:
    name: basicAuth

字段参考

spec.connectorClassName:

nexus(常量),指定用于 Nexus 集成的 ConnectorClass 名称。

spec.address:

目标 Nexus 服务器地址,例如:https://nexus.example.com。这是 Nexus 服务器的根地址,而不是特定仓库的 URL。

spec.auth:

指定 Nexus 服务器的身份验证方法。

  • spec.auth.name:对于 Nexus connector,应为 basicAuth。
  • spec.auth.secretRef:指定包含身份验证信息的 Secret。该 Secret 应创建在与 connector 相同的命名空间中。如果您的 Nexus 服务器不需要身份验证,可以省略此字段。

可选元数据字段:

  • cpaas.io/description:connector 的描述信息,例如:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: nexus-connector
      annotations:
        cpaas.io/description: "Connect to team Nexus server"

Nexus Connector 的功能

身份验证

Nexus connector 支持以下身份验证类型:

  • basicAuth:基于用户名和密码的身份验证,对应的 Secret 类型:kubernetes.io/basic-auth

使用 Basic 身份验证

apiVersion: v1
stringData:
  username: your-nexus-username
  password: your-nexus-password
kind: Secret
metadata:
  name: nexus-secret
type: kubernetes.io/basic-auth

如果 Secret 不正确,connector 中的 status.conditions 字段将显示错误消息。

有关完整的状态信息,请参阅 Connector 状态文档。

所需的凭证权限

所需权限取决于您计划如何使用 connector:

  • 仅下载:凭证仅需要目标仓库的读取权限。
  • 上传/部署:凭证必须同时拥有目标仓库的读取和写入权限。

为遵循安全最佳实践,请创建具有所需最小权限的凭证。

Subconnector 生成

单个 Nexus 服务器通常会通过不同的仓库路径提供多个包生态系统,例如 npm、Maven 和 PyPI。您无需为每个生态系统创建一个 Connector(或挂载下文所述的各格式配置文件),而是可以声明一个 Nexus 聚合器 Connector,使其为每个生态系统生成一个子 Connector:在 Nexus ConnectorClass 上设置 spec.generation.supportedClasses: [npm, maven, pypi],并在 Nexus Connector 的 spec.generators 中列出这些生态系统。控制器会为每个类别生成 npm / maven / pypi 子 Connector,这些子 Connector 共享聚合器的主机和凭证,流水线通过这些子 Connector 使用包。

这是从一个 Nexus 服务器提供多个生态系统的推荐方式。有关完整模型(包括地址模板化、身份验证继承、GenerationReady 条件、恢复和生命周期),请参阅 Connector 生成。

代理和配置文件

为使客户端能够在无需凭证的情况下访问 Nexus 仓库,Nexus connector 提供代理服务器,该服务器会自动注入身份验证信息。

Nexus ConnectorClass 提供以下配置文件,这些文件可以通过 Connectors CSI Driver 挂载到 Pod 中:

配置名称生成的文件使用场景
settingssettings.xml、ca.cert通过代理执行 Maven 操作
npmrc.npmrcNPM 包操作
yarnrc.yarnrc.ymlYarn 包操作
pipconfpip.conf下载 PyPI 包
pypirc.pypirc发布 PyPI 包
不推荐使用,应改用 Subconnector 生成

直接挂载这些各格式配置文件(settings / npmrc / yarnrc / pipconf / pypirc)已被弃用。建议使用 Subconnector 生成;该方式会生成每个类别对应的 npm / maven / pypi 子 Connector,流水线使用这些子 Connector,而不是使用这些原始配置挂载。

代理地址

创建 Connector 时,系统会自动为目标 Nexus 服务器配置代理服务。

代理端点记录在 status.proxy.httpAddress 中:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: nexus-connector
spec:
  # connector spec fields
status:
  conditions:
    # status conditions
  proxy:
    httpAddress:
      url: http://c-nexus-connector.default.svc.cluster.local

Maven:settings.xml 配置

settings 配置提供一个通过 Connectors CSI Driver 挂载的 settings.xml 文件和一个 ca.cert 文件。

生成的 settings.xml 示例:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <proxies>
    <proxy>
      <id>connectors-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>c-nexus-connector.connectors-nexus-demo.svc.cluster.local</host>
      <port>80</port>
      <username>connectors-nexus-demo/nexus-connector</username>
      <password>eyJhbGciOiJEnEZaTQ</password>
      <nonProxyHosts>localhost</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

可选参数:mirrorRepository — 用作 Maven 镜像的 Nexus 仓库。设置后,生成的 settings.xml 将包含一个 <mirrors> 部分,并指向 {address}/repository/{mirrorRepository}。

要挂载 settings 配置:

spec:
  volumes:
  - name: settings
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "nexus-connector"
        configuration.names: "settings"
        configuration.params: '{"settings": {"mirrorRepository": "maven-public"}}' # optional

NPM:.npmrc 配置

npmrc 配置为 NPM 包操作提供一个 .npmrc 文件。

可选参数:registry — Nexus NPM 代理仓库名称(例如 npm-proxy)。默认值:""。为空时,.npmrc 会以占位注释的形式呈现,而不会导致 CSI 挂载失败;提供此参数即可启用 npm install / npm publish。

可选参数:strictSSL — 是否要求 SSL(默认值:"true")。

spec:
  volumes:
  - name: npmrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "nexus-connector"
        configuration.names: "npmrc"
        configuration.params: '{"npmrc": {"registry": "npm-proxy"}}'

Yarn:.yarnrc.yml 配置

yarnrc 配置为 Yarn 包操作提供一个 .yarnrc.yml 文件。

可选参数:registry — Nexus NPM 代理仓库名称。默认值:""。为空时,.yarnrc.yml 会以占位注释的形式呈现,而不会导致 CSI 挂载失败;提供此参数即可启用 yarn install / yarn npm publish。

可选参数:strictSSL — 是否要求 SSL(默认值:"true")。

spec:
  volumes:
  - name: yarnrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "nexus-connector"
        configuration.names: "yarnrc"
        configuration.params: '{"yarnrc": {"registry": "npm-proxy"}}'

PyPI 下载:pip.conf 配置

pipconf 配置为下载 PyPI 包提供一个 pip.conf 文件。

可选参数:repository — Nexus PyPI 代理仓库名称(例如 pypi-proxy)。默认值:""。为空时,pip.conf 会以占位注释的形式呈现,而不会导致 CSI 挂载失败;提供此参数即可启用 pip install。

spec:
  volumes:
  - name: pipconf
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "nexus-connector"
        configuration.names: "pipconf"
        configuration.params: '{"pipconf": {"repository": "pypi-proxy"}}'

PyPI 发布:.pypirc 配置

pypirc 配置为发布 PyPI 包提供一个 .pypirc 文件。

可选参数:deployRepository — Nexus PyPI 托管仓库名称(例如 pypi-hosted)。默认值:""。为空时,.pypirc 会以占位注释的形式呈现,而不会导致 CSI 挂载失败;提供此参数即可启用 twine upload。

spec:
  volumes:
  - name: pypirc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "nexus-connector"
        configuration.names: "pypirc"
        configuration.params: '{"pypirc": {"deployRepository": "pypi-hosted"}}'

使用 Connectors CSI Driver

CSI 卷属性参数:

  • csi.readOnly:固定值为 true
  • csi.driver:固定为 connectors-csi
  • csi.volumeAttributes:
    • connector.name:Nexus Connector 的名称
    • connector.namespace:Nexus Connector 的命名空间;如果未指定,则使用 Pod 的命名空间
    • configuration.names:要挂载的配置(例如 settings、npmrc、yarnrc、pipconf、pypirc)
    • configuration.params:包含每个命名配置运行时参数的 JSON 字符串(见下文)

通过使用逗号分隔名称,可以同时挂载多个配置:

configuration.names: "settings,npmrc"
configuration.params: '{"settings": {"mirrorRepository": "maven-public"}, "npmrc": {"registry": "npm-proxy"}}'

Nexus 的 configuration.params

有关 configuration.params 的格式、验证规则和默认值注入行为,请参阅 Connectors CSI Driver 文档中的 configuration.params。

每个 Nexus 配置接受的参数如下:

配置参数必填默认值描述
settingsmirrorRepository否""在 settings.xml 中用作镜像的 Nexus Maven 仓库
npmrcregistry否""Nexus NPM 代理仓库名称
npmrcstrictSSL否"true"是否要求 SSL("true" 或 "false")
yarnrcregistry否""Nexus NPM 代理仓库名称
yarnrcstrictSSL否"true"是否要求 SSL("true" 或 "false")
pipconfrepository否""Nexus PyPI 代理仓库名称
pypircdeployRepository否""用于发布的 Nexus PyPI 托管仓库名称

当某个参数的默认值为 "",且调用方未在 configuration.params 中提供相应条目时,生成的文件会包含一个占位注释块(以 # WARNING: empty configuration 开头),其中会标明缺少的参数,并显示用于提供该参数所需的 JSON 代码片段 — CSI 挂载仍会成功,下游工具可以检测到空状态,而不会导致 Pod 启动失败。

延伸阅读

参考资料