Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some small improvements #44

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Some small improvements #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions call-basics.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -402,15 +402,13 @@ Some AM cannot know if a resource is ready or has stopped, or even in which stat
[[SliverOperationalActions]]
=== Sliver Operational Actions

NOTE: *TODO this section was copied from the AMv3 spec with only minor changes (mostly markup). This sections content might still be moved to better places.*

Operational actions are commands that the aggregate exposes, allowing an experimenter tool to modify or act on a sliver from outside of the sliver (i.e. without logging in to a machine), without modifying the sliver reservation. Actions may cause changes to sliver operational state.

The API defines a few operational actions: these need not be supported. AMs are encouraged to support these if possible, but only if they can be supported following the defined semantics.

AMs may have their own operational states/state-machine internally. AMs are however required to advertise such states and actions that experimenters may see or use, by using an advertisement RSpec extension (if an AM does not advertise operational states, then tools can not know whether any actions are available). Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the sliver_type element of RSpecs.

The standard advertisement RSpec extension for advertising operational states and actions can be found here, with an example with comments here.
The standard advertisement RSpec extension for advertising operational states and actions can be found link:rspec.html#RSpecExtensions[here].

Tools must use the operational states and actions advertisement to determine what operational actions to offer to experimenters, and what actions to perform for the experimenter. Tools may choose to offer actions which the tool itself does not understand, relying on the experimenter to understand the meaning of the new action.

Expand Down Expand Up @@ -831,7 +829,7 @@ XML-RPC type::
":allocation_status": <string>,
":operational_status": <string>,
":expires": <string.dateTime.rfc3339: sliver expiration time>,
(optional) ":error": <string: explaining any failure to Provision>
(optional) ":error": <string: explaining any failure of a Provision or PerformOperationalAction on the slice>
(optional) ":resource_status" : <string: resource-specific status>,
},
...
Expand All @@ -843,8 +841,10 @@ The +:operational_status+ in the sliver info list is required, unless these 2 co
* +:operational_status+ is +:pending_allocation+
* +:allocation_status+ is not +:provisioned+.

+:error+ may be omitted entirely but may not be null/None.
+:resource_status+ can be used to describe the resource specific status in more detail than +:operational_status+.
+:error+ is a free form string and may be omitted entirely or be an empty +string+, but it may not be null/None.
The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if an operation failed for a given sliver.

+:resource_status+ is optional and can be used to describe the resource specific status in more detail than +:operational_status+.

<<PerformOperationalAction>>, <<Renew>> and <<Delete>> directly return the basic sliver info list +array+ described above.
<<Allocate>>, <<Provision>>, <<Describe>> and <<Status>> return a +struct+, which contains a sliver info list +array+ and additional info.
Expand Down Expand Up @@ -932,5 +932,4 @@ Additional rules:

NOTE: *TODO this section was copied from the AMv3 spec with only minor changes (mostly markup). This sections content might still be moved to better places.*

A free form string (not null or None), optionally returned per sliver from several method returns (<<Describe>>, <<Provision>>, <<Renew>>, <<Status>>, <<PerformOperationalAction>>, <<Delete>>). The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver. This option is used in particular where an aggregate may successfully perform the operation for some slivers, but not others. See the +:best_effort+ option above. In particular, it is not returned from <<Allocate>>, which is always all-or-nothing. Note that this field may be omitted entirely from the return in most cases, but is required in the return from <<Status>>, though it may be empty. The field if present must be a valid string, not null/None.

1 change: 1 addition & 0 deletions call-performoperationalaction.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,5 +95,6 @@ EXPIRED:: The sliver has expired.
SEARCHFAILED:: The slice or sliver does not exist at this AM.
BUSY:: Slice or sliver is temporarily locked, try again later
INPROGRESS:: Requested operation is already in progress
REFUSED:: When requesting an +:update_users+ action while the sliver is in the wrong operational state.


3 changes: 2 additions & 1 deletion rspec.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -594,6 +594,7 @@ It is therefore possible to validate just the portion of an RSpec document which
It is required that actors that do not support an extension can interact with actors that do support an extension.
Thus the information added in an extension must be ignorable.
This means:

* When an extension is used in a request, aggregate managers that do not support it, must copy it unmodified into the manifest whenever possible.
* When an extensions is used in an advertisement or manifest, clients that do not support it must ignore it. They should not fail because an unknown extension is present.

Expand All @@ -614,7 +615,7 @@ Because of this, clients should ignore any extension they do not know.
TODO
Do we need this additional info from http://www.protogeni.net/ProtoGeni/wiki/RSpecExtensions2 :

Anyone can define an extension by specifying a namespace for that extension and hosting a schema document. The schema document they host is independent of the core rspec schema and any other extension schema.
Anyone can define an extension by specifying a namespace for that extension and hosting a schema document. The schema document they host is independent of the core RSpec schema and any other extension schema.

We use XML Document Schema Instance directives to specify which namespaces must be validated against which schemas. This allows the use of nearly every XML validator and parser currently available. The only disadvantage is that it is not possible to associate a particular symbol in the extension schema with a particular context in the RSpec schema and enforce validation. This means that it is possible for an incorrect document to allow an extension to pass validation even if it uses an element meant to extend nodes in a link context or vice versa. To make errors of this kind more evident, all extensions should prefix their start symbols with 'foo_' where foo is the context name.
////////////////////////////////
Expand Down