使用 Azure 容器注册表 webhook

Azure 容器注册表可存储和管理专用 Docker 容器映像,其方式类似于 Docker Hub 存储公共 Docker 映像。 它还可托管 Helm Chart(预览版)的存储库;Helm Chart 是一种将应用程序部署到 Kubernetes 的打包格式。 可以使用 Webhook 在其中一个注册表存储库中发生特定操作时触发事件。 Webhook 可在注册表级别响应事件,或者可限定为响应特定存储库标记范围内的事件。 通过异地复制注册表,可将每个 Webhook 配置为响应特定区域副本中的事件。

Webhook 的终结点必须可由注册表公开访问。 可以配置注册表 Webhook 请求来对安全终结点进行身份验证。

有关 Webhook 请求的详细信息,请参阅 Azure 容器注册表 Webhook 架构参考。

Important

使用 HTTPS,并仅在 Authorization 标头中发送 Webhook 凭据。 Azure 容器注册表屏蔽 Authorization Webhook 事件历史记录中的标头值。 它不会屏蔽服务 URI、其他自定义标头或请求或响应正文中的凭据。

不要在服务 URI 中的任何位置包括密码、访问令牌、API 密钥或其他机密。 此限制包括主机名前的凭据(例如,https://user:password@host)、路径和查询字符串。 它还包括在其查询字符串中包含身份验证令牌的已签名回调 URL。 不要在 Authorization 之外的任何自定义标头中包含机密。 有关详细信息,请参阅 保护 Webhook 凭据。

先决条件

创建 Webhook - Azure 门户

  1. 登录 Azure 门户。

  2. 导航到要在其中创建 Webhook 的容器注册表。

  3. 在服务下,选择Webhooks。

  4. 在 webhook 工具栏中选择 添加。

  5. 使用以下信息完成创建 webhook窗体:

值 说明
Webhook 名称 想要赋予 webhook 的名称。 它只能包含字母和数字,且长度必须为 5-50 个字符。
位置 对于异地复制注册表,请指定注册表副本的 Azure 区域。
服务 URI Webhook 应在其中发送 POST 通知的 HTTPS URI。 不要在 URI 中的任何位置包括密码、访问令牌、API 密钥或其他机密。 此规则适用于主机名前的凭据(例如 https://user:password@host)、路径和查询字符串。
自定义标头 想要随 POST 请求一起传递的标头。 它们的格式应该为:“键: 值”。 仅在标头中 Authorization 发送凭据。 不要在任何其他标头中包含密码、访问令牌、API 密钥或其他机密。 在 Webhook 事件历史记录中,仅屏蔽 Authorization 标头值。
触发操作 触发 webhook 的操作。 操作包括映像推送、映像删除、Helm Chart 推送、Helm Chart 删除和映像隔离。 可选择一个或多个操作来触发 Webhook。
状态 Webhook 创建后的状态。 默认启用。
Scope Webhook 生效的作用域。 如果未指定,则范围为注册表中的所有事件。 可通过使用“存储库:标记”格式指定存储库或标记的范围,或使用“存储库:*”格式指定某个存储库下的所有标记。

示例 Webhook 窗体:

显示 Azure 门户中 ACR Webhook 创建 U I 的屏幕截图。

创建 Webhook - Azure CLI

若要使用 Azure CLI 创建 webhook,请使用 az acr webhook create 命令。 以下命令为注册表 mycontainerregistry 中的所有映像删除事件创建 Webhook:

az acr webhook create --registry mycontainerregistry --name myacrwebhook01 --actions delete --uri https://webhookuri.com --headers "Authorization=$WEBHOOK_AUTH"

保护 Webhook 凭据

Azure 容器注册表 存储 Webhook 配置,并在 Webhook 事件历史记录中记录 webhook 向你的终结点发送的请求及其响应。 若要降低泄露凭据的风险,请遵循以下准则:

  • 使用 HTTPS 服务 URI。 不要通过 HTTP 发送凭据。

  • 仅在标头中 Authorization 发送凭据。 在 Webhook 事件历史记录中,Azure 容器注册表 会对记录的请求和响应标头中的 Authorization 标头值进行掩码处理。

  • 不要将凭据放在其他任何位置。 Azure 容器注册表不会在 Webhook 事件历史记录中屏蔽这些值:

    • 服务 URI,包括主机名前的凭据(例如 https://user:password@host)、路径和查询字符串。

    • 除 Authorization 外的自定义标头。

    • 请求和响应正文。

  • 确保终结点不会在其响应正文中或除 Authorization 之外的响应标头中回显凭据。

  • 不要依赖编码来隐藏凭据。 URL 编码、Base64 编码和 shell 引用不会保护机密。

  • 限制谁可以读取 Webhook 配置。 具有 Microsoft.ContainerRegistry/registries/webhooks/getCallbackConfig/action 权限的用户可以读取配置的服务 URI 和所有自定义标头,包括未屏蔽的 Authorization 标头值。 具有 Microsoft.ContainerRegistry/registries/webhooks/listEvents/action 权限的用户可以读取 Webhook 事件历史记录,但无法查看未屏蔽的 Authorization 标头值。 “所有者”和“参与者”等内置角色包括这些权限。

  • 如果凭据以前包含在服务 URI、另一个自定义标头或请求或响应正文中,请撤销或轮换该凭据。

测试 webhook

Azure 门户

使用 Webhook 之前,可使用 Ping 按钮对它进行测试。 Ping 将向指定的终结点发送泛型 POST 请求并记录响应。 使用 ping 功能可帮助验证是否已正确配置 Webhook。

  1. 选择想要测试的 webhook。

  2. 在顶部工具栏中,选择 Ping。

  3. 在 HTTP 状态 列中检查终结点的响应。

Azure 门户中的 ACR Webhook 创建 UI

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 门户

每个 webhook 均可通过在 Azure 门户中选择 webhook,然后选择 删除 按钮进行删除。

Azure CLI

az acr webhook delete --registry mycontainerregistry --name myacrwebhook01

后续步骤

Webhook 架构参考

有关 Azure 容器注册表 发出的 JSON 事件负载的格式和属性的详细信息,请参阅 Webhook 架构参考:

Azure 容器注册表 webhook 架构描述参考