Importing an image

Modified: 16 Mar 2023 03:08 UTC

Images are used to create instances in Triton. Images can be created by the customer or downloaded from Joyent.

Note: This document covers the process of importing Triton Images. For a discussion of Docker Images, please see Docker registries.

Import an image from images.smartos.org

The website images.smartos.org contains a list of images that MNX provides. Available images can be listed like so:

# images-imgadm list
UUID                                  NAME                            VERSION       FLAGS  OS       PUBLISHED
...
4e60ee8e-370f-4126-b15b-a17ee13aab19  debian-11                       20230127      P      linux    2023-01-27T22:37:57Z
1c4ee516-ac27-4f3a-8004-941e6a94130b  debian-10                       20230127      P      linux    2023-01-27T22:44:36Z
bfea06c8-23a4-40e7-ad4b-10cb2ad574d0  ubuntu-18.04                    20230127      P      linux    2023-01-27T23:36:30Z
cf120bc1-4c01-449f-bc4d-504133f12e05  ubuntu-20.04                    20230127      P      linux    2023-01-27T23:42:42Z
55595e1a-0223-4f65-9437-6c4d4c29aa60  ubuntu-22.04                    20230127      P      linux    2023-01-27T23:48:40Z
a6ad84ed-5179-49c5-8773-c4e9631a98ae  centos-stream-8                 20230131      P      linux    2023-01-31T05:14:20Z
6d981c23-4073-4a4d-ac71-167d97cb1691  centos-stream-9                 20230131      P      linux    2023-01-31T05:34:50Z
2852d09a-c19b-11ed-8798-00151714048c  minimal-64-trunk                20230313      P      smartos  2023-03-13T12:32:45Z
e6b8e342-c19d-11ed-b9d1-00151714048c  base-64-trunk                   20230313      P      smartos  2023-03-13T12:52:24Z
7375df20-c1a2-11ed-bf77-00151714048c  pkgbuild-trunk                  20230313      P      smartos  2023-03-13T13:24:58Z

The following will import an image from images.smartos.org, but the -S flag can be used to import from another source, given a UUID of the image.

headnode# sdc-imgadm import  c3321aac-a07c-11e3-9430-fbb1cc12d1df -S https://images.smartos.org

Import a custom image

To import a custom Image into Triton, you must move the image files to the head node. From here, you can import the Image like so:

headnode# sdc-imgadm import -m /var/tmp/my-example-1.0.0.dsmanifest  -f /var/tmp/my-example-1.0.0.zfs.gz

Upon completion, you will see the following.

Imported image 3d73e502-9fa6-11e3-8fa8-bb6a8876bb21 (myImage, 1.0.0, state=unactivated)
3d73e502-9fa6-11e3-8fa8-bb6a8876bb21  [==============================================>] 100%     264B
Added file "/var/tmp/my-example-1.0.0.zfs.gz" (compression "gzip") to image 3d73e502-9fa6-11e3-8fa8-bb6a8876bb21
Activated image 3d73e502-9fa6-11e3-8fa8-bb6a8876bb21

Changing the owner of an image

Once you have imported the image, you will need to assign the ownership as required. To do this, first find the UUID of the owner that you wish to assign the image to via sdc-useradm.

headnode# sdc-useradm search admin
UUID                                  LOGIN  EMAIL           CREATED
930896af-bf8c-48d4-885c-6573a94b1853  admin  root@localhost  2015-01-15

Then run the sdc-imgadm command to update the ownership.

headnode# sdc-imgadm update 5f67e820-1489-4db7-9df2-1d8e3ec5cd90 owner=930896af-bf8c-48d4-885c-6573a94b1853
Update image 5f67e820-1489-4db7-9df2-1d8e3ec5cd90 (myImage, 20140929, state=active)

Finally, you can check ownership:

headnode# sdc-imgapi /images/5f67e820-1489-4db7-9df2-1d8e3ec5cd90 | json -Hag owner
930896af-bf8c-48d4-885c-6573a94b1853

Troubleshooting

If you see an error of the format:

headnode# sdc-imgadm import -f myImage-zfs.gz -m myImage.json
sdc-imgadm: error (OwnerDoesNotExist): owner "0edc1460-7144-4417-cba2-25ca478c5a78" does not exist

This indicates that the manifest file contains an owner UUID that does not exist in the target Triton installation.

You can verify this by pulling the owner out of the manifest:

headnode# cat myImage.json | json -Hag owner
0edc1460-7144-4417-cba2-25ca478c5a78

And then checking to see if the owner exists:

headnode# sdc-useradm get 0edc1460-7144-4417-cba2-25ca478c5a78
sdc-useradm get: error (ResourceNotFound): 0edc1460-7144-4417-cba2-25ca478c5a78 does not exist

There are three ways to solve this issue.

  1. Update the manifest file with the UUID of an owner in the current Triton installation, such as the admin account for public images (you can retrieve that UUID with sdc-useradm get admin). Then retry the import command.

  2. Update the manifest file with the "zero UUID", which is 00000000-0000-0000-0000-000000000000. Then retry the import command.

  3. Pass the --skip-owner-check flag through to sdc-imagadm; this flag tells imgadm to ignore the owner on the manifest. If you do this, you will also need to follow the section on Changing the Owner of an Image.