ConoHa API を利用してサーバーを再起動するシェルスクリプトを書く

VPS である ConoHa には、API が用意されています。Web のプロトコルである HTTPS (TLS/SSL) を使って、特定のサーバーに命令を送ることで、いろいろな操作を行うことができるのです。

このページでは、APIを使った簡単なシェルスクリプトを書き、ConoHa に立てたサーバーを再起動する方法について説明します。

注意：このページでは、シェルスクリプトの文法などについて説明していません。

1. ConoHa API について
2. ConoHa API を使うための準備
3. 必要な情報を整理
4. サーバーを再起動するシェルスクリプトを作成する
5. シェルスクリプトを実行する
6. おわりに
7. 参考

1. ConoHa API について

OpenStack

OpenStack は、簡単に言ってしまうとクラウドや VPS のようなサービスを構築できるソフトウェアです。仮想マシンを複数生成して管理することができます。

ConoHa は、この OpenStack を使って構築されているサービスです。

OpenStack API

OpenStack には、HTTP(S)プロトコルを使って利用することができる API が用意されています。Web で使われているのと同じプロトコルで、サーバーに命令を送れば（やりとりすれば）、各種操作を実行することができるのです。

API を利用したプログラムを書けば、仮想マシンの操作や周辺の設定などを自動化することができます。管理画面を開いてあれこれ手動で操作する必要がなくなります。

ConoHa API

ConoHa では、OpenStack準拠のAPIを公開しています（ConoHa API）。

ConoHa API のドキュメントは、「ConoHa API Documentation」にあります。

ConoHa API (OpenStack API もそうですが) は、

○○というURLに、△△ というパラメータを送ると、□□ という操作ができる

といった決まりの集合体なので、この動作さえ実現できるのであれば、どんなプログラミング言語を使っても構いません。

本ページでは、シェルスクリプト (Bash) を使います。

2. ConoHa API を使うための準備

ConoHa API を使うには、APIユーザーが必要です。

まだ作成していない場合は、ConoHa の管理パネルで、APIユーザーを作成します。

手順

(1) ConoHa のウェブサイトにログインします。

(2) 管理パネルの [API]メニュー – [+ ユーザー]ボタンをクリックします。

(3) パスワードを入力して、[保存] ボタンを押します。

(4) APIユーザーが作成されました。

ユーザー名は自動で設定されます。

※ 1つのConoHaアカウントで作成できるAPIユーザーは最大1ユーザーのようです。

3. 必要な情報を整理

今回必要になる情報は以下になります。

テナントID
エンドポイントとなる各種URL
APIユーザーのユーザー名
APIユーザーのパスワード
操作対象となるサーバーのUUID (オプション)

テナントID

テナントID は、管理パネル – [API]メニュー – [テナント情報] のところにあります（下のスクリーンショット参照。）。

エンドポイントとなる各種URL

「エンドポイントとなる各種URL」は、同画面 [テナント情報] の下にある [エンドポイント] にあります。操作（処理）の種類によって使うURLが違います。今回必要になるのは、トークンを取得するための処理に使う「Identity Service（）」と、仮想マシンの操作のための「Compute Service（）」の２つです。リージョンは「東京」でよいでしょう。

APIユーザーのユーザー名

APIユーザーのユーザー名は、同画面の下に表示されています。パスワードは先程APIユーザーを作成した時に入力したパスワードです。

操作対象となるサーバーのUUID (オプション)

サーバーに対して何か処理を行う API は、そのサーバーの UUID をパラメータとして指定する必要があります。この UUID 自体も API を使って取得することができますが、今回は、管理パネル上に載っている UUID をメモしてシェルスクリプト内で使用します。

サーバーのUUIDが載っている箇所

管理パネルサイト – [サーバー] – [サーバーリスト]画面において、操作対象となるサーバーの「ネームタグ」列にあるリンクをクリックします。

[VPS設定] の中に「UUID」があります。

4. サーバーを再起動するシェルスクリプトを作成する

1. 今回想定する環境

クライアント側のOSは、Linux を想定しています。この Linux は、パソコンにそのままインストールしたものでもよいですし、Windows の WSL (Windows Subsystem for Linux) を使ってインストールしたものでもよいです。

2. 準備作業

jq をインストールします。

jq は、JSONフォーマットの文字列を操作するツールです。ConoHa API では、JSON形式でデータをやり取りすることが多いので使用します。

(a) Debian/Ubuntu 系の Linuxディストリビューションの場合

$ sudo apt install jq

(b) CentOS など、RedHat系の Linuxディストリビューションの場合

$ sudo yum install jq

では、シェルスクリプトを書いていきます。

3. シェルスクリプト全体

今回のシェルスクリプトは以下になります。

※ スタートアップスクリプト｜VPSならConoHa にあったスクリプトを参考にしました。

#!/bin/bash

set -eu

readonly API_TENANT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # テナントID
readonly API_USERNAME="yyyyyyyyyyyy" # APIユーザー名
readonly API_PASSWORD="zzzzzzzzzzzzzzzzzzzz" # APIパスワード
readonly SERVER_UUID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # サーバーのUUID
readonly URL_END_POINT_IDENTITY="https://identity.tyo1.conoha.io/v2.0" # エンドポイント: Identity Service
readonly URL_END_POINT_COMPUTE="https://compute.tyo1.conoha.io/v2/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # エンドポイント: Compute Service


#-------------------------------------------
echo "(1) トークン発行 - Identity API v2.0"
# ref. https://www.conoha.jp/docs/identity-post_tokens.html
#-------------------------------------------
REQUEST_TOKEN_BODY="{\"auth\":{\"passwordCredentials\":{\"username\":\"${API_USERNAME}\",\"password\":\"${API_PASSWORD}\"},\"tenantId\":\"${API_TENANT_ID}\"}}" \

RESPONSE_TOKEN=$( curl -s -X POST \
     -H "Accept: application/json" \
     -d "${REQUEST_TOKEN_BODY}" \
     ${URL_END_POINT_IDENTITY}/tokens )

API_TOKEN=""
API_EXPIRES=""

#echo "${RESPONSE_TOKEN}" | jq '.'

API_TOKEN=$(echo "${RESPONSE_TOKEN}" | jq -r '.access.token.id')
API_EXPIRES=$(echo "${RESPONSE_TOKEN}" | jq -r '.access.token.expires')

echo "API_TOKEN   = $API_TOKEN"
echo "API_EXPIRES = $API_EXPIRES"

if [ "${API_TOKEN}" = "null" ]; then
    echo "トークンの取得に失敗しました。"
    exit 1
fi


#----------------------------------------
echo -e "\n(2) VM再起動 - Compute API v2"
# ref. https://www.conoha.jp/docs/compute-reboot_vm.html
#----------------------------------------
RESPONSE_REBOOT=$( curl -i -s -X POST \
  -H "Accept: application/json" \
  -H "X-Auth-Token: ${API_TOKEN}" \
  -d '{"reboot": {"type": "SOFT"}}' \
  ${URL_END_POINT_COMPUTE}/servers/${SERVER_UUID}/action )

HTTP_STATUS=$(echo "$RESPONSE_REBOOT" | head -n1 | cut -d ' ' -f2- | tr -d "\r\n")

if [ "${HTTP_STATUS}" = "202 Accepted" ]; then
    echo "再起動に成功しました！"
    exit 0
else
    echo "再起動に失敗しました。"
    echo "HTTP_STATUS = ${HTTP_STATUS}"
    exit 1
fi

各処理についてざっと説明します。

1. 設定値を変数にセットする

管理パネルから得た各情報をここにセットします。

readonly API_TENANT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # テナントID
readonly API_USERNAME="yyyyyyyyyyyy" # APIユーザー名
readonly API_PASSWORD="zzzzzzzzzzzzzzzzzzzz" # APIパスワード
readonly SERVER_UUID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # サーバーのUUID
readonly URL_END_POINT_IDENTITY="https://identity.tyo1.conoha.io/v2.0" # エンドポイント: Identity Service
readonly URL_END_POINT_COMPUTE="https://compute.tyo1.conoha.io/v2/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # エンドポイント: Compute Service

2. ConoHa APIを使用するためのトークンを取得する処理

この後、サーバーを再起動させる処理 (API) では、ConoHa 側から発行してもらったトークンと呼ばれる値をパラメータとしてセットして送る必要があります。ここでそのトークンを取得しておきます。

このトークンを取得する処理も１つの API になっており、公式ドキュメントにおける「トークン発行 – Identity API v2.0 / ConoHa API」というのがこれに当たります。

Request URL ()

タイトルのところにもありますが、「identity API v2.0 とあるので、エンドポイントは「Identity Service」を使うことが分かります。
「POST」とあるので、HTTP(S)通信する際のメソッドが POST であることが分かります。
「/v2.0/tokens」とあるのは、エンドポイント「Identity Service」のURLの末尾に追加する文字列です。

Request Parameters ()

パラメータが3つありますが、Style が “plain” になっており、これは Request Json () に書いてある通りにセットすればよいです。

Request Json ()

POSTメソッドでは「メッセージボディ」と呼ばれる部分にテキストを付けて送信することができるのですが、ConoHa API ではここに書いてあるように、JSON というフォーマットでパラメータを記述して送信します。JSON は、ここにあるように、「項目名」と「その値」をコロンで連結し、それをカンマで区切って並べたり、括弧で階層構造にしてデータを表現するフォーマットです。

また、Example のところを見ると、実際の HTTP(S)通信でやり取りされる内容が書いてあります。

サーバーから返ってくるレスポンスのメッセージボディには、JSON形式でデータが入っていることが分かります。この JSONデータの中から必要な値を上手く取得しなければならないです。そのために、jq コマンドを最初にインストールしておきました。

以上、ドキュメントの説明から、トークンを取得する API を利用するための「URL」「メソッド」「パラメータ」「フォーマット」などは分かりました。

この内容に沿って HTTP(S)のリクエストを送信することができるのであれば、どんなツールを使って通信を行うかは自由です。

今回は、Example にも使用されていた curl というコマンドを使うことにします（参照：curl）。curl は、手軽に HTTP(S)通信ができるコマンドで、世界中でよく使われています。

このドキュメント通りの動きをシェルスクリプトで実装したのが、以下の部分です。

#-------------------------------------------
echo "(1) トークン発行 - Identity API v2.0"
# ref. https://www.conoha.jp/docs/identity-post_tokens.html
#-------------------------------------------
REQUEST_TOKEN_BODY="{\"auth\":{\"passwordCredentials\":{\"username\":\"${API_USERNAME}\",\"password\":\"${API_PASSWORD}\"},\"tenantId\":\"${API_TENANT_ID}\"}}" \

RESPONSE_TOKEN=$( curl -s -X POST \
     -H "Accept: application/json" \
     -d "${REQUEST_TOKEN_BODY}" \
     ${URL_END_POINT_IDENTITY}/tokens )

API_TOKEN=""
API_EXPIRES=""

#echo "${RESPONSE_TOKEN}" | jq '.'

API_TOKEN=$(echo "${RESPONSE_TOKEN}" | jq -r '.access.token.id')
API_EXPIRES=$(echo "${RESPONSE_TOKEN}" | jq -r '.access.token.expires')

echo "API_TOKEN   = $API_TOKEN"
echo "API_EXPIRES = $API_EXPIRES"

if [ "${API_TOKEN}" = "null" ]; then
    echo "トークンの取得に失敗しました。"
    exit 1
fi

大雑把ですが、以下のようなことをやっています。

curl コマンドで HTTP(S)リクエストを送信する。
返ってきたレスポンスの中から、jq コマンドを使って必要なトークンを取り出す。
- ついでに、トークンの利用期限も取得しています。
トークンが取得できたかチェックし、失敗していたらそこで処理を終了する。

レスポンスに含まれている JSONデータ内のどこにトークンが含まれているかは、スタートアップスクリプト｜VPSならConoHa の「Let’s Encryptインストール」用スタートアップスクリプトと、APIを使用するためのトークンを取得する｜VPSならConoHa を参考にしました。

3. 仮想マシンを再起動する処理

こちらで使っている API は、「VM再起動 – Compute API v2 / ConoHa API」です。

先ほどと同じ要領でドキュメントを読み解いていきます。

今回は、1つ目の API で取得したトークンをパラメータ(X-Auth-Token)としてセットしています。

また、問題がなければ、202 という response code (HTTP Status code) が返ってくると書いてあったので、この部分をチェックする処理を入れました（参考：HTTPステータスコード – Wikipedia）。

このドキュメント通り + 独自のチェック処理を実装したのが、以下の部分です。

#----------------------------------------
echo -e "\n(2) VM再起動 - Compute API v2"
# ref. https://www.conoha.jp/docs/compute-reboot_vm.html
#----------------------------------------
RESPONSE_REBOOT=$( curl -i -s -X POST \
  -H "Accept: application/json" \
  -H "X-Auth-Token: ${API_TOKEN}" \
  -d '{"reboot": {"type": "SOFT"}}' \
  ${URL_END_POINT_COMPUTE}/servers/${SERVER_UUID}/action )

HTTP_STATUS=$(echo "$RESPONSE_REBOOT" | head -n1 | cut -d ' ' -f2- | tr -d "\r\n")

if [ "${HTTP_STATUS}" = "202 Accepted" ]; then
    echo "再起動に成功しました！"
    exit 0
else
    echo "再起動に失敗しました。"
    echo "HTTP_STATUS = ${HTTP_STATUS}"
    exit 1
fi

5. シェルスクリプトを実行する

まず、サーバーがどれくらい起動したままになっているかを、以下のコマンドで調べておきます。ssh コマンドを使います。

$ ssh -p ポート番号 ユーザー名@ホスト名  uptime

これは、サーバー上で uptime というコマンドだけ実行してすぐに終了するコマンドです。

実際に実行するとこんな感じになります。

$ ssh -p ポート番号 ユーザー名@ホスト名  uptime
23:30:37 up 21:23, 0 users, load average: 0.00, 0.01, 0.05

この場合であれば、「21時間23分」連続稼働していることを示しています。

では次に、今回のシェルスクリプトを reboot.sh などといった名前で保存して、実行してみましょう。

$ chmod u+x reboot.sh
$ ./reboot.sh

成功したでしょうか？

成功したのであれば、少し待ってから、もう一度 uptime を実行します。

$ ssh -p ポート番号 ユーザー名@ホスト名  uptime
23:41:65 up 0 min, 0 users, load average: 0.37, 0.08, 0.03

「0 min」ということで、1分以下しか連続稼働していない、つまり先程再起動したことが分かります。

6. おわりに

OpenStack API や ConoHa API といった API は、今回のように「ただ再起動する」ためにあるわけではなく、本来はもっと複雑な仮想マシンの管理操作を自動化するのが目的だと思います。

ただ、この手の API がどんなものなのかを理解するには、単純な処理を実装してみることが近道ですので、そのためには本ページが役に立つはずです。解説されているページも、それほどあるわけでもなさそうです。

API を使った自動化が可能であるのが ConoHa の大きな強みの１つであると思います。ConoHa の機能を十分に活用するためにも、ConoHa API がどんなものなのか知りたい場合には、是非本ページを参考にしてください。

ConoHa VPS のレビュー・評価

2018.04.16