Open Telekom Cloud for Business Customers

Automating the Open Telekom Cloud with APIs

Using the “service console” web interface to quickly set up a virtual network, storage and VMs on your own is certainly a big step forward in terms of agility - especially if you previously had to order VMs or physical servers from your internal IT department.

But the fun really starts with the next step. Rather than manually setting up your virtual environment, you can automate that process, allowing you to close a gap on the way towards a fully automated CI/CD chain. When you need to change your environment, you apply a patch to your git repository and the automation takes care of deploying a new server or network. When your monitoring detects that your web application is overloaded, you just spin up more infrastructure (scale-out) and remove it again when not needed any longer (scale-in).

All of this is done via Application Programming Interfaces (APIs) that the cloud platform offers. Open Telekom Cloud (OTC) offers REST interfaces, where you transfer small pieces of JSON encoded data via https to some well-known URLs (API endpoints). You can program this yourself or use simple command line interface (CLI) tools that know how to talk to the APIs. You can use the CLI tools to support integration to other software systems like for example development and test and tools for IT automation like for example ansible, puppet or chef.

This post highlights what APIs and CLI tools are available in Open Telekom Cloud and how to use them. It assumes the reader is familiar with Open Telekom Cloud (from using its web interface) or has had exposure to other public cloud solutions.

Importance of APIs

Nowadays n-tier applications are distributed to several virtual machines when they run on a cloud platform. That requires you to configure dozens and often hundreds of platform resources. This is best done using a programming interface so the operation can be automated and manual processes and errors using a graphical interface can be avoided. The API offers a standardized way to setup n-tier applications for the cloud. APIs are the interface for cloud orchestration tooling frameworks to setup complex application clusters in a reproducible way.

Application Programming Interfaces (API)

The API uses encrypted http(s) and the REST-Protocol with a set of commands from categories listed in the table below. The API endpoints are separated by services.

Identity and Access Management (IAM)
Used to authenticate user and authorize API commands.
DNS-Name for region “eu-de” is iam.eu-de.otc.t-systems.com.

Elastic Compute Services (ECS)
Provides management of virtual compute machines, abbreviated to virtual machine (VM).
DNS-Name for region “eu-de” is ecs.eu-de.otc.t-systems.com.

Image Management (IMS)
Provides management of operating systems’ images. These are used to create VMs (ECS instances).
DNS-Name for region “eu-de” is ims.eu-de.otc.t-systems.com.

Elastic Volume Service (EVS)
Management of volumes that build the virtual hard disks of ECS instances. Also known as block storage.
DNS-Name for region “eu-de” is evs.eu-de.otc.t-systems.com.

Virtual Cloud Service (VPC)
Administration of the network that connects ECS instances to internal and public networks as well as managing port filtering.
DNS-Name for region “eu-de” is vpc.eu-de.otc.t-systems.com.

Volume Backup Service (VBS)
Management of backup from elastic volumes.
DNS-Name for region “eu-de” is vbs.eu-de.otc.t-systems.com.

Elastic Load Balancer (ELB)
Manage load balances instances such as session scheduling policies, application instance associations and monitoring.
DNS-Name for region “eu-de” is elb.eu-de.otc.t-systems.com.

Cloud Eye (CES)
Administer monitoring of ECS and EVS, such as selecting which resources to monitor and when to raise an alarm.
DNS-Name for region “eu-de” is ces.eu-de.otc.t-systems.com.

Auto Scaling (AS)
Manage auto-scaling of ECS instances using ECS groups and scaling policies.
DNS-Name for region “eu-de” is as.eu-de.otc.t-systems.com.

Supported HTTP Requests

GETThe GET method requests a representation of the specified resource.
PUTThe PUT method requests that the enclosed entity be stored under the supplied URI.
POSTThe POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI.
DELETEThe DELETE method deletes the specified resource, for example, an object.
PATCHThe PATCH method applies partial modifications to a resource. If the resource does not exist, the PATCH method creates a resource.

Table: Supported REST-Requests for API-Commands

API classes

Open Telekom Cloud 2.0 is based on FusionSphere 5.1, which itself is based on OpenStack Mitaka plus a number of backports from newer OpenStack releases and some enhancements from Huawei.

The API is exposed to the tenant users via a central API gateway, which multiplexes all API endpoints into the appropriate control nodes of the system. The Open Telekom Cloud currently exposes minimal keystone v3 functionality (authentication, token handling, service catalog), nova v2 (VM management), cinder v2 (block storage/volume management), glance v2 (image management) and somewhat limited neutron v2 (network management) functionality. The scope of native OpenStack API coverage is broad enough to cover the DefCore 2016.01 requirements, but is being worked on for further enhancements currently, especially in the networking space.

In addition to the OpenStack APIs, Open Telekom Cloud also exposes additional APIs; some of these enhance the native APIs while some others cover aspects that are currently not well covered by mature OpenStack APIs, such as e.g. the Elastic Load Balancer APIs.
The product specific Open Telekom Cloud tools (see below) use both the OpenStack APIs and the Open Telekom Cloud-specific APIs whereas the OpenStack CLI tools obviously only leverage the native APIs.

API documentation

The APIs for Open Telekom Cloud are well documented. You can find them in the help center. The APIs are structured per service and the documents notes whether they are OpenStack native or Open Telekom Cloud-specific APIs.
Furthermore, there is also a document solely covering OpenStack native APIs.

API documentation API information is available in the help centre

Command Line Interfaces (CLI) tools

Open Telekom Cloud’s CLI tools can be categorized into native OpenStack tools and Open Telekom Cloud-specific tools. The Open Telekom Cloud tools can offer broader (and sometimes more convenient) functionality than the pure native OpenStack tools. As T-Systems and Huawei work on exposing more native OpenStack APIs, that difference will become smaller over time for the current services. Also, the otc-tool strategy will focus on providing plugins into the python-openstackclient tool and, more precisely, on providing functionality that is not covered by native APIs, to avoid too much overlap.

Overview of native OpenStack tools and Open Telekom Cloud-specific tools An overview of native OpenStack tools and Open Telekom Cloud-specific tools

OpenStack CLI Clients

For the current Open Telekom Cloud version (02/2017), the recommended open source CLI tool version are as follows, one can download them from github (openstack.git) and use them unchanged or install them using python-pip. Currently, not all commands provided by the python clients are supported by Open Telekom Cloud. The specific commands are stated in the use cases described.

  • Compute (nova v2) - Nova: 2.22.0 – 2.23.3 (Kilo)
  • Images (glance v2) - Glance: 0.15.0 – 0.16.0 (0.17.x does not work, 1.1.0 does)
  • Block Storage (cinder v2) - Cinder: 1.1.1 – 1.3.1 (all versions tested worked)
  • Networking (neutron v2) - Neutron: 2.3.11/2.3.12 (newest versions fail)
  • IAM (keystone v3) - Keystone: 1.3.4 (only libs needed, client itself deprecated)
  • OpenStack: 1.0.4 – latest

A set of working OpenStack client tools as well as libs3 and the shell Open Telekom Cloud tools are included in the openSUSE-42.1 images that are provided in Open Telekom Cloud, so starting a VM with this image is probably the quickest way to get a working tool set.

Open Telekom Cloud CLI clients

The Open Telekom Cloud shell tool is a small shell script that provides commands to setup a VPC tenant such as creating an access token as well as configuring vCPUs, storage, elastic IP addresses (aka floating IP), security groups and so on. To use this script, one does not need the full OpenStack python clients deployed. To run it on a linux box one only needs

  • a bash interpreter
  • the curl tool to exchange https messages
  • the s3-tooling to work with the object storage (optional)
  • json query (jq) to handle the json data format used in the API HTTP-messages

The tool is simple enough to understand the mechanics of how to use the OpenStack and Open Telekom Cloud REST APIs. It is a good starting point for using the API via a CLI, but it can also be used to fill in functionality lacking in native tools. The code is open source and published on github, RPM/DEB packages are available on openSUSE Build Service in the home:garloff:OTC project.

The Object Storage solution in Open Telekom Cloud uses the S3 protocol natively and works with the large number of available s3 tools, such as e.g. libs3, s3cmd (both linux), cyberduck (Mac), S3Browser (Windows). Open Telekom Cloud does not currently support swift.

The Open Telekom Cloud python tool is constantly being enhanced to provide commands to manage Open Telekom Cloud-specific resources as well as OpenStack generic. The structure of the commands are of similar syntax and semantics as command line tools from other public cloud vendors like Amazon. The python client will have a lot smaller footprint (in terms of resource and dependencies) and thus be easier to handle for operators.

API authentication

To submit API calls, the user must authenticate against the system. Open Telekom Cloud provides two mechanisms to authenticate:

  • AK/SK: An access key (AK) and a secret key (SK) can be generated and used to authenticate API calls. This is the only authentication mechanism that works for object storage (s3) and can, if desired, also be used to talk to the REST APIs for compute, storage etc.
  • API password: Please note that this has changed as of January 2017. This is the normal OpenStack authentication scheme. The user sets an API password that, along with the username, is used to authenticate against keystone. Keystone will return an access token that can be used for the next 24hours to authenticate API calls (unless replaced by a newer token). The native OpenStack CLI tools as well as the Open Telekom Cloud tools support this way of working.

Set an initial API password

To set an initial API password, we will use the new IAM login located at https://console.otc.t-systems.com/ and select “Forgot Password?” (1) to start the recovery process. This is not exactly correct, but let’s put that aside for the moment.

Just enter the domain name (format is like “OTC00000000001xxxxxxxxx”) (2) and the e-mail address (3) or mobile number that is associated with your MyWorkplace account and press the “Next” button (4).

The following dialogue box asks you for the new password twice (5+6). For your own security, generate a strong password by, for example, using a password generator software of your choice. Before you can change the password you need to go through a verification process to ensure that you are the registered account owner and not some imposter who has gained access to the management console. Press the button “Get Code” (7) to receive a verification code via the e-mail address associated with this account. Before the code is send, you have to enter a CAPTCHA code to show you are human and not a bot (8+9). Check your e-mail for the code (10).

Enter the code in box “E-mail Verification Code” (11) and press “Next” (12) button to finish setting your API Password.

Password recovery process Select “Forgot Password?” to start the recovery process

Confirm Account Enter your domain name and email/mobile associated with your MyWorkplace account

Enter new passwort

Security check Enter the Captcha code

E-Mail verification A typical email verification code message

Set password Your API password is set

Changing API Password

To change the API password please navigate to the change dialogue box as shown below. You need to provide your old API password to apply a new one.

Changing API Password: My Credential Select a new, strong password


APIs for automation at Open Telekom Cloud

Using the API key

To use the API key method, you need to input

1. Your User Name

Look up your Username: Click the person with number (146…) on the right side of the page header and select MyCredential (see screenshot). Your Username has the following format: „14610698 OTC00000000001000000205”. Please notify the space to separate both user name parts.

2. Your API Password

Please create your API password as described before.

3. Your Domain Name

Your domain name is the second part of the user name, starting with “OTC”, in our example it is (without the quotes): „OTC00000000001000000205”.

4. The Project Name

This is „eu-de” (without the quotes) for the region currently available in Open Telekom Cloud (more are on the way :-)).

With these four pieces of input, you can use Open Telekom Cloud tools and OpenStack CLI tools to receive valid tokens from keystone and make use of their functionality (see next section).

If you want to create your own API tooling, the first thing you need to do is to request an access token via authenticating against the IAM-API. By default, the token stays valid for 24 hours. At anytime you can create a new access token, but we encourage everyone to reuse tokens to prevent high load for this API call only.

After a successful return, we should get:

  • Access Token, which starts with „MII…..”
  • The Project ID, which is „a90ddf531f934a9aac8acebf1abdf19a”

With both pieces of data we are ready to manage our tenant / OpenStack tenant with calls to the REST-APIs.

Here a snippet of the Request/Reply message using curl statement:

curl -i -H „Content-Type: application/json“ -d '
 {
  „auth“: {
   „identity“: {
    „methods“: [„password“],
    „password“: {
     „user“: {
      „domain“: { „name“: „Open Telekom Cloud00000000001000000205“ },
      „name“: „14610698 Open Telekom Cloud00000000001000000205“,
      „password“: „XXXXXX“
     }
    }
   },
   „scope“: {
    „project“: {
     „name“: „eu-de“
    }
   }
  }
 }' https://iam.eu-de.otc.t-systems.com/v3/auth/tokens
 HTTP/1.1 201 Created
 Server: nginx
 Date: Tue, 10 May 2016 20:51:14 GMT
 Content-Type: application/json;charset=UTF-8
 Transfer-Encoding: chunked
 Connection: keep-alive
 X-Subject-Token: MII....
 …
 {„token“:{„expires_at“:“2016-05-11T20:51:14.087000Z“,“issued_at“:“2016-05-10T20:51:14.087000Z“,“methods“:[„password“],“project“:{„name“:“eu-de“,“id“:“a90ddf531f934a9aac8acebf1abdf19a“,“domain“:{„name“:“Open Telekom Cloud00000000001000000205“,“id“:“167dd7366b734d789bdaf448050d7966“,“xdomain_type“:“TSI“,“xdomain_id“:“00000000001000000205“}},“user“:{„do.....

Open Telekom Cloud tools and OpenStack environment

The shell Open Telekom Cloud tools and the native OpenStack tools use the same environment variables to be configured. Put the following into a simple ~/.ostackrc or ~/novarc file:

$ cat .ostackrc
 export OS_PASSWORD=„XXXXX“
 export OS_USERNAME=„14610698 Open Telekom Cloud00000000001000000205“
 export OS_TENANT_NAME=eu-de
 export OS_PROJECT_NAME=eu-de
 export OS_USER_DOMAIN_NAME=„${OS_USERNAME##* }“
 export OS_AUTH_URL=https://iam.eu-de.otc.t-systems.com:443/v3
 export OS_PROJECT_DOMAIN_NAME=
 export OS_IDENTITY_API_VERSION=3
 export OS_VOLUME_API_VERSION=2
 export OS_IMAGE_API_VERSION=2
 export OS_ENDPOINT_TYPE=publicURL
 export NOVA_ENDPOINT_TYPE=publicURL
 export CINDER_ENDPOINT_TYPE=publicURL

The example uses some shell magic to extract the domain name from the username by cutting off the number before the white space. Note that the openSUSE42.1 public image contains the template above in ~/.ostackrc, so you only need to fill in username and password.

Using the Open Telekom Cloud Shell Tool to create your first server

To start, use a simple command to create a single ECS instance aka virtual machine server using the Open Telekom Cloud shell tool. Please note that the Open Telekom Cloud shell tool will automatically fetch an access token. You can watch this by using the command otc iam token. Just use otc without any arguments to get a short usage summary. But let’s create a VM now ...

$ otc ecs create \
 --wait --instance-type computev1-1 \
 --instance-name TEST_VM \
 --image-name Standard_openSUSE_42.1_JeOS_latest \
 --subnet-name subnet-32 --vpc-name vpc-32 \
 --security-group-name sg-ssh \
 --admin-pass „Cloud.4321“ \
 --key-name SSHkey-205a \
 --public false --disksize 6
 {
           „server“: {
            „availability_zone“: „eu-de-02“,
            „name“: „TEST_VM“,
            „imageRef“: „1cec66fa-036a-4192-835d-75f1568f2821“,
             „root_volume“: {
                    „volumetype“: „SATA“, „size“: „6“
             },
             „flavorRef“: „computev1-1“,
             „vpcid“: „b4690bfa-6d61-40b4-86b5-e8ab903ef11e“,
             „security_groups“: [ { „id“: „fa96c994-b43c-4793-b763-7b624e690511“ } ],
              „nics“: [ { „subnet_id“: „c095a6be-0d22-4393-8e46-05660e32da3f“ } ],
              „key_name“: „SSHkey-205a“,
              „adminPass“: „Cloud.4321“,
              „count“: „1“
             }
         }
 2c9eb2c15487316901549c98469a7e9e
 JOBID: https://ecs.eu-de.otc.t-systems.com/v1/a90ddf531f934a9aac8acebf1abdf19a/jobs/2c9eb2c15487316901549c98469a7e9e
 {„status“:“INIT“,“entities“:{},“job_id“:“2c9eb2c15487316901549c98469a7e9e“,“job_type“:“createServer“,“begin_time“:“2016-05-10T21:35:05.879Z“,“end_time“:“„,“error_code“:null,“fail_reason“:null}
 #{„status“:“RUNNING“,“entities“:{},“job_id“:“2c9eb2c15487316901549c98469a7e9e“,“job_type“:“createServer“,“begin_time“:“2016-05-10T21:35:05.879Z“,“end_time“:“„,“error_code“:null,“fail_reason“:null}
 #{„status“:“RUNNING“,“entities“:{„sub_jobs_total“:1,“sub_jobs“:[]},“job_id“:“2c9eb2c15487316901549c98469a7e9e“,“job_type“:“createServer“,“begin_time“:“2016-05-10T21:35:05.879Z“,“end_time“:“„,“error_code“:null,“fail_reason“:null}
 …
 #{„status“:“RUNNING“,“entities“:{„sub_jobs_total“:1,“sub_jobs“:[{„status“:“RUNNING“,“entities“:{},“job_id“:“2c9eb2c15487316901549c9864af7ea1“,“job_type“:“createSingleServer“,“begin_time“:“2016-05-10T21:35:13.583Z“,“end_time“:“„,“error_code“:null,“fail_reason“:null}]},“job_id“:“2c9eb2c15487316901549c98469a7e9e“,“job_type“:“createServer“,“begin_time“:“2016-05-10T21:35:05.879Z“,“end_time“:“„,“error_code“:null,“fail_reason“:null}
 #{„status“:“SUCCESS“,“entities“:{„sub_jobs_total“:1,“sub_jobs“:[{„status“:“SUCCESS“,“entities“:{„server_id“:“03df968c-72d5-40bf-8f7a-0ac2914c864b“},“job_id“:“2c9eb2c15487316901549c9864af7ea1“,“job_type“:“createSingleServer“,“begin_time“:“2016-05-10T21:35:13.583Z“,“end_time“:“2016-05-10T21:38:25.672Z“,“error_code“:null,“fail_reason“:null}]},“job_id“:“2c9eb2c15487316901549c98469a7e9e“,“job_type“:“createServer“,“begin_time“:“2016-05-10T21:35:05.879Z“,“end_time“:“2016-05-10T21:38:34.569Z“,“error_code“:null,“fail_reason“:null}
 #ECS Creation status: SUCCESS
 
 $ otc ecs list
 03df968c-72d5-40bf-8f7a-0ac2914c864b TEST_VM
 ... 


Ok, this is quite a lot of output but in essence it shows that a virtual machine can be created with one command (otc ecs create ...) using the exposed API. Furthermore, it shows that a command that runs longer will indicate in its status when it is initiated (status: “INIT”), running (status: “RUNNING”) and finally done (status: “SUCCESS”). Later we will discuss the options used in detail.

We can list the newly created virtual machine by submitting “otc ecs list” command from the shell.

For the command above to succeed, a VPC vpc-32 containing a subnet-32 in the availability-zone eu-de-02 had already been created, as well as the security-group sg-ssh and the SSH keypair SSHkey-205a. The creation of these can all be done using the Open Telekom Cloud tool or the web interface, as we will show in a later post.

Using OpenStack tools

Creating a VM using the native OpenStack client tools is slightly harder (three step process) and we will cover this operation in one of the next blogs about the API. For now, suffice to say that you can issue openstack server list or just nova list and see the VM created above.

Summary

Open Telekom Cloud offers its own CLI tooling as well as the vanilla python-clients from the OpenStack upstream project. The Open Telekom Cloud platform exposes encrypted APIs for different services – we looked at nine of them. In this example, we set up an Open Telekom Cloud project/tenant for authentication via the web console which is needed to submit commands to the API endpoints.

Resources

Open Telekom Cloud Documentation Center: https://docs.otc.t-systems.com/
OpenStack on github: https://github.com/openstack/openstack
otc-tools on github: https://github.com/OpenTelekomCloud/otc-tools


Book now and claim starting credit of EUR 250* (code: 4UOTC250)
24/7 Service
Take advantage of our consulting services!

Our experts will be happy to help you.

We will answer any questions you have regarding testing, booking and usage – free and tailored to your needs. Try it out today!

Hotline: 24 hours a day, seven days a week 

0800 33 04477 from Germany
00800 44 556 600 from abroad

* Voucher can be redeemed until June 30, 2019. Please contact us when using the voucher for booking. The discount is only valid for customers with a billing address in Germany and expires two months after conclusion of the contract. The credit is deducted according to the valid list prices as per the service description. Payment of the credit in cash is excluded.


  • Test it today – with no obligation and free of charge

    Book now and claim starting credit of EUR 250*
    Code: 4UOTC250

    Book now

  • Telefon

    Free expert hotline

    Our certified cloud experts provide you with personal service free of charge.

    0800 33 04477 (from Germany)

    24 hours a day, seven days a week

  • E-Mail

    Our customer service is available free of charge via E-Mail

    Write an E-Mail

  • Arrange an appointment

    Our Open Telekom Cloud experts provide you with free, non-binding and idividual support

    Arrange an appointment