导读

本文以 architecture-decision-record 仓库中西班牙语示例文档 Orquestación de contenedores con Kubernetes 为核心，完整讲解一份"容器编排平台选型"类架构决策记录（ADR）的撰写骨架：问题陈述、备选方案、决策结论与论证理由。在此基础上，结合仓库内的 ADR 基础概念文档、文件命名约定、写作建议与多套决策记录模板，帮你理解如何把一次真实的技术选型（Docker Swarm vs Kubernetes vs Apache Mesos）沉淀为可追溯、可复用、可评审的架构知识资产。读完本文，你将能够复刻并改写一份属于自己的 Kubernetes 选型 ADR，并知道如何用 git 管理这些决策文件。

一、这份 ADR 示例在仓库中的位置

architecture-decision-record 是一个以"架构决策记录"为核心的开源仓库，内容分为三大类：示例（examples/ejemplos）、模板（templates/plantillas）与文档（documents/documentos），并面向多种语言维护同一套内容。

• 西班牙语示例索引位于 locales/es-001/ejemplos/index.md，其中"Orquestación de contenedores específica"小节将容器编排示例细分为两条：Docker Swarm 与 Kubernetes 各一份 ADR；
• 本次讲解的 Kubernetes 选型 ADR 位于 locales/es-001/ejemplos/orquestación-de-contenedores-con-kubernetes/README.md，同目录下还有一个内容一致的index.md（仓库惯例是 README 与 index 双份镜像，便于不同入口引用）；
• 英文源版本位于 locales/en-001/examples/kubernetes-container-orchestration/index.md，可对照阅读原文措辞。

这份文档属于"ChatGPT 生成后经人工编辑"的示例型 ADR（文档末尾有<h6>Crédito: esta página fue generada por ChatGPT...的署名标注），其价值不在于结论本身，而在于展示一份结构完整、理由充分的决策记录应该如何组织。

二、ADR 基础：这份文档在记录什么

仓库的西班牙语文档 ¿Qué es un registro de decisión de arquitectura? 给出了 ADR 领域的基本概念框架：

• ADR（Architecture Decision Record，架构决策记录）：记录一项重要架构决策及其上下文与后果的文档；
• AD（Architecture Decision，架构决策）：一个回应重大需求的软件设计选择；
• ADL（Architecture Decision Log，架构决策日志）：某个项目或组织维护的全部 ADR 集合；
• ASR（Architecturally-significant Requirement，架构意义重大的需求）：对软件系统架构有可度量影响的需求；
• AKM（Architecture Knowledge Management，架构知识管理）：上述内容所属的学科领域。

Kubernetes 选型正是一项典型的 AD：它响应"云原生应用组合规模持续增长、现有部署平台过慢且敏捷性不足"这一 ASR，因此值得用 ADR 形式记录。仓库将这份记录放在ejemplos/目录下，正是为了给"如何写决策记录"提供可模仿的范例。

三、原文核心内容：问题陈述、备选方案与决策结论

3.1 问题陈述（Planteamiento del problema）

原文档用一段话界定决策的触发背景：

我们需要为不断增长的云原生应用组合选择一款容器编排平台。当前在遗留平台上的部署过于缓慢，敏捷性不足以跟上不断增长的需求。我们期望找到一套系统，能够在兼顾敏捷性与易用性的前提下，以最高效的方式扩展我们的服务。

这段陈述遵循了"写好 ADR"的仓库建议（见 sugerencias-para-escribir-buenos-adr）中的"Contexto"要求：说明组织现状（遗留平台慢）、业务优先级（高效扩缩、保持敏捷）、以及决策动机（跟上云原生组合的增长）。它没有罗列技术细节，而是先讲清"为什么现在必须做这个决定"。

3.2 备选方案（Alternativas consideradas）

原文档列出了三个候选平台：

1. Docker Swarm—— Docker 官方出品的集群编排方案；
2. Kubernetes—— 由 CNCF 托管的开源容器编排平台；
3. Apache Mesos—— 面向大规模集群资源调度的分布式系统内核。

仓库中恰好还有一份"反方向"的平行示例 Orquestación de contenedores con Docker Swarm，它从另一个团队视角选了 Docker Swarm，并补充了候选清单中的Mesosphere DC/OS（Mesos 的商用发行版）。两份文档对照阅读，能直观看到"同一类决策、不同结论、不同论证结构"的写法差异——这正是决策记录示例库的价值。

3.3 决策结论（Decisión tomada）与四条理由

原文档的结论是：采用 Kubernetes 作为企业级容器编排平台，并给出四条理由，必须完整保留：

1. 可扩展性（Escalabilidad）：Kubernetes 独特的设计非常适合应用扩展；随着未来扩展需求的变化，Kubernetes 具备内建能力，可以无摩擦地应对这些变化。
2. 去中心化架构（Arquitectura descentralizada）：Kubernetes 的 master-worker（主-工作节点）拓扑保证了去中心化架构，从而确保不存在单点故障（single point of failure）。
3. 社区支持（Apoyo de la comunidad）：Kubernetes 拥有规模最大、最活跃的开源社区，意味着有大量的贡献者、开发者与厂商，更容易获得帮助和找到资源。
4. 生态支持（Apoyo del ecosistema）：Kubernetes 拥有持续增长的生态系统，涵盖各种第三方工具、与容器镜像仓库（container registries）的集成、CI/CD 流水线、数据存储等。

结论文段以"因此，我们决定在当下及可预见的未来，采用 Kubernetes 作为我们的容器编排平台"收束，明确给出了决策的时间边界（presente y futuro inmediato），符合 ADR 记录中"时间戳与时效性"的实践要求。

四、仓库佐证：与 Docker Swarm 平行示例的论证对照

为了让 Kubernetes 这份 ADR 的理由更有参照价值，可以对照仓库中的 Docker Swarm ADR（orquestación-de-contenedores-con-docker-swarm/index.md）看两套论证如何互相印证：

从源码结构看，仓库刻意用两份结论相反的示例，演示同一决策问题可以有不同的适用语境：Docker Swarm ADR 明确写了"Kubernetes 学习曲线更陡、对我们的需求可能过重"，而 Kubernetes ADR 则强调社区与生态规模。决策记录不追求"谁更正确"，而是把每个团队当时的选择依据固化下来——这正是架构知识管理的核心。

五、把这份示例落地为你的 ADR：模板与写作规范

5.1 套用仓库提供的决策记录模板

仓库的西班牙语模板索引 locales/es-001/plantillas/index.md 收录了 11 套模板，与本文示例最相关的是：

• Michael Nygard 模板（plantilla-de-registro-de-decisión-de-michael-nygard）：极简四段式——Estado（状态）/ Contexto（上下文）/ Decisión（决策）/ Consecuencias（后果）。本文的 Kubernetes 示例基本可映射到该结构（问题陈述≈Contexto，决策与理由≈Decisión，但示例未单列"Consecuencias"段，这是一处值得补强的差异）；
• MADR 项目模板（plantilla-de-registro-de-decisión-del-proyecto-madr）：结构最完整，包含"Contexto y planteamiento del problema → Factores de decisión（决策因素）→ Opciones consideradas → Resultado de la decisión → Consecuencias positivas/negativas → Ventajas y desventajas"。若把本示例改写为正式 ADR，可用它补上缺失的"决策因素"与"正负后果"章节；
• 商业案例模板（plantilla-de-registro-de-decisión-para-caso-de-negocio）：面向成本、候选者分析与 SWOT，适合需要向管理层论证选型成本的场景。

5.2 遵守仓库的文件命名约定

按 convenciones-de-nombres-de-archivo 的建议，ADR 文件名应满足三点：

• 使用现在时祈使短语（如choose-container-orchestration.md），便于阅读并与 git commit message 风格一致；
• 使用小写字母加连字符（与仓库目录命名一致），兼顾可读性与系统易用性；
• 扩展名为markdown（.md），便于格式化与渲染。

仓库中该示例的目录名orquestación-de-contenedores-con-kubernetes即遵循此约定（西班牙语小写加连字符），英文对应目录kubernetes-container-orchestration亦同。

5.3 用 git 管理 ADR 文件

仓库文档 cómo-empezar-a-usar-adr-con-git（英文版内容内嵌于根 README.md）给出了最轻量的落地流程：

$ mkdir adr # 为 ADR 文件创建目录 $ vi adr/choose-container-orchestration.md # 为每个决策创建一个文本文件 # 写入任何你想记录的内容（可参考仓库模板） $ git add adr/ && git commit -m "add ADR: choose Kubernetes for container orchestration"

将 ADR 纳入版本控制后，每个决策都拥有了变更历史、评审记录与责任人，天然支持后续的"一月一回顾"式复盘（仓库写作建议中明确提到：团队常在决策一个月后对比 ADR 与实际发生的情况，以持续学习改进）。

六、写好这类选型 ADR 的四个质量要点

依据仓库文档 sugerencias-para-escribir-buenos-adr，结合本示例可提炼四条可直接套用的检查标准：

1. 要有理由（Rationale）：解释为什么做这个特定决策。本示例的四条理由（可扩展性、去中心化、社区、生态）正是"rationale"的体现——不是简单说"选了 Kubernetes"，而是给出可争论、可比较的依据；
2. 保持具体（Specific）：一份 ADR 只记录一个决策。本示例只解决"容器编排平台选型"这一个问题，没有混入镜像仓库、CI/CD 等衍生话题；
3. 标注时间（Timestamps）：标明各项内容的写入时间，尤其对成本、排期、扩缩等随时间变化的信息。本示例的结论特意限定"当下与可预见的未来"，就是时效性意识的体现；
4. 保持不可变（Immutable）：不修改既有 ADR 内容，而是通过追加信息修订，或用新 ADR 取代旧 ADR。若未来容器编排栈发生迁移，正确做法是新建一份 ADR 并声明"supersedes"关系（MADR 模板中的sustituido por [ADR-0005]字段即为此设计）。

七、多语言与站点构建：一份内容、多端复用

该示例在仓库中并非孤立存在：

• 英文源版本 kubernetes-container-orchestration/index.md 内容与西语版完全对应；
• 仓库通过locales/目录维护 30 余种语言的内容镜像，并在站点子项目architecture-decision-record.github.io/中构建成可浏览网站（其static/search/*.json包含各语言的搜索索引，例如es-001.json、zh-cn.json等）；
• 根目录 README.md 提供了完整的模板与示例索引，是检索全部 ADR 素材的入口。

这意味着：一份 Kubernetes 选型 ADR 可以同时服务于多语言团队、静态站点检索与 AI Agent 检索，体现了"决策即文档、文档即知识库"的仓库理念。

八、小结

以 Orquestación de contenedores con Kubernetes 为例的这份 ADR，用"问题陈述 → 备选方案 → 决策与理由"三段式，把一次容器编排选型讲得清楚且可追溯。结合仓库的模板（Nygard/MADR/商业案例）、命名约定、写作建议与平行示例（Docker Swarm），你可以直接复制这份骨架，替换为自己的业务背景与候选清单，产出一份结构合格、理由充分、可纳入 git 版本管理的架构决策记录。