Changes between Version 42 and Version 43 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
03/15/12 12:12:42 (7 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v42 v43  
    4040 - [#ChangeSetF1:DefineSliverStates Change Set F1]: Define sliver states, and the state changes that various methods cause
    4141 - [#ChangeSetF2:ActOnSlivers Change Set F2]: Add a new general !ActOnSlivers method allowing AMs to support AM and resource-type specific operations
    42  - [#ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support
     42 - ADOPTED: [#ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support
    4343 - Change Set H: Clarify: A second call to !CreateSlivers without an intervening !DeleteSlivers is an error.
    44  - Change Set I1: !SliversStatus return structure includes sliver expiration
    45  - Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
    46  - Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
     44 - ADOPTED: Change Set I1: !SliversStatus return structure includes sliver expiration
     45 - ADOPTED with changes: Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
     46 - ADOPTED: Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
    4747 - Change Set I4: !CreateSlivers optionally does not start resources.
    4848 - [#ChangeSetJ:Proxyaggregatemanagersaresupported Change Set J]: Support proxy aggregates with 1 new option and 1 new !GetVersion entry
    49  - [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
     49 - Partially Adopted: [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
    5050  - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
    5151  - Define slice ID as the UUID in slice certificates
    52   - Define slice name, sliver name, and user name restrictions, and similar for URNs
     52  - ADOPTED: Define slice name, sliver name, and user name restrictions, and similar for URNs
    5353  - Publish schemas for credentials and certificates
    5454 - [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges
     
    420420Define the control API (the AM API) as about moving slivers through various states at an AM.
    421421
     422The proposal here elicited concerns (the method !ActOnSlivers is an ioctl, and the states mix allocation and operational states).
     423
     424For a newer alternative proposal, see http://lists.geni.net/pipermail/dev/2012-March/000727.html
     425
    422426== Motivation ==
    423427AM API methods logically change the state of the slivers at this AM. But the API is not clear what experimenters should expect, and does not provide easy ways for experimenters to control when and how states change. There is in particular no way to move slivers through states and change them in ways otherwise undefined by the API.
     
    522526
    523527= Change Set G: Credentials are general authorization tokens. =
     528
     529'''This change was adopted at GEC13.'''
     530
    524531== Motivation ==
    525532Most AM API methods take a list of credentials to authorize operations. Currently the API requires credentials in a particular format, and would disallow others, such as ABAC.
     
    536543 - AMs may get other authorization material from other sources: EG a future Credential Store service.
    537544
     545== Advertising supported credentials ===
     546Aggregates must advertise the types of credentials honored by the aggregate.
     547
     548Aggregates that support credentials other than the SFA style slice/user credentials shall include a new entry in !GetVersion:
     549{{{geni_credential_types}}}
     550This entry is a list of structs:
     551{{{
     552{
     553   type = <'sfa', 'abac', others>,
     554}
     555}}}
     556Where the type field is case insensitive.
     557Other entries may be in the struct.
     558If the aggregate does not include this entry, then 'sfa' is assumed.
     559
    538560= Changes to existing methods =
    539561Modify a few existing methods to make certain operations easier or more experimenter friendly.
     
    546568
    547569 - '''Change Set I1''': Add {{{geni_expires}}} to return from !SliversStatus for whole slice and then each sliver
     570  - '''This change was adopted at GEC13'''
    548571  - This change standardizes behavior necessary for experimenters to determine their sliver expiration times.
    549572  - Format is RFC3339 (http://www.ietf.org/rfc/rfc3339.txt)
     
    553576 - '''Change Set I2''': Add SSH logins/keys to each node that supports SSH login in the return from !SliversStatus
    554577This change standardizes behavior so experimenters can readily find how to log in to reserved resources. Aggregates that allocate resources that an experimenter can 'log in to', should use this struct to return that information. Other aggregates will not use this at all.
     578
     579'''This change was adopted at GEC13 in principle, but with a different mechanism.'''
     580
     581Aggregates shall use a new RSpec extension to include all login information in manifest RSpecs. This extension is version controlled in the GENI RSpec git repository.
     582
     583The extension adds information to the <services> tag, which already has the <login> tag.
     584
     585The <login> tag tells you the kid of authentication (ssh), the port, and the username.
     586The new extension adds an entry per login username
     587 - URN of the user
     588 - 1+ public SSH keys that can be used under that login
     589
     590Note that 1 of the <user:services_user login>s in the extension duplicates the default username already in the base <login> tag. The extension allows specifying the keys usable with that login username.
     591
     592EG:
     593{{{
     594.......
     595  <services>
     596    <login authentication="ssh-keys" hostname="pc27.emulab.net" port="22" username="flooby"/>
     597    <user:services_user login="flooby" urn="http://urn:publicid:IDN+jonlab.tbres.emulab.net+user+flooby">
     598      <user:key>asdfasdfasdf;lkasdf=foo@bar</user:key>
     599      <user:key>asdfasdfasdf;lkjasdf;lasdf=foobar@barfoo</user:key>
     600    </user:services_user>
     601    <user:services_user login="io" urn="http://urn:publicid:IDN+jonlab.tbres.emulab.net+user+io">
     602      <user:key>asdfasdfasdf;lkasdf=foo@bar</user:key>
     603      <user:key>asdfasdfasdf;lkjasdf;lasdf=foobar@barfoo</user:key>
     604    </user:services_user>
     605  </services>
     606}}}
     607
     608And the RNC schema:
     609{{{
     610# An extension for describing user login credentials in the manifest
     611
     612default namespace = "http://www.protogeni.net/resources/rspec/ext/user/1"
     613
     614# This is meant to extend the services element
     615Services = element services_user {
     616  attribute login { string } &
     617  attribute urn { string }? &
     618  element key { string }*
     619}
     620
     621# Both of the above are start elements.
     622start = Services
     623}}}
     624
     625Old proposal:
    555626{{{
    556627'users' => [{'urn'   => $user1_urn.
     
    572643
    573644 - '''Change Set I3''': Return sliver expiration from !CreateSlivers
     645'''This change was adopted at GEC13.'''
     646
    574647Experimenters currently do not know the expiration of their slivers without explicitly asking.
    575648This change makes the !CreateSlivers return value become a struct:
     
    606679
    607680= Change Set K: Standardize certificates and credentials =
     681'''Parts of this proposal were adopted at GEC13'''
    608682== Motivation ==
    609683The current AM API specifies that certificates and credentials follow a particular format, using URNs that are based on experimenter supplied names. However that specification is not sufficiently specific, and there are currently differences in implementation among existing certificate and credential producers. This has led to errors, experimenter confusion, and messy code.
     
    615689
    616690Some overall points:
    617  - Aggregates are expected to fail requests that use certificates or URNs or names that violate this API.
     691 - '''Adopted''': Aggregates are expected to fail requests that use certificates or URNs or names that violate this API.
    618692 - Aggregates are required to consult and accept Certificate Revocation Lists in accordance with [http://tools.ietf.org/html/rfc3280 RFC 3280] and [http://tools.ietf.org/html/rfc5280 RFC 5280].
    619693 - Schemas for certificates & credentials will be published on geni.net.
    620694
    621 Certificates:
     695'''Adopted''': Certificates:
    622696 - GENI uses x509v3 identity certificates to identity users, slices, aggregates, and authorities, and these restrictions apply to all such certificates.
    623697 - See http://groups.geni.net/geni/wiki/GeniApiCertificates.
     
    625699
    626700Certificate contents:
    627  - {{{Version}}} shall be properly marked: 3
    628  - {{{serialNum}}} is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
     701 - '''Adopted''': {{{Version}}} shall be properly marked: 3
     702 - '''Adopted''': {{{serialNum}}} is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
    629703 - The Distinguished Name should include a human readable identifier, for both subject and issuer. Details are not specified
    630  - Only authority certificates (but all authorities that issue certificates) shall be marked {{{CA:TRUE}}} in the x509 v3 basic constraints; Slices and users shall be marked {{{FALSE}}}.
     704 - '''Adopted''': Only authority certificates (but all authorities that issue certificates) shall be marked {{{CA:TRUE}}} in the x509 v3 basic constraints; Slices and users shall be marked {{{FALSE}}}.
    631705 - The Subject Alternative Name field must include 3 pieces of information
    632   - Entries are comma separated ('{{{, }}}'), and may be in any order.
    633   - The URN identifier, following GENI URN standards as described here: http://groups.geni.net/geni/wiki/GeniApiIdentifiers
     706  - '''Adopted''': Entries are comma separated ('{{{, }}}'), and may be in any order.
     707  - '''Adopted''': The URN identifier, following GENI URN standards as described here: http://groups.geni.net/geni/wiki/GeniApiIdentifiers
    634708   - The URN is identifiable by looking for the entry beginning "{{{URI:urn:publicid:IDN}}}", for example: {{{URI:urn:publicid:IDN+emulab.net+user+stoller}}}.
    635709  - A UUID, providing a globally unique ID for the entity.
     
    644718 - Slice URN is a label - unique at a point in time but not over time.
    645719  - Format: {{{urn:publicid:IDN+<SA name>+slice+<slice name>}}}
    646  - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): {{{'^[a-zA-Z0-9][-a-zA-Z0-9]+$'}}}
    647  - Aggregates are required to accept any compliant slice name and URN.
     720 - '''Adopted''': Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): {{{'^[a-zA-Z0-9][-a-zA-Z0-9]+$'}}}
     721 - '''Adopted''': Aggregates are required to accept any compliant slice name and URN.
    648722  - Note that this currently causes problems at PlanetLab/SFA aggregates, where node login names are based on slice names and are limited to 31 characters.
    649723
    650 Slivers:
     724'''Adopted''': Slivers:
    651725 - Have a URN (returned in manifest RSpec), determined by the aggregate.
    652726 - This URN should be unique over time within an AM for record-keeping / operations purposes.
     
    656730  - May use only alphanumeric characters plus hyphen.
    657731
    658 Usernames:
     732'''Adopted''': Usernames:
    659733 - Usernames (user identifiers to the system) are set at the authority.
    660734 - Usernames are case-insensitive internally, though they may be case-sensitive in display.