目的
Db2データベースはV11.5からRESTに対応して、RESTサービスの作成/実行が可能になっています。
REST利用開始までのセットアップがそれなりの手間だったため、備忘録としてメモを残します。
前提
以下の作業が済んでいることを前提とします。
- Db2 11.5 インストール
- インスタンス/データベース作成
- IBM Cloud アカウント作成済であること
作業の流れ
手順の全体像は、こちらの Db2マニュアルに記載されます。
Db2 11.5 「IBM Db2 REST サービスをダウンロードする」(下記のStep1.-4.)
Db2 11.5 「REST 機能のアクティブ化および初期化」(下記のStep5.-6.)
Step1. IBM Cloud コマンド行ツールとプラグインのインストール
Step2. コンテナー・レジストリーへのログイン
Step3. Db2 RESTサービス・コンテナ・イメージをPull
Step4. Db2 RESTサービス・コンテナ実行
Step5. Db2 RESTサービス機能の初期化
Step6. Db2 RESTサービスのドキュメント確認
1つの製品マニュアルでは完結しないため、複数文書を読み合わせながら進めます。
下記手順それぞれの中で、参照した文書リンクを貼っていきます。
環境
Db2 REST サービスは、RESTサービス・コンテナを構成することで利用可能になります。
今回は、Db2が稼働するサーバとは別のサーバにRESTサービス・コンテナを立てる構成としています。
-
Db2 データベース稼働サーバ
- RHEL 7.9
- Db2 11.5.6
-
Db2 RESTサービス・コンテナ稼働サーバ
- WSL2/Ubuntu 22.04
- podman version 3.4.4
- Db2 Rest Service Container
- curl 7.81.0
Step1. IBM Cloud コマンド行ツールとプラグインのインストール
Step1-1. IBM Cloud CLI のインストール
参考：https://cloud.ibm.com/docs/cli?topic=cli-getting-started
最新バージョンのIBM Cloud CLIをインストールします。
curl -fsSL https://clis.cloud.ibm.com/install/linux | sh
CLI が正常にインストールされたことを検証するには、help コマンドを実行します。
出力例：
kanako@IBM-PF2E8K5F:~$ ibmcloud help
名前:
ibmcloud - IBM Cloud と対話するためのコマンド・ライン・ツール
詳しくは https://ibm.biz/cli-docs を参照してください
使用法:
[environment variables] ibmcloud [global options] command [arguments...] [command options]
バージョン:
2.10.0+e37e09e-2022-08-24T17:31:27+00:00
コマンド:
account アカウント、ユーザー、組織、およびスペースを管理します
api ターゲットの API エンドポイントを設定または表示します
app [非推奨] Cloud Foundry アプリケーションとアプリケーションに関連したドメインおよび経路を管理します。
billing 使用量および請求先情報を取得します
(以下略)
Step1-2. CLI プラグイン cr(Container-registry) のインストール
参考：https://cloud.ibm.com/docs/cli?topic=cli-plug-ins
後続のStep2.でコマンド ibmcloud cr region-set global を実行する必要があるため、プラグインcrを導入しておきます。
プラグイン情報の取得：
kanako@IBM-PF2E8K5F:~$ ibmcloud plugin repo-plugins -r "IBM Cloud"
リポジトリー 'IBM Cloud' からプラグインを取得しています...
リポジトリー: IBM Cloud
状況 名前 バージョン 説明
未インストール container-registry 0.1.579, 0.1.578, 0.1.571... Manage IBM Cloud Container Registry content and configuration.
未インストール container-service[kubernetes-service/ks] 1.0.439, 1.0.433, 1.0.431... Manage IBM Cloud Kubernetes Service clusters
未インストール analytics-engine 1.0.186, 1.0.181, 1.0.177... Manage Analytics Engine service
未インストール cloud-functions[wsk/functions/fn] 1.0.59, 1.0.58, 1.0.56... Manage Cloud Functions
未インストール cloud-internet-services[cis] 1.14.5, 1.14.4, 1.14.2... Manage Cloud Internet Service
未インストール dbaas-cli[dbaas] 2.1.7, 2.1.6, 2.1.2... Manage Hyper Protect DBaaS clusters
未インストール cloud-databases[cdb] 0.11.0, 0.10.10, 0.10.9... Manage Cloud databases
未インストール key-protect[kp] 0.6.12, 0.6.11, 0.6.10... Manage encryption keys on IBM Cloud
未インストール doi[doi] 0.3.9, 0.3.8, 0.3.7... Integrate with DevOps Insights service
未インストール tke 1.3.0, 1.2.3, 1.1.4... Manage the master key of Cloud HSMs from Hyper Protect Crypto service
未インストール cloud-object-storage 1.5.0, 1.4.0, 1.3.1... Manage Cloud Object Storage service
未インストール event-streams 2.3.2, 2.3.1, 2.3.0... Manage Event Streams service
未インストール power-iaas[pi] 0.3.17, 0.3.13, 0.3.12... Manage IBM Cloud Power Virtual Server service
未インストール vpc-infrastructure[infrastructure-service] 5.1.0, 5.0.1, 5.0.0... Manage Virtual Private Cloud infrastructure service
未インストール schematics[sch] 1.12.2, 1.12.1, 1.12.0... Managing IBM Cloud resources with Terraform
未インストール cloud-dns-services[dns] 0.7.0, 0.6.2, 0.5.3... Manage IBM Cloud Dns Service
未インストール dl-cli 0.4.11, 0.4.10, 0.4.9... Manage Direct Link
未インストール watson 0.0.11, 0.0.10, 0.0.9... Manage Watson services
未インストール catalogs-management 2.2.1, 2.2.0, 2.1.20... Manage personal catalogs and offerings
未インストール tg-cli[tg] 0.8.2, 0.7.1, 0.6.1... Manage Transit Gateway service
未インストール observe-service 1.0.82, 1.0.61, 1.0.54... Manage logging and monitoring configurations for IBM Cloud Kubernetes Service clusters
未インストール code-engine 1.39.2, 1.39.1, 1.38.2... Manage Code Engine components
未インストール hpvs 1.4.19, 1.4.17, 1.4.15... Manage Hyper Protect Virtual Server service
未インストール push-notifications[push] 1.0.5, 1.0.4, 1.0.3... [Deprecated] Manage IBM Cloud Push Notifications service.
未インストール secrets-manager[sm] 0.1.21, 0.1.20, 0.1.19... Manage IBM Cloud Secrets Manager secrets and secret groups.
未インストール app-configuration[ac] 1.0.10, 1.0.9, 1.0.8... Interact with IBM Cloud App Configuration service instance
未インストール monitoring 0.2.12, 0.2.9, 0.2.8... Manage IBM Cloud monitoring
未インストール logging 0.0.8, 0.0.7, 0.0.6... Manage IBM Cloud logging
未インストール cloudant[cl] 0.0.5, 0.0.4, 0.0.3 Manage Cloudant service
未インストール hpcs-cert-mgr[hpcs-cert-mgr] 1.0.0 Manage the client certificates for IBM Cloud Hyper Protect Crypto Services
未インストール atracker[at] 0.2.17, 0.2.12, 0.1.13... Manage IBM Cloud Activity Tracker
未インストール analytics-engine-v3[ae-v3] 1.0.9, 1.0.5, 1.0.0 Manage serverless Spark instances and run applications
未インストール cra[cra] 1.0.1, 1.0.0, 0.1.22... Integrate with Code Risk Analyzer
未インストール event-notifications[en/event-notifications] 0.1.2, 0.1.1, 0.1.0... IBM Cloud Event Notifications.
未インストール dvaas[watson-query] 1.0.2 Manage data virtualization as a service
未インストール hpnet 1.0.2, 1.0.1 Manage Hyper Protect Secure Network
未インストール qiskit-runtime[qr] 0.1.5 [Beta] Manage Qiskit Runtime
未インストール hpcs 0.0.1 Manage Hyper Protect Crypto Services Instances
未インストール cbr 1.1.0, 1.0.0 Manage Context Based Restrictions
未インストール privileged-access-gateway[pag] 1.2.2, 1.2.1 [Experimental] Manage Privilege Access Gateway
ibmcloud plugin update PLUGIN_NAME -r REPO_NAME を使用して、リポジトリーからプラグインを更新します。
ibmcloud plugin update --all -r REPO_NAME を使用して、リポジトリーからすべての使用可能なプラグインをアップグレードします。
kanako@IBM-PF2E8K5F:~$
プラグイン 'container-registry'をインストール
kanako@IBM-PF2E8K5F:~$ ibmcloud plugin install container-registry -r "IBM Cloud"
リポジトリー 'IBM Cloud' から 'container-registry' を検索しています...
プラグイン 'container-registry 0.1.579' がリポジトリー 'IBM Cloud' 内で見つかりました
バイナリー・ファイルをダウンロードしようとしています...
11.25 MiB / 11.25 MiB [====================================================================================] 100.00% 1s
11800576 バイトがダウンロードされました
バイナリーをインストールしています...
OK
プラグイン 'container-registry 0.1.579' は /home/kanako/.bluemix/plugins/container-registry に正常にインストールされました。 'ibmcloud plugin show container-registry' を使用して詳細を表示してください。
kanako@IBM-PF2E8K5F:~$
Step1-3. Podmanのインストール
後続のStep2で登場する「ibmcloud cr login」コマンドの実行には、dockerもしくはpodmanが必要となります。
dockerはコスト面の懸念があるため、こちらを参考にさせていただきつつpodmanを導入します。
kanako@IBM-PF2E8K5F:~$ sudo apt -y install podman
[sudo] kanako のパスワード:
パッケージリストを読み込んでいます... 完了
依存関係ツリーを作成しています... 完了
状態情報を読み取っています... 完了
(中略)
アップグレード: 0 個、新規インストール: 32 個、削除: 0 個、保留: 0 個。
26.2 MB のアーカイブを取得する必要があります。
この操作後に追加で 115 MB のディスク容量が消費されます。
(中略)
Scanning processes...
Scanning processor microcode...
Scanning linux images...
Failed to retrieve available kernel versions.
Failed to check for processor microcode upgrades.
No services need to be restarted.
No containers need to be restarted.
No user sessions are running outdated binaries.
No VM guests are running outdated hypervisor (qemu) binaries on this host.
kanako@IBM-PF2E8K5F:~$
導入されたこと(と、バージョン)を確認します。
kanako@IBM-PF2E8K5F:~$ podman --version
podman version 3.4.4
kanako@IBM-PF2E8K5F:~$
Step2. コンテナー・レジストリーにログイン
Step2-1. ibmcloud login
下記の情報を参考にAPIKEYを生成し、ibmcloudコマンドでログインします。
取得したAPIKEYはローカルファイル(mykey.json)として保持しておきます。
https://qiita.com/nishikyon/items/fa8b951267efbe911fe7
https://qiita.com/testnin2/items/3ff57e6c92eacd664ff3
Db2マニュアルに従い、リージョン選択はスキップしてログインします。
kanako@IBM-PF2E8K5F:~$ ibmcloud login --apikey @mykey.json
API エンドポイント: https://cloud.ibm.com
認証中です...
OK
ターゲットのアカウント IBM - ISE Cloud (1fc8373f538a408187ffedbe62e5796a) <-> 1707641
リージョンを選択します (または Enter キーを押してスキップします):
1. au-syd
2. in-che
3. jp-osa
4. jp-tok
5. kr-seo
6. eu-de
7. eu-fr2
8. eu-gb
9. ca-tor
10. us-south
11. us-south-test
12. us-east
13. br-sao
数値を入力してください> ←-- Enter を押してスキップ
API エンドポイント: https://cloud.ibm.com
Region:
ユーザー: KUTSUMI@jp.ibm.com
アカウント: IBM - ISE Cloud (1fc8373f538a408187ffedbe62e5796a) <-> 1707641
リソース・グループ: リソース・グループがターゲットになっていません。'ibmcloud target -g RESOURCE_GROUP' を使用して ください
CF API エンドポイント:
組織:
スペース:
kanako@IBM-PF2E8K5F:~$
Step2-2. ibmcloud cr region-set global
kanako@IBM-PF2E8K5F:~$ ibmcloud cr region-set global
地域は「global」に設定されました。地域は「icr.io」です。
OK
kanako@IBM-PF2E8K5F:~$
Step2-3. ibmcloud cr login
kanako@IBM-PF2E8K5F:~$ ibmcloud cr login
'podman' を 'icr.io' にログインしています ...
「icr.io」にログインしました。
OK
kanako@IBM-PF2E8K5F:~$
Step3. Db2 RESTサービス・コンテナ・イメージをPull
podman pull コマンドでコンテナイメージをpullします。
kanako@IBM-PF2E8K5F:~$ podman pull icr.io/obs/hdm/db2rest:latest-amd64
Trying to pull icr.io/obs/hdm/db2rest:latest-amd64...
Getting image source signatures
Copying blob 00f071514b11 done
Copying blob 0d725b91398e done
Copying blob 030fe302b577 done
Copying blob 3d60ce6dc219 done
Copying blob 1e09a5ee0038 done
Copying blob e9b8a2ffc7d6 done
Copying blob 75c1404812e9 done
Copying blob 535f562837f4 done
Copying blob 334ced49f4e8 done
Copying config 3549fc40c4 done
Writing manifest to image destination
Storing signatures
3549fc40c4a5a9dc42bb6745b07fe7836417730003ab4fab8024df18e6071f86
kanako@IBM-PF2E8K5F:~$
Step4. Db2 RESTサービス・コンテナ実行
今回は気づかなかったのですが、サービス・コンテナ開始のタイミングで選択可能なオプションがいくつか存在します。
docker(podman) run オプションで指定するものですので、コンテナ開始前に検討しておきたいところです。
例1) SQL 直接実行の無効化
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-disabling-direct-sql-execution
Db2 REST では、サービスの作成および実行に加え、/v1/services/execsql エンドポイントを使用して SQL を直接実行できます。 コマンド行から IBM Db2 REST サービス・コンテナーを開始するときに、このエンドポイントの使用を無効にできます。
-e DB2REST_EXECSQL_DISABLED=true
例2) HTTPS を使用しない IBM Db2 REST サーバーの実行
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-running-rest-without-https
外部アクセスのリスクが低い環境では、HTTP のみを使用して IBM® Db2® REST サーバーを実行できます。
注: HTTPS を無効にすると、 IBM Db2 REST サービスのセキュリティーに影響するため、アクセスが制御される分離環境にサーバーがある環境でのみ実行してください。
-e DB2REST_USE_HTTP=true
Db2 RESTサービス・コンテナ実行：
kanako@IBM-PF2E8K5F:~$ podman run -it --net=host -e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64
Opening License Agreement...
Use the keys [k] and [j] to scroll up and down
Use the key [q] to exit and proceed to prompt
Do you accept the License Agreement? [y/n] y ←--「y」を選択
Proceeding to install...
Generating a RSA private key
................................................+++++
......................................................+++++
writing new private key to '/opt/ibm/dbrest/auth/dbrest.key'
-----
Starting the Db2 REST server...
Starting server with https
SERVER STATUS: ACTIVE
####################################################################################
### IBM Db2 REST container was deployed successfully ###
####################################################################################
* To return to the host after viewing and accepting the license, press
Ctrl+p followed by Ctrl+q.
* To return to the host after viewing the logs with
[ docker | oc | kubectl -n <NS> ] logs <rest container name>,
press Ctrl+c.
* To get a command line prompt, issue the following command from the host:
[ docker | oc | kubectl -n <NS> ] exec -it <rest container name> bash
####################################################################################
→ ACTIVE ということで問題なく稼働している
→ Ctrl - c で元のコンソールに戻る
Step5. Db2 RESTサービス機能の初期化
前提(権限)
今回は簡易的な検証で、インスタンスオーナー db2inst1 で実施しますので考慮の必要はありませんが、
メタデータのセットアップには、以下の権限が必要です。
- 管理者権限。
- 許可 ID の SYSPROC.AUTH_LIST_GROUPS_FOR_AUTHID、 SYSPROC.AUTH_LIST_ROLES_FOR_AUTHID、および SYSPROC.AUTH_LIST_AUTHORITIES_FOR_AUTHID 表関数に対する 実行特権。
- メタデータ表を含むスキーマのプロシージャー権限に対する CREATE TABLE、CREATE PROCEDURE、および GRANT EXECUTE 特権。
- メタデータ表に対する GRANT SELECT 特権。
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-required-privileges
Step5-1. アクティブ化および初期化処理
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-activating-initializing-rest-capability
上記マニュアルを参考に、REST機能をアクティブ化および初期化します。
コンテナに配置されたコマンドを3つ実行するか、もしくはREST API「setup_metadata」を実行するか、どちらかの方法を選択できます。
今回は、Db2 RESTサービス・コンテナを稼働するサーバにログインし、コマンド3つを実行しています。
コマンド構文：
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-stop.sh
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-setup.sh DBホスト名 DB名 ポート番号 SSL(TLS有無) メタデータ格納用テーブルのスキーマ メタデータ作成ユーザID メタデータ作成ユーザパスワード
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-start.sh
実行ログ：
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-stop.sh
Stopping the Db2 REST server...
SERVER STATUS: INACTIVE
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-setup.sh toriringo testdb2 50300 N db2rest db2inst1 パスワード文字列
Creating REST Services metadata...
REST Services metadata created in schema db2rest.
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-start.sh
Starting the Db2 REST server...
Starting server with https
SERVER STATUS: ACTIVE
kanako@IBM-PF2E8K5F:~$
Step5-2. メタデータ表の存在確認
Step5-1.が成功すると、今後作成するRESTサービスについてのメタデータが格納されるためのRESTSERVICE表が作成されます。
[db2inst1@4c4fd18c3faf ~]$ db2 list tables for schema db2rest
Table/View Schema Type Creation time
------------------------------- --------------- ----- --------------------------
RESTSERVICE DB2REST T 2022-09-06-09.37.57.357031
1 record(s) selected.
この段階では、メタデータは格納されていません。
[db2inst1@4c4fd18c3faf ~]$ db2 "select * from db2rest.RESTSERVICE"
NAME VERSION DESCRIPTION PROCSCHEMA PROCNAME ISQUERY SERVICE_CREATOR SERVICE_UPDATER LAST_MODIFIED
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------- ------- ----------------------------------------------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------- --------------------------
0 record(s) selected.
[db2inst1@4c4fd18c3faf ~]$
Step6. Db2 RESTサービスのドキュメント確認
Db2 RESTサービス・コンテナを立てると、RESTのドキュメントを参照できるようになり、
どんな操作が可能であるか、確認できます。
(webで見られる Db2製品マニュアル とはまた別にドキュメントが提供されています)
REST ドキュメントURL：
https://<db2restservice_container_host>:50050//docs
これで、Db2 RESTサービスの作成ができるようになりました。
RESTサービス作成/実行のメモはこちらに残します → Link