call-provision.adoc

Provision

Request that the named :allocated slivers be made :provisioned, instantiating or otherwise realizing the resources, such that they have a valid :operational_status and may possibly be made :ready for experimenter use. This operation is synchronous, but may start a longer process, such as creating and imaging a virtual machine.

Redeem a reservation, requesting that the listed slivers move from :allocated to :provisioned. Only when slivers are provisioned are the resources 'instantiated' and made ready for operational use. Note that at some aggregates and for some resource types, this operation may be a no-op. At other aggregates, this operation starts a long running process (e.g. loading an image on a machine and booting it). Tools should monitor the sliver status (by calling [Status]), looking for an operational state other than :pending_allocation. Depending on the resource type, that next state may differ. See the advertisement RSpec for the resource type specific operational states and actions.

As with the [Allocate] method, some aggregates may not support provisioning only some reserved resources. See the Operations On Individual Slivers section for more information.

Call Syntax

Provision(string urns[], struct credentials[],
          struct rspec_version, struct options)

Note	Note that resources are not necessarily ready for experimenter use after the work that this function initiates finally completes. Consult the :operational_status, and the advertised operational state machine. Consider calling [PerformOperationalAction], e.g. with the command name :start.

As described in the Operations On Individual Slivers section, the :single_allocation return from [GetVersion] advertises whether or not a client may invoke this method on only some of the slivers in a given :allocation_state in a given slice (default is false - the client may operate on only some of the slivers in a given state).

When only a slice URN is supplied (no specific sliver URNs), this method applies only to the slivers currently in the :allocated allocation state.

Argument 1: urns

See the urns argument for details.

Argument 2: credentials

The standard authorization argument. See the Credentials section.

Argument 3: rspec_version

See the rspec_version argument for details.

Argument 4: options

A struct containing optional arguments, indexed by name. See General Options Argument Section.

Option: :end_time

See the :end_time option for details.

As with the [Allocate] method, experimenters may request a sliver expiration time; aggregates may allow the operation while ignoring the requested expiration time or granting a different expiration time.

Option: :best_effort

Do all slivers fail if any single sliver fails?

See :best_effort option for details.

Option: :users

Supported by the server	Mandatory
Included by client	Optional
XML-RPC type	array of struct

Resource login information.

Some resource types allow experimenter access. The :users option allows specifying login key material to be installed on the resources (e.g. SSH public keys).

Clients may omit this option. Aggregates should honor this option for any resource that accepts the provided login keys, and ignore it for other resources. This option is an array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. For example, this option is the mechanism by which users supply their SSH public keys, permitting SSH login to allocated nodes. In such cases, the corresponding manifest RSpec will contain the ssh-users element on each such node, showing the login username and applicable public keys. Aggregates accepting this option for a resource are expected to install all supplied SSH keys - creating separate login accounts for each supplied user if possible. When this option is supplied, each struct must include the key keys, which is an array of strings and can be empty. The struct must also include the key urn, which is the user’s URN string. For example:

Example

[
  {
    urn: urn:publicid:IDN+geni.net:gcf+user+alice
    keys: [<string: ssh key>, <string: ssh key>]
  },
  {
    urn: urn:publicid:IDN+geni.net:gcf+user+bob
    keys: [<string: ssh key>]
  }
]

Return Value

XML-RPC type

  ":rspec": <string.rspec: RSpec manifest>,
  ":slivers":
  [
    {
     ":sliver_urn": <string>,
     ":allocation_status": <string>,
     ":operational_status": <string>,
     ":expires": <string.dateTime.rfc3339: when the sliver expires from its current state>,
     (optional) ":error": <string: explaining any failure to Provision this sliver. The field may be omitted entirely but may not be null/None>
    },
    ...
  ],

On success, the value field of the return struct will contain a struct containing the RSpec manifest (using the string.rspec data type) and a list of sliver info.

See the sliver info list return for details on the sliver info list.

Expired, deleted and unknown slivers, or slices without valid slivers, will cause this call to return SEARCHFAILED. See the urns argument for more details on this error code and return value.

Note that previously allocated slivers may have expired (been deleted) by the time you call Provision.

Return Codes and Errors

The Provision call can return the usual error codes: BADARGS, ERROR, SERVERERROR and UNAVAILABLE. See Error Codes for general errors.

Additionally, the Provision call can return the following error codes:

FORBIDDEN	Credential does not grant permission to a slice or sliver specified in the urns argument. Or the slice/sliver does not have permission to allocate resources at this slice. Or the slice has been shut down.
BADVERSION	Bad Version of manifest RSpec requested with the rspec_version argument.
UNSUPPORTED	The aggregate does not permit operations on individual slivers in the same slice of this form. See the Operations On Individual Slivers section for more information.
EXPIRED	The slivers has expired.
SEARCHFAILED	The slice or sliver does not exist at this AM.
BUSY	Slice or sliver is temporarily locked, try again later