83. 由机器池排序引起的非预期的 terraform 配置漂移

Terraform provisioned RKE2 downstream cluster.
Terraform 配置了 RKE2 下游集群。

When adding a new machine pool to an existing Rancher2 RKE2 cluster, Terraform may plan to modify existing machine pools that were provisioned in previous runs, causing unintended updates to control plane and worker nodes.
在向现有的 Rancher2 RKE2 集群添加新机器池时，Terraform 可能会计划修改之前运行中已配置的机器池，导致控制平面和工作节点出现意外更新。

Stable ordering of keys is the simplest and most reliable workaround until a provider-level fix is available.
稳定排序密钥是最简单、最可靠的变通方法，直到提供者层面的修复方案出现。

• Use ordered keys (prefix keys with numbers) in the map so that lexicographical sorting produces a stable list order. Example:
  在映射中使用有序键（带数字的前缀键），以便字典序排序产生稳定的列表顺序。示例：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>1-control: name: control control_plane_role: true quantity: 3 2-worker: name: worker worker_role: true quantity: 2 3-NEW-POOL: name: NEW-POOL worker_role: true quantity: 1</code></span></span></span>

• When adding pools: 添加池时：

  • Add the new entry with a key that maintains the intended final alphabetical order (using numeric prefixes as above). Test in a non-production environment before applying to production clusters.
    添加一个保持最终字母顺序的键（使用数字前缀，如上所述）。在应用到生产集群之前，先在非生产环境中测试。

Terraform maps are unordered collections. When the Rancher provider converts a map into the provider's TypeList, keys are sorted lexicographically. Machine pools are matched by position (index) inside that list — not by name. Adding a new pool changes the alphabetical order, which shifts indexes. Terraform then incorrectly associates existing list positions with different pool configurations and plans in-place updates to the wrong pools.
Terraform 地图是无序集合。当牧场提供者将映射转换为提供者的类型列表时，键按字典序排序。机器池是根据列表中的位置（索引）匹配的，而不是按名称。添加新池会改变字母顺序，从而改变索引。Terraform 随后错误地将现有列表位置与不同的池配置关联，并计划将原地更新到错误的池中。

Impact 影响

• Unexpected in-place modifications of existing pools.
  对现有泳池进行意外的原地修改。

• Potential disruption of node roles (control/etcd/worker) and pod scheduling.
  可能扰乱节点角色（控制/etcd/工作者）和舱体调度。

Illustrative Example 示例

Assume a scenario where existing cluster has two machine pools: control and worker.
假设现有集群有两个机器池：控制池和工人池。

Initial Terraform run 最初的 Terraform 运行

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>Map input (unordered): control -> control_plane: true, quantity: 3 worker -> worker_role: true, quantity: 2 Lexicographical sort creates ordered list: [0] control -> creates control pool [1] worker -> creates worker pool</code></span></span></span>

Adding new pool NEW-POOL
新增泳池 NEW-POOL

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>Map input (unordered): control -> control_plane: true, quantity: 3 worker -> worker_role: true, quantity: 2 NEW-POOL -> worker_role: true, quantity: 1 Lexicographical sort creates new ordered list: [0] NEW-POOL -> (index 0 already exists) [1] control -> (index 1 already exists) [2] worker -> new</code></span></span></span>

Result (incorrect): 结果（错误）：

• Terraform sees index mismatches and plans to:
  Terraform 发现指数不匹配，计划：

  • Modify existing pool at index 0 (previously control) to NEW-POOL configuration.
    将索引为 0 的现有池（之前为控制）修改为 NEW-POOL 配置。

  • Modify existing pool at index 1 (previously worker) to control configuration.
    修改索引 1 的现有池（之前是 worker）以控制配置。

  • Create a new worker pool at index 2.
    在指数2创建一个新的劳动力池。

Expected: Create one new NEW-POOL pool without modifying control or worker.
预期：创建一个新的 NEW-POOL 池，但不修改控制权或工人。

Example Terraform plan snippet (illustrative)
Terraform 平面图示例（示例）

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># rancher2_cluster_v2.cluster_rke2 will be updated in-place ~ resource "rancher2_cluster_v2" "cluster_rke2" { ~ rke_config { # Index [0]: Existing "control" pool → incorrectly changed to "NEW-POOL" ~ machine_pools { ~ name = "control" -> "NEW-POOL" ~ control_plane_role = true -> false ~ etcd_role = true -> false ~ worker_role = false -> true ~ quantity = 3 -> 1 ~ machine_labels = { ~ "nodepool" = "control" -> "worker" } } # Index [1]: Existing "worker" pool → incorrectly changed to "control" ~ machine_pools { ~ name = "worker" -> "control" ~ control_plane_role = false -> true ~ etcd_role = false -> true ~ worker_role = true -> false ~ quantity = 2 -> 3 ~ machine_labels = { ~ "nodepool" = "worker" -> "control" } } # Index [2]: New pool created as "worker" (expected "NEW-POOL") + machine_pools { + name = "worker" + control_plane_role = false + worker_role = true + quantity = 2 } } } Plan: 0 to add, 1 to change, 0 to destroy.</code></span></span></span>

Please note that this behaviour is not considered a defect in the provider but rather an edge case resulting from ordering inconsistencies that lead to configuration drift. An enhancement request has been submitted at the provider level to better handle such scenarios, and the improvement is expected to be incorporated in a future release.
请注意，这种行为不被视为提供者的缺陷，而是由于排序不一致导致配置漂移的边缘情况。已在提供者层面提交了增强请求以更好地处理此类情景，预计改进将在未来版本中纳入。