アカウント APIを使用してワークスペースを作成する
このページでは、 ワークスペース API を使用して、 Databricks アカウントに新しいワークスペースをデプロイする方法について説明します。
必要な設定オブジェクト
Databricks ワークスペースを作成するには、次の 2 つの構成オブジェクトを参照する必要があります。アカウント内の既存の設定を使用することも、必要に応じて新しい設定を作成することもできます。
- ストレージ構成 : データ、ライブラリ、ログなどのワークスペース資産が格納されているルート S3 バケットへのアクセスを定義し、Databricks に付与します。ストレージ構成を作成するを参照してください
- 資格情報の構成 : AWS アカウントにリソースをデプロイするためのアクセス許可を Databricks に付与します。資格情報構成の作成を参照してください。
追加の設定オブジェクト
次のいずれかの機能を使用する場合は、ワークスペースをデプロイするときに特定の構成オブジェクトを参照する必要があります。
- ネットワーク構成 : ワークスペースを自分のVPC (カスタマー管理VPC ) にデプロイするには、ネットワーク構成を参照する必要があります。 「VPC を Databricks に登録する」を参照してください。
- キー設定 : 顧客管理キーを使用してマネージドサービス、ワークスペースストレージ、またはその両方を暗号化するには、キー設定を参照する必要があります。 暗号化のための顧客管理キーの構成を参照してください。
- プライベートアクセス設定 AWS PrivateLink でプライベート接続を提供するには、プライベートアクセス設定オブジェクトを参照する必要があります。プライベートアクセス設定の管理を参照してください。
ワークスペース パラメーター参照の作成
新しいワークスペースを作成する CLI コマンド の例を次に示します。
databricks account workspaces create --json '{
"aws_region": "us-west-2",
"workspace_name": "string",
"deployment_name": "workspace-1",
"pricing_tier": "PREMIUM",
"storage_configuration_id": "b43a6064-04c1-4e1c-88b6-d91e5b136b13",
"credentials_id": "ccc64f28-ebdc-4c89-add9-5dcb6d7727d8",
"network_id": "fd0cc5bc-683c-47e9-b15e-144d7744a496",
"private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
"managed_services_customer_managed_key_id": "849b3d6b-e68e-468d-b3e5-deb08b03c56d",
"storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
"custom_tags": {
"property1": "string",
"property2": "string"
}
}'
標準 パラメーター
aws_region: ワークスペースのコンピュートプレーンの AWSリージョン。 Databricks のクラウドとリージョンを参照してください。workspace_name：人間にとってわかりやすいワークスペースの名前。これは、Databricks UIでユーザーに表示されるワークスペース名です。deployment_name: (推奨されますが、省略可能) ワークスペースの一意のデプロイ名。詳細については、 ワークスペース API リファレンスを参照してください。custom_tags: リソースを整理するためのメタデータとして機能するキーと値のペア。タグは、リソースの管理、識別、整理、検索、フィルタリング、およびコストと属性の使用状況の監視に役立ちます。pricing_tier: ワークスペースの価格レベル。PREMIUM、ENTERPRISE、またはCOMMUNITY_EDITIONstorage_configuration_id: ストレージ コンフィギュレーション ID は、ルート S3 バケットを表します。既存の構成を使用するか、新しいストレージ構成を作成します。credentials_id: 資格情報の構成 ID。既存の設定を使用するか 、新しい認証情報設定を作成します。
高度な構成
次の省略可能なパラメーターを使用して、ワークスペースのネットワーク機能とセキュリティ機能を構成します。
network_id: ネットワーク構成 ID。顧客管理VPCにワークスペースをデプロイする場合に必要です。 「VPC を Databricks に登録する」を参照してください。private_access_settings_id: AWS PrivateLink を有効にするために使用されるプライベートアクセス設定オブジェクトの ID。プライベートアクセス設定の管理を参照してください。すべての接続の種類 (フロントエンド、バックエンド、またはその両方) の PrivateLink アクセスに必要です。ワークスペースをデプロイするときに構成する必要があります。managed_services_customer_managed_key_id: マネージドサービスのキー設定 ID は、キー設定オブジェクトのcustomer_managed_key_idフィールドです。 ノートブックなどのマネージドサービスやコントロールプレーン内のシークレットデータを暗号化するために使用されます。 マネージドサービスとワークスペースストレージの両方を暗号化する場合は、storage_customer_managed_key_idフィールドに同じIDを使用します。 ワークスペースをデプロイするときに構成する必要があります。マネージドサービスの顧客管理キーを参照してください。storage_customer_managed_key_id: ワークスペースストレージのキー設定 ID (キー設定オブジェクトのcustomer_managed_key_idフィールド)。マネージドサービスとワークスペースストレージの両方を暗号化する場合は、managed_services_customer_managed_key_idフィールドに同じIDを使用します。 ワークスペースストレージの暗号化にのみ使用されます。ワークスペースをデプロイするときに構成する必要があります。ワークスペース ストレージの顧客管理キーを参照してください。
ワークスペースの応答を作成する
ワークスペースの作成 API を呼び出すと、次のような応答が表示されます。
{
"account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
"aws_region": "string",
"creation_time": 0,
"credentials_id": "c7814269-df58-4ca3-85e9-f6672ef43d77",
"custom_tags": {
"property1": "string",
"property2": "string"
},
"deployment_name": "string",
"managed_services_customer_managed_key_id": "faacdc79-6530-4583-a154-5d427a663e53",
"network_id": "d6797cf4-42b9-4cad-8591-9dd91c3f0fc3",
"pricing_tier": "PREMIUM",
"private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
"storage_configuration_id": "04aae505-1b1e-4cb9-997d-e1c49282675d",
"storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
"workspace_id": 1614665312930232,
"workspace_name": "string",
"workspace_status": "PROVISIONING",
"workspace_status_message": "Workspace resources are being set up."
}
ワークスペースの作成時にエラーが発生した場合は、「 ワークスペースの作成エラーのトラブルシューティング」を参照してください。
新しいワークスペースを確認する
ワークスペースのステータスを確認するには、get workspace APIを呼び出します。
ワークスペースの作成時に返されたJSON応答のworkspace_id値を使用します。
応答では、可能なworkspace_status値は次のとおりです。
NOT_PROVISIONED：まだプロビジョニングされていません。PROVISIONING：まだプロビジョニング中です。 数分待ってから、このAPIリクエストを繰り返します。RUNNING：デプロイメントが正常に完了し、現在実行されています。FAILED：デプロイメントに失敗しました。BANNED：禁止されています。CANCELLING：キャンセル処理中。
失敗したステータス値を処理する方法については、 ワークスペース作成エラーのトラブルシューティング を参照してください。
例えば：
curl -X GET
'https://accounts.cloud.databricks.com/api/2.0/accounts/<databricks-account-id>/workspaces/<databricks-workspace-id>' \
--header 'Authorization: Bearer $OAUTH_TOKEN'
応答：
{
"workspace_id": 123456789,
"workspace_name": "my-company-example",
"aws_region": "us-west-2",
"creation_time": 1579768294842,
"deployment_name": "my-company-example",
"workspace_status": "RUNNING",
"account_id": "<databricks-account-id>",
"credentials_id": "<aws-credentials-id>",
"storage_configuration_id": "<databricks-storage-config-id>",
"workspace_status_message": "Workspace is running.",
"network_id": "339f16b9-b8a3-4d50-9d1b-7e29e49448c3",
"managed_services_customer_managed_key_id": "<aws-kms-managed-services-key-id>",
"storage_customer_managed_key_id": "<aws-kms-notebook-workspace-storage-id>",
"pricing_tier": "ENTERPRISE"
}
この例では、ワークスペースのステータス（workspace_status）がRUNNINGに設定されているため、成功しました。PROVISIONINGの場合は、成功するまでこのAPIリクエストを繰り返します。
価格は、デフォルトでアカウントに関連付けられているプランになります。AWSプラットフォーム層を参照してください。
新しいワークスペースのステータスがRUNNINGになったら、新しいワークスペースをテストします。
-
新しいワークスペースでのユーザーインターフェイスログイン — URL で Web アプリケーションにログインできることを確認します
https://<deployment-name>.cloud.databricks.com。 たとえば、ワークスペースの作成時に指定したデプロイメント名がABCSalesの場合、ワークスペースの URL はhttps://abcsales.cloud.databricks.comになります。 アカウントのユーザー名を使用してログインします。 -
新しいワークスペースでのREST APIログイン — REST APIにアクセスできることを確認します。次の例では、ワークスペースユーザーAPIを呼び出してユーザーのリストを取得します。
Bashcurl -u <user-name> -X GET 'https://<deployment-name>.cloud.databricks.com/api/2.0/scim/v2/Users' \
--header 'Authorization: Bearer $OAUTH_TOKEN'Databricks REST APIの使用に関するその他の認証オプションなどの詳細については、ワークスペース APIを参照してください。
デプロイ後の PrivateLink 構成 (省略可能)
このステップは、 AWS PrivateLink を設定する場合にのみ必要です。
ワークスペースの作成後：
- フロントエンド PrivateLink 接続を実装している場合は、 「手順 5: 受信 Private Link の DNS を構成する」で説明されているように、関連する DNS 構成の変更を実装します。
- オプションで、「 ステップ 5: 他の AWS サービスの VPC エンドポイントを追加する」の説明に従って、他の VPC エンドポイントを作成します。
その他のオプションのデプロイ後構成
新しいワークスペースに対して、次のオプションの構成手順を検討することをお勧めします。
IP アクセス リストの有効化
Web アプリケーション、 REST API、 JDBC/ODBC エンドポイント、および DBConnect に接続できる IP アドレスを構成します。 許可リストとブロックリストは、IP アドレスまたは範囲として指定できます。 ワークスペースの IP アクセス リストの構成を参照してください。
監査ログシステムテーブルの有効化
Databricksは、Databricksユーザーが行ったアクティビティと発生した使用状況を監視するために、監査ログシステムテーブルを有効にすることを強く推奨します。ワークスペースではUnity Catalog有効になっている必要があります。 手順については、システムテーブルのリファレンスを参照してください。
ワークスペースの作成エラーのトラブルシューティング
次のセクションでは、一般的なワークスペース作成エラーの解決策を説明します。
アドレスの最大数に達しました
Databricks がユーザーに代わって VPC を作成する場合は、少なくとも 1 つの未使用の Elastic IP が必要です。そうしないと、VPC は作成されず、次のエラーが発生します。
The maximum number of addresses has been reached.
Elastic IPの数を増やして、う一度お試しください。
一般的なトラブルシューティング手順
すべてのワークスペース作成エラーについては、次のトラブルシューティング手順を記載された順序で試してください。
ネットワークの検証
ワークスペースの作成手順または状態チェックの手順でネットワーク関連のエラーが示されている場合は、 ネットワーク構成の取得 API を呼び出して、ネットワーク設定が正しいことを確認します。
応答で、warning_messages error_messagesフィールドを表示します。両方の配列が空の場合、警告やエラーはありません。
そうでない場合は、警告とエラーのJSONオブジェクトを注意深く確認してください。
- 警告の場合、
warning_typeの列挙は、問題がサブネットかセキュリティグループのどちらかにあったことを示します。warning_messageには、追加の詳細が記載されています。（NATゲートウェイではなく）ファイアウォールまたはNATインスタンスがある場合、ネットワーク検証によって常に警告が発行されることに注意してください。 - エラーの場合、
error_typeの列挙は認証情報、VPC、サブネット、セキュリティグループ、ネットワークACLのいずれかに問題があったことを示します。error_messageには、追加の詳細が記載されています。
インフラストラクチャの問題を修正する
ネットワーク設定取得APIのAPIリクエストに対するレスポンスのエラーに応じて、次のことを確認します。
- セキュリティ グループは、 顧客管理VPC の要件に準拠しています。
- クロスアカウント IAM ポリシーに必要な権限が含まれています。展開タイプに使用するポリシーの資格情報構成の作成を参照してください。
失敗したワークスペースを更新する
失敗したワークスペースを更新するには、 ワークスペースの更新 API を呼び出します。
同じAPIを使用して、実行中の（正常にデプロイされた）ワークスペースを更新できますが、変更できるのは資格情報とネットワーク設定のみです。
これらのワークスペース構成フィールドを渡して変更できます：credentials_id、storage_configuration_id、network_id、managed_services_customer_managed_key_id、およびstorage_customer_managed_key_id
workspace_status値がPROVISIONINGを返す場合は、 get ワークスペース APIを使用してRUNNING状態を引き続き確認します。
ワークスペースの更新に失敗した場合は、ネットワークとワークスペースを再作成します
ワークスペースの更新 API が機能しない場合は、ネットワークを削除して再作成する必要があります (独自の VPC を指定した場合)、失敗したワークスペースを次の順序で再作成する必要があります。
-
ワークスペースの削除 API を使用してワークスペースを削除します。
-
独自の VPC を提供した場合は、 ネットワーク設定の削除 API を使用してネットワーク設定を削除します。
-
vpc_id、subnet_ids、security_group_idsの正しい値を使用してネットワークを再作成します。 -
credentials_id、storage_configuration_id、network_id、managed_services_customer_managed_key_id、storage_customer_managed_key_idの正しい値を使用してワークスペースを再作成します。workspace_status値PROVISIONINGを取得した場合は、get ワークスペース APIを使用してRUNNING状態を確認します。