This is still a work in progress, there are many things that haven't been implemented and some interesting restrictions have been placed on this project, mostly to account for the fact that many nasty hacks are involved in the implmementation of this project. All identification must be in UIDs to avoid ambiguity
Note: Not all features of these APIs have been implemented, refer their individual sections for more details
If there are any errors, the program generally will handle it apppropriately, returning a status code with JSON output in the format
{
"error" : {
"error" : *error_type*,
"error_description" : *error_description*
}
}Return status codes are:
| Status code | Type | Description |
|---|---|---|
| 200 | OK | |
| 201 | OK | Resource created/allocated |
| 202 | OK | Operation completed asynchronously |
| 400 | bad_request | This usually means parameters are missing or are of the wrong data types. There will be an extra field, "details" containing a string with an explanation of the fields with errors. |
| 401 | unauthorized | Either invalid or no credentials were supplied when attempting to access resources in the API. Check if your credentials are correct (OS_USERNAME = application ID, OS_PASSWORD = application secret) |
| 401 | invalid_token | There was a problem with the supplied token. It has either expired, revoked or been otherwise invaldiated. A description of the error will be provided in the "error_description" section |
| 401 | invalid_client | This will only occur when there is a problem with the specified credentials. More details will be provided in error_description section. |
| 401 | invalid_request | This will only occur when trying to authenticate, and the request failed (parameters that were supplied were not correct). More details will be in the "error_description" section |
| 403 | forbidden | The request was recieved, however, it is an unauthorized action |
| 404 | not_found | The request failed because a resource with a given ID doesn't exist, or the requested URL doesn't exist |
| 422 | validation_fail | Many situations can cause this error, including more fine-grained validations on field values that aren't picked up by the basic field checking that the 400 error would catch. It may also happen when attempting to perform actions on a resource when it is currently in an inappropriate state to do so. An extra field "details" will be supplied, which is a dictionary with keys and values indicating the specific field on the object and its errors as an array of strings. |
| 500 | internal_server_error | Something on our end has gone wrong. We've been notified and are probably attempting a fix. If the issue persists, contact support. |
| 502 | not_implemented | Currently the requested feature isn't supported. If the feature is something which is absolutely necessary. |
On the OrionVM platform, internal restrictions are already in place and so tenant IDs/project IDs are inherent in the credentials used to authenticate, therefore there is no need for tenant IDs and project IDs - If they are provided, they are disregarded
Inside the OrionVM organization settings, there is a section under the heading INTERGRATIONS named Applications. In here, you can create an application which has security credentials. Use the Application ID as the Openstack Username and the Application Secret as the Openstack Password.
Inside the OrionVM organization settings, there is a section under the heading INTEGRATIONS named Access Tokens. In here, you can generate a token which will provide access to all the services. This token doesn't expire.
There are a few restrictions and requirements that creation of vms have currently.
Due to the structure of the OrionVM platform, it is preferred to specify the availability zone of where the VM should be stored. In OrionVM speak, it is the region in which the VM will be stored in. Due to platform restrictions, all resources must be from the same region (if inval;id combinatios of resources are specified, the process will error out). If the availability zone is not specified, the current default is for the region to be defaulted either to the flavor's region or the disks's region and if both of the above aren't specified, it will default to SY3 (Sydney).
The flavor of the machine must also be specified in a specific format. It runs under the format of
<FLAVOR_ID>_<RAM_AMOUNT>And the details of flavor only specifies the ratio of CPU to RAM (which is why all cores are set to 1)
Again, there are different regions for each flavor, so ensure that the correct region is chosen, lest the default place the VM in a region which isn't preferable.
Creation of VMs supports creation with root passwords set and contents in files set. This feature is only supported on *nix images and may or may not work on snapshots or booting of pre-exisiting disks. Extra charges may occur.
Only IPv4 is supported for external access, creation of IPs and viewing of these IP's availabilities can be found in the floating-ip calls.
Metadata storage in VMs is done in the format of context variables.
Mass creation of VMs are not supported.
Currently only specifying UUIDs is available for specifying VMs (since names aren't unique). There aren't any niches to this section, only that meta tags will be taken up with the direct output of the API queries.
VMs can only be deleted when their state is stopped, otherwise it'll error out.
As mentioned above, the flavor format is defaulted to
<FLAVOR_ID>_<RAM_AMOUNT>The Flavor ID can be queried by itself, however, it will only return the ratio, for exact RAM amounts and the exact amount of CPUs that will be allocated, specify the RAM amount.
Flavors come in standardized formats, so currently when asking to create a flavor, the user will recieve a 403.
Currently serial console access is supported and served through the Mosh Client. The return value of this call will be something along the lines of:
MOSH_KEY=<KEY> mosh-client <ip> <port>This output can directly copied and pasted into a terminal (given that the machine has mosh installed) for serial console access.
Unlike the Openstack platform, the OrionVM platform supports live attaching/detaching of disks. This can be done with the endpoint /compute/servers/{server_id}/os-volume_attachments
This attachment request doesn't support the "device" flag.
Normal attachment also works with the aforementioned endpoint.
At this stage, images are only partially supported by this compatability layer. Images are predefined templates that are on our backend, and thus we only support reading of these images (so creation of VMs/disks off these images). Deletion and any other forms of editing images are not supported.
It is also recommended to use Glance/Image API (v1) instead of using compute to do it because apparently it will be deprecated.
The translation works as Openstack Availability Zones <=> OrionVM Regions. Currently things are uniquely identifiable by region (so Standard Tier for Sydney has a different UID from Stand Tier in Virginia). With this system in place, it is possible for the program to infer the region. If the region is not inferrable, it will default to Sydney.
Preference order (for inference):
Currently only subnets and floating-ips are supported. Translation becomes floating-ips <=> external IP addresses, subnest <=> internal (or private) networks/IP addresses
Floating IPs are orgainised by deletable and not deletable pools. They're pretty self-explanatory, deletable is safe to remove, not deletable can still be deleted, but it might remove connectivity to a VM
On creating floating IPs, the Pool in which the IP is created is aliased to the region that it will be allocated in (since there is no other option and it cannot be infered), and then will be placed into the default pool of not deletable
All listed features are mostly supported, with only slight issues in disk operations and a lack of description/metadata handling. Currently, disk encryption isn't supported on our end, and so by default, all disks don't have encryption turned on.
Disks must have a volume_type specified. This represents their performance_tiers on the OrionVM side. Each region has their own list of performance_tiers, so be sure to have the correct region's perfomance tier. If a volume type isn't specified, it will default to Sydney: Standard
Otherwise disk operations should operate as they would normally be expected to, the only difference is that they have different states. Valid states for disks are attached, attaching, detaching, failed_to_provision, failed_to_terminate, initial, pending, pending_verification, provisioning, resizing, terminated, terminiating, transferred, unattached
Disk types are currently a required thing (soft requirement, can still be created, but with hard-coded defaults). Since each region has their own version of "disk types", ensure that the "disk type's" location is the correct one.
Disk Types are formatted like
<region>: <type>e.g.
Sydney: StandardThe translation works as Openstack Availability Zones <=> OrionVM Regions. Currently things are uniquely identifiable by region (so Standard Tier for Sydney has a different UID from Stand Tier in Virginia). With this system in place, it is possible for the program to infer the region. If the region is not inferrable, it will default to Sydney.
Preference order (for inference):
Backups are fully supported (aside from the global restrictions). Backups are implemented as disk clones, so they may result in extra charges.
Snapshots are implemented as special disk clones - they may incur extra charges.
As mentioned in the compute section, only listing is supported by our Image API, simply because Images are global templates. For "images" that can be created/deleted/modified, use a snapshot.
As with all regions (availability-zones) and performance_tiers (flavors/disk types), images are also uniquely by their regions, so Ubuntu 16.04 in Sydney has a different UID to Ubuntu 16.04 in Virginia. Ensure that the correct UID is used to prevent ambiguity/confusion within the program