# @mcpg-dev/pulumi 中文文档

规范地址：https://npmcn.com/package/%40mcpg-dev/pulumi/

版本：0\.1\.0-beta\.45
npm 元数据更新时间：2026-11-01T19:12:41.183Z
中文译文更新时间：2026-11-01T20:29:52.273Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40mcpg-dev/pulumi
原文对照：https://npmcn.com/package/%40mcpg-dev/pulumi/?lang=original
项目主页：https://github.com/mcpg-dev/pulumi-mcpg#readme
源码仓库：https://github.com/mcpg-dev/pulumi-mcpg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：98.1 kB，47 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-08-13T14:52:02.125Z
- 最新版本发布：2026-11-01T19:12:40.855Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

针对MCPG（运营商、网关、租户、信任）的固执己见的Pulumi组件。

## 安装

```sh
npm install @mcpg-dev/pulumi
```

也可以使用：`pnpm add @mcpg-dev/pulumi`、`yarn add @mcpg-dev/pulumi`、`bun add @mcpg-dev/pulumi`

## README

# @mcpg / pulumi

用于在Kubernetes上运行MCPG的固执己见的Pulumi组件：操作器，组件 crd、集群信任、网关、插件集、路由和租户。每个组件 包含了平台中容易出现微妙错误的部分——CRD生命周期， 网关配置形状，租户隔离——在类型化TypeScript输入之后。 建立在 `@mcpg/pulumi-crds` （生成的、键入的CRD SDK）和 `@pulumi/kubernetes`.

当您的MCPG部署在Pulumi程序中时，您可以使用它 与其集合Helm，不如表达“一个经营者，一个门户，三个租户” 手工发布和原始自定义资源。

## 先决条件

-   使用TypeScript运行时的Pulumi，以及为其配置的Kubernetes提供程序 目标集群。
-   集群中的Cert-manager，除非您将其关闭。操作者的入场 webhook关闭失败，需要真正的TLS，所以 `Operator` 集合 `certManager.enabled=true` 默认情况下。

## 快速启动

```ts
import { McpgStack } from "@mcpg/pulumi";

new McpgStack("prod", {
  operator: { chartVersion: "<chart-version>" },
  gateway: {
    image: { repository: "ghcr.io/mcpg-dev/source-code/gateway", tag: "<tag>" },
    governance: { audit: { sinks: [{ kind: "dev.mcpg.builtin.audit.local-file" }] } },
  },
});
```

`McpgStack` 构成常见的大小写：an `Operator`,一个 `TrustBootstrap` 播种 集群默认的吊销列表(设置为 `trust: false` 跳过它)，和- when `gateway` 给定- 1 `Gateway` 在操作符的命名空间中。两者都是 后者取决于首先安装的操作器。

这个包是从这个工作区构建的：

```bash
pnpm --filter ./iac/pulumi/components run build       # tsc → bin/
pnpm --filter ./iac/pulumi/components exec tsc -b --noEmit   # tsc --noEmit
```

## 组件

| 组件 | 创建 |
| --- | --- |
| `Operator` | 作业者Helm释放和crd作为一级资源。 |
| `Gateway` | 一个 `MCPGGateway`, `spec.config` 由配置构建器组装。 |
| `PluginSet` | 一个 `MCPGPluginSet` -插件条目和可选的能力授予。 |
| `TrustBootstrap` | 的cluster-default `MCPGRevocationList`，并携带签名密钥引用。 |
| `Cluster` | 一个 `MCPGCluster` -网关的协调后端 `clusterRef` 点。 |
| `Route` | 一个 `MCPGRoute` —绑定到具有身份、策略和审计链的共享网关的工具子集。 |
| `TenantCR` | 一个 `MCPGTenant` -声明式租户治理。 |
| `Tenant` | 具有隔离的名称空间，以及可选的插件集和网关。 |
| `McpgStack` | 运营商+信任+一个网关。 |

### 操作人员和CRD生命周期

Helm将文件安装在图表的 `crds/` 一次目录，永不目录 升级或删除它们。 `Operator` 通过将crd应用为 `ConfigGroup` 它拥有-服务器端应用，像任何其他资源一样升级- 并让图表退后 `skipCrds` 加上 `crd.install=false`. `crdsDir` 指向CRD YAMLs（默认） `../../codegen/schemas/v1alpha1/crds`， 从Pulumi程序的目录中解析)。

release默认为namespace `mcpg-system`、图表 `mcpg-operator` 从 `ociChartRepo()`，并启用cert-manager。集 `watchNamespace` 来限制 操作符到单个命名空间。任何 `values` 分布在这些地方 默认，因此您提供的键将替换相应的默认块。

`ociChartRepo()` 组成 `oci://<base>/charts` 从注册表坐标中 `src/oci.ts`，其默认值反映了 `tools/release/oci-registry.json`． 覆盖 一张图表 `chartRepo`，或者一整堆 `MCPG_OCI_HOST` / `MCPG_OCI_NAMESPACE` / `MCPG_OCI_PATH` -相同的环境合同壳 和Node发布helper荣誉。 `ociImageRepo(name)` 和 `ociPluginRegistry()` 在相同的基础上组合图像和插件引用。

### 网关准备

`Gateway` 对资源进行注释 `pulumi.com/waitFor: condition=Ready`,所以 `pulumi up` 等待报告网关就绪的操作员，而不是等待 自定义资源仅存在。通过 `waitForReady: false` 跳过等待。

### 租赁：两个不同的东西

`Tenant` 是命令式扇形输出（它创建名称空间），还是默认拒绝 跨租户入口 `NetworkPolicy` (除非 `networkPolicy: false`), 可选的插件集和其中的网关。在循环中实例化它 建立一支舰队。它 **不** 创建一个 `MCPGTenant`，所以它不参与 运营商的租户治理。

`TenantCR` 创建 `MCPGTenant` 自定义资源：插件allowlist， 每个命名空间配额、副本上限和独占的命名空间所有权 操作员在入场时强制执行。在必须强制执行租户边界时使用它 而不是仅仅安排，在旁边或代替 `Tenant`.

### 集群凭证

`Cluster` 接受 `credentialRefs` 命名已存在的秘密，以及 `credentials`，其中一项载有 `data` 使组件创建 的秘密 `operatorNamespace` (默认 `mcpg-system`)，并为 你。两种形式表面的网关 `cred://cluster/<name>`. `TrustBootstrap` 以同样的方式接受签名密钥秘密引用：只有 参考传递，而不是密钥字节，所以没有签名材料到达Pulumi 状态。

## 配置

`Gateway` 建立门户的 `spec.config` 从输入部分。操作员 将文档原封不动地传递出去，网关严格解析它 未知键是一个启动时错误，这使得形状值得纠正。

```ts
import { Gateway } from "@mcpg/pulumi";

new Gateway("orders", {
  namespace: "mcpg-system",
  image: { repository: "ghcr.io/mcpg-dev/source-code/gateway", tag: "<tag>" },
  server: { bind_address: "0.0.0.0:8080" },
  governance: { audit: { sinks: [{ kind: "dev.mcpg.builtin.audit.local-file" }] } },
  plugins: [
    { id: "dev.mcpg.backend.sql", source: { oci: "ghcr.io/mcpg-dev/source-code/plugins/backend-sql:protocol-1" } },
  ],
  extraConfig: { mcp: { capabilities: { tools: [] } } },
});
```

| 场 | 类型 | 默认的 | 描述 |
| --- | --- | --- | --- |
| `server` | 对象 | 省略了 | 在发出 `config.gateway.server`，在 `gateway:` 伞——顶层 `server` 密钥被网关解析器拒绝。 |
| `governance` | 对象 | 省略了 | 在发出 `config.governance`． 审计接收器是一个列表(`audit.sinks[]`)，而不是标量。 |
| `observability` | 对象 | 省略了 | 在发出 `config.observability`. |
| `mcp` | 对象 | 省略了 | 在发出 `config.mcp`. |
| `plugins` | 数组 | 省略了 | 在发出 `config.plugins`，且仅当非空时。每个条目都包含 `id` 和一个 `source` 声明其中之一 `path` 或者 `oci`;每个条目的切换是 `disabled`,而不是 `enabled`. |
| `extraConfig` | 对象 | `{}` | 任意配置片段最后合并，因此其顶级键获胜。用于类型化部分未涵盖的任何内容的逃生舱口。 |

同样的最后获胜规则也适用于上一层： `extraSpec` 在 `Gateway` 合并 在组装的上面 `spec`，在键入的直通块之后 （`acceptedRouteNamespaces`， `podAnnotations`， `podLabels`， `resources`， `service`， `ingress`， `autoscaling`， `monitoring`， `networkPolicy`， `podDisruptionBudget`， `workloadIdentity`， `scheduling`， `probes`， `imagePullSecrets`）。

配置构建器的语义由不需要的单元测试覆盖 Node本身之外的依赖：

```bash
pnpm --filter ./iac/pulumi/components run build
node --test iac/pulumi/components/bin/config.test.js
```

## 执照

apache - 2.0。

## 看到也

-   [https://mcpg.dev/docs/self-hosting/pulumi](https://mcpg.dev/docs/self-hosting/pulumi) -使用Pulumi部署MCPG。
-   [https://mcpg.dev/docs/reference/operator-crds](https://mcpg.dev/docs/reference/operator-crds) -自定义资源这些 创建组件。
-   [https://mcpg.dev/docs/reference/configuration](https://mcpg.dev/docs/reference/configuration) -完整的网关 后面的配置模式 `spec.config`.
-   `iac/pulumi/crds` （键入的CRD SDK）和 `iac/pulumi/policy` (CrossGuard 策略包，在预览时验证这些资源)。

## 常见问题

### @mcpg-dev/pulumi 是什么？

针对MCPG（运营商、网关、租户、信任）的固执己见的Pulumi组件。

### 如何安装 @mcpg-dev/pulumi？

在项目目录运行 npm install @mcpg-dev/pulumi，或使用 pnpm add / yarn add / bun add。

### @mcpg-dev/pulumi 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @mcpg-dev/pulumi 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @mcpg-dev/pulumi 可以商用吗？

@mcpg-dev/pulumi 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @mcpg-dev/pulumi 还在维护吗？

最新版本 0\.1\.0-beta\.45 发布于 2026/11/02（1 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。