Changes between Version 104 and Version 105 of GAPI_AM_API_DRAFT
- Timestamp:
- 02/04/14 09:33:35 (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_DRAFT
v104 v105 612 612 This proposal is based on the functionality exported by ProtoGENI based aggregates. '''FIXME''': This proposal must be made more generic. 613 613 614 Some 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 614 623 '''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? 619 630 620 631 === `CreateImage` === … … 627 638 - credentials giving the caller rights on this slice 628 639 - 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. 630 641 631 642 Returns: … … 633 644 - 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` 634 645 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. 646 Image 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 648 If 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`). 636 649 637 650 This 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. 638 651 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`.652 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 (successfully or due to error), the operational state transitions back to `geni_ready`. 640 653 641 654 The aggregate will email the user who created the snapshot at the email address found in the user's certificate, providing status and results. … … 646 659 Arguments: 647 660 - 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) 649 662 - options 650 663 - `creator_urn`: image creator URN (a valid "user" URN). If not supplied, the current user is assumed 651 664 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?''' 665 Return: XML-RPC boolean for success. On error, return codes include `SEARCHFAILED`, `FORBIDDEN` and `ERROR`. 666 667 Only users in the same project / sub-Slice Authority may delete an image (as authorized by the supplied slice credential). 668 669 Note that the experimenter who created the image locally or imported it from another aggregate is the image 'creator' for purposes of this method. 655 670 656 671 === `ListImages` === 657 672 List the disk images created by the given user at the aggregate you are calling. 673 658 674 Arguments: 659 675 - creator URN 660 - credentials 676 - credentials, including optionally a valid slice credential for the project / sub-slice authority whose images you want to list 661 677 - options 662 678 663 679 The creator URN must be from the same authority as the caller (i.e. the portion of the user URN before `user` must be identical). 664 680 665 Return: a list of structs, each containing the url and urn of the images at this aggregate. 666 ''' FIXME: Details''' 681 Note that the experimenter who created the image locally or imported it from another aggregate is the image 'creator' for purposes of this method. 682 683 Return: 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 685 Only 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?''' 667 689 668 690 === Image URN type === … … 670 692 671 693 ''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 672 697 673 698 === 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? 699 A 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. 700 If 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. 701 The 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 710 When 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 712 This 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. 681 713 682 714 == Declined: No Reservation Allocate ==