Previous topic

Resource Configuration

Next topic

Unprovisioning Resources

Last updated 12-Jul-2017

Provisioning Resources

Resource provisioning uses REST POST request sent to the APS controller, which in turn will interact with the application service responsible for the requested resource type.


Not all services are able to guarantee reasonable timings of processing requests. When an application operates a request with a very short delay (real time processing, usually not longer than several seconds), the APS controller can wait for the completion of the operation and then return its response to the initiator of the operation immediately.

However, sometimes, it may require several hours or so, especially when manual operations are involved. When this happens, the APS controller should not wait for the completion of the request. Instead, it must be aware that the operation is started and that it must complete in a certain period of time. This information must be forwarded to the initiator of the operation immediately. Once the time-out passed, the controller would request the application for the operation status again and repeat it until it is completed or failed.

APS proposes two different ways of synchronizing the resource provisioning: synchronous and asynchronous. The APS controller explicitly specifies it in the APS-Request-Phase header of a REST request.

Synchronous Provisioning

To require a synchronous provisioning, the APS controller must use the POST request with the APS-Request-Phase: sync header. In the following example, a user requests creation of a VPS. The controller forwards the POST request to the application service endpoint (/vpscloud/vpses/). It also specifies that the request must be processed by a sync operation.

The endpoint must call the provision() method that returns the completion code notifying about success or failure. In the example above, the endpoint notifies the APS controller about successful completion of the operation. The APS controller forwards the return code to the initiator of the operation. The resource status will be aps:ready.

Asynchronous Provisioning

Asynchronous provisioning is started the same way as the synchronous operation considered earlier. The application service must decide whether to complete the operation as synchronous or transfer it to asynchronous. The whole transaction actually contains two request phases.

  • The transaction is started with the synchronous phase, as described earlier.
    1. The APS controller requires the synchronous provisioning by sending a POST request with the APS-Request-Phase: sync header.
    2. Once a sync request is received, the endpoint will call the method for synchronous provisioning. If APS PHP runtime is used, it must be the provision() method.
    3. The difference starts here. The method contains a decision code that completes the provisioning either synchronously (as described earlier) or informs the APS controller that the provisioning can be started in the asynchronous mode. Here, we will consider the second case, when the application service requires transferring to the asynchronous phase. Therefore, it returns the 202 Accepted code to the APS controller. In the same response packet, it sends two headers that helps the APS controller to arrange the asynchronous phase. The APS-Info header contains task description, and the APS-Retry-Timeout header defines the period the controller must use for sending subsequent requests.
    4. Once the 202 Accepted code is received, the APS controller completes the synchronous phase by forwarding the response to the initiator of the operation. The resource status will be aps:provisioning.
  • The asynchronous phase is processed as follows.
    1. The APS controller calls the task manager of the hosting platform to schedule a workflow and set its timeout equal to APS-Retry-Timeout. In accordance with this workflow, the task manager must wake up the APS controller to initiate the asynchronous request.
    2. First time, the task manager will activate the scheduled workflow immediately. The APS controller sends its first asynchronous request to the endpoint to confirm its readiness to proceed in the asynchronous mode. This time, inside the endpoint, the method for asynchronous provisioning must be called. APS PHP runtime calls the provisionAsync() class method, when a provisioning operation with APS-Request-Phase: async is required.
    3. If the endpoint returns the expected 202 Accepted code, the APS controller reschedules the workflow task.
    4. Next time, the task manager runs the scheduled task not earlier than the specified APS-Retry-Timeout value. This is repeated until the endpoint returns a code different from 202 Accepted.
    5. Once a code different from 202 Accepted is received, the APS controller calls the task manager to finish the scheduled workflow. If the requested resource was created successfully, its status will be aps:ready.


The following example illustrates how the APS PHP runtime on the application endpoint helps to develop operations for synchronous and asynchronous provisioning. The sample code defines two operations in the custom vps class.

  • The provision() method is called when the request for synchronous provisioning is received. It checks the hardware->VM property to identify the kind of VPS required.

    • If VM is false, a container must be created. Since this does not take long, the synchronous operation is completed successfully. Actually, the provision() function does nothing in this case, and the PHP runtime returns 200 OK to the APS controller.

    • If VM is true, the virtual machine (VM) is required. Since this usually takes long, the method throws the exception that the PHP runtime processes and returns 202 Accepted to the APS controller.

      In the code here, we simulate 5 retries with 30 sec timeout.

public function provision() {
         // VM requires more time, thus the *async* operation is required
     if ($this->hardware->VM) {
         $this->state = "creating"; // VPS state is intermediate
         $this->retry = 5;     // Assuming VM provisioning requires 5 retries
               // Throw exception to return code *202 Accepted* to APS controller
         throw new \Rest\Accepted($this, "Creating VPS", 30);
     };  // Else do nothing to return code *200 OK*

public function provisionAsync() {
     $this->retry -=1; // Decrement the retry counter
     if ($this->retry <= 0) {
         $this->state = "ready"; // Finish the Async operation - return *200 OK* to APSC
     else {                      // Return code *202 Accepted*
         throw new \Rest\Accepted($this, "Creating VPS", 30);
  • When the endpoint receives a request for asynchronous provisioning, it calls the provisionAsync() method.
    • If the provisioning is not completed (simulated by a number of retries), the function throws the same exception as the provision() function does. The 202 Accepted code is returned. The state property is an internal resource property managed by the provisioning code as needed. It can be used by the custom UI script to display the VPS state to users.
    • If the provisioning is completed, the function will not throw an exception, and the PHP runtime returns the 200 OK code to the APS controller.


Asynchronous provisioning is not supported when a resource is created automatically as in the following case:

  • Resource R2 is provisioned automatically to satisfy a requirement of resource R1. In this case, resource R2 cannot be provisioned asynchronously.

The application must not return code 202 Accepted in this case.