NPM 连接器
NPM 连接器是一个与平台无关的连接器,可用于连接到任何 NPM registry。
你可以使用 NPM Connector 在 CICD pipeline 中安全地执行 NPM 操作,或者在 kubernetes 工作负载中使用它,在无需凭证的情况下执行 NPM 操作。
此外,你还可以集中管理跨命名空间的 NPM 访问配置,无需在每个命名空间中重复配置 NPM 凭证。
目录
概述集成要求创建一个简单的 NPM 连接器字段参考NPM 连接器的能力认证所需的凭证权限使用 npmrc 和 yarnrc.yml 文件的 NPM 连接器代理与配置代理地址.npmrc 配置文件.yarnrc.yml 配置文件ca.cert 文件使用 Connectors CSI Driver 挂载 .npmrc 和 .yarnrc.yml 文件延伸阅读参考概述
本文档涵盖以下内容:
- 集成要求:目标 NPM registry 的前置条件
- 创建 NPM 连接器
- 高级功能:NPM 连接器的代理能力和配置能力
集成要求
NPM Registries 前置条件
- NPM registry 必须支持 NPM Registry API
创建一个简单的 NPM 连接器
以下是创建基础 NPM Connector 的方法:
字段参考
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 连接器的描述信息,例如:
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。
例如:
NPM 连接器的能力
认证
NPM 连接器支持以下认证类型:
basicAuth:基于用户名和密码的认证,对应的 secret 类型:kubernetes.io/basic-auth
例如:
有关完整状态信息,请参见 Connector Status Documentation。
如果 NPM registry 不需要认证,可以省略 secretRef 字段:
所需的凭证权限
配置的凭证所需权限取决于你计划如何在 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 操作时,代理服务可以自动注入认证信息。
.yarnrc.yml 文件仅在 Yarn 2.x 版本中受支持。
代理地址
创建 Connector 时,系统会自动为目标 NPM registry 提供一个代理服务。
代理端点记录在 status.proxy.httpAddress 中:
例如:
.npmrc 配置文件
NPM 连接器提供以下配置:
.npmrc:
- 提供一个
.npmrc配置文件。结合 connector-csi-driver,此配置文件将被挂载到 Pod 中,使其能够通过代理访问 NPM registry,而无需在客户端侧配置凭证。
Pod 中生成的配置文件示例:
.yarnrc.yml 配置文件
-
提供一个
.yarnrc.yml配置文件。结合 connector-csi-driver,此配置文件将被挂载到 Pod 中,使其能够通过代理访问 NPM registry,而无需在客户端侧配置凭证。
有关代理机制的详细说明,请参见快速开始指南中的 工作原理。
当使用带有 HTTPS registry 的 yarn 时,你需要通过环境变量为 yarn 配置 Connector Proxy 证书信任,否则会出现证书错误。
yarn 的证书配置如下:
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 中。
例如:
参数说明:
csi.readOnly:固定值truecsi.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 连接器