Managing platform images

Modified: 08 Mar 2023 00:28 UTC

Platform Images (or PI's) contain the SmartOS hypervisor that powers the containers deployed in Triton DataCenter. This document explains how to manage Platform Images, including installing new PI's, updating compute nodes to use new PI's, and cleaning unused PI's from the USB Key.

Listing currently installed platform images via the command line

The easiest way to list all platforms is by using the sdcadm platform list command:

headnode# # sdcadm platform list
VERSION           CURRENT_PLATFORM  BOOT_PLATFORM  LATEST
20150806T161843Z  1                 2              true
20150723T072359Z  4                 3              false
20150709T171606Z  1                 0              false
20141016T150132Z  0                 1              false

Value	Description	Notes
Version	The platform version string
Current Platform	The number of servers currently running the version	Both compute and head node(s)
Boot Platform	The number of servers set to boot to version on reboot	Both compute and head node(s)
Latest	Flag indicating the latest platform

Installing a new platform image

Periodically Joyent will issue updates to the Platform Image (PI) to resolve issues, implement security patches, and add new features. The platform image is installed onto the USB key and then is used to boot the head and compute node(s) in the Triton installation.

Notes:

Customers should not apply updates, including platform images, without the express instruction of MNX support. If you have questions about released platforms, please contact MNX support at portal.mnxsolutions.com.
The complete installation of a new platform image requires a reboot.
This procedure does not impact the operation of Triton or cause downtime until you reboot compute nodes. Normally, this can be scheduled for off-hours or weekends, unless otherwise instructed by MNX support (for example, if there is a critical security patch).

From your head node run the following command.

headnode# sdcadm platform install --latest -C support
Checking latest Platform Image installed version
Downloading platform 20150806T063331Z (image 646e1bce-5f17-44d9-af41-55301d565416) to /var/tmp/platform-release-20150806-20150806T063331Z.tgz
Installing platform image onto USB key
==> Mounting USB key
==> Staging 20150806T063331Z
######################################################################## 100.0%
==> Unpacking 20150806T063331Z to /mnt/usbkey/os
==> This may take a while...
==> Unmounting USB Key
==> Adding to list of available platforms
==> Done!
Platform installer finished successfully
Proceeding to complete the update
Updating 'latest' link
Installation complete

The --latest flag tells sdcadm to pull the most recent platform image that is available in the support channel, which is specified by the -C support flag. Unless expressly told by MNX support, customers with current Triton support contracts should always use the support channel.

Updating the boot platform via the command line

Once you have downloaded a newer PI you can assign it to the servers you wish to use that PI. To change a server to use a different platform image, you can use the assign subcommand for sdcadm platform:

Assigning 20150806T161843Z to the compute node called "cnode02"
```
headnode# sdcadm platform assign 20150806T161843Z cnode02
```
Assigning 20150806T161843Z to all compute nodes and the head node:
```
headnode# sdcadm platform assign 20150806T161843Z --all
```

Removing old platform images via the command line

The sdcadm platform remove command will remove a given platform from your installation; by passing the --cleanup-cache option to the command the associated platform files will be removed from the usb key. It's important to manage the number of PI's you keep on the key, as you can run out of space.

For example, listing the current platforms:

headnode# sdcadm platform list
VERSION           CURRENT_PLATFORM  BOOT_PLATFORM  LATEST  DEFAULT
20151112T202630Z  2                 2              true    true
20151103T231017Z  0                 0              false   false
20151002T091718Z  0                 0              false   false
20151002T091442Z  0                 0              false   false

Removing a platform:

headnode# sdcadm platform remove 20151002T091442Z --cleanup-cache

The following Platform Images will be removed:
    20151002T091442Z

Would you like to continue? [y/N] y

Mounting USB key
Removing platform 20151002T091442Z
Unmounting USB key
Removing cache for platform 20151002T091442Z
Updating 'latest' link
Done.

Listing platforms showing that the selected platform has been removed:

# sdcadm platform list
VERSION           CURRENT_PLATFORM  BOOT_PLATFORM  LATEST  DEFAULT
20151112T202630Z  2                 2              true    true
20151103T231017Z  0                 0              false   false
20151002T091718Z  0                 0              false   false

Rebooting nodes

You will now need reboot the head node and compute nodes to load the new platform image. This can be done by using the reboot button in the Operations Portal. Alternatively, you can log into the compute node directly and issue the shutdown -i6 -g0 command. You will need to answer "y" to the "do you want to continue? (y or n):" confirmation dialog to initiate the reboot process.

Notes:

All instances will be returned to the state that they were prior to the reboot after the compute node comes back up.
Orchestration will be affected while the head node reboots; while the head node is rebooting, you will not be able to perform functions such as provisioning, adding users, changing cloud firewall rules, managing instance states, etc.
DO NOT REBOOT ALL COMPUTE NODES AT THE SAME TIME. This could significantly slow down the reboot of each compute node and cause protracted down time for instances.

In addition to the command line, platform images can be viewed in two places in the Operations Portal. The first place is on the Servers page for each individual server. The currently booted platform image is displayed along with the next platform image which will be used at the next reboot:

To see the full list of platform images available, you can click on the edit icon to the right of the platform image name in the "Next Boot" field. This will display all the available platform images in a drop down, from which you can select the next boot image. This is the image that will be used the next time the compute node is rebooted.

It is also possible to see the current list of platform image from the Default Boot Options page. You can reach this page by going to the Servers page and then clicking on Default Boot Options:

This will cause the screen to expand and show the following detail:

The listbox can be expanded to show the full list of platform images available and to set the default platform image for all new compute nodes.

Best practices

Joyent recommends that you keep only the platform images you are actively using, as each platform image will take up roughly 300MB of space on your USB key.

Ideally, you will only keep only three platform images:

Platform Image	Description
Current	The currently running platform.
Previous	The platform that was most recently booted.
Last	The version most recently deployed prior to the current one.

However, you will need to keep as many platform images that you may have a need to use.

DOCUMENTATION

APIs