call-allocate.adoc

Allocate

Allocate resources as described in a request RSpec argument to a slice with the named URN. On success, one or more slivers are allocated, containing resources satisfying the request, and assigned to the given slice. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec. Allocated slivers are held for an aggregate-determined period. Clients must [Renew] or [Provision] slivers before the expiration time (given in the return struct), or the aggregate will automatically [Delete] them. Aggregates should implement Allocate() as quick, cheap, and not impacting provisioned resources, such that it can be readily undone. Allocate is an all or nothing request: if the aggregate cannot completely satisfy the request RSpec, it should fail the request entirely.

At some aggregates, experimenter tools may call Allocate multiple times, to add resources to the existing reservation for the same slice. Other aggregates may limit such requests or forbid them entirely. See the Operations On Individual Slivers section.

Call Syntax

Allocate(string slice_urn,
         struct credentials[],
         string.rspec rspec,
         struct options)

As described in the Operations On Individual Slivers section, the :allocate return from [GetVersion] advertises when a client may legally call Allocate (only once at a time per slice, whenever desired, or multiple times only if the requested resources do not interact).

Argument 1: slice_urn

Supported by the server	Mandatory
Included by client	Mandatory
XML-RPC type	string
String content type	URN

The URN of the slice to which the resources specified in rspec will be allocated. For details on URN identifiers, see this document.

Argument 2: rspec

Supported by the server	Mandatory
Included by client	Mandatory
XML-RPC type	string
String content type	string.rspec

An RSpec containing the resources that the caller is requesting for allocation to the slice specified in slice_urn. These are expected to be consistent with the resources returned by a previous invocation of [ListResources]. If this RSpec is in a format not listed as supported by [GetVersion], then the aggregate will return an error of BADVERSION (4).

For more details on RSpecs and RSpec versions, see the type string.rspec and the Rspec Document.

Argument 3: credentials

The standard authorization argument. See the Credentials section.

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.

Return Value

XML-RPC type

struct

See the sliver info list return for details.

On success, the value field of the return struct will contain a struct:

XML-RPC type

    {
     ":rspec" : <string.rspec: manifest of newly allocated slivers>,
     ":slivers" : [
            {
                      :sliver_urn: <string: sliver urn>
                      :expires: <string.dateTime.rfc3339: allocation expiration string, as in :expires from Status>,
                      :allocation_status: <string: sliver state - e.g. :allocated>
            },
            ...
        ]
    }

The manifest is a manifest RSpec of only newly allocated slivers, using the schema matching the input request schema.

Return Codes and Errors

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

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

FORBIDDEN	Credential does not grant permission to a slice specified in the slice URN argument. Or the slice does not have permission to allocate resources at this slice. Or the slice has been shut down.
BADVERSION	Bad Version of RSpec provided in the rspec argument.
TOOBIG	Request is too big to be satisfied.
UNSUPPORTED	The aggregate does not permit multiple allocations to the same slice of this form. See the Operations On Individual Slivers section for more information.