企业官网建设流程全解析

• CLI
• 开发工具
• 云原生

Kustomize 是一套面向 Kubernetes 的"模板无关、结构化定制"工具，围绕它形成了kustomization、base、overlay、variant、patch等一整套专属术语。本文以仓库中的官方术语表（site/content/en/docs/Reference/glossary.md）为主体骨架，逐条讲解这些术语的定义、使用场景与彼此关系，并结合当前仓库的源码与示例（如 api/types/kustomization.go、api/filters/patchjson6902/patchjson6902.go、examples/multibases）给出实现级佐证。读完本文，你将能准确使用 Kustomize 的术语体系，正确组织 base/overlay 目录结构、理解kustomize build的 target 语义、区分两种 patch 语法，并看懂kustomization.yaml中四类字段的职责划分。

核心对象与背景概念

kubernetes（k8s）

Kubernetes 是一套用于自动化部署、扩缩与运维容器化应用的开源系统，常缩写为k8s。Kustomize 的所有定制行为都围绕 k8s 对象展开，因此必须先理解"对象"的含义。

kubernetes-style object（Kubernetes 风格对象）

一个以 YAML 或 JSON 文件表达的、具备 Kubernetes 所要求字段的对象。本质上只需要三个字段即可构成一个可被识别的对象：

• kind：标识对象类型；
• metadata/name：标识具体实例；
• apiVersion：标识 API 版本（存在多个版本时用于区分）。

这也是后续resource（资源）定义的判定基础：任何带有kind与metadata/name字段的正确 YAML 文件，都可以作为 Kustomize 的处理对象。仓库中 api/ifc/ifc.go 等接口层即围绕"读取、持有、变换这类对象"来设计。

application（应用）

application指一组因共同目的而关联的 k8s 资源，例如"数据库后端 + Web 服务器 + 负载均衡器"。历史上，人们通过资源标签、命名与元数据方案将资源聚合在一起，以支持list、remove等集体操作。Kubernetes 社区曾提出过一种名为application的新资源类型，用于更正式地描述这一概念并为应用级操作与仪表盘提供支持；而在 Kustomize 视角下，这个提议中的 application 资源"只是另一个资源"，与 ConfigMap、Deployment 一样可被定制。

apply（应用）

在 k8s 语境中，动词apply指kubectl apply命令（以及一个演进中的 API 端点），用于变更集群状态。工作方式是：以"完整资源列表"的形式向集群提交一份期望状态声明；集群将这份声明与之前已 apply 的状态、实际状态三方合并，得出新的期望状态，再由集群的调谐循环（reconciliation loop）去落实。这正是 k8s 基于水位（level-based）状态管理的基石。Kustomize 的价值在于：为apply准备好这份"完整资源列表"。

declarative application management（声明式应用管理，DAM）

Kustomize 自视为 [Declarative Application Management] 这套"管理 k8s 集群最佳实践"的实现，其核心主张（在术语表中被凝练为 kustomize 应当做到的几点）：

• 能处理任意配置：自研（bespoke）、现成（off-the-shelf）、无状态、有状态等；
• 支持常见定制与变体的创建（如 development vs. staging vs. production）；
• 暴露并教授原生 k8s API，而不是把用户与底层 API 隔离开；
• 与版本控制集成零摩擦，支持评审与审计追踪；
• 以 Unix 风格与其他工具组合；
• 不越界去做模板化、领域专用语言（DSL）等会妨碍上述目标的事情。

gitops

DevOps 或 CI/CD 工作流的一种形态：以 git 仓库作为唯一事实来源，当该"事实"发生变化时触发构建、测试或部署等动作。术语表中特别指出：在简单的 gitops 管理下，一个 base 配置可以是"专为该用途而设的 git 仓库的唯一内容"，overlays 同理；仓库中的变更即可触发一次"构建 → 测试 → 部署"循环。这与仓库示例 examples/multibases/README.md 中"一个 base + 多个 overlay 变体"的目录组织方式天然契合。

kustomization 体系

kustomization

kustomization指kustomization.yaml文件，或更一般地指一个目录——即根目录及其内所有被该文件立即引用的相对路径文件（所有无需 URL 规范的本地数据）。因此，别人给你一份"kustomization"时，其交付形态可以是：

• 一个名为kustomization.yaml的文件；
• 一个 tarball（内含该 YAML 及其引用内容）；
• 一个 git archive（同上）；
• 一个指向 git 仓库的 URL（同上），等等。

kustomization.yaml中的字段可划分为四类，这一分类在源码 api/types/kustomization.go 的Kustomization结构体中有着一一对应的体现：

值得注意的是源码中同时标注了大量弃用字段：bases（改用resources）、imageTags（改用images）、patchesJson6902/patchesStrategicMerge（改用统一的patches）、vars（改用replacements）、commonLabels（改用labels）。Kustomization.FixKustomization()与FixKustomizationPreMarshalling()会自动完成这些迁移，例如把Bases并入Resources、把PatchesJson6902并入Patches；CheckDeprecatedFields()则会对仍使用弃用字段的配置输出 "Run 'kustomize edit fix' to update your Kustomization automatically." 的提示，可用kustomize edit fix自动修复。

kustomization root（kustomization 根目录）

指直接包含kustomization.yaml文件的目录。处理一份 kustomization 时，其能否访问根目录之外的文件受安全限制约束：

• 资源 YAML、用于 ConfigMap/Secret 的name=value文本、patch 文件等数据文件必须位于根目录内或之下，因此只能以相对路径引用；
• 其他 kustomization（其他含kustomization.yaml的目录）则可以通过 URL、绝对路径或相对路径引用。

这一限制的源码实现在 api/internal/loader/loadrestrictions.go：RestrictionRootOnly会检查目标文件d.HasPrefix(root)，不满足即报错security; file '%s' is not in or below '%s'；而 v2.1 引入的--load_restrictions none标志对应同文件中的RestrictionNone，直接放行任意路径，例如允许一个 patch 文件被多个 kustomization 共享（flag 定义见 kustomize/commands/build/build.go 的AddFlagLoadRestrictor）。

此外，若 kustomizationA依赖 kustomizationB，则：B 不能包含 A；B 不能依赖 A（即使传递依赖也不行）。A 可以包含 B，但此时更简单的做法往往是让 A 直接依赖 B 的资源、去掉 B 的kustomization.yaml（即把 B 吸收进 A）。惯例上 B 位于 A 的兄弟目录，或位于完全独立的、可被任意 kustomization 引用的 git 仓库中。

术语表给出的典型目录布局如下：

├── base │ ├── deployment.yaml │ ├── kustomization.yaml │ └── service.yaml └── overlays ├── dev │ ├── kustomization.yaml │ └── patch.yaml ├── prod │ ├── kustomization.yaml │ └── patch.yaml └── staging ├── kustomization.yaml └── patch.yaml

其中dev、prod、staging三个根目录（大概率）都引用了base根——具体需查看各自的kustomization.yaml才能确认。仓库中的 examples/multibases 正是这一布局的活样例：base/kustomization.yaml 只声明resources: [pod.yaml]，而 dev/kustomization.yaml 以resources: [- ../base]引用 base 并叠加namePrefix: dev-。术语表中 "root" 条目即指向本概念。

base（基础）

base是被其他 kustomization 引用的 kustomization。任何 kustomization——包括 overlay——都可以作为另一 kustomization 的 base。base不知道有哪些 overlay 引用它（单向依赖，无反向感知）。

在 examples/multibases/README.md 中可看到完整的 base + 多变体演示：一个只含单个 Pod 的 base，被dev、staging、production三个 overlay 分别引用并加上不同的namePrefix；甚至还可以再做一层"组合 overlay"，把三个变体作为 base 引入并统一加namePrefix: cluster-a-，从而对"不在你控制之下的 base"应用公共标签或最左前缀。

overlay（叠加层）

overlay是依赖另一个 kustomization的 kustomization。overlay 所引用的 kustomization（通过文件路径、URI 或其他方式）称为其 bases。要点：

• overlay 离开 base 便不可用；
• overlay 本身也可作为另一个 overlay 的 base（可多层叠加）；
• overlay 在有多个时最有意义，因为它们基于公共 base 制造出不同变体——例如 development、QA、staging、production 环境变体。这些变体复用同一套资源，仅以相对简单的方式变化：Deployment 的副本数、某 Pod 的 CPU、ConfigMap 中的数据源等。

配置集群的典型方式是把 overlay 作为 target 构建并交给 apply：

kustomize build someapp/overlays/staging |\ kubectl apply -f - kustomize build someapp/overlays/production |\ kubectl apply -f -

base 的使用是隐式的——由 overlay 的 kustomization 指向 base 即可。参见 kustomization root。

variant（变体）

variant是将 overlay 应用到 base 之后、在集群中呈现的结果。例如 staging 与 production 两个 overlay 都修改某个公共 base，从而产生不同的变体：

• staging 变体：暴露给质量保证测试、或希望预览下一版 production 的外部用户的那组资源；
• production 变体：暴露给生产流量的那组资源，因此可能使用大副本数的 Deployment 与更高的 CPU、内存请求。

target（构建目标）

target是kustomize build的参数：

kustomize build $target

$target必须是某个 kustomization 的路径或 URL，包含或引用生成"可发送给 apply 操作的定制资源"所需的全部信息。target 可以是 base 或 overlay。在 kustomize/commands/build/build.go 中，Validate限制只接受一个路径参数（省略时默认.），并支持 git 仓库 URL 加路径后缀的形式（如https://github.com/kubernetes-sigs/kustomize.git/examples/helloWorld?ref=v1.0.6）；RunE通过krusty.MakeKustomizer(...).Run(fSys, path)完成构建。

bespoke configuration（自研配置）

bespoke配置是某组织内部为自己目的创建和维护的 kustomization 与资源。其工作流比 off-the-shelf 配置简单，因为没有"周期性吸收他人对现成配置的升级"这一概念。

off-the-shelf configuration（现成配置）

off-the-shelf配置是有意公开发布供他人使用的 kustomization 与资源。例如创建一个这样的 git 仓库：

github.com/username/someapp/ kustomization.yaml deployment.yaml configmap.yaml README.md

他人可以 fork 该仓库并 clone 到本地进行定制，这个 clone 可作为用户自己 overlays 的 base。仓库中的 examples/helloWorld（含kustomization.yaml、deployment.yaml、service.yaml、configMap.yaml）就是可被当作 base 引用的典型结构。

package（包）

package一词在 Kustomize 中没有含义——Kustomize 不是 apt、rpm 那样的包管理工具，请勿混淆。

资源生成与变换

resource（资源）

在 RESTful API 语境下，resource是 HTTP 操作（GET、PUT、POST 等）的目标对象，k8s 提供 RESTful API 面与客户端交互。在 kustomization 语境下，resource是：

• 一个描述 k8s API 对象（如 Deployment、ConfigMap）的 YAML 或 JSON 文件的、相对根目录的路径；
• 或一个指向 kustomization 的路径；
• 或一个解析到 kustomization 的 URL。

更一般地，任何带kind与metadata/name字段、定义对象的正确 YAML 文件都可视为资源。对应源码见 api/types/kustomization.go 的Resources []string字段注释："relative paths to files holding YAML representations of kubernetes API objects, or specifications of other kustomizations via relative paths, absolute paths, or URLs"。

generator（生成器）

generator生成可直接使用的资源，或生成后交给 transformer 进一步处理。内置生成器的实现示例：

• ConfigMapGenerator.go / configmap.go：由本地数据生成 ConfigMap；
• SecretGenerator.go / secret.go：由本地数据生成 Secret；
• HelmChartInflationGenerator.go：由 Helm Chart 展开资源。

按 api/types/kustomization.go 的注释，生成的 ConfigMap/Secret 是普通操作数（operand），同样受 namePrefix、patch 等处理，且默认名称会带内容哈希后缀。

transformer（转换器）

transformer可以修改资源，也可以在kustomize build过程中仅访问资源并收集其信息。它是"对资源做什么"的一类操作。内置转换器以"Transformer"结尾的 builtin 插件形式存在于 api/internal/builtins，例如 PrefixTransformer.go、ImageTagTransformer.go、NamespaceTransformer.go；其过滤器实现位于 api/filters（如 labels、namespace、imagetag 等子目录）。术语表把namePrefix、nameSuffix、images、commonLabels、patchesJson6902等字段归入 transformers 类别，源码中它们对应的正是这批 transformer 的实现。

plugin（插件）

plugin是 Kustomize 使用的代码块，不一定要编译进 Kustomize 二进制，其职责是在一次 kustomization 中生成和/或变换某个 Kubernetes 资源。仓库的 plugin 目录展示了两种形态：

• plugin/builtin：内置插件（annotationstransformer、configmapgenerator、imagetagtransformer 等，每个目录含 go.mod 与实现源码）；
• plugin/someteam.example.com/v1：按"域名/版本"组织的外部插件样例。

内置插件的注册与加载逻辑见 api/internal/plugins（builtinconfig、builtinhelpers、execplugin、fnplugin、loader 等子包）。源码 api/types/kustomization.go 中的Generators、Transformers、Validators三个字段（v2.1）即用于挂载这类自定义插件文件。

补丁（patch）机制

patch（补丁）

patch是修改资源的通用指令，存在两种能力相近但记法不同的技术：strategic merge patch 与 JSON patch。在kustomization.yaml中，现代推荐写法是统一的patches字段（源码 api/types/kustomization.go 的Patches []Patch，"each one can be either a Strategic Merge Patch or a JSON patch, and each patch can be applied to multiple target objects"），旧的patchesStrategicMerge、patchesJson6902字段已被标记弃用并会在构建时自动迁移。

patchStrategicMerge（策略合并补丁，SMP）

patchStrategicMerge即 strategic-merge 风格补丁。SMP 看起来像一个不完整的 k8s 资源 YAML 描述：包含用于定位目标资源 group/version/kind/name 的TypeMeta字段，再加上恰好足够进入嵌套结构、指定新字段值（如镜像 tag）的其余字段。

默认行为是替换值——当目标值是简单字符串时通常正是所需，但当目标值是列表时可能不符合预期。要改变默认行为，可添加指令（directive）；YAML 补丁中识别的指令有replace（默认）与delete。需要注意：对自定义资源（CR）而言，SMP 会被当作 [JSON merge patch] 处理。

一个有趣的特性：任何资源文件都可以当作 SMP 使用——它会覆盖另一个同 group/version/kind/name 资源中的匹配字段，其余字段保持不变。源码实现见 api/filters/patchstrategicmerge/patchstrategicmerge.go：通过merge2.Merge将补丁节点与目标节点合并（列表方向为 prepend），从而支持节点删除等语义。

patchJson6902（JSON 补丁）

patchJson6902指一个 Kubernetes resource 加一份描述如何修改该资源的 [JSONPatch]（RFC 6902）。它能完成 patchStrategicMerge 几乎所有能做的事，但语法更简练。仓库中有完整可运行示例 examples/jsonpatch.md：以Ingress为例，补丁文件是一组op/path/value操作（replace、add），并通过patches字段配合target（group/version/kind/name）定位对象：

patches: - path: ingress_patch.json target: group: networking.k8s.io version: v1beta1 kind: Ingress name: my-ingress

补丁内容示例（JSON 格式，也可用 YAML 书写，规则不变）：

[ {"op": "replace", "path": "/spec/rules/0/host", "value": "foo.bar.io"}, {"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/servicePort", "value": 80}, {"op": "add", "path": "/spec/rules/0/http/paths/1", "value": { "path": "/healthz", "backend": {"servicePort":7700} }} ]

运行验证：

kustomize build $DEMO_HOME >out_actual.yaml diff out_actual.yaml out_expected.yaml

源码实现见 api/filters/patchjson6902/patchjson6902.go：补丁若不以[开头则先经YAMLToJSON转成 JSON，再交给gopkg.in/evanphx/json-patch.v4的DecodePatch/Apply执行（该实现会先序列化为 JSON 再应用，因此不保证字段顺序）。

其他术语

custom resource definition（自定义资源定义，CRD）

通过创建 Custom Resource Definition（CRD）可以扩展 k8s API，定义一种全新的自定义资源（术语表中写作 CD），可与 ConfigMap、Deployment 等原生资源并列使用。Kustomize 可以定制自定义资源，但前提是必须同时提供对应的 CRD，以便正确解释其结构。对应源码为 api/types/kustomization.go 的Crds []string字段（"relative paths to Custom Resource Definition files. This allows custom resources to be recognized as operands, making it possible to add them to the Resources list. CRDs themselves are not modified."），实际加载逻辑见 api/internal/accumulator/loadconfigfromcrds.go，它会把 CRD 中的 OpenAPI 结构并入 kustomize 的 schema 解释能力。

sub-target / sub-application / sub-package

"sub-什么"都不是一个正式概念——在 Kustomize 的术语体系中只有 bases 和 overlays。任何"子"依赖关系都应表达为这两个概念之一。

快速对照速查

掌握这套术语，是正确阅读 Kustomize 文档、设计 base/overlay 目录、理解kustomize build行为与 patch 语法的基础；本文所述的每个概念都能在仓库的源码与示例中找到对应实现，可作为后续深入学习的索引。

• CLI
• 开发工具
• 云原生