在多磁盘裸金属主机上选择固定系统磁盘

当一个 SeedImage ISO 必须在多个裸金属主机之间重复使用，且每台主机都拥有多个磁盘时，请使用本指南。本操作步骤可防止 Elemental 在每次启动时自动选择不同的磁盘，并允许 operator 根据稳定的 WWN 在每台主机上选择系统磁盘。

为什么必须设置手动磁盘门控先决条件配置共享的 MachineRegistration 准备每台主机 1. 启动预期的 Live ISO 并阻止自动安装 2. 确认主机正在从 Live ISO 运行 3. DHCP 不可用时配置 Live ISO 网络 4. 识别所有磁盘和预期的系统磁盘 5. 重新安装主机时移除陈旧的 Elemental 标签 6. 创建每台主机的安装目标 7. 运行最终门控并开始安装验证已安装的主机故障排查限制

为什么必须设置手动磁盘门控

在多磁盘主机上，不要将 MachineRegistration.spec.config.elemental.install.device 留空。空设备和空的 device-selector 并不会让 Elemental 等待 operator 选择磁盘。多个已发现的磁盘可能匹配，其中一个磁盘会在未进行唯一性检查的情况下被选中。

也不要将 /dev/sda 用作持久化磁盘标识。存储控制器的发现顺序可能会在 Live ISO 与已安装系统之间发生变化，因此同一个逻辑磁盘在一次启动期间可能显示为 /dev/sda，而在另一次启动期间显示为 /dev/sdb。

本指南使用一种失败即关闭的手动门控机制：

每个可重复使用的 ISO 都包含相同的、初始不存在的安装路径：/dev/elemental-install-target。
该路径不存在时，安装服务无法继续，并且不会回退到自动磁盘选择。
在每台主机上，operator 根据 /dev/disk/by-id/wwn-* 识别目标整盘，并创建指向该磁盘的符号链接作为门控路径。
只有在磁盘、网络、挂载和陈旧标签检查均通过后，operator 才会启动安装服务。

WARNING

本指南中的清理操作会永久销毁数据。只能从 Live ISO 控制台运行该操作，只能在获准重新安装的磁盘上运行，并且必须先确认这些磁盘均未挂载。

先决条件

裸金属 provider 和 elemental-operator 已安装在 global 集群上。
你可以在 cpaas-system 中创建或编辑 MachineRegistration 和 SeedImage 资源。
你可以通过 BMC、iDRAC、iLO 或同等接口访问每台主机的控制台。
每个目标系统磁盘都有稳定的 /dev/disk/by-id/wwn-* 条目。
你知道哪些磁盘可以擦除。如果主机包含必须保留的数据磁盘，请在每个清理命令中排除这些磁盘。
如果 Live ISO 网络没有 DHCP 服务，你已准备好主机 IP 地址、前缀、网关、DNS 服务器和 Global 注册 URL。

有关完整的 provider 和集群创建工作流，请参阅在裸金属上创建集群。

配置共享的 MachineRegistration

将安装设备设置为 /dev/elemental-install-target。不要为此工作流配置 device-selector。

MachineRegistration install settings

apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: <cluster-name>-registration
  namespace: cpaas-system
spec:
  machineName: "<cluster-name>-${System Information/UUID}"
  config:
    elemental:
      install:
        device: /dev/elemental-install-target
        eject-cd: true
        reboot: true
        snapshotter:
          type: btrfs
          maxSnaps: 4
      registration:
        auth: tpm
        # Use hardware TPM when available. For hosts without TPM, enable
        # emulation and derive a unique identity for every host.
        emulate-tpm: true
        emulated-tpm-seed: -1

Live ISO 启动时，该路径会被有意保留为不存在。文件系统标签、GPT PARTLABEL 或 /dev/disk/by-label/* 路径都不能替代它：这些用于标识分区，而 Elemental 要求使用整盘安装目标。

创建引用此 MachineRegistration 的 SeedImage，或者在更改安装设备后重新构建现有的 SeedImage。该 SeedImage 还必须采用首次安装前调整 COS_STATE 大小中所述的 state 分区大小 — 主机升级到不同镜像后，Elemental 默认的 8 GiB 太小，并且必须重新安装主机才能更改该大小。

WARNING

MachineRegistration 设置会嵌入生成的 ISO 中。修改 MachineRegistration 不会更改已经构建并下载的 ISO。请重新构建 SeedImage，等待其就绪，下载新的 ISO，并在使用该 ISO 启动主机前验证其校验和。

准备每台主机

一次只对一台主机执行以下步骤。需要清理磁盘时，不要并行准备多台主机。

1. 启动预期的 Live ISO 并阻止自动安装

从共享 ISO 启动主机。Live ISO 控制台可用后，立即停止并屏蔽自动安装程序：

systemctl stop elemental-register-install.service
systemctl mask elemental-register-install.service
systemctl reset-failed elemental-register-install.service

确认 ISO 包含手动门控路径：

grep -n -C 3 '/dev/elemental-install-target' \
  /run/initramfs/live/livecd-cloud-config.yaml

如果路径不存在，说明主机未启动预期的 ISO。不要继续。

2. 确认主机正在从 Live ISO 运行

findmnt -n -o SOURCE,FSTYPE,TARGET /
findmnt /run/initramfs/live
lsblk -e7 -o NAME,PATH,TYPE,SIZE,MODEL,SERIAL,WWN,FSTYPE,LABEL,MOUNTPOINTS

确认以下所有事项：

/ 是 Live 根目录，例如 LiveOS_rootfs。
虚拟 CD 设备（通常为 /dev/sr0）具有 COS_LIVE 标签。
你计划清理或用作安装目标的磁盘均未挂载。

检查物理磁盘、device-mapper、swap、LVM 和 multipath 的使用情况：

findmnt -rn -o SOURCE,TARGET | grep -E '^/dev/(sd|mapper/)' || \
  echo NO_PHYSICAL_DISK_MOUNTS
swapon --show
pvs 2>/dev/null || true
vgs 2>/dev/null || true
multipath -ll 2>/dev/null || true

如果目标磁盘已挂载，或者无法证明根文件系统属于 Live ISO，请停止操作。

3. DHCP 不可用时配置 Live ISO 网络

首先识别实际的 NetworkManager 连接和接口。不要假设连接始终名为 Wired connection 1。

nmcli device status
nmcli connection show
ip -br link

使用分配给此主机的值配置选定的连接：

nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.254.76/24 \
  ipv4.gateway 192.168.254.1 \
  ipv4.dns 192.168.16.19 \
  ipv4.ignore-auto-dns yes

nmcli connection up "Wired connection 1"

验证地址、默认路由、DNS 解析以及完整的注册 URL：

ip -br addr
ip route
cat /etc/resolv.conf
ping -c 2 -W 2 192.168.254.1
getent hosts <global-domain>
curl -ksS --connect-timeout 10 \
  -o /dev/null -w 'REG_HTTP=%{http_code}\n' \
  'https://<global-domain>/<registration-path-and-token>'

使用特定于站点的网络值，而不要直接复制示例地址。不要将完整的注册 URL 和令牌存入源代码管理系统或共享日志。

此网络配置仅用于连接 Live ISO，以完成注册和初始安装。它不会替代 Cluster API 重新置备期间应用于已安装系统的持久网络配置。

4. 识别所有磁盘和预期的系统磁盘

列出稳定的磁盘属性：

lsblk -d -e7 -o NAME,PATH,TYPE,SIZE,MODEL,SERIAL,WWN,HCTL

for current_disk in /dev/sda /dev/sdb /dev/sdc /dev/sdd; do
  echo "=== ${current_disk} ==="
  udevadm info -q symlink -n "${current_disk}" | tr ' ' '\n' |
    grep -E 'disk/by-id/(wwn|scsi)-' || true
done

根据当前主机调整磁盘列表。记录并交叉核对：

当前内核设备名称。
大小、型号、序列号和控制器地址（HCTL）。
/dev/disk/by-id/wwn-* 路径。
哪个整盘已获准作为系统磁盘。

使用 WWN 以及大小、型号和控制器信息做出决定。不要仅根据内核名称或容量选择磁盘。

5. 重新安装主机时移除陈旧的 Elemental 标签

对于必须保留数据的磁盘，跳过破坏性清理。完全重新安装主机时，请在清理获准的磁盘前移除旧映射：

swapoff -a
vgchange -an 2>/dev/null || true
systemctl stop multipathd.service multipathd.socket 2>/dev/null || true
systemctl mask multipathd.service multipathd.socket 2>/dev/null || true
multipath -F 2>/dev/null || true
udevadm settle

如果主机具有无关的 LVM、multipath 或共享存储设备，请不要使用全局停用命令。只能停用属于获准磁盘的映射。

对于每个获准的磁盘，请在磁盘开头和结尾清除其 GPT、已识别的签名和元数据。以下示例对 /dev/sda 执行操作；仅对你已独立识别并批准的每个磁盘重复该操作。

disk_to_wipe=/dev/sda

lsblk -d -o NAME,PATH,SIZE,MODEL,SERIAL,WWN,HCTL "${disk_to_wipe}"
sgdisk --zap-all "${disk_to_wipe}"
wipefs -a -f "${disk_to_wipe}"
dd if=/dev/zero of="${disk_to_wipe}" \
  bs=1M count=64 conv=fsync status=progress

disk_sectors=$(blockdev --getsz "${disk_to_wipe}")
if [ "${disk_sectors}" -le 262144 ]; then
  echo 'REFUSE: disk is too small; stop and recheck the target'
else
  dd if=/dev/zero of="${disk_to_wipe}" bs=512 \
    seek=$((disk_sectors-131072)) count=131072 \
    conv=fsync status=progress
fi

清理所有获准的磁盘后，刷新内核和 udev：

partprobe /dev/sda /dev/sdb /dev/sdc /dev/sdd 2>/dev/null || true
udevadm trigger --subsystem-match=block
udevadm settle

调整 partprobe 列表，使其仅包含在此主机上清理的磁盘。

验证已清理的磁盘不具有签名、分区、文件系统类型、标签或分区标签：

wipefs /dev/sda /dev/sdb /dev/sdc /dev/sdd
lsblk -e7 -o \
NAME,PATH,TYPE,SIZE,MODEL,SERIAL,WWN,FSTYPE,LABEL,PARTLABEL,MOUNTPOINTS

if blkid /dev/sda /dev/sdb /dev/sdc /dev/sdd 2>/dev/null |
  grep -E 'LABEL="(OLD_)?COS_(GRUB|OEM|RECOVERY|STATE|PERSISTENT)"'; then
  echo COS_LABELS_REMAIN
else
  echo NO_COS_LABELS
fi

调整每个设备列表，使其与已清理的磁盘匹配。仅当以下条件均满足时继续：

wipefs 对任何已清理的磁盘均不打印签名。
lsblk 不显示旧的子分区、FSTYPE、LABEL 或 PARTLABEL。
检查会打印 NO_COS_LABELS。
唯一剩余的 COS_LIVE 标签属于虚拟 CD 设备，而不是系统磁盘。

6. 创建每台主机的安装目标

清理后再次列出稳定的 WWN 路径：

ls -l /dev/disk/by-id/wwn-*
lsblk -d -e7 -o NAME,PATH,SIZE,MODEL,SERIAL,WWN,HCTL

选择并验证预期的整盘后，再创建门控路径。将示例 WWN 替换为记录的此主机 WWN：

test ! -e /dev/elemental-install-target
test ! -L /dev/elemental-install-target

ln -s \
  /dev/disk/by-id/wwn-0x0123456789abcdef \
  /dev/elemental-install-target

readlink -f /dev/elemental-install-target
test -b /dev/elemental-install-target && echo TARGET_IS_BLOCK
lsblk -d -o NAME,PATH,SIZE,MODEL,SERIAL,WWN,HCTL \
  "$(readlink -f /dev/elemental-install-target)"

如果别名已存在或是悬空链接，请不要覆盖它。使用 readlink 检查该别名，确定其存在原因，并仅在确认其已陈旧后将其移除。

该链接只存在于当前 Live ISO 会话中。重启后它应当消失；已安装系统正常启动不需要该链接。

7. 运行最终门控并开始安装

最后一次验证 Live 根目录、挂载、目标链接、网络和 DNS：

findmnt -n -o SOURCE,FSTYPE,TARGET /
findmnt -rn -o SOURCE,TARGET | grep -E '^/dev/(sd|mapper/)' || \
  echo NO_PHYSICAL_DISK_MOUNTS
readlink -f /dev/elemental-install-target
test -b /dev/elemental-install-target
ip -br addr
ip route show default
getent hosts <global-domain>

仅在所有检查均通过后启动安装程序：

systemctl unmask elemental-register-install.service
systemctl reset-failed elemental-register-install.service
systemctl start elemental-register-install.service
journalctl -fu elemental-register-install.service

在日志中确认注册成功、/dev/elemental-install-target 解析到预期的 WWN 磁盘、分区和安装完成，并且配置的弹出/重启操作已执行。

验证已安装的主机

安装触发重启后：

弹出 BMC 虚拟介质，并恢复正常的磁盘优先启动顺序。
确认主机不会重新进入 Live ISO。

在 Global 集群上验证新的 MachineInventory：

kubectl -n cpaas-system get machineinventories.elemental.cattle.io -o wide
kubectl -n cpaas-system describe machineinventory <inventory-name>

确认 inventory 为 Ready=True，报告了预期的网络，并且只有一个当前的 Elemental 磁盘布局。
只有在 inventory 就绪后，才将其添加到 MachineInventoryPool。
Cluster API 分配主机后，按照在裸金属上创建集群中的说明，验证 BaremetalMachine、工作负载 Node、控制平面组件和 CNI。

故障排查

症状	原因和操作
在选择磁盘之前，安装服务就失败了。	这是 `/dev/elemental-install-target` 不存在时预期的安全失败行为。停止并屏蔽该服务，完成检查，创建链接，然后重置并启动服务。
`test -b /dev/elemental-install-target` 失败。	WWN 路径错误、不存在，或未解析为整个块设备。重新检查 `lsblk` 和 `/dev/disk/by-id`；不要启动安装。
仍有多个磁盘具有 `COS_STATE` 或 `COS_PERSISTENT`。	仍然存在之前的 Elemental 布局。停止安装，并清理每个获准用于重新安装的磁盘，直到 `wipefs`、`blkid` 和 `lsblk` 均通过。
同一物理磁盘在重启后显示不同的 `/dev/sdX` 名称。	某些存储控制器出现这种情况是正常的。请比较 WWN、序列号、容量和控制器地址，而不要比较内核名称。
MachineRegistration 已打补丁，但 ISO 仍使用旧目标。	重新构建 SeedImage 并下载新生成的 ISO。MachineRegistration 的更改不会追溯应用到现有 ISO。
Live ISO 中注册成功，但重新配置后已安装的主机没有网络。	请分别诊断已安装系统的 cloud-init 和 NetworkManager 激活情况。Live ISO 的 `nmcli` 配置文件是临时的，不能证明持久化的重新配置网络已成功。

限制

此工作流有意要求对每台主机执行一次控制台操作。它会阻止自动选择，但不会提供完全无人值守的异构磁盘选择。
MachineRegistration 元数据标签不会插入到 install.device 中。
仅基于磁盘大小的 device-selector 只有在确切地只有一个磁盘可以匹配时才是安全的，而当前选择不会强制要求唯一性。对于具有多个相同大小磁盘的主机，首选 WWN gate。
目标必须是整个磁盘。不要将 gate 指向分区。

#在多磁盘裸金属主机上选择固定系统磁盘

#目录

#为什么必须设置手动磁盘门控

#先决条件

#配置共享的 MachineRegistration

#准备每台主机

#1. 启动预期的 Live ISO 并阻止自动安装

#2. 确认主机正在从 Live ISO 运行

#3. DHCP 不可用时配置 Live ISO 网络

#4. 识别所有磁盘和预期的系统磁盘

#5. 重新安装主机时移除陈旧的 Elemental 标签

#6. 创建每台主机的安装目标

#7. 运行最终门控并开始安装

#验证已安装的主机

#故障排查

#限制