Skip to content
Hands-on IT IT Drills

Day 13: API and Automation

Goal: Talk to OpenNebula directly through its APIs: XML-RPC from Python without extra packages and the OneFlow REST API with curl. · Duration: approx. 60 min · Prerequisite: Day 9

Briefing

  • Everything in OpenNebula goes through an XML-RPC API on port 2633: CLI, Sunstone, OpenTofu. Every call is named one.<objekt>.<aktion>, such as one.vm.info or one.vmpool.info, and gets the session "benutzer:passwort" as its first argument.
  • Every response is a list: [Erfolg, Ergebnis oder Fehlermeldung, Fehlercode, …]. Objects come as XML text.
  • OneFlow has its own REST API with JSON on port 2474.
  • Python ships with an XML-RPC client (xmlrpc.client). The pyone library from the OpenNebula project does the same more conveniently, but it is not required.
 vms.py ──► XML-RPC :2633/RPC2 ──► oned
 curl   ──► REST    :2474/service ──► OneFlow ──► XML-RPC ──► oned

Drill 1: The first call

mkdir -p ~/one-lab/tag13
cd ~/one-lab/tag13
python3 -c 'import xmlrpc.client; print(xmlrpc.client.ServerProxy("http://localhost:2633/RPC2").one.system.version("oneadmin:lab-one-pass-123"))'

Expected:

[True, '7.4.1', 0]

The same with a wrong password:

python3 -c 'import xmlrpc.client; print(xmlrpc.client.ServerProxy("http://localhost:2633/RPC2").one.system.version("oneadmin:falsch"))'

Expected:

[False, "[one.system.version] User couldn't be authenticated, aborting call.", 256, -1, -1]

Not a Python error, but False and a code. A script must therefore always check the first element.

Save your progress? Sign up for free

Drill 2: All VMs

cat > vms.py <<'EOF'
#!/usr/bin/env python3
"""Listet alle VMs über die XML-RPC-API von OpenNebula."""
import xml.etree.ElementTree as ET
import xmlrpc.client

SESSION = "oneadmin:lab-one-pass-123"
one = xmlrpc.client.ServerProxy("http://localhost:2633/RPC2")

ok, body, code = one.one.vmpool.info(SESSION, -2, -1, -1, -1)[:3]
if not ok:
    raise SystemExit(f"Fehler {code}: {body}")
for vm in ET.fromstring(body).findall("VM"):
    ip = vm.findtext("TEMPLATE/NIC/IP", default="-")
    print(vm.findtext("ID"), vm.findtext("NAME"), vm.findtext("STATE"), ip)
EOF
python3 vms.py

Expected (IDs and IPs will differ):

30 api_0_(service_3) 3 192.168.150.33
29 db_0_(service_3) 3 192.168.150.32
Argument of vmpool.info Meaning
-2 all VMs the session may see
-1, -1 ID range from … to, -1 means no limit
-1 all states except DONE

STATE comes as a number: 3 is ACTIVE. The mapping is in the API documentation. TEMPLATE/NIC/IP is an XPath expression; it takes the first NIC.

Save your progress? Sign up for free

Drill 3: Writing

A script that attaches an attribute to a VM, for example who it belongs to:

cat > markieren.py <<'EOF'
#!/usr/bin/env python3
"""Schreibt ein Attribut in das USER_TEMPLATE einer VM."""
import sys
import xmlrpc.client

SESSION = "oneadmin:lab-one-pass-123"
one = xmlrpc.client.ServerProxy("http://localhost:2633/RPC2")

vm_id, wert = int(sys.argv[1]), sys.argv[2]
ok, body, code = one.one.vm.update(SESSION, vm_id, f"BESITZER=\"{wert}\"", 1)[:3]
print("ok" if ok else f"Fehler {code}: {body}")
EOF
python3 markieren.py 30 "Team Blau"
onevm show 30 | grep BESITZER

Expected (use the ID of your API VM):

ok
BESITZER="Team Blau"

The 1 at the end means merge: the attribute is added, everything else stays. With 0, the text would replace the entire USER_TEMPLATE.

python3 markieren.py 9999 x

Expected:

Fehler 1024: [one.vm.update] Error getting virtual machine [9999].

Save your progress? Sign up for free

Drill 4: OneFlow via REST

curl -s -u oneadmin:lab-one-pass-123 http://localhost:2474/service \
  | jq -r '.DOCUMENT_POOL.DOCUMENT[] | [.ID, .NAME, .TEMPLATE.BODY.state] | @tsv'

Expected:

3   notes-service   2

State 2 is RUNNING. Scaling works with a POST to /service/<ID>/scale:

curl -s -u oneadmin:lab-one-pass-123 -X POST http://localhost:2474/service/3/scale \
  -H "Content-Type: application/json" \
  -d '{"role_name": "api", "cardinality": 2, "force": false}'
oneflow show 3 | sed -n '/ROLE api/,/NODES/p' | grep -E 'STATE|CARD'

Expected (shortly afterwards):

ROLE STATE          : SCALING
CARDINALITY         : 2

On success, the API responds without any text. A wrong path, on the other hand, returns an HTML page “Sinatra doesn’t know this ditty”, the error page of the Ruby framework behind OneFlow.

Save your progress? Sign up for free

Checkpoint

python3 vms.py | wc -l

Expected: 3, the database and two API VMs.

diff ~/one-lab/tag13/markieren.py ~/one-lab/code/loesung/tag13/markieren.py

Expected: no output.

Challenge

Extend vms.py so that for each VM it also prints the attribute BESITZER if it is set, otherwise -.

Note: onevm show shows that BESITZER is in the USER_TEMPLATE, not in the TEMPLATE.

Solution

The first attempt, just extending the output, shows - everywhere, even for the marked VM. For speed reasons, vmpool.info only returns an excerpt of each template. The full USER_TEMPLATE is available with vmpool.infoextended, with the same arguments:

sed -i 's/one.one.vmpool.info(/one.one.vmpool.infoextended(/' vms.py
head -n -1 vms.py > neu.py
cat >> neu.py <<'EOF'
    owner = vm.findtext("USER_TEMPLATE/BESITZER", default="-")
    print(vm.findtext("ID"), vm.findtext("NAME"), vm.findtext("STATE"), ip, owner)
EOF
mv neu.py vms.py
python3 vms.py

Expected:

43 api_1_(service_3) 3 192.168.150.46 -
30 api_0_(service_3) 3 192.168.150.33 Team Blau
29 db_0_(service_3) 3 192.168.150.32 -

head -n -1 drops the last line, and the new print line replaces it. For large clouds, infoextended is considerably slower. If you only need names and states, stick with info.

Save your progress? Sign up for free

Enterprise Note

  • pyone and goca: For larger tools there are official libraries, pyone for Python and goca for Go. They translate XML into objects and know all calls.
  • Tokens instead of passwords: Scripts get their own user with a login token (oneuser token-create --time 86400). If the token expires or is revoked, only the script is affected.
  • Secure the API: Ports 2633 and 2474 listen on all addresses in the lab. In production, they sit behind a TLS proxy, and only management networks can reach them.