User Guide

REST API Endpoints

The API documentation can be found at SwaggerHub.

CLI Client Tool

The client tool http_cli.rb is an http client that can be used to easily interact with the provision engine using the CLI. It is meant to be a convenient alternative to using curl when testing the REST API. The credentials are loaded from ~/.provision_engine_auth and should be stored as user:password.

client.rb [get|post|put|delete] <URI> <JSON file path (for POST and PUT only)>

For example

./client.rb post http://localhost:1337/serverless-runtimes runtime_spec.json

However you can use any regular HTTP Client for this. Basic authentication is required.

Example runtime specifications

FaaS only runtime. Resulting service will create a VM with the default nature role VM Template contents.

{
  "SERVERLESS_RUNTIME": {
    "FAAS": {
      "FLAVOUR": "nature"
    },
    "SCHEDULING": {},
    "DEVICE_INFO": {}
  }
}

FaaS + DaaS + Custom VM requirements + Name.

{
  "SERVERLESS_RUNTIME": {
    "NAME": "Example Serverless Runtime",
    "FAAS": {
      "CPU": 1,
      "MEMORY": 128,
      "DISK_SIZE": 1024,
      "FLAVOUR": "nature"
    },
    "DAAS": {
      "CPU": 1,
      "MEMORY": 128,
      "DISK_SIZE": 1024,
      "FLAVOUR": "s3"
    },
    "SCHEDULING": {},
    "DEVICE_INFO": {}
  }
}

Usage

Create a Serverless Runtime

Create minimal runtime

./http_cli.rb post http://localhost:1337/serverless-runtimes ../../tests/templates/sr_faas_minimal.json
Response Code: 201
{
  "SERVERLESS_RUNTIME": {
    "NAME": "Function_831fb29b-bf5c-4b74-8dff-a1e2efc2e892",
    "ID": 1489,
    "FAAS": {
      "FLAVOUR": "Function",
      "VM_ID": 945,
      "STATE": "PENDING",
      "ENDPOINT": "",
      "CPU": 0,
      "MEMORY": 128,
      "DISK_SIZE": 200
    },
    "SCHEDULING": {
    },
    "DEVICE_INFO": {
    },
    "SERVICE_ID": 1488
  }
}

Once the SR instance is created, the credentials of the client issuing the API Call can be found inside the VMs backing the SR. The device /dev/sr0 contains a CD-ROM that can be mounted. When mounted, a file called context.sh will appear. That file will contain a bash variable called SR_AUTH wich contains the credentials of the client as user:password encoded in base64.

An example follows with credentials oneadmin:opennebula

localhost:~# lsblk
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sr0     11:0    1  364K  0 rom
vda    253:0    0    1G  0 disk
└─vda1 253:1    0 1023M  0 part /
localhost:~# mount /dev/sr0 /mnt/
mount: /mnt: WARNING: source write-protected, mounted read-only.
localhost:~# grep SR_AUTH | /mnt/context.sh
localhost:~# cat /mnt/context.sh | grep SR_AUTH | cut -d "'" -f 2 | base64 -d
oneadmin:opennebulalocalhost:~#

Create a complex runtime

./http_cli.rb post http://localhost:1337/serverless-runtimes ../../tests/templates/sr_daas_capacity.json
Response Code: 201
{
  "SERVERLESS_RUNTIME": {
    "NAME": "Function and Data as a Service",
    "ID": 1491,
    "FAAS": {
      "CPU": 2,
      "MEMORY": 133,
      "DISK_SIZE": 1025,
      "FLAVOUR": "Function-Data",
      "VM_ID": 946,
      "STATE": "PENDING",
      "ENDPOINT": ""
    },
    "DAAS": {
      "CPU": 3,
      "MEMORY": 197,
      "DISK_SIZE": 1337,
      "FLAVOUR": "Data",
      "VM_ID": 947,
      "STATE": "PENDING",
      "ENDPOINT": ""
    },
    "SCHEDULING": {
    },
    "DEVICE_INFO": {
    },
    "SERVICE_ID": 1490
  }
}

Get detailed Serverless Runtime information

./http_cli.rb get http://localhost:1337/serverless-runtimes/1491
Response Code: 200
{
  "SERVERLESS_RUNTIME": {
    "NAME": "Function and Data as a Service",
    "ID": 1491,
    "FAAS": {
      "CPU": 2,
      "MEMORY": 133,
      "DISK_SIZE": 1025,
      "FLAVOUR": "Function-Data",
      "VM_ID": 946,
      "STATE": "RUNNING",
      "ENDPOINT": ""
    },
    "DAAS": {
      "CPU": 3,
      "MEMORY": 197,
      "DISK_SIZE": 1337,
      "FLAVOUR": "Data",
      "VM_ID": 947,
      "STATE": "RUNNING",
      "ENDPOINT": ""
    },
    "SCHEDULING": {
    },
    "DEVICE_INFO": {
    },
    "SERVICE_ID": 1490
  }
}

Update a Serverless Runtime

The update operation can perform several tasks

• Resizing the hardware of an SR
  • CPU
  • Memory
  • Disk
• Rename the SR
• Specify new DEVICE_INFO and SCHEDULING parameters
• Perform an automatic recovery in case of error detection

Every time an update is performed the provision engine will verify the SR template being sent and based on the differences between the current SR definition and the desired SR definition, it will perform the requested changes. If changes are made, the definition will be updated and the SR instance will be rescheduled to the most suitable hosts. This process should be seamless.

./http_cli.rb put http://localhost:1337/serverless-runtimes/501 ../../tests/templates/sr_faas_capacity.json
Response Code: 200
{
  "SERVERLESS_RUNTIME": {
    "NAME": "Function as a Service",
    "ID": 501,
    "FAAS": {
      "FLAVOUR": "Function",
      "VM_ID": 304,
      "STATE": "RUNNING",
      "CPU": 3,
      "MEMORY": 177,
      "DISK_SIZE": 1338,
      "ENDPOINT": ""
    },
    "SERVICE_ID": 500
  }
}

State Machine

stateDiagram-v2
    [*] --> PENDING: Deploy Function
    PENDING --> [*]: Deployment failure
    PENDING --> RUNNING: Deployment Complete
    RUNNING --> UPDATING: Update Function
    UPDATING --> RUNNING: Function Updated
    RUNNING --> ERROR: Failure Detected
    ERROR --> RUNNING: Recovery Successful
    ERROR --> ERROR: Recovery Failed
    UPDATING --> ERROR: Update Failure

Loading