NPM 连接器

NPM 连接器是一个与平台无关的连接器,可用于连接到任何 NPM registry。

你可以使用 NPM Connector 在 CICD pipeline 中安全地执行 NPM 操作,或者在 kubernetes 工作负载中使用它,在无需凭证的情况下执行 NPM 操作。

此外,你还可以集中管理跨命名空间的 NPM 访问配置,无需在每个命名空间中重复配置 NPM 凭证。

概述

本文档涵盖以下内容:

  • 集成要求:目标 NPM registry 的前置条件
  • 创建 NPM 连接器
  • 高级功能:NPM 连接器的代理能力和配置能力

集成要求

NPM Registries 前置条件

创建一个简单的 NPM 连接器

以下是创建基础 NPM Connector 的方法:

# NPM Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: npm-connector
spec:
  connectorClassName: npm
  address: https://registry.npmjs.org

字段参考

spec.connectorClassName:

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

spec.address:

目标 NPM registry 地址,例如:https://registry.npmjs.org。

当使用 Nexus 作为 npm registry 时,需要配置仓库地址,例如:https://nexus.example.com/repository/npm-public。

spec.auth(可选):

指定 NPM registry 的认证方式

  • spec.auth.name:NPM 连接器应设置为 basicAuth。

  • spec.auth.secretRef:指定包含 NPM registry 认证信息的 secret,该 secret 应创建在与连接器相同的命名空间中。如果你的 NPM registry 不需要认证,则可以省略此字段。

可选元数据字段:

  • cpaas.io/description:NPM 连接器的描述信息,例如:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: npm-connector
      annotations:
        cpaas.io/description: "连接到团队开发 NPM registry"

spec.params(可选):

NMP Connector 支持参数,用于控制连接器配置的行为。

  • spec.params[].name:参数名称,必须与对应 ConnectorClass 中定义的参数名称匹配。
  • spec.params[].value:参数值,其值类型必须与 ConnectorClass 中定义的参数类型匹配。

支持的参数:

  • registryType:当在单个 CSI volume 中组合使用多个 NPM 连接器时,指定此连接器的角色。该参数控制下载包时使用哪个 registry 地址,以及发布时使用哪个 registry 地址。允许的值:

    • mirror — 使用此连接器的 registry 下载依赖项(例如,npm install)
    • publish — 使用此连接器的 registry 发布包(例如,npm publish)
    • all — 使用此连接器的 registry 同时用于下载和发布
    • (空) — 旧版行为;当没有任何连接器显式设置 registryType 时,当前连接器的地址将同时用于下载和发布

    当至少有一个连接器显式设置了 registryType 时,下载 registry 的解析优先级为:mirror > all > publish > 当前连接器。发布 registry 的解析优先级为:publish > all > (空) > mirror > 当前连接器。

    该参数仅在 在一个 CSI volume 中使用多个连接器 时有意义。对于单连接器用法,可以省略。

  • strict-ssl:是否为 NPM registry 写入带有 strict-ssl 参数的 .npmrc/.yarnrc.yml 文件。默认值为 true。支持 true 和 false。

例如:

spec:
  params:
    - name: registryType
      value: "mirror"
    - name: strict-ssl
      value: "false"

NPM 连接器的能力

认证

NPM 连接器支持以下认证类型:

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

例如:

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

有关完整状态信息,请参见 Connector Status Documentation。

如果 NPM registry 不需要认证,可以省略 secretRef 字段:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: npm-connector
spec:
  connectorClassName: npm
  address: https://registry.npmjs.org
  auth:
    name: basicAuth

所需的凭证权限

配置的凭证所需权限取决于你计划如何在 Pods/Pipelines 中使用它。

例如:

  • 包操作:如果你只需要使用 npm install 下载依赖项,则凭证只需要对目标 NPM repository 具有读权限。
  • 包和部署操作:如果你需要使用 npm publish 发布制品,则凭证必须对目标 repository 同时具有读权限和写权限。

出于安全最佳实践,我们建议创建仅具备最小必要权限的凭证。当需要额外权限时,可以创建具有更高权限 secret 的独立连接器,并使用命名空间隔离来控制哪些用户可以访问每个连接器。

使用 npmrc 和 yarnrc.yml 文件的 NPM 连接器代理与配置

为了让客户端能够在无需凭证的情况下访问 NPM registry,NPM 连接器提供了一个代理服务器,可自动注入认证信息。

客户端可以使用此代理服务器访问 NPM registry,而无需在客户端侧配置凭证。

为了简化使用,NPM connectorclass 提供了 .npmrc 和 .yarnrc.yml 文件,可通过 CSI 挂载到 Pods 中。在 Pod 中执行 NPM 操作时,代理服务可以自动注入认证信息。

WARNING

.yarnrc.yml 文件仅在 Yarn 2.x 版本中受支持。

代理地址

创建 Connector 时,系统会自动为目标 NPM registry 提供一个代理服务。

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

例如:

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

.npmrc 配置文件

NPM 连接器提供以下配置:

.npmrc:

  • 提供一个 .npmrc 配置文件。结合 connector-csi-driver,此配置文件将被挂载到 Pod 中,使其能够通过代理访问 NPM registry,而无需在客户端侧配置凭证。

Pod 中生成的配置文件示例:

# NPM Registry Configuration
registry=http://npm-registry.example.com/

 # The authentication token is fake, because the connector will not use it, it will be used for proxy requests.
//npm-registry.example.com/:_auth=fAd326jYkI123456789xxx

# Set the connector proxy URL for npm registry access
https-proxy=http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/
proxy=http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/

# Disable npm audit to avoid security warnings during CI/CD
audit=false

# Disable funding messages to reduce output noise
fund=false

.yarnrc.yml 配置文件

  • 提供一个 .yarnrc.yml 配置文件。结合 connector-csi-driver,此配置文件将被挂载到 Pod 中,使其能够通过代理访问 NPM registry,而无需在客户端侧配置凭证。

    # Set the NPM registry server URL for package resolution
    npmRegistryServer: "http://npm-registry.example.com/"
    
    # The authentication token is fake, because the connector will not use it, it will be used for proxy requests.
    npmAuthIdent: "fAd326jYkI123456789xxx"
    
    # Always authenticate to the registry
    # This is required for the connector to work correctly, if the npmAlwaysAuth is not set to true, the metadata request will not be authenticated.
    npmAlwaysAuth: true
    
    # The unsafeHttpWhitelist is used to whitelist the host for proxy requests.
    unsafeHttpWhitelist:
    - npm-registry.example.com
    
    # authentication for proxy requests
    httpProxy: "http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/"
    httpsProxy: "http://connector-ns%2Fconnector-name:fAd326jYkI123456789xxx@c-npm-connector.default.svc.cluster.local/"
    
    # Set the registry URL for package publishing
    # Ensures packages are published to the correct registry
    npmPublishRegistry: "http://npm-registry.example.com/"

有关代理机制的详细说明,请参见快速开始指南中的 工作原理。

WARNING

当使用带有 HTTPS registry 的 yarn 时,你需要通过环境变量为 yarn 配置 Connector Proxy 证书信任,否则会出现证书错误。

yarn 的证书配置如下:

export NODE_EXTRA_CA_CERTS=/opt/yarn/ca.cert # replace with the actual path where ca.cert is mounted in the Pod

ca.cert 文件

NPM 连接器还提供了一个包含 Connector Proxy CA 证书的 ca.cert 文件。该文件可通过 Connector CSI Driver 挂载到 Pod 中,以便在通过 HTTPS 访问代理时建立 TLS 信任。

使用 Connectors CSI Driver 挂载 .npmrc 和 .yarnrc.yml 文件

NPM 连接器提供了 .npmrc、.yarnrc.yml 和 ca.cert 文件,可通过 Connector CSI Driver 挂载到 Pod 中。

例如:

spec:

  volumes:
  - name: npmrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "npm-connector"
        configuration.names: "npmrc"
  - name: yarnrc
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "npm-connector"
        configuration.names: "yarnrc"

参数说明:

  • csi.readOnly:固定值 true
  • csi.driver:Connector CSI Driver,固定为 connectors-csi。
  • csi.volumeAttributes:CSI Volume 属性
    • connector.name:NPM 连接器的名称
    • connector.namespace:NPM 连接器的命名空间;如果未指定,则使用 Pod 的命名空间
    • configuration.names:配置名称,由 NPM 连接器提供。与上文一致,支持 npmrc 和 yarnrc。

有关如何通过 connectors-csi-driver 在 Pod 中使用 .npmrc 和 .yarnrc.yml 文件的详细信息,请参见 在 kubernetes jobs 中使用 NPM 连接器

延伸阅读

参考