Azure Container Registry のアーティファクトキャッシュ

[アーティクル]
09/29/2024

アーティファクトキャッシュ機能を使用すると、ユーザーはコンテナーイメージをプライベートコンテナーレジストリにキャッシュできます。アーティファクトキャッシュは、Basic、Standard、Premium のサービスレベルで利用できます。

アーティファクトキャッシュは、パブリックリポジトリとプライベートリポジトリの両方にキャッシュソリューションを提供することで、コンテナーイメージの管理を強化します。

アーティファクトキャッシュは、Azure Container Registry (ACR) を通じたより高速で "信頼性の高いプル操作" を提供し、geo レプリケーションや可用性ゾーンのサポートなどの機能を利用して、より高い可用性と高速なイメージプルを実現します。

アーティファクトキャッシュによって、ユーザーがファイアウォール構成とコンプライアンス標準にシームレスに従うために "プライベートネットワーク" 経由でキャッシュされたレジストリにアクセスすることが可能になります。

アーティファクトキャッシュは、パブリックレジストリによって課されるプル制限の課題を解決します。アップストリームのソース資格情報を使用してキャッシュルールを認証することをお勧めします。次に、レート制限の軽減に役立つように、ローカル ACR からイメージをプルします。

用語

キャッシュ規則 - キャッシュ規則は、サポートされているリポジトリからキャッシュに成果物をプルするために作成できる規則です。
- キャッシュ規則には、次の 4 つの部分が含まれています。
  - 規則名 - キャッシュ規則の名前。たとえば、「 Hello-World-Cache 」のように入力します。
  - ソース - ソースレジストリの名前。
  - リポジトリパス - キャッシュする成果物を検索および取得するリポジトリのソースパス。たとえば、「 docker.io/library/hello-world 」のように入力します。
  - 新しい ACR リポジトリ名前空間 - 成果物を格納するための新しいリポジトリパスの名前。たとえば、「 hello-world 」のように入力します。このリポジトリは、ACR インスタンス内に既に存在していることはできません。
資格情報
- 資格情報は、ソースレジストリのユーザー名とパスワードのセットです。パブリックリポジトリまたはプライベートリポジトリで認証するには、資格情報が必要です。資格情報には 4 つの部分が含まれています
  - 資格情報 - 資格情報の名前。
  - ソースレジストリログインサーバー - ソースレジストリのログインサーバー。
  - ソース認証 - 資格情報を格納するキーコンテナーの場所。
  - ユーザー名とパスワードのシークレット - ユーザー名とパスワードを含むシークレット。

制限事項

キャッシュは、使用可能なコンテナーイメージで少なくとも 1 つのイメージプルが完了した後にのみ発生します。新しいイメージが使用可能になるたびに、新しいイメージプルが完了する必要があります。アーティファクトキャッシュは、新しいタグが利用できるようになっても、新しいタグのイメージを自動的にはプルしません。これはロードマップに含まれていますが、このリリースではサポートされていません。
アーティファクトキャッシュがサポートしているキャッシュルール数は 1,000 までです。

アップストリームのサポート

アーティファクトキャッシュが現在サポートしているアップストリームレジストリは以下のとおりです。

警告

お客様は、Docker Hub からコンテンツを取得するために資格情報セットを生成する必要があります。

アップストリームレジストリ	サポート	可用性
Docker Hub	認証されているプルのみがサポートされます。	Azure CLI、Azure portal
Microsoft アーティファクトレジストリ	認証されていないプルのみがサポートされます。	Azure CLI、Azure portal
AWS Elastic Container Registry (ECR) パブリックギャラリー	認証されていないプルのみがサポートされます。	Azure CLI、Azure portal
GitHub Container Registry	認証されたプルと認証されていないプルの両方がサポートされます。	Azure CLI、Azure portal
Quay	認証されたプルと認証されていないプルの両方がサポートされます。	Azure CLI、Azure portal
registry.k8s.io	認証されたプルと認証されていないプルの両方がサポートされます。	Azure CLI
Google Container Registry	認証されたプルと認証されていないプルの両方がサポートされます。	Azure CLI

ワイルドカード

ワイルドカードでは、アスタリスク (*) を使用し、コンテナーイメージレジストリ内の複数のパスを照合します。アーティファクトキャッシュが現在サポートしているワイルドカードは以下のとおりです。

Note

キャッシュルールは、ターゲットリポジトリからソースリポジトリにマップされます。

レジストリレベルのワイルドカード

レジストリレベルのワイルドカードを使用すると、アップストリームレジストリからすべてのリポジトリをキャッシュできます。

キャッシュルール	マッピング	例
contoso.azurecr.io/* => mcr.microsoft.com/*	ACR の下にあるすべてのイメージを MCR にマッピング。	contoso.azurecr.io/myapp/image1 => mcr.microsoft.com/myapp/image1 contoso.azurecr.io/myapp/image2 => mcr.microsoft.com/myapp/image2

リポジトリレベルのワイルドカード

リポジトリレベルのワイルドカードを使用すると、アップストリームレジストリマッピングからリポジトリプレフィックスにすべてのリポジトリをキャッシュできます。

キャッシュルール	マッピング	例
contoso.azurecr.io/dotnet/* => mcr.microsoft.com/dotnet/*	ACR 下の特定のリポジトリをそれに対応する MCR のリポジトリにマッピングします。	contoso.azurecr.io/dotnet/sdk => mcr.microsoft.com/dotnet/sdk contoso.azurecr.io/dotnet/runtime => mcr.microsoft.com/dotnet/runtime
contoso.azurecr.io/library/dotnet/* => mcr.microsoft.com/dotnet/* contoso.azurecr.io/library/python/* => docker.io/library/python/*	ACR 下の特定のリポジトリを、さまざまなアップストリームレジストリからリポジトリにマッピングします。	contoso.azurecr.io/library/dotnet/app1 => mcr.microsoft.com/dotnet/app1 contoso.azurecr.io/library/python/app3 => docker.io/library/python/app3

ワイルドカードベースのキャッシュルールの制限事項

ワイルドカードキャッシュルールでは、アスタリスク (*) を使用し、コンテナーイメージレジストリ内の複数のパスを照合します。これらのルールは、他のワイルドカードキャッシュルールと重複できません。つまり、特定のレジストリパスにワイルドカードキャッシュルールがある場合、それと重複する別のワイルドカードルールを追加することはできません。

重複するルールの例をいくつか次に示します。

例 1:

既存のキャッシュルール: contoso.azurecr.io/* => mcr.microsoft.com/*
追加される新しいキャッシュ: contoso.azurecr.io/library/* => docker.io/library/*

ターゲットリポジトリパス contoso.azurecr.io/library/* が既存のワイルドカードルール contoso.azurecr.io/* と重複するため、新しいキャッシュルールの追加はブロックされます。

例 2:

既存のキャッシュルール: contoso.azurecr.io/library/* =>mcr.microsoft.com/library/*
追加される新しいキャッシュ: contoso.azurecr.io/library/dotnet/* =>docker.io/library/dotnet/*

ターゲットリポジトリパス contoso.azurecr.io/library/dotnet/* が既存のワイルドカードルール contoso.azurecr.io/library/* と重複するため、新しいキャッシュルールの追加はブロックされます。

静的/固定キャッシュルールの制限事項

静的または固定キャッシュルールはもっと具体的なものであり、ワイルドカードは使用しません。ワイルドカードベースのキャッシュルールと重複してもかまいません。キャッシュルールが固定のリポジトリパスを指定する場合は、ワイルドカードベースのキャッシュルールとの重複が許可されます。

例 1:

既存のキャッシュルール: contoso.azurecr.io/* =>mcr.microsoft.com/*
追加される新しいキャッシュ: contoso.azurecr.io/library/dotnet =>docker.io/library/dotnet

contoso.azurecr.io/library/dotnet は静的パスであり、ワイルドカードキャッシュルール contoso.azurecr.io/* と重複しても良いため、新しいキャッシュルールの追加は許可されます。

アーティファクトキャッシュを有効にする - Azure CLI

以下の手順に従うことで、Azure CLI を使用して認証有りまたは無しで Azure Container Registry のアーティファクトキャッシュを有効にすることができます。

前提条件

この記事のサンプルコマンドは、Azure Cloud Shell または Azure CLI のローカルインストールを使用して実行できます。これをローカルで使用したい場合は、バージョン 2.46.0 以降が必要です。 az --version を実行してバージョンを確認します。インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。
資格情報を格納するための既存の Key Vault があります。 Key Vault での資格情報の作成と格納に関する詳細を確認してください。
Key Vault からシークレットを設定および取得できます。 Key Vault からシークレットを設定および取得する方法の詳細を確認してください。

資格情報を使用せずにキャッシュルールを構成して作成します。

az acr Cache create コマンドを実行してキャッシュルールを作成します。
- たとえば、特定の MyRegistry Azure Container Registry の資格情報セットがないキャッシュルールを作成します。
```
az acr Cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu-
```
az acr Cache show コマンドを実行してキャッシュルールを表示します。
- たとえば、特定の MyRegistry Azure Container Registry のキャッシュルールを表示します。
```
 az acr Cache show -r MyRegistry -n MyRule
```

資格情報を作成する

資格情報を構成する前に、Azure KeyVault にシークレットを作成して格納し、Key Vault からシークレットを取得する必要があります。 Key Vault での資格情報の作成と格納に関する詳細を確認してください。そして Key Vault でシークレットの設定と取得を行うこと。

az acr credential set create コマンドを実行して、資格情報を作成します。

たとえば、特定の MyRegistry Azure Container Registry の資格情報を作成します。

az acr credential-set create 
-r MyRegistry \
-n MyDockerHubCredSet \
-l docker.io \ 
-u https://MyKeyvault.vault.azure.net/secrets/usernamesecret \
-p https://MyKeyvault.vault.azure.net/secrets/passwordsecret

az acr credential set update を実行して、資格情報セットのユーザー名またはパスワード KV シークレット ID を更新します。
- たとえば、資格情報のユーザー名またはパスワード KV シークレット ID を更新するには、特定の MyRegistry Azure Container Registry を設定します。
```
az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.net/secrets/newsecretname
```
az acr credential-set show を実行して資格情報を表示します。
- たとえば、特定の MyRegistry Azure Container Registry の資格情報セットを表示します。
```
az acr credential-set show -r MyRegistry -n MyDockerHubCredSet
```

資格情報を使用してキャッシュルールを構成して作成する

az acr cache create コマンドを実行してキャッシュルールを作成します。
- たとえば、特定の MyRegistry Azure Container Registry の資格情報を使用してキャッシュルールを作成します。
```
az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet
```
az acr cache update コマンドを実行して、キャッシュルールの資格情報を更新します。
- たとえば、特定の MyRegistry Azure Container Registry のキャッシュルールで資格情報を更新します。
```
az acr cache update -r MyRegistry -n MyRule -c NewCredSet
```
- たとえば、特定の MyRegistry Azure Container Registry の既存のキャッシュルールから資格情報を削除します。
```
az acr cache update -r MyRegistry -n MyRule --remove-cred-set
```
az acr cache show コマンドを実行してキャッシュルールを表示します。
- たとえば、特定の MyRegistry Azure Container Registry のキャッシュルールを表示します。
```
 az acr cache show -r MyRegistry -n MyRule
```

アクセスポリシーを使用して Key Vault にアクセス許可を割り当てる (レガシ)

Key Vault にアクセスするために使用されているシステム ID のプリンシパル ID を取得します。

PRINCIPAL_ID=$(az acr credential-set show 
                -n MyDockerHubCredSet \ 
                -r MyRegistry  \
                --query 'identity.principalId' \ 
                -o tsv)

イメージをプルする前に、az keyvault set-policy コマンドを実行して、キーコンテナーへのアクセス権を割り当てます。
- たとえば、資格情報のアクセス許可を割り当てるには、KeyVault シークレットにアクセスします
```
az keyvault set-policy --name MyKeyVault \
--object-id $PRINCIPAL_ID \
--secret-permissions get
```

イメージをプルする

レジストリログインサーバー名、リポジトリ名、および目的のタグで Docker コマンドを使用して、キャッシュからイメージをプルします。
- たとえば、特定のレジストリログインサーバー myregistry.azurecr.io の目的のタグ latest を使用してリポジトリ hello-world からイメージをプルする場合などです。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

リソースのクリーンアップ

az acr cache list コマンドを実行して、Azure Container Registry のキャッシュルールを一覧表示します。
- たとえば、特定の MyRegistry Azure Container Registry のキャッシュルールを一覧表示します。
```
 az acr cache list -r MyRegistry
```
az acr cache delete コマンドを実行して、キャッシュルールを削除します。
- たとえば、特定の MyRegistry Azure Container Registry のキャッシュルールを削除します。
```
az acr cache delete -r MyRegistry -n MyRule
```
az acr credential set list を実行して、Azure Container Registry 内の資格情報を一覧表示します。
- たとえば、特定の MyRegistry Azure Container Registry の資格情報を一覧表示します。
```
az acr credential-set list -r MyRegistry
```
az acr credential-set delete を実行して資格情報を削除します。
- たとえば、特定の MyRegistry Azure Container Registry の資格情報を削除します。
```
az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet
```

アーティファクトキャッシュを有効にする - Azure portal

以下の手順に従うことで、Azure portal を使用して認証有りまたは無しで Azure Container Registry のアーティファクトキャッシュを有効にすることができます。

前提条件

Azure ポータル
資格情報を格納するための既存の Key Vault があります。 Key Vault での資格情報の作成と格納に関する詳細を確認してください。
ロールベースのアクセス (RBAC) コントロールのない既存のキーコンテナーがあること。

資格情報を使用せずにアーティファクトキャッシュを構成する

Azure portal で、手順に従ってキャッシュ規則を作成します。

自分の Azure Container Registry に移動します。
サイドの [メニュー] の [サービス] で [キャッシュ] を選びます。
[規則の作成] を選択します。
[New cache rule] (新しいキャッシュ規則) のウィンドウが表示されます。
[規則名] を入力します。
ドロップダウンメニューから、[ソース] レジストリを選択します。
キャッシュする成果物の [リポジトリのパス] を入力します。
プライベートリポジトリにアクセスしたり、認証済みのプルを実行したりしていない場合は、認証をスキップできます。
[宛先] で、キャッシュ対象の成果物を保存する新しい ACR リポジトリ名前空間の名前を入力します。
[保存] を選択します。
レジストリログインサーバー名、リポジトリ名、および目的のタグで Docker コマンドを使用して、キャッシュからイメージをプルします。
- たとえば、特定のレジストリログインサーバー myregistry.azurecr.io の目的のタグ latest を使用してリポジトリ hello-world からイメージをプルする場合などです。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

認証を使用してアーティファクトキャッシュを構成する

Azure portal で、手順に従ってキャッシュ規則を作成します。

自分の Azure Container Registry に移動します。
サイドの [メニュー] の [サービス] で [キャッシュ] を選びます。
[規則の作成] を選択します。
[New cache rule] (新しいキャッシュ規則) のウィンドウが表示されます。
[規則名] を入力します。
ドロップダウンメニューから、[ソース] レジストリを選択します。
キャッシュする成果物の [リポジトリのパス] を入力します。
リポジトリに認証を追加するために、[認証] ボックスをオンにします。
[Create new credentials] (新しい資格情報の作成) を選択して、ソースレジストリのユーザー名とパスワードを保存するための新しい資格情報セットを作成します。新しい資格情報を作成する方法を確認してください。
資格情報の準備ができたら、ドロップダウンメニューから資格情報を選択します。
[宛先] で、キャッシュ対象の成果物を保存する新しい ACR リポジトリ名前空間の名前を入力します。
[保存] を選択します。
レジストリログインサーバー名、リポジトリ名、および目的のタグで Docker コマンドを使用して、キャッシュからイメージをプルします。
- たとえば、特定のレジストリログインサーバー myregistry.azurecr.io の目的のタグ latest を使用してリポジトリ hello-world からイメージをプルする場合などです。
```
 docker pull myregistry.azurecr.io/hello-world:latest
```

新しい資格情報を作成する

[資格情報]>[資格情報の作成] の順に移動します。
ソースレジストリの新しい資格情報の [名前] を入力します。
[Source Authentication] (ソース認証) を選択します。アーティファクトキャッシュが現在サポートしているのは、[Key Vault から選択] と [シークレット URI を入力] です。
[キーコンテナーから選択する] オプションの場合、キーコンテナーを使用した資格情報の作成について詳しく学習してください。
[作成] を選択します。

次のステップ

次の記事に進み、レジストリキャッシュのトラブルシューティングガイドを確認してください。

次の方法で共有

Azure Container Registry のアーティファクトキャッシュ

用語

制限事項

アップストリームのサポート