[vpsFree.cz: community-list] haveapi-fs: připojte si API jako souborový systém

[Jakub Skokan]

Ahoj,

haveapi-fs [1] je virtuální souborový systém založený na FUSE [2], který
umožňuje připojit jakékoli API využívající HaveAPI [3], a pracovat s ním
na úrovni adresářů a souborů. Samozřejmě to funguje také s naším
api.vpsfree.cz [4,5].

Práce s haveapi-fs by měla být ještě jednodušší, než s konzolovým
klientem, protože je vše hned vidět jako adresáře a soubory, nemusíme
zjišťovat názvy objektů, akcí, parametrů, přepínačů, apod.

haveapi-fs je napsán v Ruby a instaluje se tak pomocí RubyGems:

  $ gem install haveapi-fs

API se připojí následujícím příkazem:

  $ haveapi-fs <api_url> <mountpoint>

tedy konkrétně naše API jako

  $ haveapi-fs https://api.vpsfree.cz /mnt/api.vpsfree.cz

Odpojení se provede buď přímo příkazem umount jako root, nebo
fusermount -u /mnt/api.vpsfree.cz jako neprivilegovaný uživatel.

Mountpoint obsahuje seznam objektů v API a soubory s nápovědou:

  $ cd /mnt/api.vpsfree.cz
  $ tree -L 1 .
  ├── ...
  ├── dataset/
  ├── environment/
  ├── location/
  ├── node/
  ├── vps/
  ├── help.html
  ├── help.man
  ├── help.md
  ├── help.txt
  └── ...

Soubory help.{html,man,md,txt} se nachází v každém adresáři a obsahují
vždy popis aktuálního adresáře, tzn. jaké má vlastnosti a jaké má
podadresáře a soubory.

V adresáři objektu je seznam všech jeho záznamů, tedy např. seznam všech
VPS patřících k účtu:

  $ tree -L 1 vps/
  vps
  ├── 1112/
  ├── 1171/
  ├── 1234/
  ├── 1245/
  ├── actions/
  ├── create.yml
  ├── help.html
  ├── help.man
  ├── help.md
  └── help.txt

Záznamy můžeme rovnou i filtrovat:

  $ tree -L 1 vps/by-node/103/by-os_template/26
  vps/by-node/103/by-os_template/26
  ├── 1112/
  └── ...

  $ cat vps/by-node/103/by-os_template/26/1112/node_id
  103

  $ cat vps/by-node/103/by-os_template/26/1112/os_template_id
  26

Podíváme-li se do adresáře nějakého konkrétního VPS, uvidíme seznam jeho
atributů jako soubory, asociované objekty jako adresáře a akce, které
můžeme volat, jsou v adresáři `actions/`:

  $ tree -L 1 vps/1112
  vps/1112
  ├── actions/
  ├── id
  ├── hostname
  ├── node/
  ├── os_template/
  ├── edit.yml
  ├── save
  └── ...

  $ cat vps/1112/hostname
  moje-vps

  $ cat vps/1112/node/domain_name
  node3.prg

  $ cat vps/1112/node/location/label
  Praha

  $ cat vps/1112/os_template/label
  Scientific Linux 6.6

Dle oprávnění lze vybrané atributy i měnit, např. změna hostname:

  $ echo novy-hostname > vps/1112/hostname
  $ echo 1 > vps/1112/save

Zavolat jde i jakákoli jiná akce:

  $ tree -L 1 vps/1112/actions
  vps/1112/actions
  ├── ...
  ├── passwd/
  ├── reinstall/
  ├── restart/
  ├── start/
  ├── stop/
  ├── swap_with/
  └── update/

  $ echo 1 > vps/1112/actions/passwd/exec

Informace o úspěchu či neúspěchu akce je vždy v souboru `status`:

  $ cat vps/1112/actions/passwd/status
  1

Výstupní parametry jsou pak v adresáři `output/`:

  $ cat vps/1112/actions/passwd/output/password
  cmrdBcm72KkAM85Ux2MK

Přes další soubory se lze dostat k případné chybové hlášce (`message`),
seznamu chyb (`errors/`) a také zadávat vstupní parametry (`input/`).

Akce lze vykonávat i pomocí `exec.yml` souboru, ve kterém se vyplní
vstupní parametry v YAMLu a po uložení a zavření souboru se akce vykoná.
Takto se dají jednoduše vytvářet nové objekty (`create.yml`) i upravovat
existující (`edit.yml`).

  $ vim vps/1112/edit.yml
  hostname: dalsi-zmena
  :wq

Kompletní popis toho, co haveapi-fs umí, je v README.md [6].

[1] https://github.com/vpsfreecz/haveapi-fs

[2] https://en.wikipedia.org/wiki/FUSE_%28Linux%29

[3] https://github.com/vpsfreecz/haveapi

[4] https://api.vpsfree.cz/

[5] https://kb.vpsfree.cz/navody/vps/api

[6] https://github.com/vpsfreecz/haveapi-fs#usage

Jakub