Prepare Alauda OS for Hosts

A host joins the platform by booting from an ISO. On this page, you build that ISO: one registration and one ISO for each OS and architecture of your hosts. One registration serves the hosts of its OS and architecture for every workload cluster. Do this before you register the hosts.

Meet the Bare Metal prerequisites first. Run the ac commands on this page from a machine where ac is logged in to the platform.

Find your case, and follow its sections:

Your caseSections to follow
The global cluster was installed on Bare Metal with ac. The hosts have the same OS and architecture as the hosts of the global cluster, and are for a new cluster that uses the registry of the global cluster.Generate the Commands, then Create the Registration and the ISO. The installation of the global cluster already pushed the images and added the image catalog keys.
Any other new cluster: hosts of another OS or architecture, a cluster with a dedicated registry, or a global cluster that was not installed on Bare Metal with ac.All sections, in order.
An existing cluster of an older version needs hosts of an architecture that it has never used.Generate the Commands with the ACP version of that cluster, then Push the OS Images and Add the Image Catalog Keys.

Generate the Commands

Fill in the generator below, once for each OS:

FieldValue
ACP versionThe ACP version of the global cluster. A new cluster always has this version.
OSAlauda OS M55 or Alauda OS KU. All hosts of a cluster run the same OS.
ArchitecturesThe architectures of the hosts. Alauda OS M55 hosts are amd64. The hosts of an Alauda OS KU cluster can mix amd64 and arm64.
OS image tagOne for each architecture: the file name of the OS archive without .tar. See Look Up the Image Tags.
Registry addressThe registry of the global cluster. The generator shows the command that prints it.

The generator prints these outputs:

For the registry of the global cluster, run ac config use-cluster global, then ac -n cpaas-system get secret public-registry-credential -o jsonpath='{.data.registry}' | base64 -d.

v4.5.0 ยท Kubernetes v1.36.4-acp.3

An OS image tag is the file name of its OS archive without .tar, and the tag of both images of the archive.

Push the OS images

amd64
read -rsp 'Registry password: ' REGISTRY_PASSWORD; echo
for repo in baremetal-base-image-iso baremetal-base-image; do
  <extract-dir>/res/<host-arch>/packtool image push <bare-metal-os-archive> \
    "<registry-address>/tkestack/${repo}:<os-image-tag-for-v4.5.0>" --ref "${repo}:<os-image-tag-for-v4.5.0>" \
    -u "<registry-username>" -p "${REGISTRY_PASSWORD}"
  curl -sSk -u "<registry-username>:${REGISTRY_PASSWORD}" \
    "https://<registry-address>/v2/tkestack/${repo}/tags/list"; echo
done
unset REGISTRY_PASSWORD

Add the image catalog keys

ac -n cpaas-system patch configmap elemental-image-catalog --type merge --patch-file /dev/stdin <<'EOF'
{
  "data": {
    "v1.36.4-acp.3": "tkestack/baremetal-base-image:<os-image-tag-for-v4.5.0>",
    "v1.36.4-acp.3_etcd": "acp/k8s/etcd:v3.6.13-acp.5"
  }
}
EOF

ac -n cpaas-system get configmap elemental-image-catalog -o yaml

Registration file

alaudaos-m55-amd64.yaml
apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: alaudaos-m55-amd64
  namespace: cpaas-system
  labels:
    app.kubernetes.io/part-of: cluster-api-provider-baremetal
spec:
  # ${...} placeholders are expanded by elemental-register from SMBIOS data.
  machineName: "alaudaos-m55-amd64-${System Information/UUID}"
  machineInventoryLabels:
    app.kubernetes.io/part-of: cluster-api-provider-baremetal
    pool.baremetal.alauda.io/eligible: "true"
    elemental.cattle.io/serial-number: "${System Information/Serial Number}"
    # Architecture of the host, reported by elemental-register. Keep the value as is.
    os.baremetal.alauda.io/arch: "${Runtime/Architecture}"
    # OS identifier of the image this registration installs.
    os.baremetal.alauda.io/id: alaudaos.m.55
  machineInventoryAnnotations:
    elemental.cattle.io/machine-uuid: "${System Information/UUID}"
  config:
    elemental:
      install:
        # Each host reports its disks and waits until you select its system disk.
        device-selection: inventory
        eject-cd: true
        reboot: true
        snapshotter:
          type: btrfs
          maxSnaps: 4
      registration:
        # Each host uses its hardware TPM when usable, otherwise an emulated one.
        tpm-mode: auto
        emulated-tpm-seed: -1
---
apiVersion: elemental.cattle.io/v1beta1
kind: SeedImage
metadata:
  name: alaudaos-m55-amd64-iso
  namespace: cpaas-system
  labels:
    app.kubernetes.io/part-of: cluster-api-provider-baremetal
spec:
  type: iso
  baseImage: <registry-address>/tkestack/baremetal-base-image-iso:<os-image-tag-for-v4.5.0>
  registrationRef:
    apiVersion: elemental.cattle.io/v1beta1
    kind: MachineRegistration
    name: alaudaos-m55-amd64
    namespace: cpaas-system
  targetPlatform: linux/amd64
  size: 20Gi
  cleanupAfterMinutes: 120
  cloud-config:
    stages:
      boot:
        - name: "Size COS_STATE for reprovisioning"
          files:
            - path: /etc/elemental/config.d/partitions.yaml
              permissions: 0644
              content: |
                install:
                  partitions:
                    state:
                      size: 20480

Create the registration and build the ISO

alaudaos-m55-amd64
ac config use-cluster global
ac apply -f alaudaos-m55-amd64.yaml
ac -n cpaas-system wait --for=condition=SeedImageReady=True \
  seedimage/alaudaos-m55-amd64-iso --timeout=30m
ac -n cpaas-system get seedimage alaudaos-m55-amd64-iso \
  -o jsonpath='{.status.conditions[?(@.type=="SeedImageReady")].reason}{"\n"}{.status.downloadURL}{"\n"}{.status.checksumURL}{"\n"}'

Push the OS Images

Download the OS archive of each architecture for the ACP version; see Downloading Alauda OS.

Run Push the OS images as root, one block for each architecture, on a Linux host that meets these conditions:

  • It can reach the registry.
  • It has the Core Package of the current platform version extracted. The packtool of this package also pushes the archives of earlier ACP versions.
  • It has at least as much free space in /var/tmp as the archive size.

In the commands, <extract-dir> is the extracted installer/ directory, and <host-arch> is the architecture of the host, amd64 or arm64. Each block pushes the two images of one archive, and then lists the tags of both repositories in the registry.

  • The tkestack project must exist in the registry.
  • Use a registry account that can push to the tkestack project.
  • Do not push with docker push or another tool that rewrites the image manifest, because the Alauda OS KU installer reads the manifest exactly as it is in the archive.
  • Take both images from the same archive. Do not pair images from different archives, and do not point cluster resources at a build registry.
  • For a workload cluster with a dedicated registry (cluster.registrySecretRef), push the images into that registry as well, with its address and account. Each time a host is reinstalled, it pulls the OS image that the image catalog names from the registry of the cluster; see Image Registry.
  • In a disaster recovery pair where the two global clusters use different registries, push the images into both registries.

Continue when each tags/list response includes the OS image tag. Otherwise, check the registry address, the credentials, the tkestack project, and the push output.

Add the Image Catalog Keys

The image catalog tells the provider which OS image to install on a host. Until the catalog has the key for the Kubernetes version, architecture, and OS of a host, the host waits and is not installed.

Select the global cluster, and run Add the image catalog keys:

ac config use-cluster global
ac whoami --show-server

The command adds the keys to the image catalog, keeps the existing keys, and prints the catalog. Continue when the printed catalog has the keys that you added. Otherwise, run the command again with the correct values.

In a disaster recovery pair, the image catalog is not synchronized. Run the command again for the standby global cluster: use export KUBECONFIG=<standby-kubeconfig> instead of ac config use-cluster global, and run unset KUBECONFIG afterwards.

Create the Registration and the ISO

For each architecture:

  1. Save the Registration file under the file name that the generator shows, for example alaudaos-m55-amd64.yaml. Use the file as generated. If the hosts need site-specific DNS settings to register on first boot, add them to MachineRegistration.spec.config.cloud-config. Do not add /etc/resolv.conf to SeedImage.spec.cloud-config.
  2. Run Create the registration and build the ISO. It applies the file on the global cluster, waits until the ISO is built, and prints three lines: the result of the build, the download URL of the ISO, and the URL of its checksum.

Continue when the first line is SeedImageBuildSuccess and the two URLs are not empty. Then download the ISO, and verify it.

Verify the ISO

The checksum file holds the SHA-256 hash and the original file name of the ISO. The original name contains colons, which Windows does not allow in file names. The saved file therefore often has another name, and sha256sum -c cannot find it. Compare the hashes instead:

curl -sSk <checksum-url> | awk '{print $1}'    # expected hash
sha256sum <saved-iso-file> | awk '{print $1}'  # actual hash

Continue when the two hashes are the same. Otherwise, download the ISO again. On Windows, certutil -hashfile <saved-iso-file> SHA256 prints the actual hash.

Rebuild the ISO

After cleanupAfterMinutes, the URLs are cleared, but SeedImageReady can stay True. Check the reason again before you download the ISO. To get a new URL, delete the SeedImage and apply the file again:

ac config use-cluster global
ac -n cpaas-system delete seedimage <name>-iso
ac apply -f <name>.yaml

Then repeat the wait and get commands of Create the registration and build the ISO. If you no longer have <name>.yaml, generate it again as described in Generate the Commands, with the same ACP version and OS image tag.

Hosts that have already booted the old ISO continue to register. Boot the remaining hosts from the new ISO.

Next Steps