Kustomize 配置合并实战：用 base + overlay 混合管理模式融合 DevOps 与开发者的配置数据

CLI开发工具云原生【免费下载链接】kustomizeCustomization of kubernetes YAML configurations项目地址https://gitcode.com/gh_mirrors/ku/kustomize点击查看免费下载导读在大型 Kubernetes 项目中不同环境的配置往往由不同角色共同维护DevOps/SRE 关注生产环境的敏感数据与基础设施参数而开发团队注册、结账、搜索等需要随时调整开发环境的行为。本指南基于 kustomize 仓库中的 combineConfigs 示例完整演示如何通过属性分片Property Sharding base/overlay 混合管理模式Mixin Approach把多团队、多环境的配置数据组织为可复用、可审计、可自动化的声明式配置。读完本文你将掌握如何用configMapGenerator、namePrefix/nameSuffix、behavior: merge与内容哈希命名实现一份公共配置 每环境差异化覆盖并理解 kustomize 在底层是如何生成、合并与命名 ConfigMap 的。场景多团队共同维护的多环境 Java 服务设想一个基于 Java 的在线商店服务运行在development开发、testing测试、staging预发和production生产四个环境中配置参数来自 Java properties 文件。随着团队增多为每个环境维护一个巨大的 properties 文件变得难以管理文件改动频繁且必须由 DevOps 独占修改因为文件中至少有一部分取值是 DevOps 关心、而开发者无需知晓的例如负载均衡端口、日志落点生产环境的 properties 包含敏感数据如生产数据库凭据不能对开发者开放。问题的本质是同一份文件里混合了不同所有权ownership的数据。解决的思路是先把属性按职责分片再用 kustomize 的 base/overlay 机制按环境重组。属性分片Property Sharding把配置按所有权切分观察后可以发现全部属性可以分成三类分别对应不同的变更频率和访问权限。Common properties全环境一致国际化数据、物理常量、外部服务地址等静态数据无论哪个环境取值都一样只需要维护一份。放在common.properties中。Plumbing properties环境差异的根源静态内容HTML/CSS/JS的提供位置、产品与用户数据表的位置、负载均衡期望的端口、日志收集器等这些属性的不同取值恰恰定义了环境之间的差异DevOps/SRE 要完全控制生产环境的取值测试环境使用固定的测试数据库开发者希望随心所欲地在开发环境尝试各种场景。分别放入development/plumbing.propertiesstaging/plumbing.propertiesproduction/plumbing.propertiesSecret properties仅 DevOps 可见用户表真实位置、数据库凭据、解密密钥等是 DevOps 控制的子集其他任何人都不应有也不应有权限有访问权。分别放入development/secret.propertiesstaging/secret.propertiesproduction/secret.properties访问控制手段可以是 unix 文件属主与权限位更好的做法是把密码放入专用密钥管理服务并在 kustomization 中使用secretGenerator字段生成 Kubernetes Secret 来承载它们本示例不展开注释中给出了secretGenerator的示意指定name、files与type: kubernetes.io/tls即可生成 TLS 类型的 Secret。从源码结构看configMapGenerator与secretGenerator共用同一套生成参数api/types/generatorargs.go中GeneratorArgs同时被 ConfigMap 和 Secret 生成器使用而KvPairSources见 api/types/kvpairsources.go统一支持literals、files、envs三种键值来源。混合管理方法n 个 overlay 共享一个 base创建共享部分公共信息的n个集群环境的通用做法是针对公共 base 创建n个 overlay。每个集群环境由对某个恰好是 [overlay] 的 [target] 运行kustomize build产生。为简洁本示例只做n2development与production增加环境只是同样的模式重复。示例将聚焦 ConfigMap 的构建不展开 ConfigMap 如何挂载到 Deployment那是 helloWorld 示例 的内容。所有文件——包括前面讨论的共享 properties 文件——都按 base vs overlay 的目录布局组织在同一个工作目录中DEMO_HOME$(mktemp -d)第一步创建 basebase 按定义存放所有环境共有的资源。这里只定义一个 Java properties 文件以及引用它的kustomization文件mkdir -p $DEMO_HOME/base cat EOF $DEMO_HOME/base/common.properties colorblue height10m EOF cat EOF $DEMO_HOME/base/kustomization.yaml configMapGenerator: - name: my-configmap files: - common.properties EOF这里的核心是configMapGenerator它声明式地描述从文件生成 ConfigMap而不是手写 ConfigMap 资源。files列表中每一项形如[{key}]{path}省略key时以文件 basename 作为键名提供key时可自定义键名解析逻辑见 api/internal/generators/utils.go 中的ParseFileSource。第二步创建并应用developmentoverlayOVERLAYS$DEMO_HOME/overlays mkdir -p $OVERLAYS/development cat EOF $OVERLAYS/development/plumbing.properties port30000 EOF cat EOF $OVERLAYS/development/secret.properties dbpasswordmothersMaidenName EOF cat EOF $OVERLAYS/development/kustomization.yaml resources: - ../../base namePrefix: dev- nameSuffix: -v1 configMapGenerator: - name: my-configmap behavior: merge files: - plumbing.properties - secret.properties EOF注意三个关键字段resources: - ../../base声明本 overlay 以 base 为底namePrefix: dev-与nameSuffix: -v1给所有生成资源的名称加前后缀behavior: merge与 base 中同名生成器my-configmap的结果合并而不是替换。behavior的可选值create/replace/merge缺省视为create定义在 api/types/generationbehavior.go其字符串到枚举的映射由NewGenerationBehavior完成。merge的语义是以 base 生成的内容为底把 overlay 提供的键值合并进去因此最终 ConfigMap 同时包含color、height、port、dbpassword四个键——这正是公共 差异化的落点。现在生成开发环境的 ConfigMapkustomize build $OVERLAYS/development检查生成的 ConfigMap 名称输出中可以看到生成的 ConfigMap 名称类似dev-my-configmap-v1-2gccmccgd5其组成可以拆解为名称片段来源dev-namePrefix字段my-configmapconfigMapGenerator/name字段-v1nameSuffix字段-2gccmccgd5kustomize 根据 ConfigMap内容计算出的确定性哈希这个哈希后缀是关键设计只要 ConfigMap 内容变化名称就会变化kustomize输出 YAML 中对该名称的所有引用也会随之更新。这正是 Kubernetes 中 ConfigMap 更新的惯用手段——名称变了Deployment 才会感知变化。从源码看哈希并非随机api/hasher/hasher.go中的Hasher.Hash对 ConfigMap 的kind、metadata/name、data、binaryData字段序列化为 JSON 后计算 SHA-256再取十六进制前 10 位并把0/1/3/a/e映射为g/h/k/m/t等字母encode函数避免以数字开头的名称问题。因此同样的内容永远得到同样的后缀内容一变后缀必变。ConfigMap 不可变与滚动重启名称变化意味着如果把该 YAML 用如下命令应用到集群Deployment 会因 ConfigMap 名称变化而滚动重启以加载新数据kustomize build $OVERLAYS/development | kubectl apply -f -因为 Deployment 没有手段自动感知其正在使用的 ConfigMap 是否改变如果改了 ConfigMap 内容却不改名称及所有引用就必须手工重启 Pod 才能生效。因此最佳实践是将 ConfigMap 视为不可变对象immutable不要编辑已有的 ConfigMap而是修改集群期望状态的声明式描述让 Deployment 指向新名称的新 ConfigMapkustomize的configMapGenerator指令与命名控制前缀/后缀/哈希让这一过程完全自动化。如需清理过期 ConfigMap可以给资源打上清理标签例如kustomize-cleanuptrue然后用kubectl的 prune 能力按标签回收kustomize build | kubectl apply --prune -f- -l kustomize-cleanuptrue另外kustomize 还支持在configMapGenerator的options中设置immutable: true在生成的资源上直接写入immutable: true字段见 api/internal/generators/utils.go 的setImmutable从资源定义层面强化不可变约定。第三步创建并应用productionoverlay生产 overlay 与开发 overlay 结构一致但使用生产取值且省略nameSuffixmkdir -p $OVERLAYS/production cat EOF $OVERLAYS/production/plumbing.properties port8080 EOF cat EOF $OVERLAYS/production/secret.properties dbpasswordthisShouldProbablyBeInASecretInstead EOF cat EOF $OVERLAYS/production/kustomization.yaml resources: - ../../base namePrefix: prod- configMapGenerator: - name: my-configmap behavior: merge files: - plumbing.properties - secret.properties EOF生成生产环境的 ConfigMapkustomize build $OVERLAYS/productionCI/CD 流程可直接将输出应用到集群kustomize build $OVERLAYS/production | kubectl apply -f -底层原理configMapGenerator 是如何工作的理解了实操再看底层实现可以加深认识。configMapGenerator的声明最终转化为 api/types/configmapargs.go 中的ConfigMapArgs其内嵌的GeneratorArgsapi/types/generatorargs.go包含name生成资源的部分名称完整名称是NamePrefix name hash(内容)namespace可选命名空间behaviorcreate/replace/merge三者之一KvPairSourcesliterals形如keyvalue、files文件路径键默认取 basename、envs形如.env的键值对文件options局部覆盖全局generatorOptions可设置标签、注解与immutable。实际生成逻辑在 api/internal/generators/configmap.go 的MakeConfigMapmakeBaseNode构造apiVersion: v1, kind: ConfigMap骨架并写入名称/命名空间makeValidatedDataMap加载全部键值对校验键名合法性字母数字及-、_、.并拒绝重复键——这正是behavior: merge之上还有一层安全网在同一生成器内部重复定义同一键会直接报错见 api/internal/generators/utils.go将数据写入 ConfigMap 的data字段应用options中的标签与注解视immutable选项写入immutable: true。示例中被合并的三个 properties 文件彼此键不重叠color/height、port、dbpassword因此合并过程干净无冲突如果开发者与 DevOps 在 overlay 里定义了相同的键kustomize 会以 overlay 覆盖 base 的对应键在 base/overlay 的叠加语义中 overlay 优先这也是混合管理模式中devops 全权控制生产值的机制保证。目录布局回顾与扩展完成上述步骤后工作目录呈现如下结构$DEMO_HOME ├── base │ ├── common.properties # 全环境公共配置 │ └── kustomization.yaml # configMapGenerator: my-configmap └── overlays ├── development │ ├── plumbing.properties │ ├── secret.properties │ └── kustomization.yaml # namePrefix: dev-, nameSuffix: -v1, behavior: merge └── production ├── plumbing.properties ├── secret.properties └── kustomization.yaml # namePrefix: prod-, behavior: merge增加testing、staging环境只需按同样模式各建一个 overlay 目录、提供各自的 plumbing/secret 文件即可。这一布局与 helloWorld 示例 中的 base/overlay 约定完全一致且本示例在仓库中由 hack/testExamplesAgainstKustomize.sh 等测试脚本持续验证可放心照做。要点总结所有权决定组织方式把配置按 common / plumbing / secret 分片common 进 baseplumbing 与 secret 按环境进 overlay敏感数据与普通数据物理隔离base overlay 是环境复用的骨架n 个环境 1 个 base n 个 overlay每个环境是一个可独立kustomize build的 targetbehavior: merge完成数据合并公共配置与差异化配置在生成 ConfigMap 时融合overlay 中的同名键覆盖 base内容哈希命名是变更传播的关键ConfigMap 内容一变、名称即变、引用即变从而触发 Deployment 滚动更新无需手工重启把 ConfigMap 视为不可变用新名称的新 ConfigMap 代替就地编辑配合--prune -l清理过期资源CI/CD 友好kustomize build ... | kubectl apply -f -一步完成渲染与应用且所有产物均由声明式文件确定性生成便于评审与回滚。如需进一步阅读可继续查看仓库中的 combineConfigs 英文原文档、中文翻译、helloWorld 基础示例 以及 examples 目录总览。赞分享CLI开发工具云原生【免费下载链接】kustomizeCustomization of kubernetes YAML configurations项目地址https://gitcode.com/gh_mirrors/ku/kustomize点击查看免费下载相关推荐ESLint 配置组合实战用 extends 合并配置对象与配置数组ESLint 配置组合实战用 extends 合并配置对象与配置数组 在实际项目中 eslint.config.js 很少完全从零手写你通常会将社区预定义开发工具Lint静态分析代码质量BenchmarkDotNet 配置联合ConfigUnion实战深入理解本地配置与全局配置的合并规则BenchmarkDotNet 配置联合ConfigUnion实战深入理解本地配置与全局配置的合并规则 本篇技术指南围绕 BenchmarkDotNet性能测试开发工具Hydra 配置组合Composition实战用 Defaults List 拼装数据库、UI 与数据模式的 N 维配置Hydra 配置组合Composition实战用 Defaults List 拼装数据库、UI 与数据模式的 N 维配置 本指南围绕 Hydra 的配置组开发工具后端CLI上一篇如何快速掌握 Laf.js 云函数处理 HTTP 请求的核心技巧下一篇Auto_Bangumi项目文件重命名功能详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考