Azure Cosmos DBの今回の更新で押さえるべき結論は、データベースとコンテナーを操作するCosmosDBShellの管理系コマンドが、Entra IDなどでARMコンテキストを利用できる場合はAzure Resource Manager（ARM）経由を優先するようになったことです。一方で、ドキュメントや実装上、アイテム単位の読み書き・更新・削除は引き続きCosmos DBのデータプレーンを使います。アカウントキー、エミュレーター、静的トークンでの接続は従来どおりデータプレーンへフォールバックするため、すぐに全利用者の運用が壊れる変更ではありません。(GitHub)
ただし、Entra ID、マネージドID、DefaultAzureCredential、MCP/Copilot系のワークフローでCosmosDBShellを使っている管理者・開発者は、「管理系操作には管理プレーン権限、アイテム操作にはデータプレーンRBACが必要になる」という権限設計を見直す必要があります。特にCI/CDや複数サブスクリプション環境では、--subscription と --resource-group を明示しないと、意図しない探索や権限不足で詰まる可能性があります。
Azure Cosmos DBの今回の更新は何が変わったのか
2026年5月19日にAzure/CosmosDBShellのPull Request #75がマージされ、データベース・コンテナー管理コマンドでAzure Resource Managerを優先する変更が反映されました。PRの要約では、ARMコンテキストが利用できる場合はデータベースとコンテナーのコマンドをARM経由で実行し、利用できない場合はCosmos DBデータプレーンへフォールバックすると説明されています。(GitHub)
この変更を一言でいうと、CosmosDBShellが「管理する操作」と「データを扱う操作」をより明確に分けるようになったということです。
Azureでは、リソース作成や設定変更などの管理操作はコントロールプレーン、実データの読み書きはデータプレーンとして扱われます。Microsoft Learnでも、Azure Cosmos DBデータベースの作成はコントロールプレーン、データベース内のデータ照会はデータプレーンの例として説明されています。(Microsoft Learn)
今回のCosmosDBShell更新は、この考え方に沿って、データベースやコンテナーの管理操作をARMに寄せるものです。
| 操作の種類 | 代表例 | 変更後の主な実行経路 |
|---|---|---|
| データベース管理 | mkdb、rmdb、データベース一覧 | ARMコンテキストがあればARM、なければデータプレーン |
| コンテナー管理 | mkcon、rmcon、settings <con>、indexpolicy | ARMコンテキストがあればARM、なければデータプレーン |
| ナビゲーション・補完 | ls、cd、入力補完、存在確認 | DB/コンテナー対象はARM優先 |
| アイテム操作 | rm、replace、コンテナー内のアイテム一覧 | データプレーン |
| アカウント概要設定 | settings | データプレーン |
PRのルーティング表でも、ls、cd、mkdb、mkcon、rmdb、rmcon、settings <con>、indexpolicyなどはARM優先になり、rm、replace、アイテムのlsなどはデータプレーンに残ると整理されています。(GitHub)
影響を受ける利用者と、影響が小さい利用者
今回の更新は、Azure Cosmos DBそのもののデータモデルやAPIを突然変えるものではありません。主に影響するのは、CosmosDBShellを使ってデータベースやコンテナーを作成・削除・確認している人です。
影響が大きいケース
次のような環境では、確認をおすすめします。
| 利用パターン | 確認すべきポイント |
|---|---|
| Entra IDでCosmosDBShellに接続している | ARM経由の管理操作に必要なAzure RBAC権限があるか |
| マネージドIDを使っている | 管理プレーン権限とデータプレーン権限を分けて付与しているか |
| DefaultAzureCredentialで接続している | 実行環境でどのIDが選ばれているか |
| CI/CDでCosmosDBShellを使う | --connect-subscription、--connect-resource-groupを明示しているか |
| 複数サブスクリプションを扱う | 自動探索ではなく明示的なARM座標指定にしているか |
| MCP/Copilot系のクライアントからCosmosDBShellを使う | AIクライアントに渡る出力や削除操作の承認フローを確認しているか |
CosmosDBShellの接続ドキュメントでは、ARMコンテキストが付与されるのは、Visual Studio Code Credential、Managed Identity、Interactive Browser、Device Code、DefaultAzureCredentialなどのEntra ID系フローとされています。アカウントキー、エミュレーター、COSMOSDB_SHELL_TOKENではARMコンテキストは付与されず、データプレーンへフォールバックします。(GitHub)
影響が比較的小さいケース
一方で、次の利用者は大きな影響を受けにくいと考えられます。
| 利用パターン | 理由 |
|---|---|
| Cosmos DBエミュレーターだけで検証している | ARMコンテキストを使わず、従来どおりデータプレーンへフォールバックする |
| アカウントキー接続のみを使っている | ARM優先にはならず、既存のデータプレーン権限で動く |
| アイテムのクエリや更新だけを行っている | アイテム操作は引き続きデータプレーン |
| Azure CLIやBicepなど別手段でDB/コンテナーを管理している | CosmosDBShellの管理系コマンドを使わなければ直接影響は限定的 |
ただし、「影響が小さい」は「確認不要」という意味ではありません。特に本番環境でキー認証を避け、Entra IDとRBAC中心の設計にしている場合は、権限不足やフォールバック時の挙動を事前にテストしておくべきです。
ARM優先になるコマンドと、データプレーンのままのコマンド
今回の更新で混乱しやすいのは、「CosmosDBShell全体がARMに切り替わる」と誤解してしまう点です。実際には、データベース・コンテナーというリソース管理に近い操作だけがARM優先になります。
ARM優先になる主な管理系コマンド
CosmosDBShellのコマンドドキュメントでは、データベースとコンテナー管理コマンドは、ARMコンテキストがある場合にAzure Resource Managerを優先すると説明されています。Entra ID接続では、必要に応じて--subscriptionと--resource-groupを指定して明示的に対象アカウントを決められます。(GitHub)
代表的なコマンドは次のとおりです。
| コマンド | 用途 | 確認ポイント |
|---|---|---|
ls | データベース・コンテナー一覧 | アイテム一覧とは実行経路が異なる場合がある |
cd | データベース・コンテナーへの移動 | 存在確認でARMが使われる可能性がある |
mkdb | データベース作成 | 管理プレーンの作成権限が必要 |
mkcon | コンテナー作成 | パーティションキー指定と管理権限を確認 |
rmdb | データベース削除 | 削除権限と承認フローが重要 |
rmcon | コンテナー削除 | 本番環境では誤削除防止策が必須 |
settings <con> | コンテナー設定確認 | ARM経由とデータプレーン経由で取得できる項目差に注意 |
indexpolicy | インデックスポリシー確認・更新 | 設定変更として扱い、変更管理に含める |
データプレーンのままの主な操作
アイテムに対する操作は、引き続きCosmos DBデータプレーンを使います。
| 操作 | 用途 | 実務上の注意点 |
|---|---|---|
query | SQLクエリ実行 | RU消費や取得件数を確認 |
print | IDとパーティションキーでアイテム取得 | パーティションキーの型に注意 |
mkitem | アイテム作成・Upsert | 本番データへの誤投入を防ぐ |
replace | アイテム置換 | ETagや階層型パーティションキーに注意 |
patch | 部分更新 | 配列操作や数値加算の対象を確認 |
rm | アイテム削除 | パターン指定による削除範囲を必ず確認 |
PRの要約でも、アイテムレベルのコマンドはデータプレーンのままと明記されています。(GitHub)
なぜARMを使うようになったのか
ARMを優先するメリットは、単に「新しい経路に変わった」ことではありません。Azureの管理プレーンとして扱うことで、RBAC、Activity Log、Azure Policy、管理ロックなど、Azureリソース管理の文脈に乗せやすくなります。Microsoft Learnでは、ARMがコントロールプレーン要求を処理し、Azure RBAC、Azure Policy、管理ロック、Activity Logsなどの管理機能を適用できると説明されています。(Microsoft Learn)
Azure Cosmos DBのデータベースやコンテナーは、アプリケーションの実データを保持する一方で、作成・削除・設定変更はインフラ変更に近い操作です。これらをARM経由に寄せることで、次のような運用上の利点があります。
権限を「管理」と「データアクセス」に分けやすい
たとえば、開発者にはコンテナー内のアイテム読み書きだけを許可し、データベースやコンテナーの削除は運用管理者だけに許可する、といった設計がしやすくなります。
逆に、これまでアカウントキーで何でもできる前提の運用をしていた場合は、権限設計の粗さが表面化します。これは不便に見えますが、本番環境では望ましい方向です。
監査しやすくなる
データベース作成、コンテナー削除、インデックスポリシー変更のような操作は、障害やコスト増に直結します。ARM経由に寄せることで、Azure側の管理ログや権限設計と整合しやすくなります。
Entra IDベースの運用と相性がよい
Microsoft LearnのCosmos DB RBACドキュメントでは、本番やセキュリティ重視のワークロードではキーベース認証を無効化し、Entra IDとデータプレーンRBACを使うことが推奨されています。CosmosDBShellの接続ドキュメントでも同様に、Azure AD/Entra IDとRBACを使う方向が説明されています。(GitHub)
管理者が確認すべき設定
今回の更新後に管理者が見るべきポイントは、コマンドの成否だけではありません。誰が、どのIDで、どの経路から、どのリソースを管理できるのかを確認することが重要です。
管理プレーン権限を確認する
ARM経由でデータベースやコンテナーを扱う場合、対象IDには管理プレーン権限が必要です。CosmosDBShellの接続ドキュメントでは、ARM使用時には、アイテム操作向けのデータプレーンRBACに加えて、データベース・コンテナーリソース向けのAzure管理プレーン権限が必要になると説明されています。(GitHub)
実務では、次のように分けて確認すると整理しやすくなります。
| 確認項目 | 見るべき内容 |
|---|---|
| 実行ID | ユーザー、サービスプリンシパル、マネージドIDのどれか |
| 管理プレーン権限 | Cosmos DBアカウント、データベース、コンテナー管理に必要なAzure RBACがあるか |
| データプレーン権限 | アイテム読み書きに必要なCosmos DBネイティブRBACがあるか |
| スコープ | サブスクリプション全体ではなく、必要なリソースグループやアカウントに絞っているか |
| 削除操作 | rmdb、rmconを誰が実行できるか |
最小権限を重視するなら、「アプリケーション実行IDにコンテナー削除権限を持たせない」「CI/CD用IDだけに特定環境の作成・更新権限を付ける」など、役割ごとに分けるのが現実的です。
データプレーンRBACを確認する
アイテム操作はデータプレーンのままなので、ARM権限だけでは不十分です。
たとえば、mkconでコンテナーを作成できても、queryでアイテムを読めない場合があります。逆に、アイテムを読めても、mkdbやrmconが失敗する場合もあります。
Cosmos DBのネイティブデータプレーンRBACでは、スコープをアカウント全体、特定データベース、特定コンテナーなどに設定できます。Microsoft Learnでは、相対スコープとして/dbs/<database-name>/colls/<container-name>や、全データベース・コンテナーを示す/の例が示されています。(Microsoft Learn)
複数サブスクリプション環境ではARM座標を明示する
CosmosDBShellは、ARMコンテキストがある場合、接続中のデータプレーンエンドポイントとアクセス可能なサブスクリプションを照合してARMアカウントを探索できます。ただし、CI/CDや複数サブスクリプション環境では、対象を明示する方が安全です。ドキュメントでは、--subscriptionと--resource-groupを指定する例が掲載されています。(GitHub)
例:
connect https://myaccount.documents.azure.com:443/ \
--tenant=<tenant-id> \
--subscription=<subscription-id> \
--resource-group=<resource-group>起動時に接続する場合は、次のように指定できます。
cosmosdbshell \
--connect https://myaccount.documents.azure.com:443/ \
--connect-tenant=<tenant-id> \
--connect-subscription=<subscription-id> \
--connect-resource-group=<resource-group>本番環境では、サブスクリプションやリソースグループを省略して「自動で見つかるはず」という運用にしない方が安全です。探索対象が広がると、権限不足、曖昧な一致、意図しないアカウント選択の原因になります。
開発者が確認すべき移行・展開上の注意点
開発者がまず確認すべきなのは、日常的に使っているCosmosDBShellコマンドが、管理系なのか、アイテム操作なのかです。失敗時の原因も、今後は「Cosmos DBに接続できない」だけではなく、「ARM側の権限がない」「データプレーンRBACがない」「ARMコンテキストが付いていない」などに分かれます。
接続方式ごとの挙動を理解する
| 接続方式 | ARMコンテキスト | 管理系コマンドの挙動 |
|---|---|---|
| Entra IDの対話ログイン | 付与される | ARM優先 |
| Managed Identity | 付与される | ARM優先 |
| DefaultAzureCredential | 付与される | ARM優先 |
| Visual Studio Code Credential | 付与される | ARM優先 |
| AccountKey | 付与されない | データプレーンへフォールバック |
COSMOSDB_SHELL_TOKEN | 付与されない | データプレーンへフォールバック |
| Emulator | 付与されない | データプレーンへフォールバック |
この違いを知らないと、ローカルではアカウントキーで成功したのに、CI/CDのマネージドIDでは権限不足で失敗する、といった問題が起きます。
エラーの切り分け方
管理系コマンドが失敗した場合は、次の順に確認すると効率的です。
| 症状 | 主な原因 | 確認すること |
|---|---|---|
mkdbやmkconが失敗する | 管理プレーン権限不足 | Azure RBACでCosmos DB管理権限があるか |
queryやprintが失敗する | データプレーンRBAC不足 | Cosmos DBネイティブRBACのスコープとDataActions |
| アカウント探索に時間がかかる | 複数サブスクリプション探索 | --subscription、--resource-groupを明示 |
| キー無効化環境で管理コマンドが失敗する | 非Entra接続でARMに届いていない | Entra ID接続に切り替える |
| MCP経由の操作が危険に見える | AIクライアントが削除系コマンドを実行可能 | 削除操作の手動承認、権限の縮小 |
ローカル検証と本番運用を同じ前提にしない
ローカルではエミュレーターやアカウントキー接続を使うことがあります。この場合、管理系コマンドはデータプレーンへフォールバックするため、ARM優先の挙動を十分に検証できません。
本番に近い検証をするなら、少なくともステージング環境で次を確認してください。
connect https://myaccount.documents.azure.com:443/ \
--tenant=<tenant-id> \
--subscription=<subscription-id> \
--resource-group=<resource-group>
ls
mkdb TestDb
mkcon TestContainer /tenantId
settings TestContainer
rmcon TestContainer
rmdb TestDb削除コマンドを試す場合は、必ず検証用リソースで実行してください。rmdbやrmconは、失敗すれば権限不足を見つけられますが、成功すれば実際に削除されます。
キー認証を無効化している環境で注意すべきこと
セキュリティ重視の環境では、キーベース認証を無効化し、Entra IDとRBACでCosmos DBを使う構成が増えています。この場合、今回の更新は特に重要です。
CosmosDBShellの接続ドキュメントでは、アカウントキー、静的トークン、エミュレーター接続ではARMコンテキストが付かないため、mkdb、mkcon、rmdb、rmcon、indexpolicy、コンテナーsettingsなどのリソースコマンドはデータプレーンへフォールバックすると説明されています。さらに、実Azure Cosmos DBアカウントでネイティブデータプレーンRBACが強制され、キー認証やコントロールプレーン書き込みが無効化されている場合、それらのコマンドはサービス側で拒否される可能性があるとされています。(GitHub)
つまり、次のような運用は避けるべきです。
# キー無効化・RBAC強制の本番アカウントで、静的トークンやキー前提の操作を続ける
connect "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=..."
mkcon Orders /tenantId推奨される方向は、Entra IDベースで接続し、必要に応じてARM座標を明示することです。
connect https://myaccount.documents.azure.com:443/ \
--tenant=<tenant-id> \
--subscription=<subscription-id> \
--resource-group=<resource-group>このとき、実行IDには次の2種類の権限が必要です。
| 権限 | 必要な場面 |
|---|---|
| Azure管理プレーン権限 | DB/コンテナーの作成、削除、設定変更 |
| Cosmos DBデータプレーンRBAC | アイテムの読み取り、作成、更新、削除、クエリ |
「ARM権限を付けたからクエリも通る」「データプレーンContributorを付けたからコンテナー作成も通る」と考えると、切り分けで時間を失います。
MCP/Copilot連携での注意点
今回の更新は、CosmosDBShellをMCPサーバーとして使う場合にも関係します。MCPドキュメントでは、MCPサーバーはローカルでユーザー権限により動作し、接続クライアントはデータベース・コンテナーメタデータの読み取り、ドキュメントの取得、リソースの作成・更新・削除などを実行できると説明されています。また、ARMコンテキストが付いているEntra ID接続では、データベース・コンテナーのリソース操作がARM経由で実行されます。(GitHub)
ここで重要なのは、AIやCopilot系のクライアントが「便利な操作窓口」になるだけでなく、削除や設定変更を実行できる操作面にもなることです。
MCP/Copilot連携を使う場合は、次の対策を実施してください。
| リスク | 対策 |
|---|---|
| プロンプト経由で削除操作が実行される | rmdb、rmconなどは手動承認を必須にする |
| 出力に機密データが含まれる | クエリ結果やファイル内容を外部LLMに送る前提で扱う |
| 過剰権限のIDでMCPを起動する | 読み取り専用、検証用、管理用でIDを分ける |
| ポート公開による不正操作 | ローカルホストに限定し、不要時はMCPを無効化 |
| 複数サブスクリプションで対象が曖昧 | --connect-subscriptionと--connect-resource-groupを明示 |
MCPドキュメントでも、外部LLMへコマンド出力やクエリ結果が送信される可能性、最小権限RBAC、削除操作の承認、不要時のMCP無効化などがベストプラクティスとして示されています。(GitHub)
展開前チェックリスト
今回の更新を受けて、管理者と開発者は次の順番で確認すると実務に落とし込みやすくなります。
| 確認項目 | 実施内容 | 優先度 |
|---|---|---|
| CosmosDBShellの利用箇所 | ローカル、CI/CD、MCP、運用手順書で使っているか洗い出す | 高 |
| 接続方式 | Entra ID、Managed Identity、DefaultAzureCredential、AccountKey、Token、Emulatorを分類 | 高 |
| 管理系コマンド | mkdb、mkcon、rmdb、rmcon、settings、indexpolicyの利用有無を確認 | 高 |
| ARM座標 | CI/CDと複数サブスクリプション環境で明示指定する | 高 |
| Azure RBAC | 管理プレーン権限が過不足なく付いているか確認 | 高 |
| データプレーンRBAC | アイテム操作に必要なロールとスコープを確認 | 高 |
| キー無効化環境 | 非Entra接続で管理系コマンドを使っていないか確認 | 中 |
| MCP/Copilot | 削除操作の承認、出力データの取り扱い、起動IDの権限を確認 | 中 |
| 監査ログ | 変更操作の記録とレビュー手順を確認 | 中 |
| ロールバック手順 | 変更前の設定、権限、手順書を保存 | 中 |
特に本番運用では、CosmosDBShellのバージョン更新やドキュメント更新だけを見て終わらせず、実際の接続方式ごとにコマンドを実行して確認することが重要です。
よくある誤解と失敗しやすいポイント
「ARMになったのでデータ操作もAzure RBACだけでよい」は誤解
今回ARM優先になったのは、データベースやコンテナーの管理系操作です。アイテムの読み書きやクエリはデータプレーンのままです。
そのため、Azure管理プレーンのロールだけを付与しても、queryやprintが成功するとは限りません。データプレーンRBACを別途確認してください。
「アカウントキーなら今までどおり安全」は誤解
アカウントキー接続は従来どおり動きやすい一方で、権限を細かく分けにくい運用です。セキュリティ重視の本番環境では、キー無効化とEntra IDベースのRBACを検討する価値があります。
ただし、既存スクリプトを急にEntra IDへ切り替えると、管理プレーン権限とデータプレーン権限の不足が顕在化します。段階的に検証しましょう。
「CI/CDでは自動探索で十分」は危険
複数サブスクリプションを扱う組織では、自動探索に任せるとトラブルの原因になります。CI/CDでは、対象のsubscription、resource group、アカウントエンドポイントを明示し、実行IDの権限を最小限に絞る方が安全です。
「MCP/Copilotは読み取り補助だけ」は危険
MCP経由のCosmosDBShellは、設定次第で作成・更新・削除も実行できます。AIアシスタントに自然文で指示できることは便利ですが、権限が強すぎると誤操作の影響も大きくなります。
本番アカウントでは、MCP用IDを分離し、削除系コマンドは承認なしに実行できない運用にしてください。
今回の更新を受けて次にやるべきこと
Azure Cosmos DBの今回のCosmosDBShell更新は、単なるコマンド実装の変更ではなく、Cosmos DB運用を管理プレーンとデータプレーンに分けて整理するきっかけになります。
まず、CosmosDBShellをどこで使っているかを洗い出してください。次に、接続方式ごとにARMコンテキストが付くかを確認し、管理系コマンドに必要なAzure RBACと、アイテム操作に必要なCosmos DBデータプレーンRBACを分けて点検します。
特に優先すべき対応は次の3つです。
- CI/CDや複数サブスクリプション環境では、
--subscriptionと--resource-groupを明示する - Entra ID接続では、管理プレーン権限とデータプレーンRBACを両方確認する
- MCP/Copilot連携では、削除操作の承認と出力データの取り扱いを見直す
この3点を押さえておけば、今回のARM優先化を安全に取り込みつつ、Azure Cosmos DBの運用をより監査しやすく、最小権限に近い形へ改善できます。
コメント