IDCF Cloud API Docs

ツール

IDCFクラウドを利用した開発および運用に利用可能なコマンドラインツールやSDKのドキュメントです。
ここでは、インストール方法や、利用方法をご紹介します。

コマンドラインツール

idcfcloud-cli

idcfcloud-cliは、IDCFクラウドなど各種サービスを管理するための統合ツールです。
APIの利用は自動化などに適し便利な一方、シグネチャの生成など利用までにひと手間かかります。簡単にAPIを実行するためにCLI(コマンドラインインターフェース)ツールであるidcfcloud-cliをご用意しています。

ここでは、インストールから使い方までご紹介します。

CLI対応サービス

idcfcloud-cliは現在以下のサービスに対応しています。

今後も対応サービス範囲を拡大していく予定です。
インストール
動作確認環境
  • CentOS 7.9, Ruby 3.0 (2024年以降は未対応の予定です)
  • Rocky Linux 8.6, Ruby 3.1
  • Rocky Linux 9.2, Ruby 3.1
  • Ubuntu Server 20.04, Ruby 2.7 (2024年以降は未対応の予定です)
  • Ubuntu Server 22.04, Ruby 3.0
Step1: 必要なパッケージのインストール

CentOS 7.9

                                                    # yum install centos-release-scl -y
~略~
# yum install rh-ruby30 rh-ruby30-ruby-devel gcc -y
~略~
# scl enable rh-ruby30 bash
                                                
再ログイン時など再度idcfcloud-cliを実行するときはsclコマンドによる有効化が必要です。

Rocky Linux 8.6, 9.2

                                                    # dnf module install ruby:3.1 -y
~略~
# dnf install ruby-devel gcc make -y
~略~
                                                

Ubuntu Server 20.04, 22.04

                                                    # apt update
~略~
# apt install ruby-dev gcc make -y
~略~
                                                
Step2: idcfcloud-cliのインストール

idcfcloud-cliはRubyGemsからネットワークインストールが可能です。

                                                    # gem install idcfcloud
~略~
~ gem installed
                                                

インストール確認

                                                    # idcfcloud help
Commands:
    idcfcloud compute [OPTION]  # Computeing Service
    idcfcloud configure         # create configure
    idcfcloud dns [OPTION]      # DNS Service
    idcfcloud help [COMMAND]    # Describe available commands or one specific c...
    idcfcloud ilb [OPTION]      # ILB Service
    idcfcloud init              # initialize
    idcfcloud update            # list update
    idcfcloud version           # version string
    idcfcloud your [OPTION]     # Your Service
                                                
使い方

はじめに初期設定でキーを設定します。
クラウドコンソール画面の「API」からAPI KeyとSecret Keyの情報を事前に確認してください。

                                                    # idcfcloud init
global[default]:api_key[NONE]
【API Keyを貼りつけてください】
global[default]:secret_key[NONE]
【Secret Keyを貼りつけてください】
global[default]:region(jp-east/jp-east-2/jp-east-3/jp-west)[NONE]
【デフォルト指定するリージョンを記述ください(jp-east/jp-east-2/jp-east-3/jp-west)】
global[default]:output_log(Y/n)[Y]
【エラーログを出力するか回答ください】
global[default]:log_path[~/.idcfcloud/log]
【エラーログを出力する場合はパスを指定ください】
Do you want to edit the startup script?(y/N)
【入力補完設定をシェル設定に書き込むか回答ください】
Run the following command:
source /var/lib/gems/2.3.0/gems/idcfcloud-1.0.0/output/complement.bash
                                                

キーの入力後にidcfcloud以降の引数(commandなど)をタブによる入力補完するシェル設定が出力されます。
たとえばBash環境であれば、~/.bash_profileにsource /(インストール先)/idcfcloud-cli/output/complement.bashを追記すると入力補完が利用できます。

この設定は必須ではありません。

以上で設定が完了しました。
APIキーの変更がない場合は、ここまでの設定は初回のみ実施します。

                                                    $ idcfcloud <servicename> <command> [attributes] [option]
                                                

各サービスにおいて対応しているコマンドの確認もhelpから可能です。
たとえばインフィニットLBの場合は次のように確認できます。

                                                    $ idcfcloud ilb help
Commands:
    idcfcloud ilb add_server <lb_id> <config_id> <data> [headers]
~以下略~
                                                
実行例(ビリング)

Billing APIhttps://www.idcf.jp/api-docs/apis/?id=docs_your_reference-v1_billingsを用いて、月次利用料金明細を出力します。
デフォルトでは、JSON形式で出力されます。

                                                    $ idcfcloud your list_billing_detail 2017-08
{
  "status": 200,
  "message": "",
  "data": {
  "meta": {
  "account_id": "71000000000",
  "taxable_amount": 342,
  "tax": 27,
  "total": 369,
  "updated_at": "2017-08-23T00:53:13+09:00",
  "billing_period_start_at": "2017-08-01",
  "billing_period_end_at": "2017-08-22",
  "invoice_no": null
},
~以下略~
                                                

-o tableを追加すると、テーブル形式で出力されます。

                                                    $ idcfcloud your list_billing_detail 2017-08 -o table
+-------+---------------+--------+----------------------+-------------------------------------+-------------------+----------+----------+-----+---------+-------+-------+------+---+---+
|Region |ServiceName    |ZoneName|Category              |Menu                                 |ResourceDisplayName|StartDate |EndDate   |Usage|Allocated|Running|Stopped|Amount|Tax|Net|
|jp-east|Cloud Computing|pascal  |VirtualMachine        |highcpu.M4                           |CLI                |2017-08-22|2017-08-22|24   |24       |24     |0      |326   |26 |352|
|jp-east|Cloud Computing|pascal  |Internet Data Transfer|Internet Data Transfer [out]         |                   |2017-08-22|2017-08-22|0.01 |0        |0      |0      |0     |0  |0  |
|jp-east|Cloud Computing|pascal  |Internet Data Transfer|Internet Data Transfer [in]          |                   |2017-08-22|2017-08-22|0.01 |0        |0      |0      |0     |0  |0  |
|jp-east|Cloud Computing|pascal  |Volume                |Volume/Root Disk                     |ROOT-206497        |2017-08-22|2017-08-22|360  |0        |0      |0      |14    |1  |15 |
|jp-east|Cloud Computing|pascal  |Archived Data         |Archive Storage - Template Data Usage|cli                |2017-08-22|2017-08-22|50.64|0        |0      |0      |2     |0  |2  |
+-------+---------------+--------+----------------------+-------------------------------------+-------------------+----------+----------+-----+---------+-------+-------+------+---+---+
                                                
実行例(コンピュート)

Compute APIhttps://www.idcf.jp/api-docs/apis/?id=docs_compute_referenceを用いて、停止している仮想マシンを起動します。

                                                    $ idcfcloud compute listVirtualMachines -o table -f name,id,state
+--------+------------------------------------+-------+
|name    |id                                  |state  |
|testvm-2|cafde9e8-3f15-453a-b268-b9f266423110|Stopped|
|testvm-1|020cf365-32c9-4b4e-bf5d-e2f706ad6906|Running|
+--------+------------------------------------+-------+
                                                

起動したい仮想マシンのidを取得し、対象のid指定します。

                                                    $ idcfcloud compute startVirtualMachine '{"id":"cafde9e8-3f15-453a-b268-b9f266423110"}'
{
  "status": 200,
  "message": "",
  "data": {
    "id": "cafde9e8-3f15-453a-b268-b9f266423110",
    "name": "testvm-2",
〜以下略〜
                                                
アップデート方法

すでにインストール済みの方は、idcfcloud-cliのgemにてアップデート可能です。

                                                    # gem update idcfcloud
# idcfcloud init
                                                

cloudstack-api

cloudstack-apiは、IDCFクラウドを管理するためのツールです。開発は終了していますので、後継のidcfcloud-cliをご利用ください。

インストール

コマンドラインツールはPythonで実装されており、GitHubで公開しています。Pythonのパッケージ管理ツールであるpipでインストールすることができます。ここでは、GitHubからソースをダウンロードして、pipでインストールする手順を記載します。

動作環境
  • CentOS Linux release 7.4.1708 (Core)
  • Ubuntu 16.04.2 LTS
  • Mac OS X 10.12.6 16G29
Step1: gitのインストール

gitを環境に合わせてインストールしてください。

すでにインストールされている場合はスキップしてください。

Mac OSX

                                                    $ sudo brew install git
                                                

Ubuntu

                                                    $ sudo apt-get update
$ sudo apt-get install git
                                                

CentOS

                                                    $ sudo yum update
$ sudo yum install git
                                                
Step2: pipのインストール

pipを環境に合わせてインストールしてください。

すでにインストールされている場合はスキップしてください。

Mac OSX

                                                    $ sudo brew install python
$ echo 'export PATH="../usr/local/opt/python/libexec/bin:$PATH"' >> ~/.bashrc
$ exec $SHELL -l
                                                

Ubuntu

                                                    $ sudo apt-get install python-pip
                                                

CentOS

                                                    $ curl -kL https://bootstrap.pypa.io/get-pip.py | sudo python
                                                
Step3: パッケージのインストール

Ubuntu・CentOSの場合、初期状態ではコンパイル環境が整っていないので、必要なパッケージをインストールします。

Ubuntu

                                                    $ sudo apt-get install gcc build-essential libxml2-dev libxslt1-dev python-dev
                                                

CentOS

                                                    $ sudo yum install libxml2 libxml2-devel libxslt libxslt-devel gcc python-devel
                                                
Step4: コマンドラインツールのインストール
                                                    $ sudo pip install git+https://github.com/idcf/cloudstack-api
$ cloudstack-api --version
cloudstack-api v0.10.2
                                                
使い方
Step1: API Key・Secret Key・エンドポイントの確認

IDCFクラウドにログインし、以下のリンクに記述されているAPI Key・Secret Key・コンピュートのエンドポイントを確認してください。
https://console.idcfcloud.com/user/apikey

Step2: 環境設定

ホームディレクトリに.idcfrcファイルを作成し、Step1で取得したAPI Key・Secret Key・エンドポイントの情報を設定します。

                                                    $ cat ~/.idcfrc
[account]
host=${end_point}
api_key=${API Key}
secret_key=${Secret Key}
                                                
Step3: 動作確認

正しく設定された場合は、以下のように表示されます。

                                                    $ cloudstack-api listZones
{
    "listzonesresponse": {
        "count": 1,
        "zone": [
            {
                "allocationstate": "Enabled",
                "dhcpprovider": "VirtualRouter",
                "id": "a117e75f-d02e-4074-806d-889c61261394",
                "localstorageenabled": false,
                "name": "tesla",
                "networktype": "Advanced",
                "securitygroupsenabled": false,
                "tags": [],
                "zonetoken": "bbbd8944-a3c5-3538-8a2a-71d93a788ab5"
            }
        ]
    }
}
                                                
Step4: command syntax
                                                    $ cloudstack-api ${method_name} --${option_name} ${option_value}
                                                

method一覧,option一覧の確認方法は以下のとおりです。

                                                    $ cloudstack-api --help # メソッド一覧
$ cloudstack-api ${method_name} --help # オプション一覧
                                                
Step5: 仮想マシン作成

コマンドラインツールを利用して仮想マシンを作成する手順を記載します。仮想マシンはdeployVirtualMachine methodで作成できます。
deployVirtualMachineには

  • zone
  • serviceOffering
  • template

が必要です。上記のパラメータの取得方法も合わせて記述します。

Step5-1: zoneの確認

                                                    $ cloudstack-api listZones -t id,name
+--------------------------------------+--------+
|                  id                  |  name  |
+--------------------------------------+--------+
| 01738d49-2722-4788-891e-848536663c6e | newton |
| 9703cdbb-aee7-41ba-ba80-4807eaa68b80 | henry  |
| a117e75f-d02e-4074-806d-889c61261394 | tesla  |
| a53ff3d3-042b-4cbd-ad16-494bb8d33e06 | radian |
| baf86a6e-4e3b-428e-8fd0-7fda43e468d4 | joule  |
| f0954b9b-2626-4549-82ad-ca421073b3bc | pascal |
+--------------------------------------+--------+
                                                
-tを付けることで表として出力します。(付けなければJSONとして出力されます。)
さらに-tの後にカラムを指定することで、カラムのみを表示することができます。

Step5-2: serviceOfferingの確認

serviceOfferingは性能値を表します。

                                                    $ cloudstack-api listServiceOfferings -t id,name,displaytext
+--------------------------------------+------------------+--------------------------------------------------+
|                  id                  |       name       |                   displaytext                    |
+--------------------------------------+------------------+--------------------------------------------------+
| 1bb11a77-0db9-477c-9950-51a2aad3e31b | standard.S8      | 1 CPU x 2.4 GHz / 8 GB RAM                       |
| 2504abf9-5db6-45a4-bf58-aea02731010a | light.S2         | 1 CPU x 1.6 GHz / 2 GB RAM                       |
| 36806a68-0167-4b22-a684-26ac333851ab | standard.XL32    | 8 CPU x 2.4 GHz / 32 GB RAM                      |
| 44975cf0-8ff5-422b-a053-e952c551b9d4 | highcpu.L8       | 4 CPU x 2.6 GHz / 8 GB RAM                       |
| 5e5698a3-8161-4f17-913e-b992d9b91202 | highmem.L32      | 4 CPU x 2.2 GHz / 32 GB RAM                      |
| a1edf3c2-41d0-45fa-8f93-a9280e2e3988 | highcpu.XL16     | 8 CPU x 2.6 GHz / 16 GB RAM                      |
| a7cec7ff-86d1-4ba7-864b-8db262c958d6 | highmem.XL64     | 8 CPU x 2.2 GHz / 64 GB RAM                      |
| b851997e-1c80-429c-9739-390e0a564989 | light.S1         | 1 CPU x 0.8 GHz / 1 GB RAM                       |
| b967c042-e35a-4cd8-b5a6-8c4894ccc5e6 | highmem.M16      | 2 CPU x 2.2 GHz / 16 GB RAM                      |
| ca9b1c35-1748-41d4-8876-ddd3d51f6a63 | standard.L16     | 4 CPU x 2.4 GHz / 16 GB RAM                      |
| cbb51fe7-092b-4642-83a7-258c65683cd2 | highcpu.2XL32    | 16 CPU x 2.6 GHz / 32 GB RAM                     |
| d843fa4d-ee1e-4742-8ad0-7dd86c493a18 | standard.M8      | 2 CPU x 2.4 GHz / 8 GB RAM                       |
| e9a38771-7569-4d7b-a3f9-5445edb5e423 | standard.S4      | 1 CPU x 2.4 GHz / 4 GB RAM                       |
| eafb4a53-3212-4b8e-af29-2fbe9094ac95 | highcpu.M4       | 2 CPU x 2.6 GHz / 4 GB RAM                       |
| ed444cb7-a06e-49f2-bd39-8b2f125789ad | highio.3XL128    | 24 CPU x 2.5 GHz / 128 GB RAM - Dedicated HighIO |
| ef3d51af-f8fe-473a-ad1f-3681c4a62e61 | highio.5XL128.g2 | 40 CPU x 2.6 GHz / 128 GB RAM - Dedicated HighIO |
+--------------------------------------+------------------+--------------------------------------------------+
                                                

Step5-3: テンプレートの確認

                                                    $ cloudstack-api listTemplates --templatefilter featured -t id,name,zonename
+--------------------------------------+----------------------------------------------------------------------+----------+
|                  id                  |                                 name                                 | zonename |
+--------------------------------------+----------------------------------------------------------------------+----------+
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | henry    |
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | joule    |
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | newton   |
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | pascal   |
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | radian   |
| 7c19c667-5627-4ebd-a1a7-ea0980a9e0cb | CentOS 7.3 64-bit                                                    | tesla    |
+--------------------------------------+----------------------------------------------------------------------+----------+
                                                

Step5-4:秘密鍵の名前(オプション)

                                                    $ cloudstack-api listSSHKeyPairs -t name
+----------+
|   name   |
+----------+
| hogehoge |
+----------+
                                                

Step5-5:仮想マシン作成

                                                    $ cloudstack-api deployVirtualMachine \
> --serviceofferingid e01a9f32-55c4-4c0d-9b7c-d49a3ccfd3f6 \
> --templateid fdddd391-ef26-47a2-a5d2-a2e355cb0c69 \
> --zoneid baf86a6e-4e3b-428e-8fd0-7fda43e468d4 \
> --group idcf \
> --keypair hogehoge \
> --name idcf
                                                

Step5-6:起動確認

以下のようにStep5-5で指定した仮想マシンがRunning状態となっていれば問題ありません。

                                                    $ cloudstack-api listVirtualMachines -t id,name,group,state
+--------------------------------------+------+-------+---------+
|                  id                  | name | group |  state  |
+--------------------------------------+------+-------+---------+
| a67bf3e0-51f0-43a8-8b8e-bff40f7e49cb | idcf | idcf  | Running |
+--------------------------------------+------+-------+---------+
                                                

SDK

Ruby

Ruby用の開発者向けライブラリです。インフィニットLBとDNS/GSLBに対応しています。

Ruby対応サービス

Ruby のSDKは以下のサービスに対応しています。