alibabacloud-emr-starrocks-manage

Alibaba Cloud EMR Serverless StarRocks インスタンスのフルライフサイクル管理

aliyun CLI を使用して StarRocks インスタンスを管理します。StarRocks を理解した SRE として、API の呼び出し方だけでなく、呼び出すタイミングや使用するパラメーターも把握しています。

認証

aliyun CLI にすでに設定されているプロファイルを再利用します。--profile <name> でアカウントを切り替え、aliyun configure list で設定を確認します。

ドメイン知識

製品概要

EMR Serverless StarRocks は、Alibaba Cloud 上でオープンソースの StarRocks を提供するフルマネージドサービスです。高性能でフルマネージドのリアルタイム分析データベースサービスを提供します。

主な機能：

• MPP 分散実行フレームワーク：超並列処理によってクエリのパフォーマンスを向上させます
• 完全ベクトル化エンジン：列指向ストレージとベクトル化計算により、分析クエリを効率的に処理します
• ストレージとコンピューティングの分離：ストレージリソースとコンピューティングリソースを個別にスケーリングできる、ストレージとコンピューティングを分離したアーキテクチャに対応します
• CBO オプティマイザー：コストベースのクエリオプティマイザーが、最適な実行計画を自動的に生成します
• リアルタイム更新対応の列指向ストレージエンジン：リアルタイムのデータ取り込みと更新に対応します
• インテリジェントなマテリアライズドビュー：マテリアライズドビューを自動的に維持し、クエリのパフォーマンスを向上させます
• データレイク分析：OSS や MaxCompute などの外部データソースへのクエリに対応します

ユースケース

• OLAP 多次元分析：複雑な多次元データ分析、アドホッククエリ、レポート分析
• リアルタイムデータウェアハウス：リアルタイムのデータ取り込みと処理、リアルタイムレポートとダッシュボード、リアルタイムのリスク管理と分析
• 高同時実行クエリ：高同時実行のポイントクエリや短時間クエリ、オンライン分析処理、ユーザー行動分析
• 統合分析：データレイク分析（OSS、MaxCompute などへのクエリ）、レイクハウスアーキテクチャ、複数のデータソースにまたがるフェデレーションクエリ

主な概念

概念	説明
StarRocks インスタンス	作成された StarRocks クラスター（複数の FE ノードおよび複数の BE／CN ノードを含む）をまとめて StarRocks インスタンスと呼びます
CU（コンピューティングユニット）	コンピューティングリソースの単位です。StarRocks で書き込みやクエリ操作に必要なコンピューティングリソースの合計を CU で測定します
コンピュートグループ	FE、BE、CN などのノードタイプで構成される StarRocks コンピュートノードのグループです
FE（フロントエンド）	フロントエンドノードです。メタデータ管理、クライアント接続管理、クエリ計画、クエリスケジューリングを担当します
BE（バックエンド）	バックエンドノードです。データストレージと SQL の実行を担当します（シェアードナッシングエディション）
CN（コンピュートノード）	コンピュートノードです。ホットデータキャッシュの管理、データインポート、クエリ計算タスクの実行を担当するステートレスノードです（シェアードデータエディション）
シェアードナッシング	データをクラウドディスクまたはローカルディスクに保存し、BE ノードがデータストレージと計算の両方を処理します
シェアードデータ	データを OSS オブジェクトストレージに永続的に保存し、CN ノードが計算を処理します。ローカルディスクはキャッシュに使用します

FE ノードの役割：

• Leader：プライマリノードです。メタデータの書き込みとクラスター管理を担当します
• Follower：セカンダリノードです。Leader のメタデータを同期し、選挙に参加できます
• Observer：オブザーバーノードです。メタデータのみを同期し、選挙には参加せず、クエリの同時実行数を増やすために使用します

インスタンスタイプ

インスタンスを作成するときは、アーキテクチャタイプを選択する必要があります。

アーキテクチャタイプ	RunMode の値	ノード構成	データストレージ	データディスクタイプ	ユースケース
シェアードナッシングエディション	shared_nothing	FE + BE	クラウドディスクまたはローカルディスク	ESSD クラウドディスクまたはローカルディスク	OLAP 多次元分析、高並行クエリ、リアルタイムデータ分析、レイテンシーに敏感なシナリオ
シェアードデータエディション	shared_data	FE + CN	OSS オブジェクトストレージ	ESSD クラウドディスク（キャッシュ）	クエリ効率の要件が比較的低く、コスト重視のストレージ。データウェアハウスアプリケーションなど

シェアードナッシングアーキテクチャの特徴：

• BE ノードがデータストレージと計算の両方を処理します
• データはクラウドディスクまたはローカルディスクに保存されます
• 高性能、低レイテンシーの OLAP シナリオに適しています

シェアードデータアーキテクチャの特徴：

• データは OSS オブジェクトストレージに永続的に保存されます
• CN ノードはステートレスなコンピュートノードです。ローカルディスクは主にホットデータのキャッシュに使用されます
• コンピューティングとストレージを個別にスケーリングでき、コストをより適切に最適化できます
• テーブルタイプは CLOUD_NATIVE として識別され、ストレージパスは OSS を指します

コンピューティングリソース仕様（CU）

CU（コンピュートユニット）は、EMR Serverless StarRocks のコンピューティングリソース単位です。

CU 仕様タイプ：

仕様タイプ	SpecType の値	特徴	ユースケース
スタンダード	standard	コンピューティングとメモリのバランスが取れた構成	一般的な OLAP 分析
メモリ強化	ramEnhanced	メモリ比率が高い	複雑なクエリ、高並行処理
ネットワーク強化	networkEnhanced	ネットワーク帯域幅が広い	大量のデータをスキャンする外部テーブル分析
高性能ストレージ	localSSD	高性能なストレージアクセス	ストレージ I/O 性能要件が厳しい高 I/O シナリオ
大容量ストレージ	bigData	大容量ストレージ	極めて大量のデータ、コスト重視

注：FE ノードグループの SpecType でサポートされるのは standard のみです。上記の複数の仕様タイプは、BE/CN ノードグループにのみ適用されます。

ストレージ仕様

ストレージタイプ	性能レベル	最大 IOPS	最大スループット	ユースケース
ESSD PL0	エントリーレベル	10,000	180 MB/s	開発およびテスト
ESSD PL1	スタンダード	50,000	350 MB/s	一般的な本番環境
ESSD PL2	高性能	100,000	750 MB/s	高性能要件
ESSD PL3	超高性能	1,000,000	4,000 MB/s	超高性能要件

課金方法

課金項目：

課金項目	説明	課金方法
コンピューティングリソース（CU）	FE および BE/CN ノード用のコンピューティングリソース	サブスクリプション／従量課金
ストレージリソース	クラウドディスク、エラスティック一時ディスク、データストレージ	実際の使用量に応じて課金
バックアップストレージ	データバックアップが占有するストレージ容量	実際の使用量に応じて課金

支払い方法：

支払い方法	API パラメーター値（PayType）	説明
従量課金	postPaid	使用後に支払います。課金は毎時発生し、短期的なニーズやテストに適しています
サブスクリプション	prePaid	使用前に支払います。長期的なニーズに適しており、より費用対効果に優れています

支払い方法の変更：

• サブスクリプションから従量課金に変更できます（コンソールの機能）
• 従量課金からサブスクリプションには変更できません（インスタンスを再作成する必要があります）

コストの内訳：

Shared-nothing エディションのコスト：

• FE コンピューティングリソースのコスト（固定で 24 CU）
• BE コンピューティングリソースのコスト（設定した CU 数に基づきます）
• ストレージのコスト（ESSD クラウドディスクまたはローカルディスク）

Shared-data エディションのコスト：

• FE コンピューティングリソースのコスト（固定で 24 CU）
• CN コンピューティングリソースのコスト（設定した CU 数に基づきます）
• ストレージのコスト（OSS オブジェクトストレージ＋ESSD キャッシュディスク）

バージョンシリーズ

バージョンシリーズ	PackageType の値	特徴	用途	仕様のサポート	リージョンの制限
Standard Edition	official	全機能、本番環境向けの安定性、すべての仕様タイプをサポート	本番環境、コアビジネス	標準、メモリ強化、ネットワーク強化、高性能ストレージ、大規模ストレージをサポート	すべてのリージョンで利用可能
Trial Edition	trial	簡易設定、すぐに開始可能、標準仕様のみをサポート	学習とテスト、機能の確認、小規模アプリケーション	標準仕様のみをサポート	一部のリージョンに限定（例：北京、上海）

重要：インスタンスの作成時には PackageType（official または trial）を明示的に指定する必要があります。省略すると作成に失敗します。

バージョンシリーズの選択に関する推奨事項：

• 開発テスト、学習目的：Trial Edition を選択します
• 本番環境、高性能が必要な場合：Standard Edition を選択します

使用制限

• 名前の制限：インスタンス名は最大 64 文字で、中国語、英字、数字、ハイフン、アンダースコアを使用できます
• ノード数の制限：
  • FE ノード：1～11（奇数のみ）
  • BE ノード：3～50
  • CN ノード：1～100

推奨構成

シナリオ	RunMode	PackageType	BE SpecType	CU 構成	その他の推奨事項
開発テスト／試用	shared_data	trial	standard	8 CU	従量課金、すぐに開始可能
学習・検証	shared_data	trial	standard	8～16 CU	Trial Edition に対応するリージョンを選択します
小規模な本番環境	shared_data	official	standard	16～32 CU	サブスクリプションのほうが費用対効果に優れています
高性能 OLAP	shared_nothing	official	ramEnhanced	必要に応じて	ESSD PL2/PL3、BE ノード 3～10 台
高同時実行クエリ	shared_nothing	official	localSSD	必要に応じて	ローカル SSD ストレージ
大規模データストレージ	shared_nothing	official	bigData	必要に応じて	ローカル HDD、コストを最適化
データレイク分析	shared_data	official	networkEnhanced	必要に応じて	高帯域幅、外部テーブルのスキャン
複雑なクエリ分析	shared_data	official	ramEnhanced	必要に応じて	大容量メモリ、複数テーブルの結合

インスタンス作成ワークフロー

インスタンスを作成する際は、ユーザーとやり取りするために以下の手順に従う必要があります。確認手順を省略してはいけません：

1. リージョンの確認：対象の RegionId（例：cn-hangzhou、cn-beijing、cn-shanghai）をユーザーに確認します
2. 用途の確認：開発テスト／小規模な本番環境／大規模な本番環境を確認し、支払い方法（postPaid/prePaid）を決定します
3. バージョン系列の確認：Standard Edition（official）または Trial Edition（trial）を確認します。これは PackageType パラメーターに対応します
4. アーキテクチャタイプの確認：shared-nothing エディション shared_nothing（FE+BE）または shared-data エディション shared_data（FE+CN）を確認し、それぞれの違いを説明して推奨案を提示します
5. コンピューティング仕様の確認：Standard standard／Memory Enhanced ramEnhanced／Network Enhanced networkEnhanced などを確認します。これは BE ノードグループの SpecType パラメーターに対応します
6. CU 数とバージョンの確認：CU 数（最小 8 CU）、StarRocks のバージョン、AdminPassword を確認します
7. OSS アクセスロールの確認（すべてのアーキテクチャタイプで必須）：RAM ロール名（OssAccessingRoleName）をユーザーに確認します。このロールにより、StarRocks が OSS ストレージのデータにアクセスできるようになります。通常は AliyunEMRStarRocksAccessingOSSRole です。まだ作成されていない場合は、先に RAM コンソールで承認するようユーザーに案内します
8. 前提条件の確認：VPC、VSwitch、セキュリティグループを確認します（下記の「前提条件」を参照）
9. 設定の最終確認：インスタンス名、アーキテクチャ、バージョン系列、仕様、CU 数、支払い方法、ネットワークなど、設定の完全なチェックリストをユーザーに提示し、確認後にのみ作成を実行します

前提条件

CreateInstanceV1 を呼び出す前に、まず対象の RegionId をユーザーに確認し、以下のリソースが利用可能な状態かどうかを確認します。

⚠️ 必須：VPC と VSwitch を先に照会する必要があります

インスタンスを作成する前に、以下の 2 つの API を必ず呼び出してください：

• DescribeVpcs：対象リージョンで利用可能な VPC を照会します
• DescribeVSwitches：VPC 内で利用可能な VSwitch を照会します（ZoneId も記録します）

2 つの API がどちらも正常に呼び出されるまで、CreateInstanceV1 を実行してはいけません。

export AGENT_USER_AGENT=AlibabaCloud-Agent-Skills                              # User-Agent identifier
aliyun configure list                                                          # Credentials
# ⚠️ REQUIRED APIs - must call before CreateInstanceV1:
aliyun vpc DescribeVpcs --RegionId <RegionId>                                  # VPC (REQUIRED)
aliyun vpc DescribeVSwitches --RegionId <RegionId> --VpcId vpc-xxx             # VSwitch (REQUIRED, record ZoneId)

作成 API の主なパラメーター

CreateInstanceV1 を呼び出す際、以下のパラメーターは見落としたり混同したりしやすいため、十分注意してください：

• Version：StarRocks のバージョンパラメーター名は Version です（例："Version": "3.3"）。EngineVersion、StarRocksVersion、DBVersion ではありません。誤ったパラメーター名を使用すると、作成に失敗します
• RunMode：明示的に指定する必要があり、列挙値 shared_data（shared-data エディション）または shared_nothing（shared-nothing エディション）のみをサポートします。省略すると、作成に失敗するか、予期しないアーキテクチャタイプになる可能性があります
• RegionId：CLI の --RegionId と本文の JSON "RegionId" の両方で渡す必要があります
• ZoneId + VSwitchId + VSwitches：3 つすべてをまとめて渡す必要があります。ZoneId と VSwitchId はトップレベルのフィールドで、VSwitches は配列形式 [{"VswId":"vsw-xxx","ZoneId":"cn-hangzhou-h","Primary":true}] です
• OssAccessingRoleName：すべてのアーキテクチャタイプ（shared-nothing と shared-data の両方）で必須です。通常は AliyunEMRStarRocksAccessingOSSRole です
• FrontendNodeGroups：FE ノードグループの設定で、すべてのアーキテクチャタイプで必須です。NodeGroupName、Cu、SpecType、ResidentNodeNumber、DiskNumber、StorageSize、StoragePerformanceLevel が含まれます
• BackendNodeGroups：BE/CN ノードグループの設定で、すべてのアーキテクチャタイプで必須です。パラメーターの構造は FrontendNodeGroups と同じです
• ディスク制限：StorageSize の最小値は 200 GB、最大値は 65000 GB です（すべての CU 仕様に適用）。ディスクのパフォーマンスレベルを pl2 にアップグレードするには、ディスク容量が 500 GB 以上である必要があります

重要な原則：アーキテクチャタイプ、仕様タイプ、CU 数などをユーザーに代わって決めてはいけません。いずれも明示的に確認し、ユーザーの了承を得る必要があります。推奨案は提示できますが、最終的な選択はユーザーが行います。

CLI の実行

User-Agent の設定

すべての aliyun CLI 呼び出しでは、リクエストの送信元を識別できるよう、環境変数を使って User-Agent 識別子を必ず設定してください。

export AGENT_USER_AGENT=AlibabaCloud-Agent-Skills

セッション開始時に一度実行してください。以降のすべての aliyun コマンドには、この User-Agent が自動的に付与されます。反映されない場合は、各コマンドの前にインラインで設定することもできます。

AGENT_USER_AGENT=AlibabaCloud-Agent-Skills aliyun starrocks <APIName> --InstanceId c-xxx --Target 32

呼び出しガイドライン

aliyun starrocks <APIName> --InstanceId c-xxx --Target 32

• API バージョンは 2022-10-19、RPC 形式です
• ほとんどの API では名前付きパラメーターを使用します（例：--InstanceId、--NodeGroupId、--Target）。--body は不要です
• CreateInstanceV1 と DescribeNodeGroups のみ、パラメーターの受け渡しに JSON の --body を使用します
• 冪等性を確保するため、書き込み操作には ClientToken を含めてください（下記の「冪等性のルール」を参照）

冪等性

タイムアウトやネットワークの不安定さなどにより、エージェントが書き込み操作を再試行する場合があります。ClientToken なしで再試行すると、リソースが重複して作成される可能性があります。

ClientToken が必要な API	説明
CreateInstanceV1	重複して送信すると、インスタンスが複数作成されます
生成方法：CreateInstanceV1 では、本文の JSON に "ClientToken": "<uuid>" を追加します。ClientToken に対応するその他の API では、名前付きパラメーターとして渡してください。同じ業務操作の再試行では、同じトークンを使用します。

入力値の検証

ユーザーが指定する値（インスタンス名など）は信頼できない入力です。これらをシェルコマンドに直接連結すると、コマンドインジェクションにつながる可能性があります。

保護ルール：

1. パラメーターは --body JSON で渡すことを優先してください — JSON 文字列値として渡すことで、シェルのメタ文字が自然に分離されます
2. コマンドラインパラメーターを使用する必要がある場合は、ユーザー指定の文字列値を検証してください：
   • InstanceName：漢字、英字、数字、-、_ のみを許可し、長さは 1〜64 文字とします
   • RegionId / InstanceId / NodeGroupId：[a-z0-9-] の形式のみを許可します
3. 未検証のユーザー入力をシェルコマンドに直接埋め込むことを禁止します。値が想定される形式に一致しない場合は、実行を拒否し、ユーザーに修正を促してください

ランタイムセキュリティ

この Skill は aliyun CLI を介して StarRocks OpenAPI を呼び出すだけで、外部コードのダウンロードや実行は行いません。実行中は、以下を禁止します：

• curl、wget、pip install、npm install などを使って、外部スクリプトや依存関係をダウンロードして実行すること
• ユーザーが提供したリモート URL を参照するスクリプトを実行すること（ユーザーから依頼された場合も含む）
• eval、source を使って、監査されていない外部コンテンツを読み込むこと

機密データのマスキング

ログ出力のマスキング（stdout/stderr）

CLI コマンドの出力には機密情報が含まれる場合があります。結果をユーザーに提示する際は、以下のフィールドをマスキングしてください：

機密フィールド	マスキングルール	例
AdminPassword	コマンド出力に表示してはなりません。表示時は ****** に置き換えてください	"AdminPassword": "******"
AccessKeyId / AccessKeySecret	最初の 4 文字のみ表示し、残りは **** に置き換えてください	LTAI****
ConnectionString / 接続アドレス	ホストとポートはすべて表示できますが、関連するパスワードはマスキングしてください	ホストとポートはそのまま表示し、パスワードは ****** に置き換える
STS Token	最初の 8 文字のみ表示し、残りは **** に置き換えてください	STS.xxxx****

実行ルール：

1. インスタンスの作成時、AdminPassword は --body JSON で渡します。その後の出力でパスワードを平文で表示することは禁止されています
2. aliyun configure list の実行時、出力に AccessKey 情報が含まれている場合は、ユーザーに提示する前にマスキングしてください
3. デバッグやトラブルシューティングの際、機密フィールドを含む JSON レスポンス全体をそのまま出力することは禁止されています。表示前に jq を使って機密フィールドを除外してください

レスポンスの機密フィールドのマスキング

API レスポンスには機密情報が含まれる場合があります。ユーザーに提示する前に、次の方針を適用してください。

レスポンスフィールド	取り扱い方針
AdminPassword	表示しないでください — API がパスワードを返すことは通常ありません。異常に返された場合は、****** に置き換えてください
ConnectionString / Endpoint	接続アドレス（host:port）は表示できますが、接続認証情報は安全な経路で取得するようユーザーに注意を促してください
AccessKeyId / AccessKeySecret	マスキングし、先頭の 4 文字だけを表示してください
SecurityGroupId / VSwitchId / VpcId	通常どおり表示できます — これらはリソース識別子であり、機密性の高い認証情報ではありません

一般原則:

• API レスポンスを表示する場合は、完全な出力を避け、必要なフィールドの選択に jq を使ってください
• デバッグのために完全な JSON が必要な場合は、機密フィールドを先に除外してください：jq 'del(.AdminPassword, .AccessKeySecret)'
• パスワード、トークン、その他の認証情報をログファイルや永続ストレージに書き込むことは禁止します

インテントの振り分け

曖昧さの解消ルール：ユーザーの入力が曖昧な場合（例：「リソースが足りない」「CU をスケールアップ」「インスタンスを確認」）、会話の文脈で StarRocks への言及が明確でなければ、直接実行せず、どの製品（StarRocks / EMR Cluster / Milvus / Spark）を操作するかユーザーに確認してください。会話の文脈で StarRocks のインスタンスが明確に扱われている場合に限り、直接振り分けてください。

インテント	操作	参照ドキュメント
はじめての利用／初回ユーザー	ガイド付きの一連の手順	getting-started.md
インスタンスの作成／StarRocks の新規作成	Plan → CreateInstanceV1	instance-lifecycle.md
ステータスの確認／インスタンス一覧／インスタンスの詳細	DescribeInstances	instance-lifecycle.md
コンピュートグループの確認／ノードグループの詳細	DescribeNodeGroups	instance-lifecycle.md
アップグレード可能なバージョンの確認	QueryUpgradableVersions	operations.md
API パラメーターの検索	パラメーターリファレンス	api-reference.md

タイムアウト

操作の種類	タイムアウトの推奨値
読み取り専用クエリ	30 秒
書き込み操作	60 秒
ポーリング	1 回あたり 30 秒、合計 3 分以内

ページネーション

リスト形式の API では、PageNumber + PageSize によるページネーションを使用します。

• PageNumber：ページ番号。1 から開始し、デフォルトは 1 です
• PageSize：1 ページあたりの項目数。デフォルトは 10、最大は 100 です
• 返された結果数が PageSize と等しい場合は、次のページに進んでください

出力

• リストは主要なフィールドを含む表形式で表示してください
• タイムスタンプを読みやすい形式に変換してください
• フィールドの絞り込みには jq を使ってください

エラー処理

エラーコード	原因	エージェントの対応
Throttling	API のレート制限	5 秒待ってから再試行します。最大 3 回までです
ServiceUnavailable	サービスが一時的に利用できません	5 秒待ってから再試行します。最大 3 回までとし、それでも失敗する場合は停止してユーザーに伝えます
InvalidParameter	パラメーターが無効です	エラーメッセージを読み、パラメーターを修正します
Forbidden.RAM	RAM 権限が不足しています	不足している権限をユーザーに伝えます
OperationDenied.InstanceStatus	インスタンスのステータスではこの操作を実行できません	現在のステータスを確認し、ユーザーに待機するよう伝えます
Instance.NotFound	インスタンスが存在しないか、削除されています	DescribeInstances を使用して正しい InstanceId を検索し、ユーザーに確認します
IncompleteSignature / InvalidAccessKeyId	認証情報に誤りがあるか、有効期限が切れています	認証情報を確認するため、aliyun configure list の実行をユーザーに促します

一般原則：エラーが発生した場合は、まずエラーメッセージ全体を読みます。エラーコードだけを根拠に、むやみに再試行してはいけません。自動再試行に適しているのは Throttling のみです。それ以外のエラーは、原因を特定して修正する必要があります。

関連ドキュメント

• はじめに - 最初のインスタンスを作成するための簡易ワークフロー
• インスタンスのライフサイクル全体 - 計画、作成、管理
• 日常の運用 - 設定変更、メンテナンス、診断
• API パラメーターリファレンス - パラメーターの完全なドキュメント
• RAM 権限ポリシー - 必要な RAM 権限とポリシーの例