Docker Hub で公開 Docker イメージを格納するように、Azure コンテナー レジストリではプライベート Docker コンテナー イメージを格納および管理します。 また、Kubernetes にアプリケーションをデプロイするパッケージ形式である Helm chart (プレビュー) のリポジトリをホストすることもできます。 レジストリ リポジトリで特定のアクションが発生した場合に、webhook を使用してイベントをトリガーできます。 webhook では、レジストリ レベルでイベントに応答したり、特定のリポジトリ タグに範囲を絞ったりできます。 Geo レプリケートされたレジストリを使用して、特定のリージョン レプリカ内のイベントに応答するように各 Webhook を構成します。
Webhook のエンドポイントはレジストリからパブリックにアクセスできる必要があります。 セキュリティで保護されたエンドポイントに対して認証されるように、レジストリの Webhook 要求を構成できます。
webhook 要求の詳細については、「Azure Container Registry webhook スキーマ リファレンス」を参照してください。
Important
HTTPS を使用し、Authorization ヘッダー内でのみ webhook 資格情報を送信します。 Azure Container Registryは、webhook イベント履歴のAuthorizationヘッダー値をマスクします。 サービス URI 内、他のカスタム ヘッダー内、または要求本文や応答本文内で資格情報はマスクされません。
サービス URI のどこにもパスワード、アクセス トークン、API キー、またはその他のシークレットを含めないでください。 この制限には、ホスト名の前にある資格情報(たとえば、https://user:password@host)、パス、およびクエリ文字列が含まれます。 また、クエリ文字列に認証トークンを含む署名付きコールバック URL も含まれます。
Authorization以外のカスタム ヘッダーにはシークレットを含めないでください。 詳細については、「Webhook 資格情報の保護」を参照してください。
前提条件
- Azure Container Registry - コンテナー レジストリを Azure サブスクリプションで作成します。 たとえば、Azure Portal または Azure CLI を使用します。 Azure Container Registry サービス レベルには Webhook のさまざまなクォータがあります。
- Docker CLI - ローカル コンピューターを Docker ホストとして設定し、Docker CLI コマンドにアクセスするには、Docker エンジンをインストールします。
Webhook の作成 - Azure portal
- Azure ポータル にサインインしてください。
- webhook を作成したいコンテナー レジストリに移動します。
- サービス で Webhooks を選択します。
- webhook ツールバーで [追加] を選択します。
- 次の情報を利用して、 [webhook の作成] フォームを完成させます。
| 値 | 説明 |
|---|---|
| Webhook名 | Webhook に付与する名前。 使用できる文字は英数字のみです。文字数は 5 ~ 50 文字にする必要があります。 |
| 場所 | geo レプリケートされたレジストリの場合は、レジストリ レプリカの Azure リージョンを指定します。 |
| サービス URI | Webhook が POST 通知を送信する HTTPS URI。 URI 内のどこにもパスワード、アクセス トークン、API キー、またはその他のシークレットを含めないでください。 この規則は、ホスト名の前にある資格情報 (たとえば、https://user:password@host)、パス、およびクエリ文字列に適用されます。 |
| カスタムヘッダー | POST 要求と共に渡すヘッダー。 "キー: 値" の形式にする必要があります。
Authorization ヘッダーでのみ資格情報を送信します。 他のヘッダーには、パスワード、アクセス トークン、API キー、またはその他のシークレットは含めないでください。 webhook イベント履歴では、 Authorization ヘッダー値のみがマスクされます。 |
| トリガー アクション | Webhook をトリガーするアクション。 アクションには、イメージのプッシュ、イメージの削除、Helm chart のプッシュ、Helm chart の削除、およびイメージの検疫などがあります。 Webhook をトリガーするアクションを 1 つ以上選択できます。 |
| Status | Webhook の作成後の状態。 既定で有効です。 |
| Scope | Webhook が動作するスコープです。 指定しない場合、スコープはレジストリ内のすべてのイベントです。 リポジトリまたはタグは、"リポジトリ:タグ" または "リポジトリ:*"(あるリポジトリ以下のすべてのタグの場合)という形式を使用して指定できます。 |
Webhook フォームの例:
Webhook の作成 - Azure CLI
Azure CLI を使用して Webhook を作成するには、az acr webhook create コマンドを使用します。 次のコマンドは、レジストリ mycontainerregistry 内のすべてのイメージの delete イベントに対して Webhook を作成します。
az acr webhook create --registry mycontainerregistry --name myacrwebhook01 --actions delete --uri https://webhookuri.com --headers "Authorization=$WEBHOOK_AUTH"
Webhook 資格情報を保護する
Azure Container Registry は Webhook 構成を格納し、ご使用のエンドポイントに送信する要求を応答と共に Webhook イベント履歴に記録します。 資格情報が漏えいするリスクを軽減するには、次のガイドラインに従ってください:
- HTTPS サービス URI を使用します。 HTTP 経由で資格情報を送信しないでください。
-
Authorizationヘッダーにのみ資格情報を送信します。 Webhook イベント履歴で、Azure Container Registry は、記録された要求ヘッダーと応答ヘッダーにあるAuthorizationヘッダーの値をマスクします。 - 資格情報を他の場所に保存しないでください。 Azure Container Registryは、webhook イベント履歴でこれらの値をマスクしません。
- ホスト名の前の認証情報 (たとえば、
https://user:password@host)、パス、クエリ文字列を含むサービス URI。 -
Authorization以外のカスタム ヘッダー。 - リクエストボディとレスポンスボディ。
- ホスト名の前の認証情報 (たとえば、
- エンドポイントが応答本文または
Authorization以外の応答ヘッダーで資格情報をエコーしないようにします。 - 資格情報を隠すためにエンコードに依存しないでください。 URL エンコード、Base64 エンコード、シェルでのクォートはシークレットを保護しません。
- Webhook 構成を読み取ることができるユーザーを制限します。
Microsoft.ContainerRegistry/registries/webhooks/getCallbackConfig/actionアクセス許可を持つユーザーは、構成されたサービス URI と、マスクされていないAuthorizationヘッダー値を含むすべてのカスタム ヘッダーを読み取ることができます。Microsoft.ContainerRegistry/registries/webhooks/listEvents/actionアクセス許可を持つユーザーは、webhook イベント履歴を読み取ることができますが、マスクされていないAuthorizationヘッダー値を表示することはできません。 所有者や共同作成者などの組み込みロールには、これらのアクセス許可が含まれます。 - 資格情報がこれまでに、サービス URI 内、別のカスタム ヘッダー内、または要求本文もしくは応答本文内に含まれていた場合は、その資格情報を失効またはローテーションしてください。
Webhook をテストする
Azure portal
Webhook を使用する前に、 [Ping] ボタンを使ってテストできます。 Ping は、指定されたエンドポイントに一般的な POST 要求を送信し、応答をログに記録します。 ping 機能を使用して、webhook が正しく構成されていることを確認できます。
- テストするWebhookを選択してください。
- 上部のツールバーで、 [Ping] を選択します。
- [HTTP の状態] 列でエンドポイントの応答を確認します。
Azure CLI
Azure CLI を使用して ACR Webhook をテストするには、az acr webhook ping コマンドを使用します。
az acr webhook ping --registry mycontainerregistry --name myacrwebhook01
結果を表示するには、az acr webhook list-events コマンドを使用します。
az acr webhook list-events --registry mycontainerregistry08 --name myacrwebhook01
Webhookを削除
Azure portal
Azure Portal で webhook を選択してから [削除] ボタンをクリックすると、各 webhook を削除できます。
Azure CLI
az acr webhook delete --registry mycontainerregistry --name myacrwebhook01
次のステップ
Webhook スキーマ リファレンス
Azure Container Registry によって出力される JSON イベント ペイロードの形式とプロパティについて詳しくは、Webhook のスキーマ リファレンスをご覧ください。
Azure Container Registry webhook スキーマ リファレンス
Event Grid のイベント
この記事で説明したネイティブ レジストリ Webhook イベントだけでなく、Azure Container Registry は Event Grid に対してイベントを生成できます。