工作负载 · XB 现场笔记

ConfigMap 把配置与镜像分开

Fri, 20 Aug 2027 00:00:00 +0000

ConfigMap 把非敏感配置放在镜像之外，让环境相关设置发生变化时，不必重新构建应用产物。真正有用的边界需要明确：镜像提供代码，工作负载定义则指定这些代码应该读取哪份配置。因此，一次发布不仅是一个镜像标签，配置引用同样属于正在交付的行为。只记录镜像版本，可能无法解释两个环境为什么表现不同。

给配置一个可审阅的身份

ConfigMap 的 data 值是字符串，也可以通过 binaryData 表达二进制内容及其 API 编码形式。它适合小规模配置，数据大小有一 MiB 限制，不是通用文件仓库，更不是保护秘密的机制。API 能检查对象结构，却不知道某个应用参数在业务上是否合理。因此，结构合法和业务正确仍需分别验证，不能以创建成功代替配置审查。

Pod 可以通过环境变量引用或挂载文件消费配置。普通 Pod 引用要求 ConfigMap 位于这个 Pod 所在的命名空间。名称、必需键和应用解释方式都应明确。Deployment 对象被 API 接受，并不证明它引用的每个键都存在，也不证明新容器能够带着这些值成功启动。发布检查必须继续观察真实工作负载的结果。

单位、允许值与默认值应属于应用配置规范。某个字符串看起来像布尔值或数字，并不说明接收方会采用什么转换规则。在不同环境之间推广配置之前，需要结合真实消费者检查这些规则，避免同一份文本被解释成不同业务含义。

版本化的不可变 ConfigMap 更容易表达发布身份。settings-v2 可以与 settings-v1 同时保留，而 immutable 会禁止修改当前对象的数据。但这项保护不阻止有权限的操作者删除对象，再用同名重新创建另一份内容。对象生命周期权限和发布记录，应与希望实现的不可变承诺一致，不能把一个字段理解成所有可能路径都被永久封闭。

坏掉的样子

修改配置与替换进程是两种不同动作。已经注入运行中容器的环境值，不会因为 ConfigMap 更新而被改写。普通投射文件可能最终更新，但应用仍要重新读取；subPath 挂载和已经打开的文件又有不同生命周期。因此，API 中出现了新值，并不能直接宣布应用已经完成配置切换，还需要查看消费者实际读到了什么。

把 Deployment 的 Pod 模板改为引用新的 ConfigMap，是明确的滚动替换触发条件。仅修改 ConfigMap 本身，不会自动改写这个模板。同样，校验和 annotation 只有在某个工具真正把它更新到 Pod 模板中时才起作用。Kubernetes 不会自行发现任意外部配置变化，并替应用生成期望的校验和；这部分自动化需要有真实实现。

回退依赖旧输入仍然存在。旧对象已经删除，再把工作负载指回 settings-v1 就可能失败；只恢复镜像，也不能恢复被修改的配置。清理前应检查现有消费者及回退需要，并保留必要版本。配置还要通过业务验证，例如格式正确的阈值仍可能禁用服务或改变行为，不能把版本化本身当成兼容性证明。

快速验证

准备可丢弃的 Kubernetes 测试集群，确保 kubectl 可以访问，且节点能够使用 python:3.11-slim-bookworm 镜像。把代码保存为 config-releases.py，执行 python3 config-releases.py KUBECONFIG_PATH CONTEXT，将后两个参数替换成专用集群的配置文件路径和上下文。测试账号需要创建、删除本次命名空间的权限。实测服务端为 Kubernetes 1.34.11，客户端为 kubectl 1.34.1。

import json
import subprocess
import sys
import time
from uuid import uuid4

assert len(sys.argv) == 3, 'usage: python3 example.py DISPOSABLE_KUBECONFIG CONTEXT'
base = ['kubectl', '--kubeconfig', sys.argv[1], '--context', sys.argv[2], '--request-timeout=30s']
image = 'python:3.11-slim-bookworm'


def k(*args, payload=None, expected=0):
 result = subprocess.run(base + list(args), input=json.dumps(payload) if payload is not None else None,
 capture_output=True, text=True, timeout=150)
 if expected is not None:
 assert result.returncode == expected, result.stderr
 return result


def obj(namespace, kind, name=None, selector=None):
 args = ['get', kind, '-n', namespace, '-o', 'json']
 if name:
 args.append(name)
 if selector:
 args += ['-l', selector]
 return json.loads(k(*args).stdout)


def apply(namespace, data):
 return k('apply', '-n', namespace, '-f', '-', payload=data)


def wait_for(read, ready, seconds=120):
 until = time.monotonic() + seconds
 while time.monotonic() < until:
 value = read()
 if ready(value):
 return value
 time.sleep(0.5)
 raise AssertionError('expected Kubernetes condition did not arrive')


def pod_ready(pod):
 return any(c['type'] == 'Ready' and c['status'] == 'True'
 for c in pod.get('status', {}).get('conditions', []))


def spec(script='import time; time.sleep(600)'):
 return {'automountServiceAccountToken': False, 'terminationGracePeriodSeconds': 1,
 'containers': [{'name': 'app', 'image': image, 'imagePullPolicy': 'IfNotPresent',
 'command': ['python3', '-c', script],
 'resources': {'requests': {'cpu': '10m', 'memory': '24Mi'},
 'limits': {'cpu': '200m', 'memory': '96Mi'}}}]}


def deployment(namespace, name, podspec):
 return apply(namespace, {'apiVersion': 'apps/v1', 'kind': 'Deployment', 'metadata': {'name': name},
 'spec': {'replicas': 1, 'selector': {'matchLabels': {'app': name}},
 'template': {'metadata': {'labels': {'app': name}}, 'spec': podspec}}})


def deployment_pod(namespace, name):
 wait_for(lambda: obj(namespace, 'deployment', name), lambda d:
 d.get('status', {}).get('observedGeneration', 0) >= d['metadata']['generation']
 and d.get('status', {}).get('updatedReplicas') == 1
 and d.get('status', {}).get('availableReplicas') == 1
 and d.get('status', {}).get('replicas') == 1)
 def pods():
 return [p for p in obj(namespace, 'pods', selector='app=' + name)['items']
 if not p['metadata'].get('deletionTimestamp')]
 return wait_for(pods, lambda p: len(p) == 1 and pod_ready(p[0]))[0]

namespace = 'notes-config-' + uuid4().hex[:8]
k('create', 'namespace', namespace)
try:
 for version, mode in [('v1', 'blue'), ('v2', 'green')]:
 apply(namespace, {'apiVersion': 'v1', 'kind': 'ConfigMap',
 'metadata': {'name': 'settings-' + version}, 'immutable': True, 'data': {'mode': mode}})
 podspec = spec()
 podspec['containers'][0]['env'] = [{'name': 'MODE', 'valueFrom':
 {'configMapKeyRef': {'name': 'settings-v1', 'key': 'mode'}}}]
 deployment(namespace, 'web', podspec)
 first = deployment_pod(namespace, 'web')
 def mode(pod):
 return k('exec', '-n', namespace, pod['metadata']['name'], '--', 'python3', '-c',
 'import os; print(os.environ["MODE"])').stdout.strip()
 assert mode(first) == 'blue'
 rejected = k('patch', 'configmap', 'settings-v1', '-n', namespace, '--type=merge',
 '-p', json.dumps({'data': {'mode': 'changed'}}), expected=None)
 assert rejected.returncode != 0 and 'immutable' in rejected.stderr
 assert obj(namespace, 'configmap', 'settings-v1')['data']['mode'] == 'blue'
 def select(version):
 patch = [{'op': 'replace',
 'path': '/spec/template/spec/containers/0/env/0/valueFrom/configMapKeyRef/name',
 'value': 'settings-' + version}]
 k('patch', 'deployment', 'web', '-n', namespace, '--type=json', '-p', json.dumps(patch))
 return deployment_pod(namespace, 'web')
 second = select('v2')
 assert mode(second) == 'green' and second['metadata']['uid'] != first['metadata']['uid']
 third = select('v1')
 assert mode(third) == 'blue' and third['metadata']['uid'] != second['metadata']['uid']
 image_ids = [p['status']['containerStatuses'][0]['imageID'] for p in (first, second, third)]
 assert len(set(image_ids)) == 1
 assert len({p['metadata']['uid'] for p in (first, second, third)}) == 3
 print(json.dumps({'modes': ['blue', 'green', 'blue'], 'distinct_pod_uids': 3,
 'same_image_id': image_ids[0], 'immutable_update_rejected': True,
 'retained_config_rollback_verified': True}))
finally:
 k('delete', 'namespace', namespace, '--wait=true', '--timeout=90s')

程序创建两个不可变 ConfigMap，以及引用 settings-v1 的单副本 Deployment。第一个 Pod 从环境变量读取 blue。随后尝试覆盖这份 ConfigMap 数据，API 会拒绝操作，再读取对象也确认原值仍是 blue。这验证的是服务器实际执行了约束，而不是仅在文件中找到了 immutable 字样。

接着修改 Pod 模板，让它引用 settings-v2。控制器协调完成、容器就绪之后，另一个 Pod 读取 green。再选择保留的第一版，会再次替换 Pod 并读到 blue。三次 Pod 标识各不相同，但运行时观察到的镜像身份完全一致。全部断言已经通过，实验命名空间随后删除，未留下这些测试配置和工作负载。不过镜像标签仍然可变：观察到的身份一致，只证明这次运行，没有保证未来可复现；需要固定产物时应使用镜像摘要。

这个实验使用简单工作进程，验证配置选择、进程替换以及依赖旧输入的回退，没有证明应用兼容性、生产滚动期间的可用性或外部副作用已经回滚。发布证据应把镜像、配置版本、工作负载定义和应用观测结果放在一起，让每一部分变化都有具体依据可供审阅。

来源

Kubernetes: ConfigMaps，非敏感配置、消费方式与不可变属性，已核验 2026-09-13。
Kubernetes: Deployments，Pod 模板变更及滚动替换，已核验 2026-09-13。
Kubernetes：镜像，可变标签与摘要固定身份，已核验 2026-10-15。

Kubernetes Deployment 描述期望状态

Thu, 19 Aug 2027 00:00:00 +0000

与其描述步骤，不如描述终态。这条思想支撑起副本、滚动更新与回滚的一切机制。

声明规范胜过过程脚本

一份 Deployment 是「终态」的陈述,而不是一张命令清单:多少副本、哪个镜像、哪条 tag、什么标签。操作者写下「要什么」,控制器这位 reconcile 循环决定「怎么要」。区别在于资源所有权，而不是有没有使用命令行。kubectl run 通常创建独立 Pod，kubelet 可以重启其中容器，但这个 Pod 消失后，没有 ReplicaSet 负责补足一组替代对象。Deployment 同样可以通过一条命令创建，客户端退出之后，存储下来的规范仍会持续指导控制器。中断客户端并不能可靠说明 API 是否已经接纳请求；重试或诊断收敛之前，先查看实际存储的对象，区分请求传递状态与控制器执行状态。

由控制器填补差距

Deployment 控制器管理 ReplicaSet，再由副本集控制器维持 Pod 数量。容器崩溃时，kubelet 可以在同一个 Pod 内重启容器；删除或丢失 Pod 后创建替代对象，则是另一条协调路径。它们会配合工作，但不能都说成同一个控制器每隔几秒创建一个 Pod，否则无法区分实例身份、重启与替换。

协调是异步过程，依赖控制面正常以及容量足够。镜像拉取失败、配额、准入拒绝和存储不可用，都可能长期阻止收敛。应查看条件与事件，确认究竟哪一层受阻。期望副本数是系统追求的目标，不是真实就绪容量的证据，也不是恢复时间上限；控制器反复尝试不等于问题已经得到解决。

一次次发布都是经过步骤的

修改 Pod 模板会触发发布与修订版本，单纯缩放不会。控制器按照更新策略、就绪和可用性要求调整新旧 ReplicaSet 数量。流量由 Service 与对应数据路径另行处理，Deployment 控制器本身不是逐条迁移连接的代理。发布状态和请求成功需要分别观察，不能把模板变化自动等同于无中断流量切换。

回滚恢复先前 Pod 模板，不会恢复 Deployment 所有字段，更不会撤销数据库模式等外部状态。保留的 ReplicaSet 提供回滚历史，revisionHistoryLimit 默认十份，清理从发布完成之后开始。流水线重复应用未变化的模板，并不会只因执行了一次就生成新修订；版本库审计与集群修订解决的是不同范围的历史问题。

坏掉的样子

apps/v1 Deployment 的选择器不可变，Pod 模板必须匹配它。模板违反选择器时会被 API 校验拒绝，不是先接受对象，再持续产生不受管理的游离 Pod。需要改变选择器时，应规划明确迁移。选择器重叠值得审查，但仅仅标签匹配，不会抹掉已有控制所有者引用，不能把所有重叠都解释成控制器互抢副本。

删除受管理 Pod 或直接缩放下层 ReplicaSet，可能被负责的控制器纠正。相比之下，kubectl scale deployment 修改的就是 Deployment 期望副本数，直到其他参与者再次修改才会变化。HPA、后续 apply 或 GitOps 协调器可能覆盖它；Deployment 自己不会秘密记住版本库里的旧数字。应找出真正写入该字段的主体，再制定紧急缩放流程。

受阻发布可能因清理完成条件未满足，保留超过预期数量的 ReplicaSet。宣布历史泄漏前，应查看 rollout 状态。外部变更历史与经验证回滚计划仍应保留；历史上限零会移除正常回滚目标，但数量大本身也不能证明控制面性能已经下降。需要用实际对象状态与系统指标区分暂时保留、策略选择和真实故障。

快速验证

把下面程序存成 desired_state_loop.py,运行 python3 desired_state_loop.py。它只用标准库,每轮比较期望与观测,差一个就补一个动作,直到差距归零,既演示节点丢失后的补齐,也演示手改多出的副本如何被收回。

"""期望态收敛循环模型（仅标准库）：期望 vs 观测，控制器补差直到归零。"""

def reconcile_step(desired, observed):
 if observed < desired:
 return "create-one-pod"
 if observed > desired:
 return "delete-one-pod"
 return "in-sync"


def converge(desired, observed, log):
 while observed != desired:
 action = reconcile_step(desired, observed)
 log.append(action)
 if action == "create-one-pod":
 observed += 1
 else:
 observed -= 1
 log.append("in-sync")
 return observed


def main():
 desired = 3
 observed = 1 # 节点丢失后只剩一个
 actions = []
 observed = converge(desired, observed, actions)
 assert observed == desired
 assert actions == ["create-one-pod", "create-one-pod", "in-sync"], actions

 # 手工漂移：期望未变，观测多了两个。
 observed = 5
 drift = []
 observed = converge(desired, observed, drift)
 assert observed == desired
 assert drift == ["delete-one-pod", "delete-one-pod", "in-sync"], drift

 # 在接纳期望状态前，用本地检查模拟选择器与模板的校验。
 selector = {"app": "api"}
 template_labels = {"app": "api-v2"} # 故意错配，否定对照
 matched = all(template_labels.get(k) == v for k, v in selector.items())
 assert not matched, "mismatched template must fail this validation model"

 print(f"desired={desired} final-observed={observed}")
 print(f"recovery-actions={actions}")
 print(f"observed-count-drift-corrected={drift}")
 print("PASS: controller closes the desired-vs-observed gap; mismatched template is rejected by the local validation check")


if __name__ == "__main__":
 main()

两次整数数量恢复都以同步结尾。另一个标签检查把不匹配模板作为反例拒绝，演示 API 接纳之前要检查的契约，但没有提交真实 Deployment，也没有实现接管、监听、调度和就绪机制。跑通后会打印两次补差动作序列与最终同步,手工多出的副本被删回期望数。若把期望改成你的真实副本数再跑一遍,收敛结论不变,数字跟着变。

本轮在 Linux、Python 3.12.14 上运行两种语言的断言通过。模型只验证收敛算术,不涉及调度探针与存储,发布日之前,还要去真实集群确认选择器、副本数与历史版本数，并检查真正的就绪容量与请求失败率。

来源

Kubernetes：Deployments，Deployment 资源的说明，已核验 2026-10-15。
Kubernetes：Controllers，Kubernetes 及其模型，已核验 2026-10-15。

工作负载 · XB 现场笔记

ConfigMap 把配置与镜像分开

给配置一个可审阅的身份

坏掉的样子

快速验证

来源

Kubernetes Deployment 描述期望状态

声明规范胜过过程脚本

由控制器填补差距

一次次发布都是经过步骤的

坏掉的样子

快速验证

延伸阅读

来源