# FDE 别再为每个客户复制一份 YAML

> 一个共享 base，每个客户一个只记录差异的小 overlay，上游修复只需改一次。

原文: https://fdetimes.net/zh/tools/kustomize-base-overlays-for-fdes/

2018 年 5 月 29 日，Google 的 Jeff Regan 和 Phil Wittrock 在 Kubernetes 博客上介绍 kustomize 时，开篇就讲了一个每位前线部署工程师（FDE）都遇到过的场景：复制几份描述 API 对象的 YAML 文件，再按自己的需要修改。

此时一切还正常。麻烦出在后面：原始文件有了改进，你却没有简便的办法把这些改进合并到自己的副本里。

对 FDE 来说，每来一个新客户，这件事就重复一次。设想一下：第一个客户需要 3 个副本，第二个需要更多内存，第三个运行在自己的 namespace 里。到第五个客户时，仓库里已经有五个几乎一模一样的 YAML 目录，没人能确定它们到底在哪几行不同。

Kustomize 提供了一条跳出这个循环的路，而且不用学模板语言。如果你正在或即将把同一个产品部署给多个客户，值得在写第十个 Helm chart 之前先学会它。

## 这个工具到底做什么？

Kubernetes 文档把 Kustomize 描述为一个独立工具，通过 kustomization 文件定制 Kubernetes 对象。它也内置在 kubectl 中：从 1.14 版本起，kubectl 就能读取包含 kustomization 文件的目录。只要 kubectl 是这个版本或更新版本，不必额外安装任何东西，就能渲染和应用 overlay。

区别在于理念。kubernetes-sigs/kustomize 项目的 README 强调，这个工具直接处理原始 YAML，不用模板，也不改动原始文件。2018 年那篇介绍文章的标题就叫“免模板的配置定制”。你的 YAML 始终是任何人都能读懂的合法 YAML，里面不会混进花括号。

## 三个概念，对应客户现场的三样东西

官方术语表定义了三个概念，它们和 FDE 的工作一一对应。base 是共同的部分。按照 SIG CLI 文档的说法，overlay 只是另一个 kustomization，它指向 base 以及要应用到 base 上的补丁。

variant 是 overlay 应用到 base 之后在集群中得到的结果。用 FDE 的话说，一个 variant 就是一个客户的部署。SIG CLI 文档用一个共享 base 生成 dev、staging 和 production 三个 variant，同样的机制也完全适用于客户 A、客户 B 和客户 C。

**要点:** base 存放共享部分，overlay 只记录差异，variant 是客户实际运行的东西。

## 最小示例：两个客户，一个 base

假设你的产品有一个名为 api 的 Deployment。客户 Acme 需要 3 个副本，客户 Beta 使用默认值。目录结构可以是这样：

```
base/
  deployment.yaml
  kustomization.yaml
overlays/
  acme/
    kustomization.yaml
    replicas.yaml
  beta/
    kustomization.yaml
```

Acme 的 overlay 只需指向 base 并声明补丁：

```yaml
# overlays/acme/kustomization.yaml
resources:
  - ../../base
patches:
  - path: replicas.yaml
```

```yaml
# overlays/acme/replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
```

Acme 与标准产品的全部区别，就在这个补丁文件的六行里。Kubernetes 文档也建议使用小而单一用途的补丁，比如副本数单独一个补丁。当上游在 base 中加入 liveness probe 时，你只需改一个文件，然后 `kubectl apply -k overlays/acme` 和 `kubectl apply -k overlays/beta` 就会把改动带给两个客户。

这正是对 2018 年那篇介绍所描述问题的回答：上游修复不必再手工复制到每份副本里。

还有一个附带好处。客户问自己的版本和标准版有什么不同时，答案就是他们的 overlay 目录。移交给客户运维团队时，这也是最先值得审查的内容。

## 不用模板，失去了什么？

Kustomize 的长处和局限来自同一个选择。没有模板，就写不了循环或条件，比如“如果客户启用了功能 X，就再生成三个对象”。每一处差异都必须表达为针对真实 base 的补丁。

因此补丁与 base 的结构紧密绑定。Kubernetes 文档指出，目标资源是按补丁文件中的 group、version、kind 和 name 匹配的。base 一旦给某个资源改名，给它打补丁的 overlay 也会随之失准。所以要像对待内部 API 一样对待 base：谨慎修改，合并前重新渲染每个 overlay。

如果客户配置按参数变化很大，模板工具可能更合适。但在最常见的 FDE 场景里，即同一个产品、每个客户有少量差异，没有模板反倒是优点：任何人打开 overlay，都能立刻看出为这个客户改了什么。

## 补丁写错了，不一定会报错

最容易犯的错，是补丁里有拼写错误，却以为已经改好了。错在资源名还是字段名，后果大不相同。

资源名写错时，比如补丁指向 `my-app`，而 base 中并没有这个名字的 Deployment，通常会立刻看到报错。Kubernetes 论坛上的一则报告记录了构建中止，提示信息为“failed to find unique target for patch”。

但一个社区 wiki 提醒，某些类型的补丁在匹配不到任何资源时会被直接跳过，既不报错也不警告。这种行为取决于补丁类型和 kustomize 版本。

字段名写错时，比如把 `replicas` 写成 `replica`，API server 不认识这个字段，结果取决于校验。kubectl 默认启用严格的服务端校验，因此 `kubectl apply` 通常会拒绝未知字段。

如果用 `--validate=false` 关闭了校验，或者集群版本较旧，又或者用的工具有自己的默认设置，这个错误字段可能只产生一条警告，或被悄悄丢弃。于是 Acme 仍以默认副本数运行，渲染或 diff 中 replicas 也依然没有变化。

## 看渲染结果，而不是补丁文件

第二个错误是在看到最终 YAML 之前就直接应用到客户集群。防范办法很简单：每次应用前，尤其是 base 刚改过之后，运行两条命令。

```
kubectl kustomize overlays/acme
kubectl diff -k overlays/acme
```

第一条打印 overlay 应用后的全部资源，在 api Deployment 中找 `replicas: 3` 这一行。第二条比较集群当前状态和应用后的状态。同一个社区 wiki 也建议在 CI 中为每个 overlay 运行这一步构建加 diff；在多客户仓库里，就应该这么做。

## 当 overlay 长成第二个 base

第三个错误更难察觉：某个客户的 overlay 越来越臃肿，最后变成第二个 base。这时你又回到了复制 YAML 的老问题，只是目录换了名字。

当两个 overlay 带着同一组补丁时，就说明这组补丁应该放进 base。

## 先学什么，如何展示

首先，吃透 base、overlay 和 variant，养成应用前先渲染、先 diff 的习惯。然后练习为客户间常见的差异字段写补丁，比如 replicas、resources 和 env。到了客户现场，第一件值得做的事是找出那些被复制后修改过的 YAML，把它们合并到一个 base 中。

面试那些要把同一产品部署给多个客户的 FDE 岗位时，可以直接问团队如何管理每个客户的配置。答案会告诉你，这项技能是否从第一天起就用得上。

简历上真正有分量的不是“熟悉 Kustomize”，而是数字：多少个客户共用一个 base，删掉了多少个手工复制的文件。

## 用 Acme 示例做一个 20 分钟练习

在本机重建上面的目录结构。第一步：把 `replicas.yaml` 中的 `name: api` 改成 `name: apii`，运行 `kubectl kustomize overlays/acme`，记下得到的是报错，还是一份没有任何变化的渲染结果。

第二步：恢复正确的名字，把 `replicas` 改成 `replica`，再次渲染，查看输出中的 api Deployment：出现的是哪个字段，`replicas` 的值是多少。如果有测试集群，再运行 `kubectl diff -k overlays/acme`，看服务端如何处理这个未知字段。

第三步：改正错误，渲染，直到在输出中看到 `replicas: 3` 为止。

这三次渲染能教会你补丁文件本身永远不会告诉你的事：补丁对不对，只有在输出里才看得出来。只有亲眼在渲染结果中看到客户的改动，才可以信任一个 overlay。

**本周动手试试:**

- 挑一个有两份近乎相同 YAML 副本的服务，把共享部分提取到 base/，把差异移到两个 overlay 中
- 在 base 中改一处，对两个 overlay 分别运行 kubectl kustomize，再运行 kubectl diff -k，确认改动到达了两个客户
- 在简历上加一行带数字的描述：多少个客户共用一个 base，删掉了多少个 YAML 文件

## 信源

- [Declarative Management of Kubernetes Objects Using Kustomize](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/)

- [Introducing kustomize; Template-free Configuration Customization for Kubernetes](https://kubernetes.io/blog/2018/05/29/introducing-kustomize-template-free-configuration-customization-for-kubernetes/)

- [GitHub - kubernetes-sigs/kustomize: Customization of kubernetes YAML configurations](https://github.com/kubernetes-sigs/kustomize)

- [Kustomize (SIG CLI documentation)](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/)

- [Glossary (SIG CLI, Kustomize Reference)](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/)

- [Kustomize - “failed to find unique target for patch …”](https://discuss.kubernetes.io/t/kustomize-failed-to-find-unique-target-for-patch/10582)

- [Kustomize Footguns (GrokDevOps Wiki)](https://grokdatum.github.io/grokdevops-wiki/library/topics/kustomize/footguns)

- [Kubernetes API Concepts (Field validation)](https://kubernetes.io/docs/reference/using-api/api-concepts/)
