📚 课程目录第3章节点池配置模型

3. 节点池配置模型：详解 Flux 中节点池的 CRD 定义与 YAML 结构

在 GitOps 工作流中，节点池（Node Pool）并非 Kubernetes 原生资源，而是通过 Crossplane 或 Terraform Controller 等基础设施即代码（IaC）工具以 CRD 形式暴露给 Flux 管理的抽象层。本章深入剖析节点池的 CRD 定义、核心字段以及对应的 YAML 配置结构，帮助运维人员理解 Flux 如何通过声明式配置驱动云上节点池的创建、扩缩容与版本升级。

3.1 节点池 CRD 的两种主流模型

Flux 生态中管理节点池通常依赖以下两种 CRD 模型，其设计哲学与资源抽象层级有所不同：

模型	CRD 提供方	资源抽象层级	状态同步方式	适用场景
Crossplane	Provider（如 provider-kubernetes, provider-aws）	Composite Resource (XR) + Managed Resource (MR)	Reconciliation Loop（内置）	多云、复杂依赖、需要组合资源
Terraform Controller	TF Controller（基于 Crossplane 的 Provider）	Terraform 资源（如 `aws_eks_node_group`）	TF Runner + 状态存储	已有 Terraform 代码、需复用现有 HCL 模块

选型建议： 如果团队已经深度使用 Terraform 管理基础设施，且希望保持 HCL 代码库的一致性，优先选择 Terraform Controller。如果追求更原生的 Kubernetes 体验、需要跨云统一抽象，Crossplane 是更优选择。

3.2 Crossplane 节点池 CRD 定义与 YAML 结构

以 AWS EKS 节点池为例，Crossplane 通过 NodeGroup 资源（由 provider-aws 提供）来定义节点池。其 CRD 定义遵循 Crossplane 的 Managed Resource 规范，包含 spec.forProvider 和 status 两大核心部分。

3.2.1 核心字段解析

字段路径	类型	说明	是否必填
`spec.forProvider.clusterNameRef`	Reference	引用已存在的 EKS 集群 CR 名称	是
`spec.forProvider.nodeRoleArn`	string	节点组 IAM 角色 ARN	是
`spec.forProvider.scalingConfig`	object	包含 desiredSize, minSize, maxSize	是
`spec.forProvider.amiType`	string	AMI 类型（如 AL2_x86_64, BOTTLEROCKET_x86_64）	否
`spec.forProvider.launchTemplate`	object	启动模板引用，用于自定义实例配置	否
`spec.writeConnectionSecretToRef`	object	将连接信息写入指定 Secret	否

3.2.2 完整 YAML 示例

apiVersion: eks.aws.crossplane.io/v1alpha1
kind: NodeGroup
metadata:
  name: production-node-pool-v2
  namespace: crossplane-system
spec:
  forProvider:
    clusterNameRef:
      name: production-eks-cluster
    nodeRoleArn: arn:aws:iam::123456789012:role/eks-node-role
    scalingConfig:
      desiredSize: 3
      minSize: 2
      maxSize: 6
    amiType: BOTTLEROCKET_x86_64
    diskSize: 100
    instanceTypes:
      - t3.medium
      - t3.large
    labels:
      workload: production
      pool-version: v2
    tags:
      Environment: production
      ManagedBy: Crossplane
    subnetRefs:
      - name: subnet-private-a
      - name: subnet-private-b
  writeConnectionSecretToRef:
    name: node-pool-connection
    namespace: crossplane-system
  providerConfigRef:
    name: aws-provider-config

  版本回滚关键点： 当需要回滚节点池版本时，只需将 spec.forProvider.amiType 或 spec.forProvider.launchTemplate 中的 AMI ID 改回旧版本，Flux 会自动检测差异并驱动 Crossplane 执行更新。注意 spec.forProvider.scalingConfig.desiredSize 在回滚时通常保持不变，避免触发不必要的扩缩容。

3.3 Terraform Controller 节点池 CRD 定义与 YAML 结构

Terraform Controller 将 Terraform 资源包装为 Terraform CRD。节点池配置以 HCL 代码形式嵌入或引用，通过 spec.source 指定模块来源。

3.3.1 核心字段解析

字段路径	类型	说明	是否必填
`spec.source`	object	指定 Terraform 模块来源（Git/OSS/S3）	是
`spec.vars`	map[string]string	传递给 Terraform 模块的变量	是
`spec.writeOutputsToSecret`	object	将 Terraform outputs 写入 Kubernetes Secret	否
`spec.destroyOnDelete`	bool	删除 CR 时是否销毁资源	否（默认 true）

3.3.2 完整 YAML 示例

apiVersion: tf.upbound.io/v1beta1
kind: Terraform
metadata:
  name: production-node-pool
  namespace: terraform-system
spec:
  source:
    sourceRef:
      type: Git
      name: tf-module-repo
    path: modules/eks-node-group
  vars:
    cluster_name: "production-eks"
    node_group_name: "production-pool-v2"
    desired_size: "3"
    min_size: "2"
    max_size: "6"
    instance_types: '["t3.medium", "t3.large"]'
    ami_type: "BOTTLEROCKET_x86_64"
    disk_size: "100"
    environment: "production"
  writeOutputsToSecret:
    name: node-pool-outputs
    namespace: terraform-system
  destroyOnDelete: true
  providerConfigRef:
    name: aws-tf-provider

版本回滚注意事项： Terraform Controller 的回滚依赖 Git 仓库中的历史提交。回滚时需将 spec.source 指向旧版本的 Git commit 或 tag，同时确保 spec.vars 中的版本相关变量（如 ami_type）与旧版本一致。Flux 会自动触发 Terraform Plan 和 Apply。

3.4 节点池配置模型对比与选择

以下 SVG 图展示了两种模型在 Flux 管理节点池时的架构差异与数据流：

3.5 节点池配置的通用 YAML 结构模板

无论使用哪种 CRD 模型，节点池配置在 Flux 仓库中的 YAML 结构通常遵循以下模板，便于自动化巡检与版本对比：

apiVersion: <crd-group>/<version>
kind: <NodePoolKind>
metadata:
  name: <pool-name>
  namespace: <infra-namespace>
  annotations:
    fluxcd.io/version: "v2.1.0"          # 当前节点池版本标识
    fluxcd.io/previous-version: "v2.0.0" # 上一版本标识，用于回滚验证
spec:
  forProvider:                            # Crossplane 风格
    clusterNameRef:
      name: <cluster-name>
    scalingConfig:
      desiredSize: <int>
      minSize: <int>
      maxSize: <int>
    amiType: <ami-type>
    instanceTypes:
      - <type-1>
      - <type-2>
    labels:
      pool-version: <version-tag>
  # 或
  vars:                                   # Terraform Controller 风格
    desired_size: "<int>"
    ami_type: "<ami-type>"
    instance_types: '["<type-1>"]'

巡检自动化建议： 在 Flux 仓库中为每个节点池 CR 添加 fluxcd.io/version 和 fluxcd.io/previous-version 注解。巡检脚本可通过对比这两个注解值，快速识别哪些节点池发生了版本变更，并触发后续的版本回滚验证流程。

3.6 节点池版本标识与配置快照

为了支持精确的版本回滚，节点池配置模型需要引入 版本标识 和 配置快照 的概念。以下 SVG 图展示了版本标识在 Git 仓库中的演进关系：

通过将节点池配置与版本标识绑定，Flux 可以精确地回滚到任意历史版本，而无需手动修改多个字段。巡检脚本只需对比当前集群中的 fluxcd.io/version 注解与 Git 仓库中期望的版本，即可快速定位配置漂移或版本不一致的节点池。