#NPM Connector

NPM connector 是一种与平台无关的连接器，可用于连接任意 NPM registry。

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

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

#概述

本文档涵盖以下内容：

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

#集成要求

NPM Registries 前置条件

• NPM registry 必须支持 NPM Registry API

#创建一个简单的 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 时，需要配置 repository 地址，例如：https://nexus.example.com/repository/npm-public。

spec.auth(可选)：

指定 NPM registry 的认证方式

• spec.auth.name：对于 NPM connector，应为 basicAuth。

• spec.auth.secretRef：指定包含 NPM registry 认证信息的 secret，该 secret 应创建在与 connector 相同的 namespace 中。如果你的 NPM registry 不需要认证，可以省略此字段。

可选的 Metadata 字段：

• cpaas.io/description：NPM connector 的描述信息，例如：

  apiVersion: connectors.alauda.io/v1alpha1
  kind: Connector
  metadata:
    name: npm-connector
    annotations:
      cpaas.io/description: "Connect to team development NPM registry"

spec.params(可选)：

NMP Connector 支持的参数，用于控制 connector 配置行为。

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

支持的参数：

• registryType：当多个 NPM connector 在单个 CSI volume 中一起使用时，指定此 connector 的角色。该参数控制用于下载包和用于发布包的 registry 地址。允许的值：

  • mirror — 使用此 connector 的 registry 下载依赖项（例如 npm install）
  • publish — 使用此 connector 的 registry 发布包（例如 npm publish）
  • all — 使用此 connector 的 registry 同时进行下载和发布
  • (空) — 旧版行为；当没有 connector 显式设置 registryType 时，当前 connector 的地址同时用于下载和发布

  当至少有一个 connector 显式设置了 registryType 时，下载 registry 的解析优先级为：mirror > all > publish > current connector。发布 registry 的解析优先级为：publish > all > (空) > mirror > current connector。

  该参数仅在使用 multiple connectors in one CSI volume 时有意义。对于单 connector 使用场景，可以省略。

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

例如：

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

#NPM Connector 的功能

#认证

NPM connector 支持以下认证类型：

• 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

#所需的凭证权限

所需的凭证权限取决于你打算在 Pod/Pipeline 中如何使用它。

例如：

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

出于安全最佳实践，我们建议使用仅满足最低需求权限的凭证。当需要额外权限时，请创建具有更高权限 secret 的单独 Connectors，并使用 namespace 隔离来控制哪些用户可以访问每个 Connector。

#使用 npmrc 和 yarnrc.yml 文件的 NPM Connector 代理与配置

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

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

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

#代理地址

在创建 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 connector 提供以下配置：

.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/"

有关代理机制的详细说明，请参阅 Quick Start 指南中的 How It Works。

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 还提供一个包含 Connector Proxy 的 CA 证书的 ca.cert 文件。该文件可通过 Connector CSI Driver 挂载到 Pod 中，以便在通过 HTTPS 访问代理时建立 TLS 信任。

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

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

例如：

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 的名称
  • connector.namespace：NPM Connector 的 namespace；如果未指定，则使用 Pod 的 namespace
  • configuration.names：配置名称，由 NPM Connector 提供。与上文一致，支持 npmrc 和 yarnrc。

有关如何通过 connectors-csi-driver 在 Pod 中使用 .npmrc 和 .yarnrc.yml 文件的详细信息，请参阅 Using NPM Connectors in kubernetes jobs

#延伸阅读

• 将 NPM Connectors 用作分发管理 repository

#参考资料

• Connector 的概念
• Connector Proxy
• Connector CSI Driver
• Kubernetes CSI Volume