Managing platform images

Modified: 22 Nov 2017 17:39 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
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.


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 Joyent 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:

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.

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.


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.