Changes between Version 42 and Version 43 of GAPI_AM_API_DRAFT

Timestamp:

03/15/12 12:12:42 (12 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -40 +40 @@
  - [#ChangeSetF1:DefineSliverStates Change Set F1]: Define sliver states, and the state changes that various methods cause
  - [#ChangeSetF2:ActOnSlivers Change Set F2]: Add a new general !ActOnSlivers method allowing AMs to support AM and resource-type specific operations
- - [#ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support
+ - ADOPTED: [#ChangeSetG:Credentialsaregeneralauthorizationtokens. Change Set G]: Generalize the credentials argument, allowing ABAC support
  - Change Set H: Clarify: A second call to !CreateSlivers without an intervening !DeleteSlivers is an error.
- - Change Set I1: !SliversStatus return structure includes sliver expiration
- - Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
- - Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
+ - ADOPTED: Change Set I1: !SliversStatus return structure includes sliver expiration
+ - ADOPTED with changes: Change Set I2: !SliversStatus return includes SSH logins/key for nodes that support SSH access
+ - ADOPTED: Change Set I3: !CreateSlivers return becomes a struct, adds sliver expiration
  - Change Set I4: !CreateSlivers optionally does not start resources.
  - [#ChangeSetJ:Proxyaggregatemanagersaresupported Change Set J]: Support proxy aggregates with 1 new option and 1 new !GetVersion entry
- - [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
+ - Partially Adopted: [#ChangeSetK:Standardizecertificatesandcredentials Change Set K]: Standardize certificate contents, etc
   - Include a real serial number, holder email, holder uuid, and optionally authority URL in certificates
   - Define slice ID as the UUID in slice certificates
-  - Define slice name, sliver name, and user name restrictions, and similar for URNs
+  - ADOPTED: Define slice name, sliver name, and user name restrictions, and similar for URNs
   - Publish schemas for credentials and certificates
  - [#ChangeSetL:ChangeSFAcredentialsprivileges Change Set L]: Standardize slice credential privileges
@@ -420 +420 @@
 Define the control API (the AM API) as about moving slivers through various states at an AM.
 
+The proposal here elicited concerns (the method !ActOnSlivers is an ioctl, and the states mix allocation and operational states).
+
+For a newer alternative proposal, see http://lists.geni.net/pipermail/dev/2012-March/000727.html
+
 == Motivation ==
 AM 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.
@@ -522 +526 @@
 
 = Change Set G: Credentials are general authorization tokens. =
+
+'''This change was adopted at GEC13.'''
+
 == Motivation ==
 Most 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. 
@@ -536 +543 @@
  - AMs may get other authorization material from other sources: EG a future Credential Store service.
 
+== Advertising supported credentials ===
+Aggregates must advertise the types of credentials honored by the aggregate.
+
+Aggregates that support credentials other than the SFA style slice/user credentials shall include a new entry in !GetVersion:
+{{{geni_credential_types}}}
+This entry is a list of structs:
+{{{
+{
+   type = <'sfa', 'abac', others>,
+}
+}}}
+Where the type field is case insensitive.
+Other entries may be in the struct.
+If the aggregate does not include this entry, then 'sfa' is assumed. 
+
 = Changes to existing methods =
 Modify a few existing methods to make certain operations easier or more experimenter friendly.
@@ -546 +568 @@
 
  - '''Change Set I1''': Add {{{geni_expires}}} to return from !SliversStatus for whole slice and then each sliver
+  - '''This change was adopted at GEC13'''
   - This change standardizes behavior necessary for experimenters to determine their sliver expiration times.
   - Format is RFC3339 (http://www.ietf.org/rfc/rfc3339.txt)
@@ -553 +576 @@
  - '''Change Set I2''': Add SSH logins/keys to each node that supports SSH login in the return from !SliversStatus 
 This 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.
+
+'''This change was adopted at GEC13 in principle, but with a different mechanism.'''
+
+Aggregates 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.
+
+The extension adds information to the <services> tag, which already has the <login> tag.
+
+The <login> tag tells you the kid of authentication (ssh), the port, and the username.
+The new extension adds an entry per login username
+ - URN of the user
+ - 1+ public SSH keys that can be used under that login
+
+Note 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.
+
+EG:
+{{{
+.......
+  <services>
+    <login authentication="ssh-keys" hostname="pc27.emulab.net" port="22" username="flooby"/>
+    <user:services_user login="flooby" urn="http://urn:publicid:IDN+jonlab.tbres.emulab.net+user+flooby">
+      <user:key>asdfasdfasdf;lkasdf=foo@bar</user:key>
+      <user:key>asdfasdfasdf;lkjasdf;lasdf=foobar@barfoo</user:key>
+    </user:services_user>
+    <user:services_user login="io" urn="http://urn:publicid:IDN+jonlab.tbres.emulab.net+user+io">
+      <user:key>asdfasdfasdf;lkasdf=foo@bar</user:key>
+      <user:key>asdfasdfasdf;lkjasdf;lasdf=foobar@barfoo</user:key>
+    </user:services_user>
+  </services>
+}}}
+
+And the RNC schema:
+{{{
+# An extension for describing user login credentials in the manifest
+
+default namespace = "http://www.protogeni.net/resources/rspec/ext/user/1"
+
+# This is meant to extend the services element
+Services = element services_user {
+  attribute login { string } &
+  attribute urn { string }? &
+  element key { string }*
+}
+
+# Both of the above are start elements.
+start = Services
+}}}
+
+Old proposal:
 {{{
 'users' => [{'urn'   => $user1_urn.
@@ -572 +643 @@
 
  - '''Change Set I3''': Return sliver expiration from !CreateSlivers
+'''This change was adopted at GEC13.'''
+
 Experimenters currently do not know the expiration of their slivers without explicitly asking.
 This change makes the !CreateSlivers return value become a struct:
@@ -606 +679 @@
 
 = Change Set K: Standardize certificates and credentials =
+'''Parts of this proposal were adopted at GEC13'''
 == Motivation ==
 The 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.
@@ -615 +689 @@
 
 Some overall points:
- - Aggregates are expected to fail requests that use certificates or URNs or names that violate this API.
+ - '''Adopted''': Aggregates are expected to fail requests that use certificates or URNs or names that violate this API.
  - 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].
  - Schemas for certificates & credentials will be published on geni.net.
 
-Certificates:
+'''Adopted''': Certificates:
  - GENI uses x509v3 identity certificates to identity users, slices, aggregates, and authorities, and these restrictions apply to all such certificates.
  - See http://groups.geni.net/geni/wiki/GeniApiCertificates.
@@ -625 +699 @@
 
 Certificate contents:
- - {{{Version}}} shall be properly marked: 3
- - {{{serialNum}}} is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
+ - '''Adopted''': {{{Version}}} shall be properly marked: 3
+ - '''Adopted''': {{{serialNum}}} is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
  - The Distinguished Name should include a human readable identifier, for both subject and issuer. Details are not specified
- - 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}}}.
+ - '''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}}}.
  - The Subject Alternative Name field must include 3 pieces of information
-  - Entries are comma separated ('{{{, }}}'), and may be in any order.
-  - The URN identifier, following GENI URN standards as described here: http://groups.geni.net/geni/wiki/GeniApiIdentifiers
+  - '''Adopted''': Entries are comma separated ('{{{, }}}'), and may be in any order.
+  - '''Adopted''': The URN identifier, following GENI URN standards as described here: http://groups.geni.net/geni/wiki/GeniApiIdentifiers
    - The URN is identifiable by looking for the entry beginning "{{{URI:urn:publicid:IDN}}}", for example: {{{URI:urn:publicid:IDN+emulab.net+user+stoller}}}.
   - A UUID, providing a globally unique ID for the entity.
@@ -644 +718 @@
  - Slice URN is a label - unique at a point in time but not over time.
   - Format: {{{urn:publicid:IDN+<SA name>+slice+<slice name>}}}
- - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): {{{'^[a-zA-Z0-9][-a-zA-Z0-9]+$'}}}
- - Aggregates are required to accept any compliant slice name and URN. 
+ - '''Adopted''': Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): {{{'^[a-zA-Z0-9][-a-zA-Z0-9]+$'}}}
+ - '''Adopted''': Aggregates are required to accept any compliant slice name and URN. 
   - 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.
 
-Slivers:
+'''Adopted''': Slivers:
  - Have a URN (returned in manifest RSpec), determined by the aggregate.
  - This URN should be unique over time within an AM for record-keeping / operations purposes.
@@ -656 +730 @@
   - May use only alphanumeric characters plus hyphen.
 
-Usernames:
+'''Adopted''': Usernames:
  - Usernames (user identifiers to the system) are set at the authority.
  - Usernames are case-insensitive internally, though they may be case-sensitive in display.