API#

September 2, 2024
in API
8 min read

The VergeOS API allows developers to interact with the VergeOS system programmatically. It provides access to system operations such as creating virtual machines, managing resources, and interacting with billing and catalog repositories. The API uses standard REST-like conventions and supports multiple authentication methods. This guide provides an overview of the VergeOS API, endpoint documentation, example requests, and error handling.

This document outlines the usage of the API. Detailed information for the API can be found within the VergeOS UI as a Swagger documentation page, which is dynamically generated and shows a complete listing of available API tables and operations.

Swagger Interface

To access the Swagger documentation in the VergeOS UI:

Login to the VergeOS system with valid credentials.
From the Main Dashboard, click System in the left menu.
In the System Dashboard, find the API Documentation link at the bottom left and click it.
The Swagger documentation page will open. This page provides detailed examples for each API operation, including the ability to test the API directly.

Swagger Documentation Example

Select an individual table and choose one of the available GET/POST/DELETE/PUT options to view and test API actions.

Swagger Documentation Example

Specify the parameters and click the Execute Button to run the API command. This will return the response, which includes the response body, header, and a curl example.

Swagger Documentation Example

API Basics

HTTP Methods

The VergeOS API uses standard HTTP methods like GET, POST, PUT, and DELETE for resource manipulation.

GET Parameters

fields: Specify which fields to return in the result set.
filter: Filter the result set based on certain criteria.
sort: Sort the results by a specified field.
limit: Limit the number of returned results.

Authentication

All API requests must be made over HTTPS and require authentication using basic access authentication or a session token.

Additional Notes

Rate Limits: The API supports a maximum of 1000 requests per hour per API key.
Data Formats: All responses are returned in JSON format.
Pagination: Endpoints that return large sets of data support pagination using offset and limit query parameters.

Authentication

VergeOS supports two methods of authentication:

Basic HTTP Authentication
The API is available only through SSL.
Token-based Authentication
Developers must request a token from the API by posting to the /sys/tokens endpoint. The token is then passed in subsequent API requests in the x-yottabyte-token header.

Example Authentication Request

To obtain a token:

curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://your-verge-instance.com/api/sys/tokens'

Example response:

{
   "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "$row":1,
   "$key":"3a334563456378845634563b7b82d2efcadce9"
}

Use the token from the "$key" field in all subsequent requests:

x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9

To log out, send a DELETE request to the /sys/tokens/{token} endpoint.

Example Logout Request

DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9

Example Virtual Machines

The VMs section of the VergeOS API allows users to manage virtual machines programmatically. It includes endpoints to list, create, modify, and delete VMs.

Retrieve a List of Virtual Machines

Endpoint:
GET /v4/vms?fields=most

Description:
Retrieves a list of all VMs in the system with details such as CPU cores, RAM, machine type, and configuration details.

Example Request:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vms?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Example Response:

href="#__codelineno-18-1">[ { "$key": 1, "name": "CentOS 7 (Latest) 1.0-7", "machine": 7, "cpu_cores": 2, "cpu_type": "Cascadelake-Server", "ram": 2048, "os_family": "linux", "is_snapshot": true, "boot_order": "cd", "rtc_base": "utc", "console": "vnc", "uefi": false, "secure_boot": false, "serial_port": true, "uuid": "d3914756-4ec5-9dfe-5c45-b28af2fd3d73", "created": 1724435418, "modified": 1724435418 } ]

Overview of the Data Returned:

$key: The unique identifier for the VM.
name: The name of the virtual machine.
machine: Machine ID associated with the VM.
cpu_cores: Number of CPU cores allocated to the VM.
ram: Amount of RAM allocated (in MB).
os_family: Operating system type.
uuid: Universally unique identifier (UUID) for the VM.
created: The creation timestamp.
modified: The last modified timestamp.

Create a New Virtual Machine

Endpoint:
POST /v4/vms

Description:
Creates a new virtual machine with specific configuration details, such as CPU cores, RAM, machine type, boot order, etc.

Example Request:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vms' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "rest",
    "description": "test",
    "machine_type": "pc-q35-9.0",
    "allow_hotplug": true,
    "cpu_cores": 1,
    "cpu_type": "Broadwell",
    "ram": 1024,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": false,
    "note": "test vm"
  }'

Example Response:

{
  "location": "/v4/vms/36",
  "dbpath": "vms/36",
  "$row": 36,
  "$key": "36"
}

Overview of the Data Returned:

location: The location of the newly created VM resource.
dbpath: Database path of the new VM.
$row: Row ID of the VM.
$key: Unique key for the VM.

Example Virtual Networks (Vnets)

The Vnets section of the VergeOS API allows users to manage virtual networks (Vnets) programmatically. It includes endpoints to retrieve, create, and manage network resources, including internal and external networks, and allows advanced options like rate limiting.

Retrieve Vnet Details

Endpoint:
GET /v4/vnets?fields=most

Description:
Retrieves a list of all Vnets in the system with details such as network type, MTU, DHCP settings, and DNS configuration.

Example Request:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vnets?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Example Response:

[
  {
    "$key": 6,
    "name": "Internal Test 1",
    "advanced_options": {
      "dnsmasq": [
        "--dhcp-boot=netboot.xyz.kpxe,,192.168.10.20",
        "--dhcp-match=set:efi-x86,option:client-arch,6",
        "--dhcp-boot=tag:efi-x86,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,7",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,9",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20"
      ]
    },
    "type": "internal",
    "layer2_type": "vxlan",
    "network": "192.168.100.0/24",
    "mtu": 9000,
    "dhcp_enabled": true,
    "dhcp_start": "192.168.100.100",
    "dhcp_stop": "192.168.100.200",
    "rate_limit": 0,
    "rate_limit_type": "mbytes/second",
    "gateway": ""
  }
]

Overview of the Data Returned:

$key: The unique identifier for the Vnet.
name: Name of the virtual network.
advanced_options: Advanced options to be passed to services running inside the network, in this example netboot flags for dnsmasq
type: Network type (e.g., "internal").
layer2_type: The type of Layer 2 networking, such as VXLAN.
network: Network CIDR block.
mtu: Maximum Transmission Unit (MTU) size.
dhcp_enabled: Indicates whether DHCP is enabled for this network.
dhcp_start: Starting IP address for the DHCP pool.
dhcp_stop: Ending IP address for the DHCP pool.
rate_limit: Rate limit for the network (in mbytes/second).
gateway: The default gateway for the network.

Create an Internal Network with Rate Limiting

Endpoint:
POST /v4/vnets

Description:
Creates a new internal virtual network with rate limiting and DHCP settings.

Example Request:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vnets' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"int1",
    "description":"workloads",
    "type":"internal",
    "mtu":"9000",
    "network":"192.168.80.0/24",
    "gateway":"192.168.80.1",
    "dnslist":"1.1.1.1",
    "dhcp_enabled": true,
    "rate_limit": 100,
    "rate_limit_burst": 500,
    "dhcp_start":"192.168.80.100",
    "dhcp_stop":"192.168.80.200"
  }'

Example Response:

{
  "location": "/v4/vnets/8",
  "dbpath": "vnets/8",
  "$row": 8,
  "$key": "8"
}

Overview of the Data Returned: - location: The location of the newly created Vnet resource. - dbpath: Database path of the new Vnet. - $row**: Row ID of the Vnet. - **$key: Unique key for the Vnet.

Here's the Resources section formatted for the API guide:

Resources

Below is an example URL used to query a list of machines.

Example: https://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all


https://	user	:	password	@	server	/api	/v4/machines	?	filter=&fields=all&sort=&limit=
	User name		User Password		Server host name or IP		Resource location (URI)		These options are described below

GET Options

Fields

Specify which fields to return in the result set (may also be a view if there is one defined for the table schema).
all returns every field.
most returns most fields except for argument fields and rows.
summary returns fields marked as 'summary' in their schema.
Example: fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name

Field functions: - collapse - datetime - upper - lower - count - diskspace - display - hex - sha1 - sum - avg - min - max

Filter

Filter result sets by specified criteria.
Similar to OData.
Example: filter=enabled eq true and size gt 1048576.
Example: filter=cputype eq 'qemu' or cputype eq 'kvm'.

Operator	Description
eq	Equal
ne	Not equal
gt	Greater than
ge	Greater than or equal
lt	Less than
le	Less than or equal
bw	Begins with
ew	Ends with
and	Logical and
or	Logical or
cs	Contains string (case sensitive)
ct	Contains text (case insensitive)
rx	Regex match

Sort

Sort results by the specified field.
Example: sort=+name.
Example: sort=-id.

Limit

limit (integer) limits the result set to a specified number of entries. A value of 0 means unlimited.
Example: limit=1.

Generic HTTP Response Codes

400 - Bad Request: The request was invalid.
401 - Failed Login / Login Required: Authentication failed or is required.
403 - Permission Denied: You lack the required permissions.
404 - Resource Not Found: The requested row or API does not exist.
405 - Not Permitted: The operation is not allowed.
409 - Row Exists: The resource already exists.
422 - Failed Validation / Invalid Parameter: Validation failed.
500 - Internal Server Error: An unhandled error occurred.

POST-Specific

201 - Created: A new row/resource was successfully created.

Websocket-Specific (Used for VNC/SPICE)

101 - Switching Protocols: The protocol was successfully switched.

PUT/GET/DELETE

200 - Success: The operation completed successfully.

Schema Table Definitions

Field Types

bool
text
string
num
uint8
uint16
uint32
uint64
int8
int16
int32
int64
enabled
created
created_ms
created_us
modified
modified_ms
modified_us
filename
filesize
fileused
fileallocated
filemodified
json
row
rows

Schema Owner / Parent Field

Owner Field: If the owner field is null, normal permissions apply. If the owner field has a value, permissions are replaced by a permission check to the owner.
Parent Field: The permission check is applied to the row itself, and if permissions fail, permissions are also checked on the parent row.

Full Table Schema

To retrieve a table’s schema, append $table to the URI:

/api/v4/machines/$table (replace "machines" with the table name).

You will be prompted for your credentials; this requires VergeOS admin credentials. The output will be in JSON format. Firefox displays this in a readable format by default, but other browsers may require exporting the JSON to an external program for better readability.

Example Errors

Example Error (HTTP Code 422)

{
  "err": "Validation error on field: 'dhcp_start' - 'fails validation test'"
}

VergeOS uses standard HTTP status codes to indicate the result of an API request.

400 Bad Request: The request is invalid or cannot be processed.
401 Unauthorized: The API key is missing or invalid.
403 Forbidden: The API key lacks the required permissions.
404 Not Found: The resource does not exist.
500 Internal Server Error: A server error occurred.

Document Information

Last Updated: 2024-08-29
vergeOS Version: 4.12.6

September 1, 2024
in System Administration, Automation, Development, API
2 min read

Terraform VergeIO Provider

The Terraform VergeIO Provider enables the integration and automation of VergeOS infrastructure with Terraform. It allows users to define, manage, and scale VergeOS resources as part of Infrastructure as Code (IaC) workflows.

For the latest provider documentation and examples, please refer to the following:

GitHub Repository for the VergeIO Terraform Provider.
Terraform Registry Documentation for official usage and updates.

Example Usage

For more detailed usage examples, check the docs folder in the GitHub repository.

Example Configuration

provider "vergeio" {
  host     = "https://some_url_or_ip"
  username = "my_user"
  password = "my_password"
  insecure = false  # Use true if using self-signed SSL certificates
}

resource "vergeio_vm" "new_vm" {
  name        = "NEW VM"
  description = "NEW TF VM"
  enabled     = true
  os_family   = "linux"
  cpu_cores   = 4
  machine_type = "q35"
  ram         = 8192
}

Initializing and Applying

To apply the configuration:

terraform init && terraform apply

Configuration Reference

host (Required): URL or IP address for the VergeOS system or tenant.
username (Required): Username for the VergeOS system or tenant.
password (Required): Password for the provided username.
insecure (Optional): Set to true for systems using self-signed SSL certificates.

Resources

The following VergeOS resources can be managed via Terraform:

vergeio_drive
vergeio_member
vergeio_network
vergeio_nic
vergeio_user
vergeio_vm

Data Sources

The following data sources are available for querying VergeOS resources:

vergeio_clusters
vergeio_groups
vergeio_mediasources
vergeio_networks
vergeio_nodes
vergeio_version
vergeio_vms

Testing a Sample Configuration

To test your configuration, create a main.tf file in your Terraform workspace:

terraform {
  required_providers {
    vergeio = {
      source = "vergeio/cloud/vergeio"
    }
  }
}

provider "vergeio" {
  host     = "https://someURLorIP"
  username = "username"
  password = "password"
}

resource "vergeio_vm" "new_vm" {
  name        = "NEW VM"
  description = "NEW TF VM"
  enabled     = true
  os_family   = "linux"
  cpu_cores   = 4
  machine_type = "q35"
  ram         = 8192
}

Then, run the following command:

terraform init && terraform apply

Document Information

Last Updated: 2024-09-03
VergeOS Version: 4.12.6

August 3, 2024
in API, Development, Virtual Machines
3 min read

API Helper Script

The yb-api helper script provides an easy way for developers to interact with the VergeOS API. It simplifies making API calls, such as retrieving virtual machines, updating configurations, and managing resources. This guide will outline the key commands and usage of the yb-api script.

Prerequisites

Access to a VergeOS system.
Access to the cluster via SSH or direct connection.
wget and curl must be installed on the system for certain operations.

Running the Helper Script

To get help or view the available options, run:

yb-api --help

Connect to the node and execute this command to begin using the API helper.

yb-api Example

Example Commands

Below are examples of how to use yb-api for various VM management tasks.

Get a List of Virtual Machines (excluding snapshots)

Retrieve a list of VMs and filter out snapshots.

yb-api --get --user=admin --server=10.0.0.100 \
--fields='name,$key,ram,machine#status#status as machine_status' \
--filter='is_snapshot eq false' /v4/vms

Simple Dump of All VMs

This command retrieves a list of all VMs. The --server, --user, --filter, and --fields flags are optional in this case.

yb-api --get /v4/vms

Get Detailed VM Information

Retrieve most of the fields, including drive and NIC information, for a specific VM (VM 1 in this case).

yb-api --get --user=admin --server=10.0.0.100 \
--fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

Rename a Virtual Machine

Change the name of an existing virtual machine (VM 1) to "NEWNAME".

yb-api --put='{"name":"NEWNAME"}' --user=admin --server=10.0.0.100 /v4/vms/1

Delete a Virtual Machine

Delete a specific VM (VM 1), using its $key.

yb-api --delete --user=admin --server=10.0.0.100 \
--fields='name,$key,ram' /v4/vms/1

Create a New Virtual Machine

Create a new VM with specific configurations (name, CPU cores, RAM, etc.).

yb-api --post='{"name":"NEWVM","enabled":true,"description":"test vm",\
"os_family":"linux","cpu_cores":4,"ram":"8192"}' --user=admin \
--server=10.0.0.100 /v4/vms

Get the VM Database Table Schema

Retrieve the schema for the VMs database table.

yb-api --get --user=admin --server=10.0.0.100 '/v4/vms/$table'

Clone a Virtual Machine

Clone an existing VM (VM 1) and give it a new name.

yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \
--post='{"vm":1, "action": "clone", "params": {"name": "NEW VM NAME"}}'

Power On a Virtual Machine

Power on an existing VM (VM 1).

yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \
--post='{"vm":1, "action": "poweron"}'

Notes About `yb-api`

The yb-api script relies on wget, which may not be installed by default on macOS. Make sure to install it if necessary.
curl is used for the upload function in certain API calls, such as posting data to create new VMs.

By using the yb-api helper script, developers can simplify interaction with the VergeOS API and manage virtual machines more efficiently. Let us know if you need assistance with further commands or options.

Document Information

Last Updated: 2024-08-29
vergeOS Version: 4.12.6

October 6, 2023
in API
4 min read

API Tables Description

The following is a brief description of each of the API tables. To find out more details, add /#swagger to the end of your VergeUI's URL (or navigate to System->API Documentation). Swagger provides detailed information about each table and allows you to test each method with a Get/Post/Put/Delete action. For more instructions on how to integrate with the API, refer to the API Documentation page.

API Tables

auth_source_states

Provides a list of auth source states.

auth_sources

Authorization sources table for managing authorization sources like OpenID or AzureAD.

billing

Used to get billing information for the current environment. This is stored as billing data with a from->to date.

billing_actions

Used to send billing actions. The main action is "generate," which creates a new bill.

Fields:
action : See action list below.
Actions:
generate : Generate bill
Example:

URL: '/v4/billing_actions'
POST(JSON): {"action": "generate"}

catalog_logs

Logs specific to Catalogs.

catalog_repositories

Catalog repositories and sublists for catalogs, logs, permissions, etc.

catalog_repository_actions

Used to send Catalog Repository Actions.

Fields:
repository : Row ID for the repository you want to refresh.
action : Default action is refresh. See action list below.
Actions:
refresh : Refresh the Catalog Repository.
Example:

URL: '/v4/catalog_repository_actions'
POST(JSON): {"repository": 1, "action": "refresh"}

catalog_repository_logs

View and post Catalog Repository Logs.

catalog_repository_status

Used to store and update the Catalog Repository statuses. These determine the state and status of a Catalog Repository.

catalogs

Catalogs table allowing you to update/post/delete Catalogs.

certificates

SSL Certificates for your site.

clone_iso

Stores information and status of the Verge.io Clone ISO program.

clone_iso_actions

Actions for the Clone ISO feature.

Fields:
action : Default is "update." See action list below.
Actions:
update : Update the ISO image.
delete : Delete the ISO image.
cancel : Cancel the current build.
Example:

URL: '/v4/clone_iso_actions'
POST(JSON): {"action": "update"}

cloud_restore

Stores information when a Cloud Restore is performed.

cloud_snapshot_actions

Actions for the Cloud Snapshot feature.

cloud_snapshot_tenant_actions

Actions for the Cloud Snapshot feature for a Tenant.

cloud_snapshot_tenants

Cloud Snapshots for a Tenant.

cloud_snapshot_vm_actions

Actions for a VM and Cloud Snapshots.

cloud_snapshot_vms

Used to store information when a Cloud Snapshot is downloaded to a VM.

cloud_snapshots

The Cloud Snapshots table includes information about the Cloud Snapshot, as well as a list of VMs, Tenants, and Sync Queues. This can be used to see what VMs are included in a Cloud Snapshot.

cloudinit_files

Operations for the Cloudinit Files feature.

cluster_actions

Cluster Actions is used to send actions for Clusters.

Fields:
cluster : Cluster row ID (required).
action : See action list below.
params : Parameters supplied in JSON form (optional).
Actions:
shutdown : Shutdown the Cluster.
cancel_shutdown : Cancel current shutdown request.
Example:

URL: '/v4/cluster_actions'
POST(JSON): {"cluster": 1, "action": "shutdown", "params": "{}"}

Fields:
file : File ID from files table (required).
action : See action list below.
params : Parameters supplied in JSON form (optional).
Actions:
overwrite : Overwrite the file.
add_link : Add a file link.
delete_link : Delete a file link.
delete_references : Delete file references.
Example:

URL: '/v4/file_actions'
POST(JSON): {"file": 1, "action": "add_link", "params": "{}"}

Last Updated: 2024-08-29
vergeOS Version: 4.12.6