HostAllocate

Hosts must be in the Free state to be allocated, although users with Project Admin access can re-allocate hosts which are in the Allocated state to other users in their project. Domain Admin users can re-allocate machines between projects and users, although if a machine is reallocated to a user in another project, that user must also be a member of the destination project. The user must be authorized to allocate the host. If the host is in any of the following states: Immutable, Powercycle, Rebuild, or Rebuilding, this method will fail.

URL

/cubit_api/1/alloc_host

Authentication

This method requires authentication using an API key.

Parameters

alloc_hours ( zero or once ): Amount of time for which to allocate the host. The allocation limit is subject to the limit set by the project or cloud administrator.; Type: Float
alloc_minutes ( zero or once ): Similar to alloc_hours parameter, but in minutes. It is mutually exclusive with the alloc_hours option, neither of these options should be specified, or only one of these options should be specified. If alloc_hours or alloc_minutes is set to 0, or if alloc_hours and alloc_minutes is unset, the allocation time defaults to the longest possible time available in the project.; Type: Integer
alloc_proj ( zero or once ): The project to allocate the machine to. The alloc_user must be a valid Lab Management user in the project, or else this method will fail. Only Domain Admins can change the project that a host is assigned to. If not specified, the project is not changed. At least one of alloc_user or alloc_proj must be specified.; Type: String
alloc_user ( zero or once ): Login name of user to allocate host to. Only Project Admins or better can specify a user other than themselves. Other users can only allocate machines to themselves. If not specified, defaults to userid. At least one of alloc_user or alloc_proj must be specified.; Type: String
force ( zero or once ): If the machine is currently in the Allocated state, the force option must be given to reassign the host to another user. The force option is only available to Project Admins and above. If the host is a virtual host, and any virtual guests of this host are in the Allocated state, this option must also be used, or the entire allocation will fail. The only valid value for this parameter is True.; Type: String
guests ( zero or once ): If the machine is a virtual host and has active virtual guests, setting this parameter to True will move the virtual guests along with the virtual host. Because moving a virtual host will move several hosts at once, we have a separate parameter to confirm this action. The only valid value for this parameter is True. If the host has no virtual guests, this option has no effect.; Type: String
host ( Required, once ): Fully qualified hostname to allocate.; Type: String
sig ( Required, once ): API authentication hash signature.; Type: String
userid ( Required, once ): The login name of the user initiating the request.; Type: String

Example Response

        
    Successful host allocation:
    <?xml version='1.0'?>
    <cubit version='1'>
        <status>OK</status>
    </cubit>

    If the user is unauthorized, or the host does not exist:
    <?xml version='1.0'?>
    <cubit version='1'>
        <error>You are not authorized to allocate this host.</error>
    </cubit>

    If the host is allocated to a deleted project:
    <?xml version='1.0'?>
    <cubit version='1'>
        <error>Cannot allocate host 'cu001.dev.cubitdemo.net' to a
        deleted project 'look'</error>
    </cubit>

Response Codes

200 - ok
400 - Login failed / Insufficient permissions