VO Image List Format
Introduction
AppDB produces image list files in order to provide third parties with information regarding particular virtual appliance versions (a.k.a. VM image versions), or groups thereof. There are two types of image lists; the first one is the standalone image list, generated while publishing a virtual appliance version, which contains a single image. In this case, the image list is made publicly available and accessible through AppDB, with the exception of private virtual appliances, which are only accessible by the VM authors.
The second type of image list is the VO-wide image list, which is a collection of VM versions that a VO manager has endorsed. It gets generated each time a VO manager publishes a list of endorsed VM versions and is accessible only by authenticated parties (instructions).
The format of the image list follows the HEPiX image list format and, therefore, is interoperable with the vmcatcher and the cloudkeeper clients. All of the generated image lists are signed by the AppDB service. An example of the image list structure can be found here
Image list schema
Note: Field names prefixed with ad: are AppDB-specific extensions to the HEPiX format.
| Field Name | Description |
|---|---|
| dc:date:created | Date in year-month-dayTHour:Minute:SecondTimezone format, e.g. 2021-10-06T14:37:28Z |
| dc:date:expires | Date in year-month-day format, after which the Virtual Machine Image List should no longer be trusted, e.g. 2499-12-31T22:00:00Z |
| dc:description | Description of the Virtual Machine Image List, e.g. “This is a VO-wide image list for vo.access.egi.eu VO.” |
| dc:identifier | RFC 4122 UUID for the Virtual Machine Image List, for unique identification purposes, e.g. 488dcdc4-9ab1-4fc8-a7ba-b7a5428ecb3d |
| dc:source | Source of the image list, its default value is https://appdb.egi.eu/ |
| dc:title | Title of the Virtual Machine Image List, e.g. “VO vo.access.egi.eu image list.” |
| ad:num_of_images | Number of images contained in this list, e.g. 8 |
| ad:publisher:fullname | Full name of image list publisher, as taken from the AppDB user profile |
| ad:publisher:guid | Unique identifier of image list publisher as taken from the AppDB user profile |
| ad:publisher:uri | Link to the publisher’s AppDB user profile |
| ad:vo | The name of the VO this list pertains to, e.g. vo.access.egi.eu. In the case of a standalone image list, the value is always “appdb-general” |
| hv:uri | URL to retrieve this image list, e.g. https://vmcaster.appdb.egi.eu/store/vo/vo.access.egi.eu/image.list. In the case of VO wide image lists, the URL is not publicly accessible. |
| hv:version | The version of this image list (auto-generated from AppDB per VO), e.g. 20210913143728 |
| hv:endorser/hv:x509 | Placeholder for endorser metadata |
| hv:images | The images referenced by this image list |
Endorser schema
The schema of hv:endorser/hv:x509 object describing the endorser service. In our case this is the AppDB service itself.
| Field Name | Description |
|---|---|
| hv:ca | Standard hash id for the Certification Authorities |
| hv:dn | x.509 DN of the endorser |
| hv:email | Email address of the endorser |
| dc:creator | Name of the endorser |
Image item schema
The schema of the image data objects contained in the “hv:images” list. In the case of VO wide image lists, this information is meant to be processed by a subscription service (e.g. cloudkeeper), in order to populate a cloud provider VM catalog (e.g. OpenStack Glance).
| Field Name | Optional | Description |
|---|---|---|
| dc:description | NO | Free text describing the image |
| dc:identifier | NO | RFC 4122 UUID for image unique identification purposes |
| dc:title | NO | Title of image. Default value gets auto-generated by AppDB, if not provided by user |
| dc:date:expires | NO | The expiration date of the specific VM version. The value is user-defined and may span any of 3, 6, 9, or 12 months after the publication of the image version |
| ad:appid | NO | AppDB ID referencing the virtual appliance the image belongs to |
| ad:mpuri | NO | AppDB URL referring to the VM version in relation to the specific VO image list version. In the case of a standalone image list, this value will be the same as ad:base_mpuri Note: In the case of VO-wide image lists, this information is important, as it relates the specific virtual appliance version with the specific VO image list version. Moreover, storing it in a cloud provider catalogue helps identify the distribution of the particular image. |
| ad:base_mpuri | NO | AppDB URL referring to the VM version |
| ad:group | NO | Obsolete. Used in the past to group many VMs of the same virtual appliance version. Now, each virtual appliance version corresponds to a single VM, and the value defaults to “General group”. May be ignored |
| hv:hypervisor | NO | Typically set to reflect the supported Virtualization technology, e.g. Xen, KVM. The list of all possible values may be retrieved from the AppDB API |
| hv:format | NO | The image format, e.g. OVA. User defined |
| hv:uri | NO | URI pointing to the location of this image. |
| hv:version | NO | The version of the image, so that updates can share the same metadata. It does not follow a specific pattern and it is up to the user to provide, although AppDB enforces values to be unique per virtual appliance |
| hv:size | NO | Size of the image in bytes, as measured by AppDB during checksum computation |
| sl:checksum:sha512 | NO | Computed sha512 checksum of the image from AppDB upon publication by user |
| sl:comments | NO | User comments for the specific VM version. |
| sl:arch | NO | Architecture of the image, typically ’x86_64’ The list of all possible values may be retrieved from the AppDB API |
| sl:os | NO | The operating system family the image runs, examples include “Linux”, “BSD”, “Windows” The list of all possible values may be retrieved from the application:osfamily elements of the AppDB API |
| sl:osname | NO | The operating system the image runs, examples include “Ubuntu” The list of all possible values may be retrieved from the application:os elements of the AppDB API, as long as their familyid attribute corresponds to the sl:os value |
| sl:osversion | NO | The operating system version the image runs, examples include “20.04” |
| hv:ram_minimum | YES | Minimum number of RAM required to run the virtual machine image, expressed as an integer in bytes. |
| ad:ram_recommended | YES | Recommended number of RAM required to run the virtual machine image, expressed as an integer in bytes. |
| hv:core_minimum | YES | Minimum number of virtual cores required to run the virtual machine image, expressed as an integer. AppDB constraints the value to 1,2,4,8,16 or 32 cores |
| ad:core_recommended | YES | Recommended number of virtual cores required to run the virtual machine image, expressed as an integer. AppDB constraints the value to 1,2,4,8,16 or 32 cores |
| ad:accel_type | YES | The accelerator type the VM supports. Currently, the only supported value is “GPU”. |
| ad:accel_minimum | YES | Minimum accelerator cores. Only available if accel_type is defined] AppDB constraints the value to 1,2,4,8,16 or 32 cores |
| ad:accel_recommended | YES | Recommended accelerator cores. Available if accelerator type is defined AppDB constraints the value to 1,2,4,8,16 or 32 cores |
| ad:traffic_in | YES | List of inbound network traffic rules that the VM needs to function, as defined by the user, |
| ad:traffic_out | YES | List of outbound network traffic rules that the VM needs to function, as defined by the user, |
| ad:context_format | YES | The contextualization format. Reserved for future use and may be ignored. Only supported option is “cloud-init” |
| ad:default_access | YES | The default method to access the VM. Reserved for future use and may be ignored. Defaults to “None” |
| ad:user:fullname | NO | Full name of image version publisher as taken from the AppDB user profile |
| ad:user:guid | NO | Unique identifier of image version publisher as taken from the AppDB user profile |
| ad:user:uri | NO | Link to image version publisher’s AppDB user profile |
Network traffic schema
Below are the fields of objects of ad:traffic_in and ad:traffic_out lists in the image items.
| Field Name | Description |
|---|---|
| ad:net_protocol | The type of network protocol. Possible values are “TCP”, “UDP”, or “ICMP” |
| ad:net_port | The port number the rule applies to, or a range of ports seperated by “:" e.g. “80”, “8000:8088” |
| ad:net_range | Reserved for future use for IP Ranges. Always defaults to “0.0.0.0/0” and may be ignored |