#在节点上配置注解、标签和污点

#概述

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

• 标签：通过 controller manager 同步
• 注解：通过 controller manager 同步
• 污点：通过 Machine 模板（在节点注册期间应用）

本指南介绍如何分别进行配置，以及如何验证它们是否已同时应用于 Machine 和 Node 资源。

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

#前提条件

• 具备编辑 capi-controller-manager deployment 和 cluster API 资源的权限
• 4.2.0 或更高版本

#1) 将 Machine 中的标签同步到 Node

#步骤 1：在 controller manager 上启用标签同步

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

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

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

#步骤 2：在 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: {}

#验证

# Check Machine has labels
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}'

# Check Node has labels
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels}{"\n"}{end}'

#2) 将 Machine 中的注解同步到 Node

#步骤 1：在 controller manager 上启用注解同步

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

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

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

#步骤 2：在 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: {}

#验证

# Check Machine has annotations
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}'

# Check Node has annotations
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'

#3) 将 Machine 中的污点应用到 Node

污点直接在 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: {}

#验证

# Check Machine has taints
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}'

# Check Node has taints
kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.taints}{"\n"}{end}'

#注意事项

• 确保字段名称拼写正确：metadata.labels、metadata.annotations。
• 当你在 Machine 上添加新键时，请同时更新 controller 中已同步的标签/注解列表。
• 修改完成后，请等待 reconciliation 完成；Node 更新可能需要一点时间才会显示。