Alauda DevOps Connectors Docs
  • 简体中文

    • NPM Connector

    NPM Connector 是一个平台无关的连接器，您可以使用它连接到任何 NPM registry。

    您可以使用 NPM Connector 在 CICD 流水线中安全地执行 NPM 操作，或者在 kubernetes 工作负载中使用它来执行无凭证的 NPM 操作。

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

    目录

    OverviewIntegration RequirementsCreating a simple NPM connectorFields ReferenceCapabilities of NPM ConnectorAuthenticationCredential Permissions RequiredNPM Connector Proxy and Configuration with npmrc and yarnrc.yml filesProxy Address.npmrc configuration file.yarnrc.yml configuration fileca.cert fileUsing Connectors CSI Driver to mount .npmrc and .yarnrc.yml fileFurther ReadingReferences

    Overview

    本文档涵盖：

    • Integration Requirements：目标 NPM registry 的先决条件
    • Creating NPM connector
    • Advanced Features：关于 NPM connector 的代理功能和配置能力

    Integration Requirements

    NPM Registries Prerequisites

    Creating a simple NPM connector

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

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

    Fields Reference

    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(optional)：

    指定 NPM registry 的认证方式

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

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

    Optional Metadata fields：

    • 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(optional)：

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

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

    支持的参数：

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

    例如：

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

    Capabilities of NPM Connector

    Authentication

    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

    Credential Permissions Required

    配置凭证所需的权限取决于您打算如何在 Pods/Pipelines 中使用它。

    例如：

    • Package operations：如果您只需要使用 npm install 下载依赖，凭证只需对目标 NPM 仓库具有读取权限。
    • Package and Deploy operations：如果您需要使用 npm publish 发布制品，凭证必须对目标仓库具有读写权限。

    出于安全最佳实践，建议创建权限最小化的凭证。当需要额外权限时，创建具有更高权限 secret 的独立 Connector，并通过命名空间隔离控制哪些用户可以访问各个 Connector。

    NPM Connector Proxy and Configuration with npmrc and yarnrc.yml files

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

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

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

    WARNING

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

    Proxy Address

    创建 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 configuration file

    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 configuration file

    • 提供 .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/"

    有关代理机制的详细信息，请参见快速开始指南中的 How It Works。

    WARNING

    使用 yarn 连接 HTTPS registry 时，需要通过环境变量配置 yarn 信任 Connector Proxy 证书，否则会出现证书错误。

    yarn 的证书配置如下：

    export NODE_EXTRA_CA_CERTS=/opt/yarn/ca.cert # 替换为 ca.cert 在 Pod 中挂载的实际路径

    ca.cert file

    NPM connector 还提供了包含 Connector Proxy CA 证书的 ca.cert 文件。该文件可通过 Connector CSI Driver 挂载到 Pod 中，用于在通过 HTTPS 访问代理时建立 TLS 信任。

    Using Connectors CSI Driver to mount .npmrc and .yarnrc.yml file

    NPM connector 提供 .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 卷属性
      • connector.name：NPM Connector 名称
      • connector.namespace：NPM Connector 所在命名空间；若未指定，则使用 Pod 所在命名空间
      • configuration.names：配置名称，由 NPM Connector 提供。支持 npmrc 和 yarnrc。

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

    Further Reading

    References