Update a host schematic

You can manually update a host’s schematic to change kernel boot parameters or required network configurations without deleting and recreating the machine. This is essential when updating settings for systems using systemd or ensuring a host reconnects to the management plane after a full reset.

Prerequisites:

• You have the STACKIT CLI installed on your machine.
• You have acquired a valid talosconfig for the STEC-managed Edge Cluster.
• You have either network access directly to the IP addresses of your Talos machine(s) or have enabled the cloud proxy feature in your STEC instance to be able to access your Talos machine(s) via the STEC control plane.
• You have installed talosctl.
• Console access (e.g., IPMI, iDRAC, or serial console) to the host in case of network loss.
• yq installed.

While using talosctl to alter managed configurations can break your cluster, manually updating the schematic image is a validated exception.

Retrieve the schematic ID

Before upgrading, you must create or identify an EdgeImage with your wanted configuration (such as custom extraKernelArgs) and copy its generated schematic ID. You can create an EdgeImage by following the guide here.

After creating the EdgeImage, get the schematic ID. You can fetch it using the following commands:

# Get kubeconfig to access your instance's API
> stackit beta edge-cloud kubeconfig create --instance-id "${INSTANCE_ID}" --filepath "${INSTANCE_KUBECONFIG}"
# Get schematic id of your image
> kubectl get edgeimages "${IMAGENAME}" -oyaml --kubeconfig "${INSTANCE_KUBECONFIG}" | yq .status.schematicId
4882f479852c10fe43e8d53721274726d5867581a709c37584964786342a05fc

Update the schematic

Run the upgrade command with your updated schematic ID:

Do not use this guide to upgrade your cluster. Use it only to update the schematic.

1. Back up the current schematic ID: Save the current schematic ID of your target node in case you need to rollbck. Also note down the exact version of your target node’s edgehostlet as we need to re-use it when actually changing the schematic id.

   > talosctl --talosconfig YOUR_CLUSTER.talosconfig \
       -e TALOS_PROXY_URL_OR_CONTROL_PLANE_IP \
       -n TARGET_NODE_IP \
       get extensions
   
   NODE             NAME                    VERSION
   TARGET_NODE_IP   edgehostlet             v1.12.11-stackit.v1.8.3
   TARGET_NODE_IP   edgehostlet-bootstrap   v1.12.11-stackit.v1.8.3
   TARGET_NODE_IP   schematic               4882f479852c10fe43e8d53721274726d5867581a709c37584964786342a05fc

   • Save the hash in the schematic row under VERSION. This is your original schematic ID.
   • The edgehostlet row also shows the current Talos version on the node.

2. Trigger the upgrade: Append your updated schematic ID and the exact Talos version to your environment’s image factory URL. When upgrading a worker node, you must route the command through a Control Plane or Proxy endpoint (-e) because the CLI requires the cluster kubeconfig to drain workloads before rebooting:

   > talosctl --talosconfig YOUR_CLUSTER.talosconfig \
       -e TALOS_PROXY_URL_OR_CONTROL_PLANE_IP \
       -n TARGET_NODE_IP \
       upgrade \
       --image image-factory.edge.YOUR_REGION.stackit.cloud/installer/YOUR_UPDATED_SCHEMATIC_ID:YOUR_TALOS_VERSION \
       --legacy
   
   watching nodes: [TARGET_NODE_IP]
    * TARGET_NODE_IP: post check passed

   Note: Ensure you update YOUR_REGION to the specific region where your Edge instance is deployed (for example, eu01).

3. Verify the changes: Once the node reboots and transitions back to a Ready state, verify the updated schematic is active by listing the node’s extensions:

   > talosctl --talosconfig YOUR_CLUSTER.talosconfig \
       -e TALOS_PROXY_URL_OR_CONTROL_PLANE_IP \
       -n TARGET_NODE_IP \
       get extensions
   
   NODE             NAME       VERSION
   TARGET_NODE_IP   schematic  3f02ae2c5b6a478fe9276eac798b43950edb1b4e7c15736542700d46dde21357

Rollback

If something goes wrong during the schematic update or the node fails to connect to the management plane, you can revert the host to its previous configuration.

To rollback, repeat the talosctl upgrade command from Step 2, but replace the updated schematic ID in the image URL with your original schematic ID (which you backed up in Step 1).