.. DO NOT EDIT THIS FILE BK Cloud API · Documentation for Customers ========================================== Version 1.2, 2021-02-02 Introduction ------------ The BK Cloud API is a remote procedure call (RPC) mechanism available to customers of Bradler & Krantz. It enables the customers to create, manage and delete virtual servers in the BK Cloud datacenters. API procedures ('API functions') are implemented on top of the HTTPS protocol. The API Server URL is https://cloud-api.virtualhosts.de. Each API function call uses the HTTP POST method. Its message body consists of a sequence of named data elements: - ``username``: The API Key - ``password``: The API Password associated with the API Key - ``action``: The name of the API function - ``data``: The arguments to the API function Please use the BK Manager (customer portal) https://my.virtualhosts.de/cloud/apikey/ to activate/deactivate your API Key and also to set the API Password. The ``data`` item is expected as YAML encoded dictionary (map) of named arguments to the API function. The API Server responds with an ISO-8859-1 (latin1) encoded YAML marshaled dictionary containing the items - ``status`` having value ``success`` or ``failed``, - in case of failure ``error`` contains an error message in English language, and - a return value from the implementation of the API function. The tool ``cli-adm`` can be used to explore the Cloud API function from the linux command line. It can be downloaded from https://www.ultravps.eu/download/cli-adm A PHP implementation of the Cloud API client is available at https://www.ultravps.eu/download/bk.php.txt Concepts -------- Each virtual server runs on a host node. The host nodes are located in one of a bunch of datacenters. One or more datacenters form a **zone**. At the present time there are the following zones: ==== ======= =============================== zid zname location ---- ------- ------------------------------- 1 de-dus2 Düsseldorf, Germany, EU 2 nl-ams1 Amsterdam, The Netherlands, EU 3 us-lax1 Los Angeles, California, USA 4 us-dal1 Dallas, Texas, USA 5 uk-lon1 London, UK 6 lt-sqq Siauliai, Lithuania 7 md-kiv Chisinau, Moldovia ==== ======= =============================== Only Virtual servers within the same zone may communicate via a private network. The product plans available for reselling are named "**flavors**". Currently there are the following flavors: === =============== === =================== fid Flavor fid Flavor --- --------------- --- ------------------- 1 Cloud-30 16 Cloud-500 2 Cloud-50 21 Storage-500 3 Cloud-100 22 Storage-750 4 UltraKVM-15 23 Storage-1000 5 UltraKVM-30 24 Storage-Special 6 UltraKVM-50 25 Storage-2000 7 UltraKVM-75 26 Storage-5000 8 UltraKVM-100 27 Storage-10000 10 UltraKVM-200 28 Storage-7500 11 UltraKVM-250 29 Storage-Special-2 13 UltraKVM-500 30 LowEnd-1 14 Cloud-200 31 LowEnd-2 15 Cloud-300 === =============== === =================== When a vserver is going to be created or re-installed an initial operating system must be chosen. The following images are available ==== ============== =================================================================== iid symname iname ---- -------------- ------------------------------------------------------------------- 1 CENTOS-6 centos-6 20150811 linux 2015-08-11T13:37:40Z 2 CENTOS-7 centos-7 20150630 linux 2015-06-30T15:44:09Z 3 UBUNTU-15.04 ubuntu-certified-15.04 20150807 2015-08-08T04:06:41Z 4 UBUNTU-12.04 ubuntu-certified-12.04 20150709 linux 2015-07-09T02:44:19Z 5 DEBIAN-8 20150702 linux 2015-07-02T15:37:02Z 6 DEBIAN-7 20150702 linux 2015-07-02T15:34:37Z 7 FEDORA-22 fedora-22 20151015 linux 2015-10-15 8 UBUNTU-15.10 ubuntu-certified-15.10 20160315 linux 2016-03-15 9 UBUNTU-14.04 ubuntu-certified-14.04 20160314 linux 2016-03-14 10 UBUNTU-16.04 ubuntu-certified-16.04 20160922 11 CENTOS-7 centos-7 20170327 linux zvol 2017-03-27 ==== ============== =================================================================== API functions ('actions') ------------------------- * ``accounts_list`` Lists all accounts of the current customer. * ``actions_available`` Lists all available Cloud API functions. * ``bootimages_list`` Lists all available bootimages. * ``flavors_list`` Lists all available flavors (commonly known as 'plans' or 'products'). * ``images_list`` Lists all operating system images for vserver installation or reinstallation. * ``update_reverse_dns_name_of_ip4`` and ``update_reverse_dns_name_of_ip6`` Arguments: - ``address``: the address for which a PTR RR shall be registered in the DNS. - ``rdns``: The requested reverse name of the address * ``update_reverse_dns_name_of_primary_ip4`` Arguments: - ``vid``: vserver id whose primary IPv4 address shall get a new PTR RR. - ``rdns``: The requested reverse name. * ``vserver_add`` Arguments: - ``fid``: Flavor ID - ``zid``: Zone ID - *one of* ``iid`` *and* ``symname``: Image ID or Symbolic Name of the OS Image - ``hostname`` - ``rootpw`` - ``sshkeys`` *(optional)* - ``custom_script`` *(optional)*: Will be executed on the server after its first boot - ``motd`` *(optional)*: URL to load /etc/motd * ``vserver_change_hostname`` Arguments: - ``vid`` - ``hostname`` * ``vserver_delete``: Irrevocably removes the server and all its data from the BK Cloud. Arguments: *Variant 1*: - ``vid`` *Variant 2*: - ``cid``: Client ID - ``primaryip`` * ``vserver_increase_transfer_volume``: Increases the available transfer volume for the current month by 1 TiB (2⁴⁰ B = 1,099,511,627,776 B). Arguments: - ``vid`` * ``vserver_info`` Arguments: - ``vid`` * ``vserver_reboot`` Arguments: - ``vid`` - ``force_mode`` *(optional)* * ``vserver_reinstall`` Arguments: - ``vid`` - ``rootpw`` - ``sshkeys`` *(optional)* - ``iid`` - ``motd`` *(optional)*: URL to load /etc/motd * ``vserver_rescue``: Boots the Server into the rescue system. Arguments: - ``vid`` - ``force_mode`` *(optional)* - ``biid`` *(optional)* Boot Image ID (cf. ``bootimages_list``) * ``vserver_rootpassword`` Arguments: - ``vid`` - ``rootpw`` * ``vserver_shutdown`` Arguments: - ``vid`` - ``force_mode`` *(optional)* * ``vserver_vncinfo`` Returns the responsible vncproxy and credentials for WebVNC. Arguments: - ``vid`` * ``vservers_list``: Lists all vservers of the current customer. * ``zones_list`` Lists all Zones