アーティファクトレジストリを使ってみる

備考

ベータ版

この機能はベータ版です。使用するには、ワークスペース管理者が Previews ページから Databricks アーティファクトレジストリ を有効にする必要があります。Databricksのプレビューを管理するを参照してください。Databricks は、アーティファクトレジストリが一般提供（GA）される際にその価格を発表します。

アーティファクトレジストリを使用して、Dockerでコンテナイメージをプッシュし、Unity Catalogでガバナンスを適用します。

このページでは、認証の構成、アクセスの付与、イメージのプッシュ、および検出を行う方法について説明します。概念と制限事項については、アーティファクトレジストリを参照してください。コマンドまたは操作が失敗した場合は、アーティファクトレジストリのトラブルシューティングを参照してください。

要件

始める前に、以下を用意する必要があります：

アーティファクトレジストリをサポートするリージョンのワークスペース。制限事項を参照してください。
ローカルマシンにインストールされている、バージョン 1.18.0 以降の Databricks CLI (コマンドラインインターフェイス)。
ローカルコンピューターにインストールされている Docker CLI。
ワークスペースからアクセス可能な既存のUnity Catalogカタログおよびスキーマ。
お使いの操作に対する Unity Catalog の権限。

Docker認証をセットアップする

Databricks CLIには、ワークスペースレジストリの認証情報を要求するようにDockerを構成する実験的なコマンドが含まれています。databricks auth login によって作成されたワークスペースの OAuth プロファイルが Docker 資格情報ヘルパーで必要になります。個人用アクセストークン、OAuth マシン間 (M2M) 資格情報、またはアカウントのみの認証を使用するプロファイルはサポートされていません。

ターゲットワークスペースのプロファイルを作成または更新します。
Bash
```
databricks auth login --profile <profile>
```
ワークスペースレジストリの Docker 認証を設定します：
Bash
```
databricks auth docker configure --profile <profile>
```
--profile <profile>を省略すると、デフォルトの Databricks CLIプロファイルが使用されます。

Databricks CLIはレジストリのリージョンを推測し、ワークスペースレジストリのホスト名を出力します。このホスト名は、イメージをプッシュするときに使用します。

権限を付与

アーティファクトレジストリではカタログやスキーマは作成されません。両方が Unity Catalog にすでに存在し、ワークスペースからアクセスできる必要があります。

アーティファクトレジストリは、Unity Catalogの権限を使用してイメージへのアクセスを制御します。次の表は、各操作に対する最小権限の付与を示しています。より広範な管理権限によって、一部の操作が許可される場合もあります。

オペレーション	最小権限の付与
新しいアーティファクトをプッシュする	`USE CATALOG`、 `USE SCHEMA` 、および `CREATE VOLUME`
新しいバージョンをプッシュするか、タグを移動します	`USE CATALOG`、 `USE SCHEMA` 、および `WRITE VOLUME`
アーティファクトとバージョンを検出する	`USE CATALOG`、 `USE SCHEMA` 、および `READ METADATA`
サポートされているワークロードでイメージを使用する	`USE CATALOG`、 `USE SCHEMA` 、および `READ VOLUME`

オペレーション	最小権限の付与
新しいアーティファクトをプッシュする	`USE CATALOG`、 `USE SCHEMA` 、および `CREATE VOLUME`
新しいバージョンをプッシュするか、タグを移動します	`USE CATALOG`、 `USE SCHEMA` 、および `WRITE VOLUME`
アーティファクトとバージョンを検出する	`USE CATALOG`、 `USE SCHEMA` 、および `READ METADATA`
サポートされているワークロードでイメージを使用する	`USE CATALOG`、 `USE SCHEMA` 、および `READ VOLUME`

アーティファクトレジストリ専用のスキーマの場合、管理者はスキーマレベルで権限を付与できます。スキーマレベルの権限は、後で作成されるオブジェクトを含め、スキーマ内の一致するすべてのオブジェクトに適用されます。互いのアーティファクトを変更できないようにする必要があるパブリッシャーには、別々のスキーマを使用します。各プリンシパルには、その操作に必要な権限のみを付与してください。次のステートメントを実行する前に、例の値を置き換え、不要な権限ステートメントを削除してください。

SQL
GRANT USE CATALOG ON CATALOG <catalog> TO `<principal>`;
GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT CREATE VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT WRITE VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT READ METADATA ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT READ VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;

CREATE VOLUME、WRITE VOLUME、READ METADATA、および READ VOLUME の詳細については、Unity Catalog 権限リファレンスを参照してください。その他の付与方法については、権限の表示、付与、および取り消しを参照してください。

イメージをプッシュする

ワークスペースレジストリのホスト名をイメージの catalog.schema.artifact:tag 名とともに使用します。

レジストリのホスト名を取得する

databricks auth docker configureによって出力されたレジストリのホスト名を使用します。プロファイルのホスト名を後で見つけて、そのDockerクレデンシャルヘルパーが設定されているかどうかを確認するには、次を実行します。

Bash
databricks auth docker host --profile <profile>

ホスト名を手動で作成する必要がある場合は、数値のワークスペースIDとワークスペースのリージョンを使用してください。ワークスペースIDを確認するには、ワークスペースインスタンス名、URL、IDを参照してください。

ワークスペースのリージョンを確認するには、アカウントコンソールを開き、 [ワークスペース] を選択します。

次のホスト名を使用します：

Text
<workspace-id>.container.<region>.gcp.databricks.com

アーティファクト名の要件

重要

アーティファクト名は、<catalog>.<schema>.<artifact>形式の完全修飾 Unity Catalog 名である必要があります。名前にスラッシュを使用しないでください。Unity Catalogのオブジェクト階層を参照してください。

<artifact>セグメントには最大255文字まで含めることができます。小文字、数字、アンダースコア、ハイフンのみを使用してください。先頭と末尾は文字または数字にする必要があります。連続するアンダースコアは2つまでとし、アンダースコアの隣にハイフンを配置しないでください。

イメージのタグ付けとプッシュ

警告

画像に資格情報やその他の機密データを含めないでください。プッシュする前に画像を確認してください。アーティファクトのバージョンはイミュータブルであり、削除リクエストはサポートされていません。機密データをプッシュした場合は、直ちにローテーションまたは取り消しを行い、影響を受けたアーティファクトに適用される READ VOLUME の付与を制限するよう管理者に依頼してください。影響を受けるダイジェストとそれに対応するすべてのタグの使用を停止し、ヘルプをリクエストする際に含める情報を参照してください。

アーティファクトレジストリ用のローカルイメージにタグ付けします。

Bash
docker tag <local-image>:<local-tag> \
  <registry-hostname>/<catalog>.<schema>.<artifact>:<tag>

イメージをプッシュします：

Bash
docker push <registry-hostname>/<catalog>.<schema>.<artifact>:<tag>

イメージとバージョンの検出

Software Artifacts APIを使用して、カタログとスキーマ内のアーティファクトをリストし、アーティファクトのバージョンをリストします。

注記

アーティファクトレジストリのイメージを一覧表示、管理するための専用のDatabricks CLIコマンドは提供されていません。Software Artifacts APIを呼び出すには databricks api を使用してください。

以下の例では、 Docker 認証用に構成したプロファイルを使用します。デフォルト Databricks CLI プロファイルである場合は、 --profile <profile> を省略します。

アーティファクトをリストする

アーティファクトをリストするには、次のコマンドを実行します。

Bash
databricks api get --profile <profile> \
  "/api/2.1/unity-catalog/software-artifacts?parent=schemas/<catalog>.<schema>"

応答には、アーティファクト名と所有者が含まれます。応答に next_page_token が含まれている場合は、次のページを取得するためにその値を page_token クエリーパラメーターに渡します (例: &page_token=<next_page_token>)。

バージョンの一覧表示

アーティファクトのバージョンをリストするには、次のコマンドを実行します。

Bash
databricks api get --profile <profile> \
  "/api/2.1/unity-catalog/software-artifacts/<catalog>.<schema>.<artifact>/versions"

レスポンスには、各バージョンのイメージダイジェスト、タグ、およびimage_acceleration_details.statusが含まれます。応答の制限事項については、制限事項を参照してください。

画像アクセラレーションのステータスを確認する

アーティファクトのバージョンレスポンスから image_acceleration_details.status を読み取ります：

ステータス	意味
`SUCCESS`	画像アクセラレーションが正常に完了しました。
`UNSPECIFIED`	成功した画像アクセラレーションの結果が記録されていません。このステータスは障害を特定するものではありません。

ステータス	意味
`SUCCESS`	画像アクセラレーションが正常に完了しました。
`UNSPECIFIED`	成功した画像アクセラレーションの結果が記録されていません。このステータスは障害を特定するものではありません。

サポートされている Databricks ワークロードで画像を使用する

イメージをアーティファクトレジストリにプッシュした後は、サポートされている Databricks ワークロードを作成する際にそのイメージを参照します。

要件​

Docker認証をセットアップする​

権限を付与​

イメージをプッシュする​

レジストリのホスト名を取得する​

アーティファクト名の要件​

イメージのタグ付けとプッシュ​

イメージとバージョンの検出​

アーティファクトをリストする​

バージョンの一覧表示​

画像アクセラレーションのステータスを確認する​

サポートされている Databricks ワークロードで画像を使用する​

その他のリソース​

要件