Nexus 连接器

Nexus connector 是一个与平台无关的连接器,可用于连接到 Nexus repositories。

你可以使用 Nexus Connector 在 CI/CD pipelines 或 Kubernetes workloads 中安全地执行 Maven、NPM 和 PyPI 操作,而无需凭证。

此外,你可以在多个 namespace 之间集中管理 Nexus 访问配置,避免在每个 namespace 中重复配置 Nexus 凭证。

概述

本文档涵盖以下内容:

  • 集成要求:目标 Nexus repositories 的前提条件
  • 创建 Nexus connector
  • 高级功能:Maven、NPM 和 PyPI 的代理能力和配置文件

集成要求

Nexus Repository 前提条件

  • Nexus server 必须可从 cluster 访问。
  • 支持的 repository 类型:Maven(hosted/proxy/group)、NPM(hosted/proxy/group)、PyPI(hosted/proxy/group)。

客户端前提条件

对于 Maven clients,在执行 mvn 操作之前,你必须信任 connector proxy server 的证书:

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

mvn client 还必须使用 wagon transport:

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 server 地址,例如:https://nexus.example.com。这是 Nexus server 的根地址,而不是特定 repository URL。

spec.auth:

指定 Nexus server 的认证方法。

  • spec.auth.name:对于 Nexus connector 应为 basicAuth。
  • spec.auth.secretRef:指定包含认证信息的 Secret。该 secret 应创建在与 connector 相同的 namespace 中。如果你的 Nexus server 不需要认证,可以省略此字段。

可选的 Metadata 字段:

  • 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 Authentication

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:

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

出于安全最佳实践,请创建仅具有所需最小权限的凭证。

代理和配置文件

为了让 clients 能够在无需凭证的情况下访问 Nexus repositories,Nexus connector 提供了一个会自动注入认证信息的 proxy server。

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

配置名称生成的文件使用场景
settingssettings.xml, ca.cert通过 proxy 执行 Maven 操作
npmrc.npmrcNPM package 操作
yarnrc.yarnrc.ymlYarn package 操作
pipconfpip.confPyPI package 下载
pypirc.pypircPyPI package 发布

代理地址

创建 Connector 后,系统会自动为目标 Nexus server 提供一个 proxy service。

proxy 端点记录在 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 mirror 使用的 Nexus repository。设置后,生成的 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 package 操作提供 .npmrc 文件。

可选参数:registry — Nexus NPM proxy repository 名称(例如 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 package 操作提供 .yarnrc.yml 文件。

可选参数:registry — Nexus NPM proxy repository 名称。默认值:""。当为空时,.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 packages 提供 pip.conf 文件。

可选参数:repository — Nexus PyPI proxy repository 名称(例如 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 packages 提供 .pypirc 文件。

可选参数:deployRepository — Nexus PyPI hosted repository 名称(例如 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 volume attribute 参数:

  • csi.readOnly:固定值 true
  • csi.driver:固定为 connectors-csi
  • csi.volumeAttributes:
    • connector.name:Nexus Connector 的名称
    • connector.namespace:Nexus Connector 的 namespace;如果未指定,则使用 Pod 的 namespace
    • 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 中用作 mirror 的 Nexus Maven repository
npmrcregistry否""Nexus NPM proxy repository 名称
npmrcstrictSSL否"true"是否要求 SSL("true" 或 "false")
yarnrcregistry否""Nexus NPM proxy repository 名称
yarnrcstrictSSL否"true"是否要求 SSL("true" 或 "false")
pipconfrepository否""Nexus PyPI proxy repository 名称
pypircdeployRepository否""用于发布的 Nexus PyPI hosted repository 名称

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

延伸阅读

参考资料