はじめに
本記事では「IBM Cloud Pak for Data コマンドラインインターフェイス (IBM cpdctl)」(以下 本文では cpdctl) の使用方法について紹介します。
cpdctl は watsonx.data や watsonx.ai などCP4Dの様々なサービスをサポートするコマンドライン・インターフェースです。CP4Dのインストール系のコマンドライン・インタフェースである cpd-cli とは別のコマンドライン・インタフェースとなります。
参照マニュアル
IBM Cloud Pak for Data コマンドラインインターフェイス (IBM cpdctl)
前提条件
本記事では、オンプレ環境に「IBM Cloud Pak for Data (CP4D) 5.2.2」がインストールされ、クライアント・マシンがLinuxである事を前提としています。
cpdctl のインストール
以下の2つの方法のいずれかを使用して、cpdctl をインストールします。
今回は cpdctl v1.8.45 をインストールしています。
a.オプション1
以下のコマンドを使用して cpdctl をインストールします
platform=$(uname -s | tr '[A-Z]' '[a-z]')
arch=$(uname -m | sed 's/x86_64/amd64/')
curl -LOs "https://github.com/IBM/cpdctl/releases/latest/download/cpdctl_${platform}_${arch}.tar.gz"
tar zxf cpdctl_${platform}_${arch}.tar.gz
上記のコマンドを実行したディレクトリーに cpdctl コマンドが配置されますので、cpdctl ファイルを PATHが設定された適当なディレクトリーにコピーします。
例
$ copy cpdctl /usr/local/bin
b.オプション2
IBM cpdctl リポジトリから適当な パッケージをダウンロードします。クライアント・マシンが インテル系のLinux の場合 "cpdctl_linux_amd64.tar.gz" をダウンロードします。
cpdctl は頻繁にアップデートされていますので、最新版(Latest)をダウンロードする事をお勧めします。
ダウンロードした cpdctl_linux_amd64.tar.gz ファイルを "tar zxf cpdctl_linux_amd64.tar.gz" コマンドで解凍して、cpdctl ファイルを PATHが設定された適当なディレクトリーにコピーします。
cpdctlコマンドを実行して、cpdctlコマンドのヘルプが表示される事を確認します。
オンプレ環境のCP4Dに対して cpdctl を実行する場合、USAGE: に表示されている先頭の "ibmcloud" の指定は不要です。
$ cpdctl
NAME:
cpdctl - IBM Cloud Pak for Data Command Line Interface
USAGE:
ibmcloud cpdctl [command] [options]
VERSION:
1.8.45
COMMANDS:
config Manage Configuration
asset Manage Assets
project Manage Watson Studio - Projects API - OpenAPI Docs.
space Manage Spaces
connection Manage IBM Watson Data Platform Connections service.
environment Manage Environments and Runtimes API.
notebook Manage Notebooks API.
code-package Manage Code Packages API.
job Manage IBM Watson Data Platform Jobs and Scheduling Service.
ml Manage Watson Machine Learning.
datastage Manage IBM APIs for DataStage.
find Find a resource with CPD Path
pipeline Manage IBM Orchestration Pipelines API.
wx-data Manage watsonx.data.
version Display the tool version
wx-ai Manage watsonx.ai.
以下省略
プロファイルとユーザーの設定
cpdctl を実行するためには、事前に "cpdctl config" コマンドで、プロファイルとユーザーを設定する必要があります。プロファイルとユーザーは同時に設定できますので同時に設定する事をお勧めします。
また、cpdctl の watsonx.data サポート である "cpdctl wx-data" コマンドを実行する場合、パラメーターとして watsonx.data のインスタンスIDの指定が必要ですが、プロファイルの設定時にインスタンスIDを環境変数として登録しておく事により、インスタンスIDの指定を省略する事ができますので、"cpdctl wx-data"コマンドを実行する場合は watsonx.data のインスタンスIDも登録しておきましょう。
インスタンスIDは watsonx.data の Webコンソールの左下の「インスタンスの詳細」を選択する事により確認する事ができます。
CP4Dのホスト名も必要ですので、下記のコマンドで確認しておきます。
例
$ oc get route cpd
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
cpd cpd-zen.apps.69004c6b62a593885d360db3.ap1.techzone.ibm.com / ibm-nginx-svc ibm-nginx-https-port reencrypt/Redirect None
この例では HOST/PORT に表示される "cpd-zen.apps.69004c6b62a593885d360db3.ap1.techzone.ibm.com" がCP4Dのホスト名になります。
以下の条件で、プロファイルとユーザーを設定してみます。
プロファイル名：profile1
ユーザー名：cpadmin
パスワード：xxxxxxxx
CP4Dのホスト名：cpd-zen.apps.69004c6b62a593885d360db3.ap1.techzone.ibm.com
インスタンスID : 1761711652465331
下記のコマンドでプロファイルとユーザーを設定する事ができます。
CP4D のホスト名は、"--url https://<ホスト名>" の形式で指定します。
cpdctl config profile set profile1 --username cpadmin --password xxxxxxxx --url https://cpd-zen.apps.69004c6b62a593885d360db3.ap1.techzone.ibm.com --env "WATSONX_DATA_INSTANCE_ID=1761711652465331"
プロファイルとユーザーを設定すると、コマンドを実行したユーザーのホーム・ディレクトリーの下に下記の内容の ".cpdctl/config" ファイルが作成されます。
users:
- name: profile1_user
user:
password: {aes256: rcw2O0DzK8iB7BRl3ecyEqm8Ay5DG00pQYQDTEY6HxXoGIP4}
username: cpadmin
auth_scope: accounts
profiles:
- name: profile1
profile:
type: private
version: 4.0.0.0
url: https://cpd-zen.apps.69004c6b62a593885d360db3.ap1.techzone.ibm.com
auto_updated_at: 1764578804
user: profile1_user
environment:
WATSONX_DATA_INSTANCE_ID: "1761711652465331"
apiVersion: v6
kind: Config
default-profile: profile1
今回作成した profile1 がデフォルトのプロファイルとして設定されています。
cpdctl を実行する対象のクラスターが複数ある場合、別のプロファイルを作成しておき、"cpdctl config profile use <プロファイル名>" でデフォルトのプロファイルを切り替えるか、"cpdctl" コマンドに "--profile <プロファイル名>" オプションで使用するプロファイルを明示的に指定する事ができます。
以上で cpdctl を実行する環境が整いました。
cpdctlの使用方法については IBM Cloud Pak for Data コマンドラインインターフェイス (IBM cpdctl) に記述されていますが、コマンド体系が壮大であるため、各コマンドのオプションに関する記述はありません。
以下のような手順で、ヘルプを表示させながら最終的に実行するコマンドやパラメーターを決定する必要があります。
例
#cpdctl コマンドのヘルプを表示
cpdctl --help
#cpdctl wx-data コマンドのヘルプを表示
cpdctl wx-data --help
#cpdctl wx-data ingestion コマンドのヘルプを表示
cpdctl wx-data ingestion --help
#cpdctl wx-data ingestion create コマンドのヘルプを表示
cpdctl wx-data ingestion create --help
ここまで来てようやく最終的に指定するパラメーターのヘルプが表示されますので、ヘルプの内容を確認しながら実行するコマンドとパラメーターを決定します。コマンドのサンプルも表示されますが、ヘルプの内容は親切とは言えず、コマンドを正常に実行させるには ある程度の試行錯誤が必要となります。
cpdctl を実行する上で幾つか注意点があります。
・cpdctlは頻繁にアップデートされていますので、最新版(Latest)をダウンロードして使用する事をお勧めします。
・パラメーター名が予告無く変更される場合があります。cpdctl が内部で使用しているAPIのバージョンが同じ場合は、変更前のパラメーターも使用可能です。
・"cpdctl wx-data" が内部で使用しているAPIのバージョンが変更された場合、一部のパラメーターが変更される場合があります。この場合、古いパラメーターは使用できません。APIのバージョンが変更された場合 watsonx.data の Knowledge Center の「新着情報」に記述されます。
・cpdctl 実行時 必須パラメーターが不足している場合には、下記のようなメッセージが表示されます。
required flag(s) "display-name", "type" not set
・競合するパラメーターが指定されている場合には、下記のメッセージが表示されます。パラメーター名は表示されません。
mutually-exclusive-fields
以下は "cpdctl wx-data bucket list" コマンドで、watsonx.data のインフラストラクチャ・マネージャーに登録されたバケットと関連付けられたカタログをリストする例となります。
$ cpdctl wx-data bucket list
...
Display Name Name ID Associated Catalogs State
iceberg-bucket iceberg-bucket iceberg-bucket [iceberg_data] active
hive-bucket hive-bucket hive-bucket [hive_data] active
wxd-milvus wxd-milvus wxd-milvus - active
wxd-system wxd-system wxd-system [wxd_system_data] active
tve-test-bucket tve-test-bucket tve-test-bucket [tvetestbucket] active
以上で「IBM Cloud Pak for Data コマンドラインインターフェイス (IBM cpdctl)」の使用方法の紹介を終わります。
別の記事で "cpdctl wx-data ingestion" コマンドを使用した watsonx.data の Ingestion (データの取り込み) についてご紹介しています。
CP4Dコマンドライン・インターフェース cpdctl で watsonx.data の データの取り込み (Ingestion) を実行してみた