Changes between Version 104 and Version 105 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
02/04/14 09:33:35 (10 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_DRAFT

    v104 v105  
    612612This proposal is based on the functionality exported by ProtoGENI based aggregates. '''FIXME''': This proposal must be made more generic.
    613613
     614Some general notes:
     615 - Disk images are created with snapshots of the disk of an existing compute resource
     616 - Images exist local to an aggregate: They are created, listed and deleted at a particular aggregate
     617 - Images are identified by a URN. At some aggregates, they are also identifiable by a URL (for purposes of exporting an image to another aggregate)
     618 - Exporting an image to another aggregate involves copying the image from one aggregate to another.
     619  - Not all aggregates will support exporting images
     620  - An image imported from another aggregate may not function at the new aggregate (due to hardware differences, etc)
     621  - Once imported, the disk image now exists local to the new aggregate as well
     622
    614623'''FIXME'''
    615  - Do images _have_ to be kept local to where they started? Or is it possible you can do list/delete at other aggregates? Do images get copied such that now you can list/delete them elsewhere?
    616  - Must images that you snapshot be available at other aggregates, or is that separable / optional?
    617 
    618 These images are created by taking a "snapshot" of the disk of an existing compute resource. Images "belong to" the aggregate at which the original compute resource existed, and will only be listed or deletable there.
     624 - Add a separate `SERVICE` indicating if images are exportable to other aggregates (`EXPORT_IMAGES`?)
     625 - Define rules for legal disk image names
     626 - Define URL rules for exporting images
     627 - Define return struct for `listimages`
     628 - Define authorization rules for deleting and listing images
     629 - Are exportable images always public? Or does public only control what is listable?
    619630
    620631=== `CreateImage` ===
    … …  
    627638 - credentials giving the caller rights on this slice
    628639 - options
    629   - The option `global` defines whether this image will be publicly visible or not. The value is an XML-RPC boolean indicating whether the image should be public, defaulting to False meaning private.
     640  - The option `global` defines whether this image will be publicly visible or not. The value is an XML-RPC boolean indicating whether the image should be public, defaulting to False meaning private to your project or sub-SA. "Private" images are visible and usable by any experimenter in the same project (or sub slice authority) at this aggregate. "Public" images are usable by anyone with the URL or URN of the image.
    630641
    631642Returns:
    … …  
    633644 - URL for referencing the image, for use at other aggregates, for example: `https://www.foo.net/image_metadata.php?uuid=c0b47d37-f6cd-11e1-9f72-001143e453fe`
    634645
    635 If an image of the same name already exists, then this image replaces the previous image of the same name. '''FIXME''' This should only be true for private images - public images should not be replaceable and you should get an error.
     646Image names must be unique at this aggregate. If an image of the same name already exists and is "owned" (was created or imported by this user), then this image replaces the previous image of the same name. For other experimenters, this method shall return an error code `BADARGS` indicating that the image name is taken.
     647
     648If local policy determines that this experimenter or project or slice has exceeded some quota on number of images or disk space, then this command may fail with an error message explaining the issue (code `2` or `7`).
    636649
    637650This function should return quickly, asynchronously snapshotting the disk. While the disk is being snapshotted, do not modify the state of your VM - results will be unpredictable.
    638651
    639 Only slivers in the `geni_ready` state may be imaged. While the image is being created, the sliver will be in a new operational state, `geni_imaging`. While the sliver is in this state, no operational actions are permitted. When imaging is complete, the operational state transitions back to `geni_ready`.
     652Only slivers in the `geni_ready` state may be imaged. While the image is being created, the sliver will be in a new operational state, `geni_imaging`. While the sliver is in this state, no operational actions are permitted. When imaging is complete (successfully or due to error), the operational state transitions back to `geni_ready`.
    640653
    641654The aggregate will email the user who created the snapshot at the email address found in the user's certificate, providing status and results.
    … …  
    646659Arguments:
    647660 - image URN
    648  - credentials
     661 - credentials, including a valid slice credential for a slice in the same project / sub-slice authority as the slice from which the image was created (or imported)
    649662 - options
    650663  - `creator_urn`: image creator URN (a valid "user" URN). If not supplied, the current user is assumed
    651664
    652 Return: XML-RPC boolean for success. On error, return codes include `SEARCHFAILED`.
    653 
    654 '''FIXME: Can you really delete another user's image? Public and Private?'''
     665Return: XML-RPC boolean for success. On error, return codes include `SEARCHFAILED`, `FORBIDDEN` and `ERROR`.
     666
     667Only users in the same project / sub-Slice Authority may delete an image (as authorized by the supplied slice credential).
     668
     669Note that the experimenter who created the image locally or imported it from another aggregate is the image 'creator' for purposes of this method.
    655670
    656671=== `ListImages` ===
    657672List the disk images created by the given user at the aggregate you are calling.
     673
    658674Arguments:
    659675 - creator URN
    660  - credentials
     676 - credentials, including optionally a valid slice credential for the project / sub-slice authority whose images you want to list
    661677 - options
    662678
    663679The creator URN must be from the same authority as the caller (i.e. the portion of the user URN before `user` must be identical).
    664680
    665 Return: a list of structs, each containing the url and urn of the images at this aggregate.
    666 ''' FIXME: Details'''
     681Note that the experimenter who created the image locally or imported it from another aggregate is the image 'creator' for purposes of this method.
     682
     683Return: a list of structs, each containing the url and urn of the images at this aggregate. Note that only public images will be provided in general, plus images in the same project / sub-slice authority as the slice whose valid slice credential was supplied will be listed.
     684
     685Only users in the same project / sub-Slice Authority may list private images (as authorized by the supplied slice credential).
     686
     687'''FIXME: Details of return struct'''
     688'''FIXME: Are those the right authorization rules?'''
    667689
    668690=== Image URN type ===
    … …  
    670692
    671693''FIXME: Restrictions on the characters legal in the name of an image or image name length?'''
     694 - Image names should begin with a letter and be alphanumeric or underscore, hyphen, at sign or period: ('[a-zA-Z][a-ZA-Z0-9\-_@\.]{0,63}$').
     695 - Image names are limited to 64 characters.
     696 - The authority in an image URN is the aggregate hosting the image
    672697
    673698=== Import Disk Images ===
    674 Should there be a common API for asking an aggregate to import a disk image from some other location?
    675 
    676 '''Questions''':
    677  - What about exporting a disk image?
    678  - Are there any more fine grained privacy controls beyond public and private? For example, shared within the current slice?
    679  - Do disk images expire? Is there any quota on the disk space used or # of images a slice or experimenter can have?
    680  - How do aggregates reclaim disk space from disk images?
     699A disk image that was created / is stored at one aggregate may be used at another aggregate, if the source aggregate supports it, and if the new aggregate accepts a URL for disk images in the request RSpec.
     700If both are true, then an experimenter may specify  this remote disk image by URL in the `name` slot of the `disk_image` element in a request RSpec.
     701The aggregate exporting the image serves up the image at the URL. The aggregate importing the image:
     702 - May fail the import if imports are not supported, or local policy prohibits, or local disk space or quotes are exceeded
     703 - Stores the image locally
     704 - Gives it a local name / URN, locally unique
     705 - Lists the experimenter who imported the image as the image 'creator'
     706 - Associates the image with the project/sub slice authority of the slice for which the image was imported
     707 - '''FIXME''': Makes the image public? Private? Does the experimenter get to say or change it?
     708 - Emails the 'creator' with the new URN and URL for the local copy of the image
     709
     710When an image is imported to another aggregate, the experimenter that imports the image is treated as the local image "creator", and the slice in which they import the image determines the local project / sub-slice authority for controlling local access to the image.
     711
     712This proposal does not specify how aggregates manage local disk space or might limit the number of disk images a particular experimenter or project can have. Importing a disk image therefore might fail due to local AM policy. Additionally, disk images might 'expire' at certain aggregates. This proposal does not specify this one way or another.
    681713
    682714== Declined: No Reservation Allocate ==