Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Imagehowto

Imagehowto

How To Create and Use Custom Images

Introduction

ProtoGeni allows users to create a custom image that is based on an existing node's disk contents, and then use that new image on other nodes in a different slice. Note that in this context, sliver and node are used interchangeably. Also note that in this context, ProtoGeni makes no distinction between bare metal slivers, and VM container slivers; you can create a custom image based on either one. Of course, a custom image based on a bare metal sliver is going to be a lot bigger then a VM container custom image. Also, bare metal images are not interchangeable with VM container images; you cannot use a bare metal image on a VM container, and you cannot use a VM container image on a bare metal sliver.

A note about terminology: We often use the term snapshot interchangeably with custom image. This is slightly confusing, but can be explained like this: In order to create a custom image, you take a snapshot of a node's disk contents, saving that to a new data file that can be loaded on another node.

For the remainder of this document, we will assume that you have created a slice with a single sliver, and that you have already logged into the slice, installed software, arranged to start up services, whatever else is needed on your custom image. Lets also say that the URN for this sliver is urn:publicid:IDN+foo.net+sliver+888.

Creating a New Image

The easiest way to create a new image is to the use the createimage.py test script. If you would like to use the ProtoGeni API, then take a look inside the script; both the ProtoGeni CM and AM export the CreateImage method. But lets use the test script since that is a lot easier to deal with. The test script takes at least at least two arguments. The first is what you want to name the new image, and the second is the sliver URN (of the node) that you want to snapshot. If the name already exists, the old contents of the snapshot are overridden. The name is just an identifier, comprised of alphanumeric characters. Pick something easy to remember, easy to pronounce, perhaps the name of your cat, dog, or horse. For example:

ops> createimage.py booboo urn:publicid:IDN+foo.net+sliver+888

This will typically return status within a few seconds. If there are no initial errors, you will receive an email later when the image snapshot has been completed. In the meantime, you should not alter the state of the sliver or the slice, lest you get into an inconsistent state and your image data file is worthless.

The actual return value is a list of two strings. For example:

[
 'urn:publicid:IDN+foo.net+image+foo-net:booboo,
 'https://www.foo.net/image_metadata.php?uuid=c0b47d37-f6cd-11e1-9f72-001143e453fe'
]

The first string is the URN of the new image, and is suitable for use in another rspec via the disk_image entity:

<node client_id="mynode" exclusive="true">
  <sliver_type name="raw-pc">
    <disk_image name="urn:publicid:IDN+foo.net+image+foo-net:booboo"/>
  </sliver_type>
</node>

The second string is a URL that can be used when submitting an rspec to another ProtoGeni site; this is discussed in more detail below.

Sharing an Image with Others

By default, the createimage.py script creates an image that can be shared with other users. There are no restrictions on this sharing; any other user with permission to use the same the Aggregate Manager, may use your new image. Sharing is read-only; only you or another user from the same Slice Authority may update the image file contents. Other users may create their own new image though, using your image as their starting point.

If you do not want your image to be shared, then you can supply a third argument to createimage.py script. The argument should be the integer "0" to turn sharing off.

Using an Image on another Aggregate Manager

A shared image may also be used on another Aggregate Manager by specifying the URL of that image (see the second string in the example return value above). An example rspec fragment is:

<node client_id="mynode" exclusive="true">
  <sliver_type name="raw-pc">
    <disk_image url="https://www.foo.net/image_metadata.php?uuid=c0b47d37-f6cd-11e1-9f72-001143e453fe"/>
  </sliver_type>
</node>

When this form is used, the AM will download and cache the image metadata and the image data file. Each time the image is used, the metadata is downloaded again, and if the metadata indicates that the image data file has changed, it too will be downloaded again. For this reason, starting such a sliver might take longer, depending on the bandwidth available to download the image. It might even fail outright in the case of a network partition that prevents the AM from getting the image.

As above, only images that have been marked for sharing may be used by another Aggregate Manager.

Image Compatibility

A few words about image compatibility should be mentioned. For bare metal images, it should not be assumed that an image created on one AM will work on another. It is highly dependent on the type of hardware, the version of the OS kernel, and what drivers are compiled in or available in the image. With that said InstaGeni racks are all identical and so bare metal images should work the same on any rack. Your mileage may of course vary!

For VM container images, only images based the FEDORA15-OPENVZ-STD, may be shared between AMs. This is the current default on all ProtoGeni and InstaGeni sites, so this should not be a problem in the short term. Long term, we hope to support a more flexible mapping of VM container images.

Deleting an Image

To delete an image, you should use the deleteimage.py test script. As with createimage.py, both the ProtoGeni CM and AM export the DeleteImage method. The script takes at least a single argument, the URN of the image to delete. You received this URN as a return value when you created the image. The second optional argument is necessary when you wish to delete an image you did not create; in order to avoid accidental deletion, you must specify the URN of the user that created the image. Note that you are never allowed to delete an image that was created by a user at a different Slice Authority.  For example:

ops> deleteimage.py urn:publicid:IDN+emulab.net+image+emulab-net:myimage
ops> deleteimage.py urn:publicid:IDN+emulab.net+image+emulab-net:myimage urn:publicid:IDN+emulab.net+user+stoller