VPC API

Introduction: Projects, Resources, and Quotas

The most basic element in the Virtual Private Cloud is the project. Projects are the combination of all objects available to the user: virtual machines, disks, networks, etc. Within the framework of a project, users can reserve and distribute resources (RAM, vCPUs, disk space, etc.) among their objects.

When a project is created, the user adds a specific number of resources to the project. This creates a limit, or quota, of resources available for that project.

Projects are created in specific geographic locations known as regions. Two regions are available: St. Petersburg and Moscow. Regions are made up of zones. In the context of our service, zones represent the data centers in a given region. St. Petersburg has two zones (ru-1a and ru-1b) and Moscow has one (ru-2a).

In addition to the control panel, VPC projects, resources, and objects can be managed from an API using standard HTTP requests. To send requests to the API, the user should choose the appropriate method from the documentation, formulate the request according to the description, and then execute it. API responses are returned in JSON format.

The structure of typical requests (e.g. creating projects, assigning quotas, and adding users) and their responses are described below. The full documentation is available in our control panel.

curl 'https://api.selectel.ru/vpc/resell/v2/projects' -X POST -H "Content-Type: application/json" --data-binary {project:{"name":"test"}}' -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"

Getting Started: Obtaining a Key

To use the API, you will first need an authentication key (token). Users registered at Selectel can obtain a key on the page my.selectel.ru/profile/apikeys. A token is a single string like qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx, where xxxxx is the user's account number.

Keys are sent as part of each request in the X-Token header:

curl -i https://api.selectel.ru/vpc/resell/v2/projects -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx'

Creating Projects

We'll create a project and name it "test". We do this with the following request:

curl 'https://api.selectel.ru/vpc/resell/v2/projects' -X POST -H "Content-Type: application/json" --data-binary {project:{"name":"test"}}' -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"

Response:

{"project": {"url": "https://8888.selvpc.ru", "enabled": true, "id": "fa9e778a6cb64fcca46605be6b58164c", "name": "test"}}

The response tells us that:

  • the project has been created and is now available
  • the project's external control panel is available at https://8888.selvpc.ru
  • the project's ID number is fa9e778a6cb64fcca46605be6b58164c (this will be needed for future requests and for working with third-party libraries and console clients)
  • as per the request, the project is named "test"

We'll continue by allocating resources, i.e. setting quotas, for our project.

Allocating Resources and Setting Quotas

At this stage, we'll have to indicate which resources and what quantity thereof we want available to our project.

Let's look at an example:

curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx " -H "Content-Type: application/json" -d '{"quotas": {"compute_cores": [{"region": "ru-1", "zone": "ru-1b", "value": 8}]}}'

Here we contact the VPC API and request 8 vCPUs for our project in region ru-1, zone ru-1b.

Then we request 8192 MB RAM and 100 GB of 'universal' disk space.

curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json" -H "User-Agent: python-selvpcclient/1.0" -d '{"quotas": {"compute_ram": [{"region": "ru-1", "zone": "ru-1b", "value": 8192}]}}'
curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token:qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json" -H "User-Agent: python-selvpcclient/1.0" -d '{"quotas": {"volume_gigabytes_universal": [{"region": "ru-1", "zone": "ru-1b", "value": 100}]}}'

We can view general information about our project with the command:

curl 'https://api.selectel.ru/vpc/resell/v2/projects/fa9e778a6cb64fcca46605be6b58164c' -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_22302'

The response will be a JSON array:

{
 "project": {
   "name": "test",
   "url": "https://51852.selvpc.ru",
   "enabled": true,
   "custom_url": null,
   "quotas": {
     "volume_gigabytes_basic": [
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1b",
         "value": 0
       },
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1a",
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": "ru-2a",
         "value": 0
       }
     ],
     "compute_cores": [
       {
         "region": "ru-1",
         "used": 4,
         "zone": "ru-1b",
         "value": 8
       },
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1a",
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": "ru-2a",
         "value": 0
       }
     ],
     "image_gigabytes": [
       {
         "region": "ru-1",
         "used": 0,
         "zone": null,
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": null,
         "value": 0
       }
     ],
     "volume_gigabytes_universal": [
       {
         "region": "ru-1",
         "used": 80,
         "zone": "ru-1b",
         "value": 100
       },
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1a",
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": "ru-2a",
         "value": 0
       }
     ],
     "compute_ram": [
       {
         "region": "ru-1",
         "used": 4096,
         "zone": "ru-1b",
         "value": 8192
       },
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1a",
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": "ru-2a",
         "value": 0
       }
     ],
     "volume_gigabytes_fast": [
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1b",
         "value": 0
       },
       {
         "region": "ru-1",
         "used": 0,
         "zone": "ru-1a",
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": "ru-2a",
         "value": 0
       }
     ],
     "volume_gigabytes_iso": [
       {
         "region": "ru-1",
         "used": 0,
         "zone": null,
         "value": 0
       },
       {
         "region": "ru-2",
         "used": 0,
         "zone": null,
         "value": 0
       }
     ]
   },
   "theme": {
     "color": "#ff000",
     "logo": null
   },
   "id": "fa9e778a6cb64fcca46605be6b58164c"
 }
}

This is the exact response received for the previous request. Parameters we left undefined have a value of 0.

To make the project's virtual machines available from an external network, we add a floating IP address:

curl -i -XPOST 'https://api.selectel.ru/vpc/resell/v2/floatingips/projects/fa9e778a6cb64fcca46605be6b58164c' -H 'Content-Type: application/json' --data-binary '{"floatingips":[{"region":"ru-1","quantity":3}]}' -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_22302'

The request structure is fairly clear: we added 3 addresses ("quantity":3) to region ru-1.

Response:

{"floatingips": [{"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.30", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "d5489d04-6c5f-46f5-810b-7f86c71ce8ae"}, {"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.50", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "12d78f81-3d56-4592-92f2-558d5c4e2f68"},{"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.73", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "7569e8f8-3cb1-4823-8e1e-c69574b0282f"}

Each IP address is listed with the status DOWN, but this doesn't imply any error, only that the address hasn't been attached to a machine. Like all VPC objects, every IP address has an ID.

This parameter will also be needed later on when we create virtual machines and assign them addresses.

Users and Roles

Projects can be accessible to multiple users. This is done by first creating a new user and then adding them to the project.

Users added to a project have a limited number of permissions in the project, or "role" in OpenStack terminology. Roles are required for working with third-party programs, such as the ones described in the Console Clients section of our knowledge base.

To create a new user, we send a POST request with the user's login and password:

curl -i -XPOST "https://api.selectel.ru/vpc/resell/v2/users" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json -d '{"user": {"password": "password, "enabled": true, "name": "new user"}}'

If the request is successful, the API responds:

{"user": {"enabled": true, "name": "newuser", "id": "6000869ba906427aaeb997835c4babdb"}}

To assign the user a role (i.e. add the user to a project), we submit a request in the following format:

curl -i -XPOST "https://api.selectel.ru/vpc/resell/v2/roles/projects/{id проекта}/users/{id пользователя}" -H "X-Token:qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"

Now that we have created our project, set quotas, and added a user, we can start making virtual machines.

This can be done using OpenStack console clients.