Main    /    Blog    /    The python-selvpcclient Library

←   →

The python-selvpcclient Library

25 August 2017 9 min read
Tags: ,

Our Virtual Private Cloud is built on OpenStack. The initial cloud setup and several types of objects can be managed from our API.

To make our service even easier to use, we’ve developed the selvpcclient library. The library is written in Python and covers the entire API, which lets you manage projects, quotas, and resources from your program code and console.

Setup

  1. Download the library from the PyPI: 
    pip install python-selvpcclient
  2. Obtain an API token for accessing the cloud (the key should follow the format xxxxvGBYVXcQ3q86zQCGxgvk_42069).
  3. Obtain the current API URL (for example: https://api.selectel.ru/vpc/resell/vs2).

Using the Library

Once the library has been successfully installed, it needs to be imported and initiated:

from selvpcclient.client import Client, setup_http_client
     
SEL_TOKEN=YOUR_API_TOKEN_HERE
SEL_URL="https://api.selectel.ru/vpc/resell"
SEL_API_VERSION=2
 
http_client = setup_http_client(api_url=SEL_URL,
                                api_version=SEL_API_VERSION, 
                                api_token=SEL_TOKEN)
selvpc = Client(client=http_client)

Note: The API URL and version will be shown separately!

The selvpc object contains the following fields:

  • projects — for managing projects
  • quotas — for managing project quotas
  • limits — for obtaining information on domain limits
  • users — for managing users
  • licenses — for managing licenses
  • roles — for managing user roles
  • floatingips — for managing floating IP addresses
  • subnets — for managing subnets
  • vrrp — for managing VRRP subnets
  • capabilities — for obtaining supplementary information (information on available regions, zones, etc.)
  • tokens — for obtaining OpenStack API access tokens

Fields take the following methods:

  • list — returns a list of objects (except tokens)
  • show — shows detailed object information (except tokens)
  • create — creates an object (only projects / users)
  • add — adds resources to a projects (except tokens)
  • update — updates objects (only projects / users)
  • delete — deletes objects (except tokens)

Creating Projects and Setting Quotas

When creating a project, we set our base quotas and add a Windows Server 2012 license:

project = selvpc.projects.create("Bonnie")

Note: As of version 1.1, the API can return a “naked” JSON response; this can be done by sending the key return_raw:

project_json = selvpc.projects.create("Clyde", return_raw=True)

project_json will contain the following values:

{
   "name": "Clyde",
   "id": "f3504dc929ee40e5a296143218bf435d",
   "url": "https://xxxx.selvpc.ru",
   "enabled": True
}

This will create a “Project” object class, which contains helper methods (delete, update, etc.).

Now we can set the quotas for our project:

"quotas": {
        "compute_cores": [
            {
                "region": "ru-1",
                "zone": "ru-1a",
                "value": 10
            }
        ],
        "compute_ram": [
            {
                "region": "ru-1",
                "zone": "ru-1a",
                "value": 1024
            }
        ]
    }
}
 
# via object
project.update_quotas(quotas)
 
# via quotas manager
quotas = client.quotas.update(project.id, quotas=quotas)

Next we add a license:

"licenses": [{
      "region": "ru-1",
      "quantity": 1,
      "type": "license_windows_2012_standard"
  }]
}
 
# via object
project.add_license(license)
 
# via licenses manager
licenses = selvpc.licenses.add(project.id, licenses=licenses)

CLI

The library is packaged with the selvpc console application, which is based on python-cliff, a console app framework.

Getting Started

To manage your cloud from the console app, you need an API URL and token.

There are two ways that the console app can obtain these: from the respective SEL_URL and SEL_TOKEN environment variables or from call arguments (–url and –token).

Note: The library is configured to work with API ver. 2, SEL_API_VERSION by default / -api-version doesn’t need to be given.

Note: If information is given in both an argument and environment variable, priority will be given to the argument.

export SEL_TOKEN="xxxxvGBYVXcQ3q86zQCGxgvk_42069"
export SEL_URL="https://api.selectel.ru/vpc/resell"
export SEL_API_VERSION=2
 
selvpc --url "https://api.selectel.ru/vpc/resell" --token "xxxxvGBYVXcQ3q86zQCGxgvk_42069" project list

Commands

Commands are standard for OpenStack console clients:

  1. To create an object – * create (ex: project create)
  2. To update an object – * update (ex: user update)
  3. To retrieve a list of objects – * list (ex: license list)
  4. To delete an object – * delete (ex: subnet delete)

The asterisk (*) should be replaced by the object name: project, user, role, floatingip, subnet, vrrp, license.

As an example, let’s create a project using the command project create:

selvpc project create -n awesome

We retrieve a list of projects:

selvpc project list
 
+----------------------------------+----------+-------------------------+---------+
| id                               | name     | url                     | enabled |
+----------------------------------+----------+-------------------------+---------+
| f3504dc929ee40e5a296143218bf435d | awesome  | https://xxxxx.selvpc.ru | True    |
+----------------------------------+----------+-------------------------+---------+

To view a list of available commands, run selvpc help:

selvpc help
 
Commands:
  ...
  capabilities show traffic  Show available traffic values
  complete       print bash completion command
  floatingip add  Create new floatingip IP address
  floatingip delete  Delete floatingip IP
  floatingip list  List floatingip IP
  ...

Creating an Ubuntu 16 x64 Virtual Machine

Let’s take a detailed look at how we can use the console client to create a virtual machine.

The general sequence of tasks should be as follows:

  1. Create a project, users, and assign roles
  2. Allocate resources
  3. Prepare the environment
  4. Create the virtual machine

Creating a Project

We’ll create a project:

selvpc project create -n "another-project"
 
+---------+----------------------------------+
| Field   | Value                            |
+---------+----------------------------------+
| id      | 96063b0c4a71443c8a842c647bdab316 |
| name    | "another-project"                |
| url     | https://xxxxx.selvpc.ru          |
| enabled | True                             |
+---------+----------------------------------+

Since we don’t have any users yet, we’ll have to create them, too:

selvpc user create --name "T-Rex" --password "c1017e8c8fd14b7e8057618a882240df"
 
+---------+----------------------------------+
| Field   | Value                            |
+---------+----------------------------------+
| id      | 052027b58a3f49e390c3849d6697e2f3 |
| name    | "T-Rex"                          |
| enabled | True                             |
+---------+----------------------------------+

Now we add the user T-Rex (052027b58a3f49e390c3849d6697e2f3) to the project “another-project” (96063b0c4a71443c8a842c647bdab316):

selvpc role add -p 96063b0c4a71443c8a842c647bdab316 -u 052027b58a3f49e390c3849d6697e2f3
 
+------------+----------------------------------+
| Field      | Value                            |
+------------+----------------------------------+
| project_id | 96063b0c4a71443c8a842c647bdab316 |
| user_id    | 052027b58a3f49e390c3849d6697e2f3 |
+------------+----------------------------------+

Allocating Resources

For our new machine, we’ll allocate 1 vCPU, 512 MB RAM, and 5 GB of disk space.
We can view a list of available resources with the following command:

    /output fragment/
 
selvpc capabilities show resources
 
    +-------------------------------+-------------+----------+------------+
    | name                          | quota_scope | quotable | unbillable |
    +-------------------------------+-------------+----------+------------+
    | compute_cores                 | zone        | True     | True       |
    | compute_ram                   | zone        | True     | True       |
    | volume_gigabytes_fast         | zone        | True     | False      |
    +-------------------------------+-------------+----------+------------+

Project quotas can be set using the command selvpc quota set (argument descriptions can be found in the help: “selvpc_help_quota set”):

selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 1 --resource compute_cores
selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 512 --resource compute_ram
selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 5 --resource volume_gigabytes_fast
 
+----------------------------+--------+-------+-------+
| resource                   | region | zone  | value |
+----------------------------+--------+-------+-------+
| compute_cores              | ru-1   | ru-1a | 1     |
| compute_ram                | ru-1   | ru-1a | 512   |
| volume_gigabytes_fast      | ru-1   | ru-1a | 5     |
+----------------------------+--------+-------+-------+

To manage our cloud from the OpenStack client, we have to log in.

To make this easier for our users, RC files (scripts that the console can use to authenticate in Identity API v3) can be downloaded from the control panel.

To obtain the script:

  1. Open the project control panel
  2. Open the project you’ll be working in
  3. Click the Access tab
  4. Choose the user
  5. Choose the region
  6. Click Download

RC.sh example:

export OS_AUTH_URL="https://api.selvpc.ru/identity/v3"
export OS_IDENTITY_API_VERSION="3"
export OS_VOLUME_API_VERSION="2"
 
export OS_PROJECT_DOMAIN_NAME='xxxx'
export OS_PROJECT_ID='96063b0c4a71443c8a842c647bdab316'
export OS_TENANT_ID='96063b0c4a71443c8a842c647bdab316'
export OS_REGION_NAME='ru-1'
 
export OS_USER_DOMAIN_NAME='xxxx'
export OS_USERNAME='T-Rex'
 
export OS_PASSWORD='c1017e8c8fd14b7e8057618a882240df'

Note: In the original script, the OS_PASSWORD variable will not contain a password, since it’s initialized for demonstrative purposes. Never give your password to anyone!

After downloading the script, run source:

source RC.sh

Preparing the Environment

In this example, we’ll be using an Ubuntu 16.04 LTS 64-bit image.

We retrieve a list of available images:

openstack image list
 
+--------------------------------------+---------------------------------+--------+
| ID                                   | Name                            | Status |
+--------------------------------------+---------------------------------+--------+
| 9feac917-f155-4013-b2fa-f5c8b72fd33c | Ubuntu 16.04 LTS 64-bit         | active |
+--------------------------------------+---------------------------------+--------+

Next we create a disk based on the image:

openstack volume create ubuntu-volume --image "9feac917-f155-4013-b2fa-f5c8b72fd33c" --size 5
 
+---------------------+--------------------------------------+
| Field               | Value                                |
+---------------------+--------------------------------------+
| id                  | f79c0d35-f54c-4b6a-82ad-1764e425eec8 |
+---------------------+--------------------------------------+

To create a machine, we’ll need a flavor (machine configuration).

We create a new configuration:

openstack flavor create --private --ram 512 --vcpus 1 my-flavor
 
+----------------------------+--------------------------------------+
| Field                      | Value                                |
+----------------------------+--------------------------------------+
| id                         | 006f7e84-f957-4764-a3a7-db8575c54ba7 |
| name                       | my-flavor                            |
| os-flavor-access:is_public | False                                |
| ram                        | 512                                  |
| vcpus                      | 1                                    |
+----------------------------+--------------------------------------+

Creating a Virtual Machine

Now we’ll create a virtual machine and cleverly name it “server-1”:

openstack server create --wait --volume "f79c0d35-f54c-4b6a-82ad-1764e425eec8" --flavor "006f7e84-f957-4764-a3a7-db8575c54ba7" "server-1"

Note: If you have multiple subnets in a project, you’ll have to specify which subnet should be used when creating your virtual machine.

  openstack subnet list
+--------------------------------------+----------------+--------------------------------------+----------------+
| ID                                   | Name           | Network                              | Subnet         |
+--------------------------------------+----------------+--------------------------------------+----------------+
| aa5919fb-d683-4589-a093-f185d27e046a | 192.168.0.0/24 | a220c08e-a63f-48b8-aca5-563136ee9131 | 192.168.0.0/24 |
| ce86a3f2-fa64-4803-bb8e-7f9bfeb8db2e | 192.168.0.0/24 | afc24500-65f0-4d28-ada0-773d92820850 | 192.168.0.0/24 |
+--------------------------------------+----------------+--------------------------------------+----------------+
 
openstack server create --wait --volume "f79c0d35-f54c-4b6a-82ad-1764e425eec8" --flavor "006f7e84-f957-4764-a3a7-db8575c54ba7" --network a220c08e-a63f-48b8-aca5-563136ee9131 "server-1"

Conclusion

If you have any questions, please write them in the comments below.

If you’ve run into any problems using the library or want to change anything, you can open an issue.

Note: the current library version at the time of writing this article – 1.0.

Additional Resources:

python-selvpcclient library on github
VPC API documentation
Cloud access key

25 August 2017 Tags: ,

Popular articles