#Configure Annotations, Labels, and Taints on Nodes

#Overview

Cluster API (CAPI) 可以将选定的 Machine 元数据传播到对应的 Node：

• 标签（Labels）：通过 controller manager 同步
• 注解（Annotations）：通过 controller manager 同步
• 污点（Taints）：通过 Machine 模板配置（在节点注册时应用）

本指南展示如何配置上述内容，以及如何验证它们是否已应用于 Machine 和 Node 资源。

注意：示例假设您的 Cluster API controller manager 名称为 capi-controller-manager，并且您分别管理用于工作负载节点和控制平面节点的 MachineDeployment 和 KubeadmControlPlane 对象。

#Prerequisites

• 具有编辑 capi-controller-manager 部署和 Cluster API 资源的权限
• 版本 4.2.0 或更高版本

#1) 从 Machines 同步标签到 Nodes

#第一步：在 controller manager 上启用标签同步

向 capi-controller-manager 容器添加以下参数，指定要同步到 Nodes 的 Machine 标签：

spec:
  template:
    spec:
      containers:
      - name: manager
        args:
        - --additional-sync-machine-labels=env,role,topology.kubernetes.io/zone

将逗号分隔的列表替换为您想要同步的标签。

#第二步：在 Machine 模板上添加标签

• 对于工作负载节点（MachineDeployment）：在 .spec.template.metadata.labels 上设置标签。

• 对于控制平面节点（KubeadmControlPlane）：在 .spec.machineTemplate.metadata.labels 上设置标签。

  ---
  apiVersion: cluster.x-k8s.io/v1beta1
  kind: MachineDeployment
  metadata:
    name: <md-name>
    namespace: <namespace>
  spec:
    clusterName: <cluster-name>
    template:
      metadata:
        labels:
          env: prod
          role: app
          topology.kubernetes.io/zone: az1
      spec: {}

  ---
  apiVersion: controlplane.cluster.x-k8s.io/v1beta1
  kind: KubeadmControlPlane
  metadata:
    name: <kcp-name>
    namespace: <namespace>
  spec:
    version: <k8s-version>
    clusterName: <cluster-name>
    machineTemplate:
      metadata:
        labels:
          env: prod
          role: control-plane
          topology.kubernetes.io/zone: az1
      spec: {}
    kubeadmConfigSpec: {}

#验证

# 检查 Machine 是否有标签
kubectl get machine -n <namespace> -l cluster.x-k8s.io/cluster-name=<cluster-name> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels}{"\n"}{end}'

# 检查 Node 是否有标签
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels}{"\n"}{end}'

#2) 从 Machines 同步注解到 Nodes

#第一步：在 controller manager 上启用注解同步

向 capi-controller-manager 容器添加以下参数，指定要同步到 Nodes 的 Machine 注解：

spec:
  template:
    spec:
      containers:
      - name: manager
        args:
        - --additional-sync-machine-annotations=example.com/owner,example.com/runtime

将逗号分隔的列表替换为您想要同步的注解。

#第二步：在 Machine 模板上添加注解

• 对于工作负载节点（MachineDeployment）：在 .spec.template.metadata.annotations 上设置注解。

• 对于控制平面节点（KubeadmControlPlane）：在 .spec.machineTemplate.metadata.annotations 上设置注解。

  ---
  apiVersion: cluster.x-k8s.io/v1beta1
  kind: MachineDeployment
  metadata:
    name: <md-name>
    namespace: <namespace>
  spec:
    clusterName: <cluster-name>
    template:
      metadata:
        annotations:
          example.com/owner: team-a
          example.com/runtime: containerd
      spec: {}

  ---
  apiVersion: controlplane.cluster.x-k8s.io/v1beta1
  kind: KubeadmControlPlane
  metadata:
    name: <kcp-name>
    namespace: <namespace>
  spec:
    version: <k8s-version>
    clusterName: <cluster-name>
    machineTemplate:
      metadata:
        annotations:
          example.com/owner: platform
          example.com/runtime: containerd
      spec: {}
    kubeadmConfigSpec: {}

#验证

# 检查 Machine 是否有注解
kubectl get machine -n <namespace> -l cluster.x-k8s.io/cluster-name=<cluster-name> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'

# 检查 Node 是否有注解
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'

#3) 将污点从 Machines 应用到 Nodes

污点直接在 Machine 模板上配置，因此会在节点注册时应用到 Node。

• 对于工作负载节点（MachineDeployment）：在 .spec.template.spec.taints 上设置污点。

• 对于控制平面节点（KubeadmControlPlane）：在 .spec.machineTemplate.taints 上设置污点。

  ---
  apiVersion: cluster.x-k8s.io/v1beta1
  kind: MachineDeployment
  metadata:
    name: <md-name>
    namespace: <namespace>
  spec:
    clusterName: <cluster-name>
    template:
      metadata: {}
      spec:
        taints:
        - key: dedicated
          value: db
          effect: NoSchedule

  ---
  apiVersion: controlplane.cluster.x-k8s.io/v1beta1
  kind: KubeadmControlPlane
  metadata:
    name: <kcp-name>
    namespace: <namespace>
  spec:
    version: <k8s-version>
    clusterName: <cluster-name>
    machineTemplate:
      metadata: {}
      taints:
      - key: custom-taint-key
        effect: NoSchedule
      spec: {}
    kubeadmConfigSpec: {}

#验证

# 检查 Machine 是否有污点
kubectl get machine -n <namespace> -l cluster.x-k8s.io/cluster-name=<cluster-name> \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.taints}{"\n"}{end}'

# 检查 Node 是否有污点
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.taints}{"\n"}{end}'

#注意事项

• 确保字段名称拼写正确：metadata.labels、metadata.annotations。
• 每当在 Machines 上添加新的标签或注解键时，记得更新 controller 上同步的标签/注解列表。
• 变更后，请等待协调完成；Node 的更新可能需要短时间才能生效。