docs: restyle Alauda OS install-config templates with callouts and fix installation test findings

.cspell/abbreviations.txt

@@ -13,3 +13,4 @@ VD
 blkid
 dbus
 kubelet
+VRRP

docs/en/install/alauda_os/bare-metal/overview.mdx

@@ -16,4 +16,4 @@ On Bare Metal, the `global` cluster runs on physical hosts that boot an installa
 | Optional, before step 2: plan a standby `global` cluster for disaster recovery | [Create a Global Cluster Disaster Recovery Pair](../global_dr.mdx) |
 | When the installation does not advance | [Troubleshooting](./troubleshooting.mdx) |
 
-`ac` does not delete a Bare Metal `global` cluster; see [Delete the global Cluster](./deleting.mdx). The fields of `install-config.yaml` and the rendered objects are in [Reference](./reference/index.mdx). How Bare Metal DR keeps hosts and identities apart is in [Create a Global Cluster Disaster Recovery Pair](../global_dr.mdx#bare-metal-dr).
+`ac` does not delete a Bare Metal `global` cluster; see [Delete the global Cluster](./deleting.mdx). The fields of `install-config.yaml` are described with the template in [Create the global Cluster](./create_cluster.mdx#install-config); the rendered objects are in [Reference](./reference/index.mdx). How Bare Metal DR keeps hosts and identities apart is in [Create a Global Cluster Disaster Recovery Pair](../global_dr.mdx#bare-metal-dr).

docs/en/install/alauda_os/bare-metal/prerequisites.mdx

@@ -5,43 +5,94 @@ queries:
   - bare metal global cluster prerequisites
   - bare metal global bootstrapIP 12443
   - push baremetal-base-image and baremetal-base-image-iso
+  - bare metal global cluster alauda os ku arm64
 ---
 
 # Prerequisites for Bare Metal
 
 Complete the [common prerequisites](../prerequisites.mdx) first, then prepare the following for Bare Metal. `ac` creates no machines.
 
+## Host OS and Architecture \{#host-os}
+
+Every host of the `global` cluster runs the same host OS on the same host architecture. Choose them before you push the OS images:
+
+- **Alauda OS M55**, on `amd64` only.
+- **Alauda OS KU**, on `amd64` or `arm64`.
+
+When the host architecture differs from the architecture of the bootstrap node, use the hybrid Core Package; see [Download](../../prepare/download.mdx).
+
 ## OS Images in the Registry \{#os-images}
 
-Push both Bare Metal Alauda OS images to the external registry, under `tkestack/` in `global.registry.address`. They come from one OS archive and are not interchangeable:
+Push both Bare Metal OS images of the host OS to the external registry, under its `tkestack/` project. They come from one OS archive and are not interchangeable:
+
+{/* lint ignore no-legacy-os-names */}
+
+| Image (Alauda OS M55) | Image (Alauda OS KU) | Used for |
+|---|---|---|
+| `tkestack/baremetal-base-image-iso` | `tkestack/kubeos-iso` | The live ISO that hosts boot to register. |
+| `tkestack/baremetal-base-image` | `tkestack/kubeos-rootfs` | The root filesystem that hosts are installed, upgraded, and reprovisioned with. |
 
-| Image | Used for |
-|---|---|
-| `tkestack/baremetal-base-image-iso` | The live ISO that hosts boot to register. |
-| `tkestack/baremetal-base-image` | The root filesystem that hosts are installed, upgraded, and reprovisioned with. |
+Download the OS archive of the host OS. For Alauda OS KU, download the archive of the host architecture, which holds single-architecture images. The archive is described in [Image Format by Provider](../../../overview/alauda_os_support_matrix.mdx#image-format-by-provider). The `tkestack` project must exist in the registry.
 
-The archive is described in [Image Format by Provider](../../../overview/alauda_os_support_matrix.mdx#image-format-by-provider). The `tkestack` project must exist in the registry. Run the following as root on a Linux host with containerd that reaches the external registry and has free space in `/var/lib/containerd` of at least the archive size. `<registry-address>`, `<registry-username>`, and the password are `global.registry.address`, `global.registry.username`, and `global.registry.password` from `install-config.yaml`; when the registry needs no credentials, omit the `read` line and the `-u` options.
+Run the following as root on a Linux host with containerd that reaches the external registry and has free space in `/var/lib/containerd` of at least the archive size. The same commands serve both OSes: set `ISO_REPO` and `ROOT_REPO` for your OS first.
+
+- `<registry-address>`, `<registry-username>`, and the password are the address, user name, and password of the external registry. When the registry needs no credentials, omit the `read` line and the `-u` options.
+- `<archive-tag>` is the tag that `images ls -q` prints for the two images.
+- `<os-image-tag>` is the tag the images get in the registry: the ISO image tag and the root filesystem image tag. Use the archive file name without `.tar`, such as `alaudaos-44.m55.202610030151-0.x86_64`, so that each release, OS, and architecture keeps its own tag. For Alauda OS M55 this is also `<archive-tag>`; the Alauda OS KU archive tags both images `baremetal`.
+
+{/* lint ignore no-legacy-os-names */}
 
 ```bash
+# Alauda OS M55
+ISO_REPO=baremetal-base-image-iso; ROOT_REPO=baremetal-base-image
+# Alauda OS KU
+# ISO_REPO=kubeos-iso; ROOT_REPO=kubeos-rootfs
+
 read -rsp 'Registry password: ' REGISTRY_PASSWORD; echo
 ctr -n bare-metal-os images import --all-platforms --no-unpack <bare-metal-os-archive>
-ctr -n bare-metal-os images ls -q     # baremetal-base-image:<os-image-tag> and baremetal-base-image-iso:<os-image-tag>
+ctr -n bare-metal-os images ls -q     # ${ISO_REPO}:<archive-tag> and ${ROOT_REPO}:<archive-tag>
 
-for repo in baremetal-base-image baremetal-base-image-iso; do
+for repo in "${ISO_REPO}" "${ROOT_REPO}"; do
   ctr -n bare-metal-os images push --local --skip-verify \
     -u "<registry-username>:${REGISTRY_PASSWORD}" \
-    "<registry-address>/tkestack/${repo}:<os-image-tag>" "${repo}:<os-image-tag>"
+    "<registry-address>/tkestack/${repo}:<os-image-tag>" "${repo}:<archive-tag>"
   curl -sSk -u "<registry-username>:${REGISTRY_PASSWORD}" \
     "https://<registry-address>/v2/tkestack/${repo}/tags/list"
 done
 
-ctr -n bare-metal-os images rm \
-  "baremetal-base-image:<os-image-tag>" "baremetal-base-image-iso:<os-image-tag>"
+ctr -n bare-metal-os images rm "${ISO_REPO}:<archive-tag>" "${ROOT_REPO}:<archive-tag>"
 unset REGISTRY_PASSWORD
 ```
 
+Push the images with `ctr` as shown. Do not use `docker push` or another tool that rewrites the image manifest: the Alauda OS KU installer reads the manifest as it is in the archive.
+
 Continue when each `tags/list` response contains `<os-image-tag>`; otherwise check the registry address, the credentials, the `tkestack` project, and the push output.
 
+### Look Up the Image Tags \{#os-image-tags}
+
+The ISO image tag and the root filesystem image tag are the tags of the two images in the registry. To look them up later, run the following on a host that reaches the registry, such as the bootstrap node. When the registry needs no credentials, omit the `read` line and the `-u` option.
+
+```bash
+# ISO_REPO and ROOT_REPO as set for the push above
+read -rsp 'Registry password: ' REGISTRY_PASSWORD; echo
+for repo in "${ISO_REPO}" "${ROOT_REPO}"; do
+  curl -sSk -u "<registry-username>:${REGISTRY_PASSWORD}" \
+    "https://<registry-address>/v2/tkestack/${repo}/tags/list"; echo
+done
+unset REGISTRY_PASSWORD
+```
+
+The output lists the tags of each repository, here for Alauda OS M55:
+
+```text
+{"name":"tkestack/baremetal-base-image-iso","tags":["<os-image-tag>"]}
+{"name":"tkestack/baremetal-base-image","tags":["<os-image-tag>"]}
+```
+
+{/* lint ignore no-legacy-os-names */}
+
+The tag of `tkestack/baremetal-base-image-iso` (`tkestack/kubeos-iso`) is the ISO image tag, and the tag of `tkestack/baremetal-base-image` (`tkestack/kubeos-rootfs`) is the root filesystem image tag. When a repository lists more than one tag, for example because images of another release were pushed earlier, use the tag of the archive that you downloaded for this ACP release.
+
 ## Hosts \{#hosts}
 
 One host for each control plane replica, plus one for each worker replica. Before a host boots the ISO:
@@ -53,9 +104,9 @@ One host for each control plane replica, plus one for each worker replica. Befor
 ## Network \{#network}
 
 - **An address during the live ISO boot**, from DHCP or configured on the host console as described in [Network Connectivity](../../../workload_clusters/alauda_os/bare-metal/prerequisites.mdx#network-connectivity).
-- **A route from the hosts to the bootstrap node.** `global.bootstrapIP` is the bootstrap node address that the hosts route to. For the flows from the hosts to the bootstrap node, see [Installation](../../prepare/communication_matrix.mdx#installation).
-- **A control plane endpoint.** With `internal`, the default, the provider runs a Self-built VIP on the control plane nodes: reserve an unused IPv4 address in the control plane Layer 2 domain and a `vrid` that no other VRRP instance in it uses. With `external`, your load balancer forwards the ports marked **Yes** in **Forward on load balancer** in [Platform Access Address and `global` VIP](../../prepare/communication_matrix.mdx#global_vip). See [Plan the Control Plane Endpoint](../prerequisites.mdx#control-plane-endpoint).
+- **A route from the hosts to the bootstrap node address**, the IPv4 address of the bootstrap node that the hosts reach. The hosts download the ISO and register through it on port `12443`. For the flows from the hosts to the bootstrap node, see [Installation](../../prepare/communication_matrix.mdx#installation).
+- **A control plane endpoint**, as planned in [Plan the Control Plane Endpoint](../prerequisites.mdx#control-plane-endpoint): a Self-built VIP with its VRID, or an external load balancer that forwards the ports marked **Yes** in **Forward on load balancer** in [Platform Access Address and `global` VIP](../../prepare/communication_matrix.mdx#global_vip).
 
 ## Next Steps
 
-[Create the global Cluster on Bare Metal](./create_cluster.mdx).
+You now have, in addition to the common values, the host OS and architecture, the ISO image tag and the root filesystem image tag, and the bootstrap node address. Continue with [Create the global Cluster on Bare Metal](./create_cluster.mdx).

docs/en/install/alauda_os/bare-metal/reference/install-config-parameters.mdx

@@ -1,32 +1,15 @@
 ---
 weight: 10
-title: Parameters
+title: Rendered Manifests
 queries:
-  - bare metal global cluster install-config.yaml
+  - bare metal global cluster objects rendered from install-config.yaml
   - bare metal global cluster rendered manifests
   - global-registration seedimage machineregistration
 ---
 
-# install-config.yaml Parameters for Bare Metal
+# Objects Rendered from install-config.yaml on Bare Metal
 
-This page lists the Bare Metal fields of the `global` cluster's `install-config.yaml` and the objects that `ac` renders from them. The fields that every provider shares are in [Installation Reference](../../reference.mdx#install-config). For the complete template, see [Write `install-config.yaml`](../create_cluster.mdx#install-config).
-
-## Bare Metal Fields \{#fields}
-
-| Field | Required | Default | Description |
-|---|---|---|---|
-| `global.bootstrapIP` | Yes | — | The IPv4 address of the bootstrap node that the hosts route to. It is the registration endpoint, `https://<bootstrapIP>:12443`. |
-| `cluster.network.loadBalancer.type` | No | `internal` | `internal` for a Self-built VIP, `external` for your load balancer. |
-| `cluster.network.loadBalancer.vrid` | For `internal` | — | 0-255, unique in the control plane Layer 2 domain. `0` is valid. |
-| `cluster.network.loadBalancer.interface`, `vipMode` | Not supported | — | The provider binds the VIP to the interface that carries the node address. |
-| `provider.baremetal.isoImageTag` | Yes | — | The tag of `tkestack/baremetal-base-image-iso`. Write the tag only, without registry or repository. |
-| `provider.baremetal.rootImageTag` | Yes | — | The tag of `tkestack/baremetal-base-image`. It may differ from `isoImageTag`. |
-| `provider.baremetal.serviceAccountSigningKey` | No | Generated | The base64 of the PEM private key that signs ServiceAccount tokens. Set it only for a disaster recovery pair; see [Generate the Shared Keys](../../global_dr.mdx#generate-the-shared-keys). |
-| `controlPlane.replicas` | Yes | — | An odd number: `1`, or `3` or more. The control plane runs stacked etcd. A cluster with a single control plane node is for testing and cannot be upgraded. |
-| `controlPlane.baremetal.machineInventoryPool`, `computes[].baremetal.machineInventoryPool` | Yes | — | The `MachineInventoryPool` each node group draws from. Two node groups cannot share a pool. |
-| `computes[].name` | Yes | — | A DNS-1123 label, unique per group. `control-plane` is reserved. |
-
-The node groups take no `cpuCore`, `memoryGiB`, `network`, `disks`, or `hosts` fields; writing one is an error. `credentialRef` is rejected as well.
+This page lists the objects that `ac` renders from the `global` cluster's `install-config.yaml` on Bare Metal. The Bare Metal fields are described with the template in [Write `install-config.yaml`](../create_cluster.mdx#install-config); the fields that every provider shares are in [Common `install-config.yaml` Fields](../../reference.mdx#install-config).
 
 ## Rendered Manifests \{#rendered-manifests}
 
@@ -44,9 +27,11 @@ The node groups take no `cpuCore`, `memoryGiB`, `network`, `disks`, or `hosts` f
 
 `create` also creates objects in the bootstrap cluster that are not part of `manifests/`:
 
+{/* lint ignore no-legacy-os-names */}
+
 | Object | Name | Purpose |
 |---|---|---|
-| `MachineRegistration` | `global-registration` | The registration the hosts enrol through. Hosts register as `MachineInventory` objects named `global-<system-uuid>`. Hosts install with Btrfs snapshots and keep four of them. |
-| `SeedImage` | `global-registration-iso` | Builds the installation ISO from `tkestack/baremetal-base-image-iso:<isoImageTag>`. Its `COS_STATE` partition is sized to 20 GiB. |
-| `elemental-image-catalog` entry | Kubernetes version | Maps the Kubernetes version to `tkestack/baremetal-base-image:<rootImageTag>`. `ac` writes the same entry on the `global` cluster in stage 8. It serves hosts that run Alauda OS M55 on amd64, including hosts registered without architecture and OS labels. For other hosts, add their keys after the installation; see [Add Kubernetes Versions to the Image Catalog](../../../../workload_clusters/alauda_os/bare-metal/prerequisites.mdx#add-versions-to-image-catalog). |
+| `MachineRegistration` | `global-registration` | The registration the hosts enrol through. Hosts register as `MachineInventory` objects named `global-<system-uuid>`. With Alauda OS M55, hosts install with Btrfs snapshots and keep four of them. With Alauda OS KU, hosts carry the labels `os.baremetal.alauda.io/id: alaudaos.k.25` and `os.baremetal.alauda.io/arch`, the architecture each host reports, and install the root filesystem image from `rootImageTag`. |
+| `SeedImage` | `global-registration-iso` | Builds the installation ISO for `architecture` from `tkestack/baremetal-base-image-iso:<isoImageTag>`, or `tkestack/kubeos-iso:<isoImageTag>` with Alauda OS KU. With Alauda OS M55, its `COS_STATE` partition is sized to 20 GiB. |
+| `elemental-image-catalog` entry | Kubernetes version | Maps the Kubernetes version to the root filesystem image, `tkestack/baremetal-base-image:<rootImageTag>` or `tkestack/kubeos-rootfs:<rootImageTag>`. The key is the version, such as `v1.36.4-acp.3`, for Alauda OS M55, and `<version>_<architecture>_alaudaos.k.25` for Alauda OS KU. `ac` writes the same entry on the `global` cluster in stage 8. It serves hosts of the `osType` and `architecture` in `install-config.yaml`; with Alauda OS M55, it also serves hosts registered without architecture and OS labels. For other hosts, add their keys after the installation; see [Add Kubernetes Versions to the Image Catalog](../../../../workload_clusters/alauda_os/bare-metal/prerequisites.mdx#add-versions-to-image-catalog). |
 | `Secret` | `dex.tls` | The certificate for the registration endpoint, issued for `global.bootstrapIP`. |