Knative ConfigMap 管理实战：`_example` 校验机制、Operator 协作与集群配置最佳实践

• 文档
• 教程
• 云原生

导读

在 Knative（Serving 与 Eventing）中，ConfigMap 是管理员对控制器全局行为进行配置的主要途径，几乎所有以config-前缀命名的 ConfigMap 都承载着平台级默认值与行为开关。本文以 editing-configmaps.md 为核心骨架，深入讲解 Knative ConfigMap 的_example键与knative.dev/example-checksum校验机制，给出正确的修改姿势、验证手段、存储与版本化管理（GitOps）建议，并说明在使用 Knative Operator 时如何避免配置被覆盖。读完本文，你将能够安全、可回滚地管理集群上的 Knative 配置。

一、ConfigMap 在 Knative 中的定位

Knative 遵循 Kubernetes 的声明式配置模型，管理员主要通过两种方式下发集群级配置：直接编辑 YAML 清单并用kubectl应用，或修改 Knative 自带的 ConfigMap。其中 ConfigMap 负责平台级行为的调优，绝大多数 Knative ConfigMap 位于knative-serving与knative-eventing命名空间中，其设置对所有命名空间中的相关 Knative 组件生效。

从 admin-overview.md 的配置清单可以看出，Knative 的配置面覆盖 Serving 与 Eventing 两大组件：

• Serving 侧：config-defaults（默认资源值）、config-deployment（支撑服务的 Deployment 资源配置）、config-domain（域名）、config-gc（垃圾回收与保留时间）、config-network（滚动时长、加密等）、config-certmanager（证书签发）、config-istio（Ingress 网关）。
• Eventing 侧：config-br-defaults（Broker 默认类与默认 Channel）、config-kafka-features（Kafka 交互特性）、default-ch-webhook/kafka-channel（Channel 默认值）、config-ping-defaults（PingSource 默认值）、config-sugar（Sugar Controller 行为）。

这些 ConfigMap 均由 Knative 安装时创建，管理员可以像编辑普通 Kubernetes ConfigMap 一样用kubectl修改它们；Knative 控制器会在应用后的数秒内处理新值，包括回滚到旧值。

二、_example键：内置的配置文档与校验锚点

2.1_example是什么

Knative 安装的所有 ConfigMap 中都包含一个名为_example的键，它本身不参与任何行为控制，其值是一段注释性质的说明文字，作用是向执行kubectl edit的用户展示该 ConfigMap 内所有已知配置键的用途与示例。也就是说，它是随 ConfigMap 一起分发、供管理员查阅的"活文档"。

2.2 误改_example的后果与 webhook 拦截

如果管理员没有新建配置键，而是直接修改了_example键的内容，改动不会影响集群配置——因为_example根本不被控制器读取。为避免这种"改了没反应"的困惑，Knative 的 webhook 会对这类编辑进行拦截并告警。

其判定机制基于校验和：Knative 在 ConfigMap 上维护一个knative.dev/example-checksum注解，值为_example键内容的哈希。当 webhook 发现 ConfigMap 中_example键的实际内容与注解中的校验和不再一致时，就会拒绝该更新并提示用户补丁无法生效。需要注意：

• 如果knative.dev/example-checksum注解缺失或为空，webhook 不会生成该警告；
• 因此，管理员不能修改_example键的内容，但可以整体删除_example键，或删除example-checksum注解本身。

从仓库中的真实 ConfigMap 可以印证这一点。例如 config-deployment 的元数据中就带knative.dev/example-checksum: "fa67b403"注解；而 editing-configmaps.md 给出了config-defaults的示例片段，其注解值为"5b64ff5c"。

2.3 一个带校验和的完整 ConfigMap 结构

config-defaults是 Serving 中用途最广的 ConfigMap 之一，其头部结构如下（第 11 行为校验和注解）：

apiVersion: v1 kind: ConfigMap metadata: name: config-defaults namespace: knative-serving labels: app.kubernetes.io/name: knative-serving app.kubernetes.io/component: controller app.kubernetes.io/version: devel annotations: knative.dev/example-checksum: "5b64ff5c" data: _example: | ################################ # # # EXAMPLE CONFIGURATION # # # ################################ # This block is not actually functional configuration, # but serves to illustrate the available configuration # options and document them in a way that is accessible # to users that `kubectl edit` this config map. #

注意，data._example区块只是示例文档，真正生效的键是data下并列的其它键。以config-defaults的实际默认值为例（参见 config-defaults.md）：

data: revision-timeout-seconds: "300" max-revision-timeout-seconds: "600" revision-response-start-timeout-seconds: "300" revision-idle-timeout-seconds: "0" # infinite revision-cpu-request: "400m" revision-memory-request: "100M" revision-ephemeral-storage-request: "500M" revision-cpu-limit: "1000m" revision-memory-limit: "200M" revision-ephemeral-storage-limit: "750M" container-name-template: "user-container" container-concurrency: "0" container-concurrency-max-limit: "1000" allow-container-concurrency-zero: "true" enable-service-links: "false"

这些键各自控制 Revision 的默认超时、CPU/内存/临时存储请求与限制、容器并发度等；修改时必须新增或修改这些真实键，而不是动_example。

三、如何正确修改 Knative ConfigMap

3.1 基本操作流程

以修改 Serving 的默认域名为例（完整流程见 using-a-custom-domain.md）：

1. 打开config-domainConfigMap 进行编辑：

   kubectl edit configmap config-domain -n knative-serving

2. 在data下新增或替换配置键（如将knative.dev设为所有 Route 的域名）：

   apiVersion: v1 data: knative.dev: "" _example: | ... kind: ConfigMap

3. 保存退出。若已有存量部署，Knative 会自动调和（reconcile）该 ConfigMap 的变更，并自动更新所有已部署 Service 与 Route 的主机名，无需手动逐个修改。

4. 验证生效：

   kubectl get route <route-name> --output jsonpath="{.status.url}"

   观察 Route 的 URL 是否已切换到新域名。

Eventing 侧的修改方式完全一致，例如调整 PingSource 的事件负载上限（参见 sources-configuration.md）：

kubectl edit cm config-ping-defaults -n knative-eventing

对应的data键为data-max-size（单位：字节，-1表示不限制），它控制 PingSource 写入 CloudEvents 的最大数据量。

3.2 修改时务必避开_example

正确姿势是：在data下新增自己的键，例如：

data: revision-timeout-seconds: "300" # 新增/修改真实键 # _example 保持原样，不要编辑

如果误改了_example，webhook 会因校验和失配而拒绝补丁；此时应恢复_example内容，或按前述规则删除_example键 /example-checksum注解。

四、最佳实践一：应用前的验证与测试

Knative 控制器在 ConfigMap 应用后的几秒内就会消费新值（包括回滚到旧值），因此改动传播速度快，但也意味着错误配置会很快影响到运行中的服务。建议遵循以下实践：

• 语法与内容校验：在应用前使用kubeval之类的工具校验 ConfigMap 的语法与内容，或直接使用 Kubernetes 的服务端试运行能力：

  kubectl apply --dry-run=server -f configmap.yaml

  --dry-run=server会由 API server 执行校验逻辑但不真正持久化，能在不改动集群的前提下发现格式错误。

• 先在预发布环境测试：将 ConfigMap 变更先在 staging 环境应用，确认与当前应用版本兼容后再上生产，避免因配置项在版本间变更而导致线上故障。

五、最佳实践二：存储与版本化策略

ConfigMap 的管理模式取决于"权威来源"放在哪里：

5.1 以集群为权威（导出备份到 Git）

如果直接通过kubectl edit管理 ConfigMap，集群是权威来源，那么需要定期将配置导出并提交到 Git 作为恢复手段：

kubectl get configmap -o yaml

建议把导出的 YAML 提交到版本库，并在app.properties中记录对应的版本号，以便回溯"某版本集群使用了哪组配置"。

5.2 以 Git 为权威（GitOps）

如果采用 GitOps 模式，Git 是权威来源，变更在 Git 中完成后通过以下方式之一应用到集群：

• 手动应用：kubectl apply -f <configmap.yaml>；
• 自动化同步：使用 Flux、ArgoCD 等 GitOps 工具，在提交后自动将 Git 中的 ConfigMap 同步到集群，实现配置即代码、变更可审计、回滚即git revert。

六、最佳实践三：Git 仓库中的 ConfigMap 组织建议

在版本库中管理 ConfigMap 时，推荐以下做法：

• 集中存放：在仓库中建立专门目录，例如k8s/configmaps/，所有 ConfigMap 定义集中于此，便于检索与审查；
• 用 Git tag 标记版本：为特定配置版本打标签，例如git tag config-v1.2.3，将 tag 与 ConfigMap 内容一一对应，方便精确回滚到某个配置快照；
• 配合 GitOps 工具：借助 ArgoCD 或 Flux 建立从 Git 到 Kubernetes 的同步管线，提交即生效，并自动检测集群与 Git 的配置漂移。

这些实践与 Kubernetes 通用的声明式管理理念一致，能显著降低"谁改了什么、何时改的、能否回滚"的运维成本。

七、与 Knative Operator 的协作：别直接编辑 ConfigMap

如果集群由Knative Operator安装和管理，情况有所不同：Operator 会将KnativeServing/KnativeEventing自定义资源（CR）中的spec.config值传播到系统 ConfigMap，任何对 ConfigMap 的手工修改都会被 Operator 覆盖。因此不要直接编辑 ConfigMap，而应通过修改 CR 来声明配置。

具体方式参见 configuring-with-operator.md：CR 的spec.config为每个 ConfigMap（config-<name>）提供一个<name>条目，其值为该 ConfigMap 的data内容。例如同时配置域名与自动扩缩容窗口：

apiVersion: operator.knative.dev/v1beta1 kind: KnativeServing metadata: name: knative-serving namespace: knative-serving spec: config: domain: example.org: | selector: app: prod example.com: "" autoscaler: stable-window: "60s"

需要说明的前提与限制：

• Knative 的所有 ConfigMap 创建在与对应 CR 相同的命名空间中（例如KnativeServing在knative-serving命名空间，则 Serving 的 ConfigMap 也都在该命名空间）；
• 未使用 Operator、采用 YAML 方式安装的集群，才适合按本文前述方式直接编辑 ConfigMap；
• 两种安装方式之间的切换，官方更推荐在新集群上分别安装，而不是在同一集群上迁移。

八、小结

管理 Knative 集群配置的核心要点可以概括为三句话：新增键、别动_example（避免 webhook 校验和拦截）；先验证、再应用、后观察（kubectl apply --dry-run=server+ 预发布测试）；把配置纳入 Git 版本管理（导出备份或 GitOps 自动化）。若集群由 Operator 管理，则统一通过 CR 的spec.config声明配置，而不是直接编辑 ConfigMap。掌握这些原则，即可让 Knative 的配置变更变得可预期、可审计、可回滚。

延伸阅读

• Knative 管理员配置总览（含 Serving / Eventing 全部 ConfigMap 索引）
• config-deployment 详解（含example-checksum注解的 Deployment 资源配置示例）
• config-defaults 详解（Revision 默认值全部参数）
• 通过 Operator 配置 Knative
• 自定义域名配置
• Eventing 事件源默认值配置

• 文档
• 教程
• 云原生