REST API で VCSA をバックアップからリストアする

Table of contents

概要

前回の記事では OVFTool で vCenter Server Appliance (以下 VCSA) をデプロイしました。今回の記事では VCSA のインストールのステージ1が完了したところから、REST API を使って vCenter Server のリストアを実行してみます。

なぜ API でやろうと思ったのか

vCenter Server 7.0 Update 3 時点で、VCSA の CLI インストーラにはリストアの機能だけ存在しません。VMware Docs には GUI インストーラを使う手順と、vSphere Client で OVA のデプロイ後に VAMI からステージ2を実行する方法のみが書いてあります。

• ファイルベースのバックアップからの vCenter Server のリストア
• ステージ 1 - 新しいアプライアンスをデプロイ

インストール、アップグレード、マイグレーションは CLI インストーラでも可能になっています。

• vCenter Server アプライアンスの CLI デプロイ
• vCenter ServerAppliance の CLI アップグレード
• CLI による Windows からアプライアンスへの vCenter Serverインストールの移行

このため、リストアだけコマンドラインで出来ないのもなぁ・・・と思ったのが API でやってみようとした発端です。

事前準備

事前準備として、以下の2点を実施しておきます。

• VCSA のファイルベースバックアップを取得する
• インストールのステージ1までが完了している VCSA を用意する

VCSA のファイルベースバックアップを取得する

当然ながらバックアップがないとリストアできませんので、以下の手順で VAMI からファイルベースバックアップを取得しておきます。

• vCenter Server 管理インターフェイスを使用した vCenter Server の手動によるバックアップ

なお、バックアップが完了した後は以下の情報をメモしておきます。

• VCSA のバージョン／ビルド番号
• バックアップの場所の URI (protocol://<backup server>/…)
• バックアップの暗号化パスワード
• バックアップサーバの認証情報
• SSO 管理者(administrator@vsphere.local)の認証情報

VCSA のバージョン／ビルド番号は後述しますが、インストールのステージ1で使用するインストーラ ISO を選ぶために必要になります。その他はステージ2の実行に必要です。

インストールのステージ1が完了した VCSA を用意する

前回の記事では OVFTool を使ってステージ1が完了した状態でデプロイする方法を記載しました。その他には以下のような方法でもステージ1が完了した状態の VCSA を用意できます。

• GUI インストーラを実行し、ステージ1の完了時点でインストーラを終了する
• vSphere Client や Host Client から VCSA の OVA ファイルをデプロイする

上述のファイルベースバックアップの取得時にメモした VCSA のビルド番号と同じインストーラの ISO を用意し、いずれかの方法でステージ1の VCSA をデプロイしておきます。テスト目的で使用する場合はステージ1の完了後に VCSA をシャットダウンしてスナップショットを取っておくと便利です。

なお、VCSA のファイルベースバックアップの一般的な注意点として、デプロイする VCSA のバージョン／ビルド番号やネットワーク情報はバックアップ時のものと一致している必要があります。VCSA のビルド番号やシステム名が異なる場合はステージ2のリストアが行えませんので注意してください。

REST API を叩いてリストアを実行する

では実際に REST API を叩いてリストアを実行してみます。やることは単純で、以下の3点を実施するだけです。

1. リストアのパラメータを JSON 形式で用意する
2. VCSA の認証情報で API トークンを取得する
3. JSON データを添えてリストアの API を叩く

curl で VCSA の REST API を叩いたものが以下になります。JSON の整形は jq で実施しています。

 1## Appliance hostname and credential
 2VCSA_HOSTNAME=vcsa01.jangari.lab
 3VCSA_USERNAME=root
 4VCSA_PASSWORD=VMware1!
 5
 6## SSO administrator credential
 7VC_SSO_ADMIN_USERNAME=administrator
 8VC_SSO_ADMIN_PASSWORD=VMware1!
 9
10## Backup location details
11SFTP_LOCATION=192.168.0.4/vCenter/sn_vcsa01.jangari.lab/M_7.0.3.00200_20220106-162432_
12SFTP_USERNAME=root
13SFTP_PASSWORD=Vmware@123
14
15## Encryption password for the backup file
16BACKUP_PASSWORD=VMware1!
17
18
19RESTORE_OPTS=$(jq -c <<EOF
20{
21    "piece": {
22        "backup_password": "${BACKUP_PASSWORD}",
23        "ignore_warnings": false,
24        "location_type": "SFTP",
25        "location": "sftp://${SFTP_LOCATION}",
26        "location_password": "${SFTP_PASSWORD}",
27        "location_user": "${SFTP_USERNAME}",
28        "sso_admin_user_name": "${VC_SSO_ADMIN_USERNAME}",
29        "sso_admin_user_password": "${VC_SSO_ADMIN_PASSWORD}"
30    }
31}
32EOF
33)
34
35## Obtain API token
36TOKEN=$( \
37    curl -k -X POST \
38        -H "Authorization: Basic $(echo -n ${VCSA_USERNAME}:${VCSA_PASSWORD} | base64)" \
39        -H "Content-Length: 0" \
40        https://${VCSA_HOSTNAME}:5480/rest/com/vmware/cis/session \
41    | jq .value
42)
43
44## Invoke restore
45curl -k -X POST \
46  -H "vmware-api-session-id: ${TOKEN}" \
47  -H "Content-Type: application/json" \
48  -d "${RESTORE_OPTS}" \
49  https://${VCSA_HOSTNAME}:5480/rest/appliance/recovery/restore/job

API トークンの取得、リストアに使用する REST API はそれぞれ以下です。

• Create Session | CIS | vSphere CIS REST APIs
• Create Restore Job | Recovery | vSphere Appliance REST APIs

なお、リストアの進行状況のチェックなども含むサンプルコードが VMware {code} の Programming Guide にあったのでリンクを貼っておきます。

• Bash Example of Restoring the vCenter Server Instance - VMware vCenter Server Appliance Management Programming Guide - VMware {code}

ステージ1で REST API を叩く際の注意点

ステージ1で VCSA の REST API を叩く場合、以下の点に注意が必要です。

• TCP 5480 ポートに HTTP リクエストを発行する
• API のエンドポイントは /rest (古い方)を利用する

TCP 5480 ポートに HTTP リクエストを発行する

ステージ1の完了時点では VAMI に相当する applmgmt サービスしか起動していないため、TCP 443 ポートは待ち受けすらしていません。TCP 5480 ポートにはアクセスが可能なので、VAMI に搭載されている REST API を使用します。

• vCenter Server Appliance Management Overview

API のエンドポイントは /rest (古い方)を利用する

使用している REST API のフォーマットは vSphere Automation API と同様ですが、vCenter Server 7.0 Update 3 時点で VAMI には /api のエンドポイントは実装されていないようでした¹。TCP 5480 の /api に対してリクエストを発行すると以下のように 404 Not Found のエラーになります。

 1curl -v -k -X POST \
 2  -H "Authorization: Basic $(echo -n ${VCSA_USERNAME}:${VCSA_PASSWORD} | base64)" \
 3  -H "Content-Length: 0" \
 4  https://${VCSA_HOSTNAME}:5480/api/session \
 5| jq
 6
 7  ...
 8< HTTP/1.1 404 Not Found
 9  ...
10{
11  "messages": [
12    {
13      "id": "vapi.method.invoke.exception",
14      "default_message": "Error in method invocation The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again.",
15      "args": [
16        "The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again."
17      ]
18    }
19  ],
20  "error_type": "INVALID_REQUEST"
21}

Programming Guide を見る限り、元からすべての機能の操作は想定していないようなので、vSphere Automation API とはバージョンが同期していないのかなと推測しています。

• Limitations of Programming for the vCenter Server Appliance

今のところ REST API 自体は使えるため特に困ることはないですが、vSphere Automation API としては /rest のエンドポイントは VC 7.0 U2 から非推奨になっているので、VAMI に /api のエンドポイントが実装された際には書き換えた方が良いだろうとは思います。

• vSphere 7 Update 2 - REST API Modernization

おわりに

今回の記事では REST API を使用して vCenter Server のリストアを実施してみました。

インストールに GUI しか使えないとユーザー入力が必要になるため自動化も難しいですが、CLI や API で操作ができればユーザー入力なしで自動化するなどの応用が効きます。現状は VAMI の REST API が古そうなので今後 URL の修正などが必要になる可能性もありますが、参考になれば幸いです。

補足: アプライアンスシェルの API コマンドを使う

VCSA のアプライアンスシェルには API コマンドという機能が搭載されています。com.vmware.appliance.recovery.restore.job.create コマンドが今回のリストアを実行する REST API と同様の動きをします。

• Appliance シェルの API コマンド

VCSA をステージ1の状態でデプロイした後、仮想マシンコンソールや SSH 接続でアプライアンスシェルにアクセスし、上述の API コマンドを叩くことでも同様にリストアが行えます。API コマンドのオプションなどの詳細は「help api <API コマンド名>」のヘルプで確認が可能です。

• アプライアンス シェルへのアクセス
• アプライアンスのプラグインおよび API コマンドに関するヘルプの表示

VCSA の外から REST API が叩けないような場合には、アプライアンスシェルから API コマンドを実行するといったことも可能です。VCSA の API を簡易的に試すにはこちらも良いと思います。