Custom image management

Modified: 05 Nov 2024 18:47 UTC

This page will walk you through the process of adding custom image management functionality to a Triton deployment.

Enabling custom images

Create your own custom images with these instructions for creating infrstructure container images for SmartOS and Linux, or creating HVM virtual machine images.

Prior to creating custom images, you will need to enable Image Management within your Triton installation. This can be done in one of three ways.

Configured so images are stored locally on the head node.
Configured so images are stored in a locally configured Manta object storage.
Configured so images are stored in a remotely configured Manta object storage.

The recommended best practice is to store within a locally configured Manta service. This is how Triton Compute Service is currently configured.

If custom image management is not enabled, you will see the following error returned from either CloudAPI or the node-smartdc CLI if you attempt custom image creation:

$ sdc-createimagefrommachine --machine 3d68ee48-d1fa-685c-9c33-e23064141138
--imageVersion 1.0.0 --name image1 --description "Does this work"

sdc-createimagefrommachine: error (NotAvailable): custom image creation is not
currently available

Local image management

To allow custom images using local storage, run the following in your Triton head node global zone:

headnode# echo '{"metadata": {"IMGAPI_ALLOW_LOCAL_CREATE_IMAGE_FROM_VM": true}}'
\ | sapiadm update $(sdc-sapi /services?name=imgapi | json -H 0.uuid)

When the config-agent running in the IMGAPI zone picks up this change (after about 30 seconds), the IMGAPI service will be restarted with the "allowLocalCreateImageFromVm" property set to true.

Note: Please be sure to monitor your disk usage within the imgapi zone if you are storing images local to your head node.

Image management in a local Manta

This process assumes that the Manta you are using shares a UFDS directory with the imgapi zone. If it does not, please follow the Image Management in a remote Manta section below.

To enable image management in a local Manta, you need to log into the imgapi zone and run the imgapi-manta-setup that is found under /opt/smartdc/imgapi/bin, passing in the URL for the Manta you wish to use (i.e., the value of the MANTA_URL variable that you would use to access it).

[imgapi0]# /opt/smartdc/imgapi/bin/imgapi-manta-setup --help
Setup IMGAPI in this SmartDataCenter to use a Manta sharing the same
master UFDS. Preferably the Manta is local (i.e. not across the WAN).
This will do the appropriate setup for all instances of IMGAPI in this
DC. This is also re-runnable if it fails part way.

Usage:
imgapi-manta-setup <manta-url> [<options>] | bunyan

where "<manta-url>" can be the special string "FIRST-LB" as a hack for
development/staging to indicate the first local Manta LB.

Options:
-h, --help      Print this help and exit.
-r, --remote    Indicate that the Manta is remote, i.e. across the WAN. This
info is used by IMGAPI to attempt to intelligently cache
image files locally.
-i, --insecure  Whether to ignore SSL certs when accessing Manta. This
should only be used in testing/development.

Image management in a remote Manta

Since connecting to a remote Manta usually requires passing data across a WAN it is not a recommended procedure. However, imgapi can use caching in order to help manage this type of installation.

To enable image management in a remote Manta, you need to log into the imgapi zone and run the imgapi-external-manta-setup that is found under /opt/smartdc/imgapi/bin, passing in the URL for the manta you wish to use (ie, the value of the MANTA_URL variable that you would use to access it).

[imgapi0]# ./imgapi-external-manta-setup  --help
Setup IMGAPI in this SmartDataCenter to use a given external Manta
for image storage. This will do the appropriate setup for all
instances of IMGAPI in this DC. This is also re-runnable if it fails
part way.

**Note:** The preferred IMGAPI setup is using a *local* Manta. Please
use the "imgapi-manta-setup" script for that.

Usage:
imgapi-external-manta-setup [<options>] <manta-url> <manta-user> \
<path-to-priv-key> | bunyan

Options:
-h, --help      Print this help and exit.
-i, --insecure  Whether to ignore SSL certs when accessing Manta. This
should only be used in testing/development.

Checking the status of image management

You can determine the status of image management by logging into the imagapi zone on the head node and running the following command:

[imgapi0]# json -f /opt/smartdc/imgapi/etc/imgapi.config.json storage
{
  "local": {
    "baseDir": "/data/imgapi"
  }
}

The example above shows a Triton installation that is configured to use local storage for images. In this case, all images will be stored under /data/imgapi in the imgapi zone on the head node.

An installation that is configured to use Manta for storage will return values similar to this:

[imgapi0]# json -f /opt/smartdc/imgapi/etc/imgapi.config.json storage
{
  "manta": {
    "url": "https://manta.demo.local",
    "user": "admin",
    "key": "/root/.ssh/imgapi.id_rsa",
    "keyId": "71:19:af:eb:e7:c3:ce:cf:75:09:c7:0b:bc:4e:89:ca",
    "insecure": false,
    "remote": false,
    "baseDir": "imgapi"
    },
    "local": {
      "baseDir": "/data/imgapi"
    }
  }

DOCUMENTATION

APIs