kOps Addons 完全指南：Managed 与 Static 两种 Addon 体系的配置、原理与实战

• 云原生
• 集群管理
• 运维
• IaC

kOps（Kubernetes Operations）内置了一套完整的 Addon 管理机制，分为由 kOps 负责升级与配置的Managed addons（通过 Cluster Spec 配置）和以清单文件原样应用的Static addons（通过spec.addons配置）两大类。本文以 docs/addons.md 为核心脉络，逐一讲解 AWS Load Balancer Controller、Cluster Autoscaler、Cert-manager、Karpenter、Metrics Server、Node Local DNS Cache、Node Termination Handler、Node Problem Detector、Pod Identity Webhook、Snapshot Controller 等托管 Addon 的完整配置项，并结合pkg/apis/kops中的 Spec 定义与upup/pkg/fi/cloudup/bootstrapchannelbuilder的实现细节，讲透自定义 Addon 的清单格式、版本管理原理与 S3 部署实践，帮助读者在 kOps 集群中按需启用、正确配置并自主维护 Addon。

两类 Addon 体系：Managed 与 Static

kOps 支持两种类型的 Addon：

• Managed addons：通过 Cluster Spec 配置。这类 Addon 由 kOps 托管，会跟随 kOps 与 Kubernetes 的生命周期一起升级，并根据集群 Spec 中的配置（包括 Addon 自身配置以及你配置的其他相关设置）自动生成部署清单。
• Static addons（也称 Custom addons）：通过spec.addons配置，每条记录指向一个控制平面可以读取的清单文件，kOps 将清单中的资源原样应用（as-is）。

从源码实现看，Managed Addon 的清单并不是写死的静态文件，而是由 BootstrapChannelBuilder 在构建集群模型时动态组装：它根据 Cluster Spec 中各个 Addon 配置段（如ClusterAutoscaler、MetricsServer、NodeTerminationHandler等），逐一生成带k8s-addon: <name>选择器的channelsapi.AddonSpec，最终汇总为一个addons/bootstrap-channel.yaml通道文件，由channels工具负责应用与版本跟踪。因此"Managed"的本质是：配置入口在 Cluster Spec，渲染与升级逻辑由 kOps 掌握。

Managed Addons 逐一详解

以下 Addon 均通过编辑集群 Spec 中的对应配置段启用。修改后执行kops update cluster并配合--yes应用即可生效。

AWS Load Balancer Controller

AWS Load Balancer Controller 为 AWS 上的 ELB（ALB/NLB）提供增强的编排能力，例如基于 Ingress 自动创建 ALB、管理目标组与安全组等。该 Addon 自 kOps 1.20 起默认可用：

spec: awsLoadBalancerController: enabled: true cpuRequest: "100m" cpuLimit: "200m" memoryRequest: "200Mi" memoryLimit: "500Mi"

对应源码结构体 LoadBalancerControllerSpec 显示，CPU/Memory 的 request 与 limit 默认值分别为100m、200m、200Mi、500Mi，即示例中的数值即默认值；此外还支持version字段覆盖容器镜像 tag。

集成 AWS WAF 与 Shield

虽然该控制器可以集成 AWS WAF 与 Shield 服务到 ALB，但 kOps 默认禁用这些能力。自 kOps 1.24 起，可以通过以下字段启用 WAF / WAF Classic 与 WAFv2（均为 beta 特性，接受的配置与涉及的 AWS 资源未来可能变化）：

spec: awsLoadBalancerController: enabled: true enableWAF: true enableWAFv2: true cpuRequest: "100m" cpuLimit: "200m" memoryRequest: "200Mi" memoryLimit: "500Mi"

启用 Shield Advanced：

spec: awsLoadBalancerController: enabled: true enableShield: true

需要注意：控制器一次只能为一个 ALB 关联一个 WAF。即使在同一个 Ingress 对象上同时填写alb.ingress.kubernetes.io/waf-acl-id与alb.ingress.kubernetes.io/wafv2-acl-arn注解，也只有一个会生效。

Cluster Autoscaler

Cluster Autoscaler（自 kOps 1.19 起默认可用）根据 Pod 调度需求自动调整集群节点数量。启用并配置：

spec: clusterAutoscaler: enabled: true expander: least-waste balanceSimilarNodeGroups: false emitPerNodegroupMetrics: false awsUseStaticInstanceList: false scaleDownUtilizationThreshold: "0.5" skipNodesWithCustomControllerPods: true skipNodesWithLocalStorage: true skipNodesWithSystemPods: true newPodScaleUpDelay: 0s scaleDownDelayAfterAdd: 10m0s scaleDownUnneededTime: 10m0s scaleDownUnreadyTime: 20m0s image: <the latest supported image for the specified kubernetes version> cpuRequest: "100m" memoryRequest: "300Mi"

各字段的默认值与语义可从 ClusterAutoscalerConfig 的源码注释中确认：

此外源码中还定义了ignoreDaemonSetsUtilization（忽略 DaemonSet Pod 的利用率计算）、cordonNodeBeforeTerminating（缩容终止前先 cordon 节点）、maxNodeProvisionTime（等待节点加入集群的最长时间）、podAnnotations（注入到 CA Pod 的注解）等可选字段。

Expander 策略：Priority 配置

自 kOps 1.26 起，priorityexpander 需要额外的 ConfigMap 配置。当在 Cluster Spec 中设置expander: priority时，kOps 会基于 InstanceGroup Spec 自动生成该 ConfigMap，你只需在 InstanceGroup 中设置优先级：

spec: autoscale: true autoscalePriority: 100

autoscalePriority未设置时默认为0。需要更复杂的匹配（例如用正则匹配 InstanceGroup 名称）时，可在 Cluster Spec 中提供自定义配置——一旦设置，InstanceGroup 上的优先级将被忽略：

clusterAutoscaler: customPriorityExpanderConfig: 100: - .*foo.* 50: - .*bar.* 0: - .*

对应源码字段为CreatePriorityExpenderConfig（默认true，控制 kOps 是否生成该 ConfigMap）与CustomPriorityExpanderConfig（map[string][]string，覆盖默认 ConfigMap 内容）。

关闭自动生成 priority ConfigMap

如果你希望完全在 kOps 之外管理 priority expander 的 ConfigMap，可关闭 kOps 的生成逻辑：

clusterAutoscaler: createPriorityExpanderConfig: false

针对单个 InstanceGroup 禁用 Autoscaler

自 kOps 1.20 起，可以在 InstanceGroup Spec 中单独关闭自动扩缩容：

spec: autoscale: false

注意与autoscalePriority配合使用：autoscale: true表示该实例组参与扩缩容，autoscalePriority决定扩容顺序优先级。

Cert-manager

Cert-manager（自 kOps 1.20 起，要求 K8s >= 1.16）负责为集群签发与管理 x509 证书：

spec: certManager: enabled: true defaultIssuer: yourDefaultIssuer

警告：cert-manager 每个集群只支持安装一份。如果集群中已经运行了 cert-manager，必须在启用该 Addon 之前移除现有安装，或将其标记为不由 kOps 管理（见下文）。只要使用的是 cert-manager v1 版本的资源，先删除旧安装再替换为该 Addon 是安全的。

从 CertManagerConfig 源码看，defaultIssuer用于设置一个默认的 ClusterIssuer，image可覆盖镜像，featureGates可开关实验特性，另外还有managed、nameservers、hostedZoneIDs三个重要配置项。

自托管（Self-provisioned）cert-manager

自 kOps 1.20.2 起，可让 cert-manager 由外部自己部署，同时仍让 kOps 上所有依赖它的插件正常部署（注意：在 cert-manager 真正部署完成前，相关 Addon 可能报错）：

spec: certManager: enabled: true managed: false

源码中Managed字段注释明确说明：置为false时 kOps 将跳过 cert-manager 的部署。

cert-manager Pod 的 DNS nameserver 配置

自 kOps 1.23.3 起支持为 cert-manager Pod 指定一组 DNS nameserver IP。当同一域名同时存在公有与私有 DNS 区域时，这可以确保 cert-manager 始终能访问 Ingress 或 DNS01 challenge 的 TXT 记录：

spec: certManager: enabled: true nameservers: - 1.1.1.1 - 8.8.8.8

启用 DNS-01 Challenge

自 kOps 1.25.0 起，通过给 cert-manager 授予必要的 IAM 权限，可以解决 DNS-01 challenge。这要求启用 ServiceAccount 的外部权限（IRSA），即 service-account-issuer-discovery-and-aws-iam-roles-for-service-accounts-irsa：

spec: certManager: enabled: true hostedZoneIDs: - ZONEID iam: useServiceAccountExternalPermissions: true

hostedZoneIDs是需要允许 cert-manager 做 DNS-01 校验的 Route53 hosted zone ID 列表。

Karpenter

Karpenter Addon（自 kOps 1.24 起）启用由 Karpenter 管理的 InstanceGroup，即实例组由 Karpenter 动态供给节点而非直接对应 ASG：

spec: karpenter: enabled: true

从源码看，KarpenterConfig 还支持logFormat、logLevel、image、featureGates、memoryLimit、memoryRequest、cpuRequest等字段；而new_cluster.go中的setupKarpenterNodes会为 Karpenter 集群创建Spec.Manager = InstanceManagerKarpenter的节点组（见 new_cluster.go 与其测试 new_cluster_test.go）。同时 populate_instancegroup_spec.go 显示，Karpenter v1 期望其节点注册时带一个 taint 作为竞态防护，Karpenter 接管后会移除该 taint。

详细的 Karpenter 配置方法见 kOps Karpenter 文档。

Metrics Server

Metrics Server（自 kOps 1.19 起）为 Kubernetes 内置的自动扩缩容管道提供可扩展的容器资源指标源：

spec: metricsServer: enabled: true

对应 MetricsServerConfig 包含image与insecure（默认true）字段。

安全的 TLS 校验

自 kOps 1.20 起，默认情况下 API Server不会校验 Metrics Server 的 TLS 证书。要启用 TLS 校验（要求集群已安装 cert-manager）：

spec: certManager: enabled: true metricsServer: enabled: true insecure: false

原理是：insecure: false让 API Server 验证 Metrics Server 证书，而该证书由 cert-manager 签发，因此两者必须同时启用。

Node Local DNS Cache

NodeLocal DNSCache（自 kOps 1.18 起，要求 K8s >= 1.15）在使用 CoreDNS 时可启用，它通过在每个节点上以 DaemonSet 形式运行 DNS 缓存代理来提升集群 DNS 性能。node-local-dnsPod 的memoryRequest与cpuRequest可配置，未设置时默认分别为5Mi与25m。若启用forwardToKubeDNS，则默认上游使用 kubedns：

spec: kubeDNS: provider: CoreDNS nodeLocalDNS: enabled: true memoryRequest: 5Mi cpuRequest: 25m

NodeLocalDNSConfig 还提供了更多进阶字段：localIP（本地监听 IP，可在169.254.20.0/16内任选或选择不会冲突的 IP）、image（覆盖镜像）、externalCoreFile（完全自定义 CoreFile，将忽略其他 CoreFile 相关配置）、additionalConfig（在 kOps 生成的 CoreFile 基础上追加配置）、podAnnotations。其实现位于 bootstrapchannelbuilder 的buildAddons中：仅当kubeDNS.Provider == "CoreDNS"且nodeLocalDNS.enabled时才生成对应条目（见 bootstrapchannelbuilder.go）。

Node Termination Handler

Node Termination Handler（自 kOps 1.19 起）确保 Kubernetes 控制平面能妥善响应可能导致 EC2 实例不可用的事件，如 EC2 维护事件、Spot 中断、实例 Rebalance 建议。若不处理，应用可能无法优雅停止、恢复可用性变慢，或把任务调度到即将宕机的节点上：

spec: nodeTerminationHandler: cpuRequest: 200m enabled: true enableRebalanceMonitoring: true enableSQSTerminationDraining: true managedASGTag: "aws-node-termination-handler/managed" prometheusEnable: true webhookURL: "https://hooks.slack.com/services/YOUR/SLACK/URL"

NodeTerminationHandlerSpec 是参数最丰富的托管 Addon 之一，关键字段与默认值如下：

队列处理模式（Queue Processor Mode）

自 kOps 1.21 起，只要enableSQSTerminationDraining不为false，NTH 就以Queue Processor 模式运行。相比默认的 IMDS 模式，队列模式还能处理 ASG Scale-In、AZ-Rebalance、不健康实例、通过 API 或控制台发起的 EC2 实例终止等事件。kOps 会为你预置所需基础设施：SQS 队列、EventBridge 规则和 ASG Lifecycle Hooks。managedASGTag可用于在多个集群间区分资源归属。

由于 kOps CLI 需要管理这些 EventBridge 规则与 SQS 队列，需要额外的 IAM 权限：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "events:DeleteRule", "events:ListRules", "events:ListTargetsByRule", "events:ListTagsForResource", "events:PutEvents", "events:PutRule", "events:PutTargets", "events:RemoveTargets", "events:TagResource", "sqs:CreateQueue", "sqs:TagQueue", "sqs:DeleteQueue", "sqs:GetQueueAttributes", "sqs:ListQueues", "sqs:ListQueueTags" ], "Resource": "*" } ] }

警告：在已有集群上切换两种运行模式时，旧资源必须手动清理。从 IMDS 模式切换到 Queue Processor 模式，需删除 Kubernetes 的 NTH DaemonSet；从 Queue Processor 切回 IMDS 模式，需删除 NTH Deployment 以及 AWS 侧的 SQS 队列、EventBridge 规则与 ASG Lifecycle Hooks。

源码中 IsQueueMode 方法即用于判定当前是否处于队列模式：enabled为真且enableSQSTerminationDraining未显式关闭即为队列模式。实现侧，kOps 会据此条件在 apply_cluster.go 挂载NodeTerminationHandlerBuilder来构建对应 AWS 资源。

Node Problem Detector

Node Problem Detector（自 kOps 1.22 起）运行在每个节点上，检测节点问题并上报给 apiserver，使各种节点故障对集群管理栈的上层可见：

spec: nodeProblemDetector: enabled: true memoryRequest: 32Mi cpuRequest: 10m

NodeProblemDetectorConfig 的默认值为memoryRequest: 80Mi、cpuRequest: 10m、memoryLimit: 80Mi，另有image与cpuLimit字段。

Pod Identity Webhook

使用 IAM roles for Service Accounts（IRSA） 时，Pod 需要额外的 token 来与 AWS API 认证，SDK 还需要特定的环境变量才能使用这些 token。Pod Identity Webhook（自 kOps 1.23 起）会自动变更（mutate）配置了 IRSA 的 Pod，免去手动配置；Cluster Spec 中所有配置了 AWS 权限的 ServiceAccount 都会自动被变更以承担对应角色：

spec: certManager: enabled: true podIdentityWebhook: enabled: true

注意示例中同时启用了 cert-manager——EKS Pod Identity Webhook 通常需要 cert-manager 提供证书。EKS 风格的 ServiceAccount 注解一般不需要，因为 kOps 会用 Cluster Spec 中的全部 ServiceAccount→角色映射来配置 webhook；但若需特殊配置，仍可在 ServiceAccount 上打注解覆盖 kOps 配置。对应源码为 PodIdentityWebhookSpec，支持enabled与replicas两个字段。

Snapshot Controller

Snapshot controller（自 kOps 1.21 起，要求 K8s >= 1.20）实现了 CSI 的卷快照（Volume Snapshot）功能。启用方式：

spec: snapshotController: enabled: true

SnapshotControllerConfig 还包含installDefaultClass字段，用于安装默认的 VolumeSnapshotClass。

需要留意：树内（in-tree）卷驱动不支持快照功能。在 AWS 上运行集群时，需同时启用 EBS CSI 驱动：

spec: cloudConfig: awsEBSCSIDriver: enabled: true

自管理 aws-ebs-csi-driver

自 kOps 1.25 起支持自管理（self-managed）的 aws-ebs-csi-driver。如果使用 Amazon EBS 卷，则必须安装 Amazon EBS CSI driver，否则卷操作会失败：

spec: cloudConfig: awsEBSCSIDriver: enabled: true managed: false

权限模型分为两种情况：若未启用 IRSA，控制平面拥有供给节点的权限，自管理的 controller 应运行在控制平面；若启用了 IRSA，kOps 会创建对应的 AWS IAM Role、绑定策略并建立信任关系，允许 ServiceAccount 承担该 IAM Role。要让 Pod 承担这些角色，需启用 Pod Identity Webhook；否则需要自行修改 Pod Spec。

Custom Addons：通过 spec.addons 安装静态清单

Static addons 通过spec.addons配置，每条记录指向一个控制平面可读取的清单文件：

spec: addons: - manifest: https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

对应源码 AddonSpec 非常简单，仅包含Manifest一个字段——这也印证了"静态 Addon 原样应用"的定位。

普通 Kubernetes 资源清单

自 kOps 1.36 起，spec.addons中的manifest可以是常规的 Kubernetes 资源清单，kOps 会原样应用。例如上面的 manifest 会安装 Gateway API 的 CRD。这种方式适合单文件、无版本管理诉求的场景。

Addons 索引（manifest-of-manifests）

当spec.addons中的一条记录需要指向多个带版本的清单时，应使用 kOps 的Addons索引格式。Addons是一个"清单的清单"，允许在一个索引下描述多个可用版本的 manifest，kOps 借此管理 Addon 的版本更新。其 API 定义位于 channels/pkg/api/channel.go。

下面是最小化的Addons索引示例，安装两个 Addon：

kind: Addons metadata: name: example spec: addons: - name: foo.addons.org.io version: 0.0.1 selector: k8s-addon: foo.addons.org.io manifest: foo.addons.org.io/v0.0.1.yaml - name: bar.addons.org.io version: 0.0.1 selector: k8s-addon: bar.addons.org.io manifest: bar.addons.org.io/v0.0.1.yaml

对应文件结构应为：

addon.yaml foo.addons.org.io v0.0.1.yaml bar.addons.org.io v0.0.1.yaml

foo/bar目录下的 YAML 可以是任意 Kubernetes 资源清单。通常这个文件结构会上传到 S3 或其他受支持的存储后端，再在spec.addons中引用。如果 master 节点需要访问存放 Addon 清单的 S3 bucket，可通过spec.additionalPolicies添加 IAM 策略：

spec: additionalPolicies: master: | [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": ["arn:aws:s3:::my-kops-addons/*"] }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucket" ], "Resource": ["arn:aws:s3:::my-kops-addons"] } ]

master 节点会轮询 bucket 中的变更，持续保持 Addon 更新。

版本管理与升级规则（channels 工具原理）

kOps 使用channels工具同时管理系统 Addon 与用户 Addon，两者可并存管理。其版本管理细节在 docs/contributing/addons.md 中有完整说明，核心规则如下：

• version字段：解释为 semver 版本号。channels 工具通过kube-system命名空间上的注解跟踪当前已安装版本（见 addon.go 等实现）。

• 触发升级的三个条件（详见 docs/contributing/addons.md）：

  1. 清单声明的版本大于当前已安装版本；
  2. 版本号相同但id不同；
  3. 版本与id都相同，但清单内容的 hash 已变化。

  这意味着：你手动编辑已部署的 Addon 后不会被覆盖，直到安装新版本。长期方向是 Addon 主要通过 ConfigMap/Secret 配置，且管理器不会替换 ConfigMap。

• selector字段：决定 Addon 包含哪些对象，用于构造--prune参数，使升级时移除旧版本中存在而新版本中不存在的对象（prune 规格见 channel.go 的PruneSpec）。

• kubernetesVersion字段：一个针对 Kubernetes 版本的 semver 范围说明符。目标 K8s 版本不匹配时该 Addon 版本会被忽略，从而可以为 K8s API 的重大变化提供不同版本的清单。注意：kOps 会移除 Kubernetes semver 的pre-release部分，因此1.6.0-beta.1也会匹配>=1.6.0。

• id字段：用于打破 semver 平局。典型场景是集群从 K8s 1.5 升级到 1.6 再降级回 1.5 时，1.6 的 manifest 版本号更大、总是优先，导致无法回退；引入id后，版本相同但id不同的 Addon 会被视为需要更新，从而正确安装匹配当前 K8s 版本的清单。示例：

- version: 1.6.0 selector: k8s-addon: kube-dns.addons.k8s.io manifest: pre-k8s-16.yaml kubernetesVersion: "<1.6.0" id: "pre-k8s-16" - version: 1.6.0 selector: k8s-addon: kube-dns.addons.k8s.io manifest: k8s-16.yaml kubernetesVersion: ">=1.6.0" id: "k8s-16"

实践建议：version尽量贴近上游版本号；manifest 文件名最好包含id，便于维护。

更新引导（bootstrap）Addon

如需查看并更新 kOps 自带的 bootstrap Addon，可运行 channels 命令查看哪些需要更新，追加--yes实际应用：

channels apply channel s3://KOPS_S3_BUCKET/CLUSTER_NAME/addons/bootstrap-channel.yaml

kOps 在集群创建时会生成该bootstrap-channel.yaml，其中按k8s-addon选择器列出了 coredns、kube-dns、dns-controller、cluster-autoscaler、metrics-server、node-problem-detector、aws-load-balancer-controller、eks-pod-identity-webhook 等系统 Addon（见 bootstrapchannelbuilder.go 中的buildAddons实现）。由于系统 Addon 与用户 Addon 使用同一套 channels 机制，kOps 引导安装的 Addon 可以与用户自行添加的 Addon 并存管理——不过要注意，引导 Addon 在 kOps 升级时被替换的概率更高。

实践要点总结

• Managed vs Static 的选择：官方管理的场景优先用 Managed Addon（Cluster Spec 配置，跟随 kOps 生命周期升级）；社区自定义或第三方组件用spec.addons静态清单；需要多版本管理时用Addons索引。
• 配置生效流程：编辑 Cluster Spec →kops edit cluster或直接修改 spec →kops update cluster --yes应用变更。
• 依赖关系：Metrics Server 的安全 TLS（insecure: false）、Pod Identity Webhook、cert-manager 的 DNS-01 都依赖 cert-manager 或 IRSA 的先行启用，务必按依赖顺序规划。
• 升级安全：channels 的版本管理保证已部署 Addon 不会被意外覆盖，切换运行模式（如 NTH 的 IMDS↔Queue Processor）时必须手动清理旧资源。

如需深入了解版本化 Addon 索引的完整语义，可继续阅读 Addon 管理文档；想查看当前集群生成的 bootstrap 通道内容，可从状态存储中读取addons/bootstrap-channel.yaml，对照本文所述的各 Addon 配置段逐项核对。

• 云原生
• 集群管理
• 运维
• IaC