使用客户管理的密钥加密注册表Encrypt registry using a customer-managed key

当你在 Azure 容器注册表中存储映像和其他项目时,Azure 会自动使用服务托管的密钥对注册表内容进行静态加密。When you store images and other artifacts in an Azure container registry, Azure automatically encrypts the registry content at rest with service-managed keys. 可以使用你在 Azure Key Vault 中创建和管理的密钥(客户管理的密钥),通过一个附加的加密层来补充默认加密。You can supplement default encryption with an additional encryption layer using a key that you create and manage in Azure Key Vault (a customer-managed key). 本文将引导你使用 Azure CLI 和 Azure 门户完成这些步骤。This article walks you through the steps using the Azure CLI and the Azure portal.

使用客户管理的密钥进行服务器端加密是通过与 Azure Key Vault 集成来实现的:Server-side encryption with customer-managed keys is supported through integration with Azure Key Vault:

  • 你可以创建自己的加密密钥并将其存储在密钥保管库中,或使用 Azure Key Vault 的 API 来生成密钥。You can create your own encryption keys and store them in a key vault, or use Azure Key Vault's APIs to generate keys.
  • 使用 Azure Key Vault 还可以审核密钥的使用情况。With Azure Key Vault, you can also audit key usage.
  • 当 Azure Key Vault 中有新的密钥版本时,Azure 容器注册表支持自动轮换注册表加密密钥。Azure Container Registry supports automatic rotation of registry encryption keys when a new key version is available in Azure Key Vault. 你还可以手动轮换注册表加密密钥。You can also manually rotate registry encryption keys.

此功能在“高级”容器注册表服务层级中可用。This feature is available in the Premium container registry service tier. 若要了解注册表服务层和限制,请参阅 Azure 容器注册表服务层For information about registry service tiers and limits, see Azure Container Registry service tiers.

使用须知Things to know

  • 目前只能在创建注册表时启用客户管理的密钥。You can currently enable a customer-managed key only when you create a registry. 启用密钥时,可配置用户分配托管标识以访问密钥保管库。When enabling the key, you configure a user-assigned managed identity to access the key vault.

  • 对注册表启用使用客户管理的密钥进行的加密后,无法禁用加密。After enabling encryption with a customer-managed key on a registry, you can't disable the encryption.

  • Azure 容器注册表仅支持 RSA 密钥。Azure Container Registry supports only RSA keys. 当前不支持椭圆曲线密钥。Elliptic curve keys aren't currently supported.

  • 使用客户管理的密钥加密的注册表目前不支持内容信任Content trust is currently not supported in a registry encrypted with a customer-managed key.

  • 在使用客户管理的密钥加密的注册表中,ACR 任务的运行日志目前只会保留 24 小时。In a registry encrypted with a customer-managed key, run logs for ACR Tasks are currently retained for only 24 hours. 如果需要将日志保留更长时间,请参阅有关导出和存储任务运行日志的指南。If you need to retain logs for a longer period, see guidance to export and store task run logs.

备注

如果使用具有 Key Vault 防火墙的虚拟网络限制对 Azure 密钥保管库的访问,则需要执行额外的配置步骤。If access to your Azure key vault is restricted using a virtual network with a Key Vault firewall, extra configuration steps are needed. 在创建注册表并启用客户管理的密钥后,使用注册表的系统分配托管标识设置对密钥的访问权限,并将注册表配置为绕过 Key Vault 防火墙。After creating the registry and enabling the customer-managed key, set up access to the key using the registry's system-assigned managed identity, and configure the registry to bypass the Key Vault firewall. 请首先按照本文中的步骤启用使用客户管理的密钥进行的加密,然后参阅本文后面部分中有关高级方案:Key Vault 防火墙的指导。Follow the steps in this article first to enable encryption with a customer-managed key, and then see the guidance for Advanced scenario: Key Vault firewall later in this article.

密钥版本的自动或手动更新Automatic or manual update of key versions

使用客户管理的密钥加密的注册表的一个重要的安全注意事项是以何频率更新(轮换)加密密钥。An important consideration for the security of a registry encrypted with a customer-managed key is how frequently you update (rotate) the encryption key. 你的组织可能有合规性策略,要求当 Azure Key Vault 中存储的密钥版本用作客户管理的密钥时定期对其进行更新。Your organization might have compliance policies that require regularly updating key versions stored in Azure Key Vault when used as customer-managed keys.

配置使用客户管理的密钥进行的注册表加密时,可通过两个选项更新用于加密的密钥版本:When you configure registry encryption with a customer-managed key, you have two options for updating the key version used for encryption:

  • 自动更新密钥版本 - 若要在 Azure Key Vault 中有新版本可用时自动更新客户管理的密钥的密钥版本,请在启用通过客户管理的密钥进行的注册表加密时省略密钥版本。Automatically update the key version - To automatically update a customer-managed key when a new version is available in Azure Key Vault, omit the key version when you enable registry encryption with a customer-managed key. 使用无版本的密钥对注册表加密时,Azure 容器注册表会定期检查密钥保管库中是否有新的密钥版本,在确定有新版本的情况下会在 1 小时内更新客户管理的密钥。When a registry is encrypted with a non-versioned key, Azure Container Registry regularly checks the key vault for a new key version and updates the customer-managed key within 1 hour. Azure 容器注册表自动使用最新版本的密钥。Azure Container Registry automatically uses the latest version of the key.

  • 手动更新密钥版本 - 若要使用特定版本的密钥进行注册表加密,请在启用通过客户管理的密钥进行的注册表加密时指定该密钥版本。Manually update the key version - To use a specific version of a key for registry encryption, specify that key version when you enable registry encryption with a customer-managed key. 使用特定密钥版本对注册表加密时,Azure 容器注册表会使用该版本进行加密,直到你手动轮换客户管理的密钥。When a registry is encrypted with a specific key version, Azure Container Registry uses that version for encryption until you manually rotate the customer-managed key.

有关详细信息,请参阅本文后面部分的选择带或不带密钥版本的密钥 ID更新密钥版本For details, see Choose key ID with or without key version and Update key version, later in this article.

先决条件Prerequisites

若要使用本文中所述的 Azure CLI 步骤,需要安装 Azure CLI 2.2.0 或更高版本。To use the Azure CLI steps in this article, you need Azure CLI version 2.2.0 or later. 如果需要进行安装或升级,请参阅安装 Azure CLIIf you need to install or upgrade, see Install Azure CLI.

启用客户管理的密钥 - CLIEnable customer-managed key - CLI

创建资源组Create a resource group

如果需要,请运行 az group create 命令创建一个资源组,以用于创建密钥保管库、容器注册表和其他所需资源。If needed, run the az group create command to create a resource group for creating the key vault, container registry, and other required resources.

az group create --name <resource-group-name> --location <location>

创建用户分配的托管标识Create a user-assigned managed identity

使用 az identity create 命令为 Azure 资源创建用户分配的托管标识Create a user-assigned managed identity for Azure resources with the az identity create command. 注册表将使用此标识来访问 Key Vault 服务。This identity will be used by your registry to access the Key Vault service.

az identity create \
  --resource-group <resource-group-name> \
  --name <managed-identity-name>

记下命令输出中的以下值:idprincipalIdIn the command output, take note of the following values: id and principalId. 在后续步骤中,需要使用这些值来配置注册表对密钥保管库的访问。You need these values in later steps to configure registry access to the key vault.

{
  "clientId": "xxxx2bac-xxxx-xxxx-xxxx-192cxxxx6273",
  "clientSecretUrl": "https://control-chinanorth.identity.chinacloudapi.cn/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myresourcegroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myidentityname/credentials?tid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&oid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&aid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myresourcegroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myresourcegroup",
  "location": "chinanorth",
  "name": "myidentityname",
  "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "resourceGroup": "myresourcegroup",
  "tags": {},
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

为方便起见,请将这些值存储在环境变量中:For convenience, store these values in environment variables:

identityID=$(az identity show --resource-group <resource-group-name> --name <managed-identity-name> --query 'id' --output tsv)

identityPrincipalID=$(az identity show --resource-group <resource-group-name> --name <managed-identity-name> --query 'principalId' --output tsv)

创建 key vaultCreate a key vault

使用 az keyvault create 创建一个密钥保管库来存储用于加密注册表的客户管理的密钥。Create a key vault with az keyvault create to store a customer-managed key for registry encryption.

默认情况下,在新的密钥保管库中会自动启用“软删除”设置。By default, the soft delete setting is automatically enabled in a new key vault. 为了防止意外删除密钥或密钥保管库而导致数据丢失,还请启用“清除保护”设置:To prevent data loss caused by accidental key or key vault deletions, also enable the purge protection setting:

az keyvault create --name <key-vault-name> \
  --resource-group <resource-group-name> \
  --enable-purge-protection

若要在后续步骤中使用,请获取密钥保管库的资源 ID:For use in later steps, get the resource ID of the key vault:

keyvaultID=$(az keyvault show --resource-group <resource-group-name> --name <key-vault-name> --query 'id' --output tsv)

启用密钥保管库访问权限Enable key vault access

配置针对密钥保管库的策略,使标识可以访问密钥保管库。Configure a policy for the key vault so that the identity can access it. 在以下 az keyvault set-policy 命令中,请传递前面创建并存储在环境变量中的托管标识的主体 ID。In the following az keyvault set-policy command, you pass the principal ID of the managed identity that you created, stored previously in an environment variable. 将密钥权限设置为 getunwrapKeywrapKeySet key permissions to get, unwrapKey, and wrapKey.

az keyvault set-policy \
  --resource-group <resource-group-name> \
  --name <key-vault-name> \
  --object-id $identityPrincipalID \
  --key-permissions get unwrapKey wrapKey

或者,使用用于密钥保管库的 Azure RBAC(预览版)为标识分配访问密钥保管库的权限。Alternatively, use Azure RBAC for Key Vault (preview) to assign permissions to the identity to access the key vault. 例如,使用 az role assignment create 命令将密钥保管库加密服务加密角色分配给标识:For example, assign the Key Vault Crypto Service Encryption role to the identity using the az role assignment create command:

az role assignment create --assignee $identityPrincipalID \
  --role "Key Vault Crypto Service Encryption (preview)" \
  --scope $keyvaultID

创建密钥并获取密钥 IDCreate key and get key ID

运行 az keyvault key create 命令以在密钥保管库中创建密钥。Run the az keyvault key create command to create a key in the key vault.

az keyvault key create \
  --name <key-name> \
  --vault-name <key-vault-name>

记下命令输出中的密钥 ID kidIn the command output, take note of the key's ID, kid. 在下一步骤中将会用到此 ID:You use this ID in the next step:

[...]
  "key": {
    "crv": null,
    "d": null,
    "dp": null,
    "dq": null,
    "e": "AQAB",
    "k": null,
    "keyOps": [
      "encrypt",
      "decrypt",
      "sign",
      "verify",
      "wrapKey",
      "unwrapKey"
    ],
    "kid": "https://mykeyvault.vault.azure.cn/keys/mykey/<version>",
    "kty": "RSA",
[...]

选择带或不带密钥版本的密钥 IDChoose key ID with or without key version

为方便起见,请将你为密钥 ID 选择的格式存储在 $keyID 环境变量中。For convenience, store the format you choose for the key ID in the $keyID environment variable. 你可以使用带版本的密钥 ID,也可以使用不带版本的密钥。You can use a key ID with a version or a key without a version.

手动密钥轮换 - 带版本的密钥 IDManual key rotation - key ID with version

用来通过客户管理的密钥加密注册表时,此密钥只允许在 Azure 容器注册表中手动轮换密钥。When used to encrypt a registry with a customer-managed key, this key allows only manual key rotation in Azure Container Registry.

此示例存储密钥的 kid 属性:This example stores the key's kid property:

keyID=$(az keyvault key show \
  --name <keyname> \
  --vault-name <key-vault-name> \
  --query 'key.kid' --output tsv)

自动密钥轮换 - 省略版本的密钥 IDAutomatic key rotation - key ID omitting version

用来通过客户管理的密钥加密注册表时,此密钥在 Azure Key Vault 中检测到新的密钥版本时会启用自动密钥轮换。When used to encrypt a registry with a customer-managed key, this key enables automatic key rotation when a new key version is detected in Azure Key Vault.

此示例删除密钥的 kid 属性中的版本:This example removes the version from the key's kid property:

keyID=$(az keyvault key show \
  --name <keyname> \
  --vault-name <key-vault-name> \
  --query 'key.kid' --output tsv)

keyID=$(echo $keyID | sed -e "s/\/[^/]*$//")

使用客户管理的密钥创建注册表Create a registry with customer-managed key

运行 az acr create 命令,以在“高级”服务层级创建注册表并启用客户管理的密钥。Run the az acr create command to create a registry in the Premium service tier and enable the customer-managed key. 传递托管标识 ID 和密钥 ID(以前已存储在环境变量中):Pass the managed identity ID and the key ID, stored previously in environment variables:

az acr create \
  --resource-group <resource-group-name> \
  --name <container-registry-name> \
  --identity $identityID \
  --key-encryption-key $keyID \
  --sku Premium

显示加密状态Show encryption status

若要显示是否启用了使用客户管理的密钥进行注册表加密,请运行 az acr encryption show 命令:To show whether registry encryption with a customer-managed key is enabled, run the az acr encryption show command:

az acr encryption show --name <registry-name>

输出类似于以下内容,具体取决于用于加密注册表的密钥:Depending on the key used to encrypt the registry, output is similar to:

{
  "keyVaultProperties": {
    "identity": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "keyIdentifier": "https://myvault.vault.azure.cn/keys/myresourcegroup/abcdefg123456789...",
    "versionedKeyIdentifier": "https://myvault.vault.azure.cn/keys/myresourcegroup/abcdefg123456789...",
    "keyRotationEnabled": true,
    "lastKeyRotationTimestamp": xxxxxxxx
  },
  "status": "enabled"
}

启用客户管理的密钥 - 门户Enable customer-managed key - portal

创建托管标识Create a managed identity

在 Azure 门户中为 Azure 资源创建用户分配的托管标识Create a user-assigned managed identity for Azure resources in the Azure portal. 有关步骤,请参阅创建用户分配的标识For steps, see Create a user-assigned identity.

在后续步骤中需要用到该标识的名称。You use the identity's name in later steps.

在 Azure 门户中创建用户分配的标识

创建 key vaultCreate a key vault

有关创建密钥保管库的步骤,请参阅快速入门:使用 Azure 门户创建密钥保管库For steps to create a key vault, see Quickstart: Create a key vault using the Azure portal.

为客户管理的密钥创建密钥保管库时,请在“基本信息”选项卡中启用“清除保护”设置 。When creating a key vault for a customer-managed key, in the Basics tab, enable the Purge protection setting. 此设置有助于防止意外删除密钥或密钥保管库而导致的数据丢失。This setting helps prevent data loss caused by accidental key or key vault deletions.

在 Azure 门户中创建密钥保管库

启用密钥保管库访问权限Enable key vault access

配置针对密钥保管库的策略,使标识可以访问密钥保管库。Configure a policy for the key vault so that the identity can access it.

  1. 导航到你的密钥保管库。Navigate to your key vault.

  2. 选择“设置” > “访问策略”>“+添加访问策略”。Select Settings > Access policies > +Add Access Policy.

  3. 选择“密钥权限”,然后选择“获取”、“解包密钥”和“包装密钥”。Select Key permissions, and select Get, Unwrap Key, and Wrap Key.

  4. 在“选择主体”中,选择你的用户分配的托管标识的资源名称。In Select principal, select the resource name of your user-assigned managed identity.

  5. 依次选择“添加”、“保存”。Select Add, then select Save.

    创建密钥保管库访问策略

或者,使用用于密钥保管库的 Azure RBAC(预览版)为标识分配访问密钥保管库的权限。Alternatively, use Azure RBAC for Key Vault (preview) to assign permissions to the identity to access the key vault. 例如,将密钥保管库加密服务加密角色分配给标识。For example, assign the Key Vault Crypto Service Encryption role to the identity.

  1. 导航到你的密钥保管库。Navigate to your key vault.

  2. 选择“访问控制(IAM)” > “+添加” > “添加角色分配”。Select Access control (IAM) > +Add > Add role assignment.

  3. 在“添加角色分配”窗口中:In the Add role assignment window:

    1. 选择“密钥保管库加密服务加密(预览版)”角色。Select Key Vault Crypto Service Encryption (preview) role.
    2. 将访问权限分配给“用户分配的托管标识”。Assign access to User assigned managed identity.
    3. 选择用户分配的托管标识的资源名称,然后选择“保存”。Select the resource name of your user-assigned managed identity, and select Save.

创建密钥(可选)Create key (optional)

(可选)在密钥保管库中创建密钥,以用于加密注册表。Optionally create a key in the key vault for use to encrypt the registry. 如果要选择特定的密钥版本作为客户管理的密钥,请执行以下步骤。Follow these steps if you want to select a specific key version as a customer-managed key.

  1. 导航到你的密钥保管库。Navigate to your key vault.
  2. 选择“设置” > “密钥”。Select Settings > Keys.
  3. 选择“+生成/导入”并输入密钥的唯一名称。Select +Generate/Import and enter a unique name for the key.
  4. 接受剩余的默认值,然后选择“创建”。Accept the remaining default values and select Create.
  5. 创建后,选择该密钥,然后选择当前版本。After creation, select the key and then select the current version. 复制密钥版本的密钥标识符。Copy the Key identifier for the key version.

创建 Azure 容器注册表Create Azure container registry

  1. 选择“创建资源”,在“新建”页的搜索筛选器中键入“容器注册表”,然后按回车键。Select Create a resource, type the Container Registry in search filter of NEW page, and select the return key.

  2. 在搜索结果中选择“容器注册表”对应的项,然后选择“创建”。Select the item of Container Registry in search result, then select the Create.

  3. 在“基本信息”选项卡中选择或创建一个资源组,然后输入注册表名称。In the Basics tab, select or create a resource group, and enter a registry name. 在“SKU”中选择“高级”。In SKU, select Premium.

  4. 在“加密”选项卡上的“客户管理的密钥”中,选择“已启用”。In the Encryption tab, in Customer-managed key, select Enabled.

  5. 在“标识”中,选择你创建的托管标识。In Identity, select the managed identity you created.

  6. 在“加密”中,选择以下任一项:In Encryption, choose either of the following:

    • 选择“从密钥保管库中选择”,然后选择现有密钥保管库和密钥或“新建” 。Select Select from Key Vault, and select an existing key vault and key, or Create new. 你选择的密钥不受版本控制,可启用自动密钥轮换。The key you select is non-versioned and enables automatic key rotation.
    • 选择“输入密钥 URI”,并直接提供密钥标识符。Select Enter key URI, and provide a key identifier directly. 可以提供受版本控制的密钥 URI(适用于必须手动轮换的密钥)或不受版本控制的密钥 URI(该 URI 启用自动密钥轮换)。You can provide either a versioned key URI (for a key that must be rotated manually) or a non-versioned key URI (which enables automatic key rotation).
  7. 在“加密”选项卡中,选择“查看 + 创建”。In the Encryption tab, select Review + create.

  8. 选择“创建”以部署注册表实例。Select Create to deploy the registry instance.

    在 Azure 门户中创建加密注册表

若要在门户中查看注册表的加密状态,请导航到注册表。To see the encryption status of your registry in the portal, navigate to your registry. 在“设置”下,选择“加密”。Under Settings, select Encryption.

启用客户管理的密钥 - 模板Enable customer-managed key - template

还可以使用资源管理器模板来创建注册表,并启用使用客户管理的密钥进行加密。You can also use a Resource Manager template to create a registry and enable encryption with a customer-managed key.

以下模板创建新的容器注册表和用户分配的托管标识。The following template creates a new container registry and a user-assigned managed identity. 将以下内容复制到新文件,并使用类似于 CMKtemplate.json 的文件名保存该文件。Copy the following contents to a new file and save it using a filename such as CMKtemplate.json.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vault_name": {
      "defaultValue": "",
      "type": "String"
    },
    "registry_name": {
      "defaultValue": "",
      "type": "String"
    },
    "identity_name": {
      "defaultValue": "",
      "type": "String"
    },
    "kek_id": {
      "type": "String"
    }
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.ContainerRegistry/registries",
      "apiVersion": "2019-12-01-preview",
      "name": "[parameters('registry_name')]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Premium",
        "tier": "Premium"
      },
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identity_name'))]": {}
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identity_name'))]"
      ],
      "properties": {
        "adminUserEnabled": false,
        "encryption": {
          "status": "enabled",
          "keyVaultProperties": {
            "identity": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identity_name')), '2018-11-30').clientId]",
            "KeyIdentifier": "[parameters('kek_id')]"
          }
        },
        "networkRuleSet": {
          "defaultAction": "Allow",
          "virtualNetworkRules": [],
          "ipRules": []
        },
        "policies": {
          "quarantinePolicy": {
            "status": "disabled"
          },
          "trustPolicy": {
            "type": "Notary",
            "status": "disabled"
          },
          "retentionPolicy": {
            "days": 7,
            "status": "disabled"
          }
        }
      }
    },
    {
      "type": "Microsoft.KeyVault/vaults/accessPolicies",
      "apiVersion": "2018-02-14",
      "name": "[concat(parameters('vault_name'), '/add')]",
      "dependsOn": [
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identity_name'))]"
      ],
      "properties": {
        "accessPolicies": [
          {
            "tenantId": "[subscription().tenantId]",
            "objectId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identity_name')), '2018-11-30').principalId]",
            "permissions": {
              "keys": [
                "get",
                "unwrapKey",
                "wrapKey"
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2018-11-30",
      "name": "[parameters('identity_name')]",
      "location": "[resourceGroup().location]"
    }
  ]
}

按照前面部分中的步骤创建以下资源:Follow the steps in the previous sections to create the following resources:

  • 密钥保管库,按名称标识Key vault, identified by name
  • 密钥保管库密钥,按密钥 ID 标识Key vault key, identified by key ID

运行以下 az deployment group create 命令,以使用前面的模板文件创建注册表。Run the following az deployment group create command to create the registry using the preceding template file. 根据指示提供新的注册表名称和托管标识名称,以及你创建的密钥保管库名称和密钥 ID。Where indicated, provide a new registry name and managed identity name, as well as the key vault name and key ID you created.

az deployment group create \
  --resource-group <resource-group-name> \
  --template-file CMKtemplate.json \
  --parameters \
    registry_name=<registry-name> \
    identity_name=<managed-identity> \
    vault_name=<key-vault-name> \
    kek_id=<key-vault-key-id>

显示加密状态Show encryption status

若要显示注册表加密的状态,请运行 az acr encryption show 命令:To show the status of registry encryption, run the az acr encryption show command:

az acr encryption show --name <registry-name>

使用注册表Use the registry

在注册表中启用客户管理的密钥后,可以像在未使用客户管理的密钥加密的注册表中执行操作一样,执行相同的注册表操作。After enabling a customer-managed key in a registry, you can perform the same registry operations that you perform in a registry that's not encrypted with a customer-managed key. 例如,可向注册表进行身份验证,以及推送 Docker 映像。For example, you can authenticate with the registry and push Docker images. 请参阅推送和拉取映像中的示例命令。See example commands in Push and pull an image.

轮换密钥Rotate key

更新 Azure Key Vault 中的密钥版本,或者创建新密钥,然后更新注册表以使用该密钥加密数据。Update the key version in Azure Key Vault, or create a new key, and then update the registry to encrypt data using the key. 可以使用 Azure CLI 或者在门户中执行这些步骤。You can perform these steps using the Azure CLI or in the portal.

轮换密钥时,通常需要指定在创建注册表时所用的同一标识。When rotating a key, typically you specify the same identity used when creating the registry. (可选)配置新的用户分配标识以用于进行密钥访问,或者启用并指定注册表的系统分配标识。Optionally, configure a new user-assigned identity for key access, or enable and specify the registry's system-assigned identity.

备注

确保针对为进行密钥访问而配置的标识设置了所需的密钥保管库访问权限Ensure that the required key vault access is set for the identity you configure for key access.

更新密钥版本Update key version

更新密钥(用作客户管理的密钥)的版本是一种常见情况。A common scenario is to update the version of the key used as a customer-managed key. Azure 容器注册表中的客户管理的密钥会自动更新,或者必须手动更新,具体取决于注册表加密的配置情况。Depending on how the registry encryption is configured, the customer-managed key in Azure Container Registry is automatically updated, or must be manually updated.

Azure CLIAzure CLI

使用 az keyvault key 命令来创建或管理密钥保管库密钥。Use az keyvault key commands to create or manage your key vault keys. 若要创建新的密钥版本,请运行 az keyvault key create 命令:To create a new key version, run the az keyvault key create command:

# Create new version of existing key
az keyvault key create \
  --name <key-name> \
  --vault-name <key-vault-name>

下一步取决于注册表加密的配置情况:The next step depends on how the registry encryption is configured:

  • 如果注册表配置为检测密钥版本更新,则客户管理的密钥会在 1 小时内自动更新。If the registry is configured to detect key version updates, the customer-managed key is updated automatically within 1 hour.

  • 如果注册表配置为要求对新密钥版本进行手动更新,请运行 az acr encryption rotate-key 命令并传递要配置的新密钥 ID 和标识:If the registry is configured to require manual updating for a new key version, run the az acr encryption rotate-key command, passing the new key ID and the identity you want to configure:

若要手动更新客户管理的密钥的版本,请执行以下代码:To update the customer-managed key version manually:

# Rotate key and use user-assigned identity
az acr encryption rotate-key \
  --name <registry-name> \
  --key-encryption-key <new-key-id> \
  --identity <principal-id-user-assigned-identity>

# Rotate key and use system-assigned identity
az acr encryption rotate-key \
  --name <registry-name> \
  --key-encryption-key <new-key-id> \
  --identity [system]

提示

运行 az acr encryption rotate-key 时,可以传递带版本的密钥 ID 或无版本的密钥 ID。When you run az acr encryption rotate-key, you can pass either a versioned key ID or a non-versioned key ID. 如果使用无版本的密钥 ID,则会将注册表配置为自动检测以后的密钥版本更新。If you use a non-versioned key ID, the registry is then configured to automatically detect later key version updates.

门户Portal

使用注册表的“加密”设置来更新客户管理的密钥所用的密钥保管库、密钥或标识设置。Use the registry's Encryption settings to update the key vault, key, or identity settings used for the customer-managed key.

例如,若要配置新密钥,请执行以下操作:For example, to configure a new key:

  1. 在门户中导航到你的注册表。In the portal, navigate to your registry.

  2. 在“设置”下,选择“加密” > “更改密钥”。Under Settings, select Encryption > Change key.

    在 Azure 门户中轮换密钥

  3. 在“加密”中,选择以下任一项:In Encryption, choose one of the following:

    • 选择“从密钥保管库中选择”,然后选择现有密钥保管库和密钥或“新建” 。Select Select from Key Vault, and select an existing key vault and key, or Create new. 你选择的密钥不受版本控制,可启用自动密钥轮换。The key you select is non-versioned and enables automatic key rotation.
    • 选择“输入密钥 URI”,并直接提供密钥标识符。Select Enter key URI, and provide a key identifier directly. 可以提供受版本控制的密钥 URI(适用于必须手动轮换的密钥)或不受版本控制的密钥 URI(该 URI 启用自动密钥轮换)。You can provide either a versioned key URI (for a key that must be rotated manually) or a non-versioned key URI (which enables automatic key rotation).
  4. 完成密钥选择,然后选择“保存”。Complete the key selection and select Save.

撤销密钥Revoke key

撤销客户管理的加密密钥,方法是:更改针对密钥保管库的访问策略或权限,或者删除密钥。Revoke the customer-managed encryption key by changing the access policy or permissions on the key vault or by deleting the key. 例如,使用 az keyvault delete-policy 命令更改注册表使用的托管标识的访问策略:For example, use the az keyvault delete-policy command to change the access policy of the managed identity used by your registry:

az keyvault delete-policy \
  --resource-group <resource-group-name> \
  --name <key-vault-name> \
  --object-id $identityPrincipalID

撤销密钥会有效阻止对所有注册表数据的访问,因为注册表无法访问加密密钥。Revoking the key effectively blocks access to all registry data, since the registry can't access the encryption key. 如果启用了对密钥的访问或者还原了已删除的密钥,则注册表将选取该密钥,使你可以再次访问已加密的注册表数据。If access to the key is enabled or the deleted key is restored, your registry will pick the key so you can again access the encrypted registry data.

高级方案:Key Vault 防火墙Advanced scenario: Key Vault firewall

如果 Azure 密钥保管库部署在具有 Key Vault 防火墙的虚拟网络中,请在注册表中启用客户管理的密钥加密后执行以下附加步骤。If your Azure key vault is deployed in a virtual network with a Key Vault firewall, perform the following additional steps after enabling customer-managed key encryption in your registry.

  1. 将注册表加密配置为使用注册表的系统分配的标识Configure registry encryption to use the registry's system-assigned identity
  2. 使注册表可以绕过 Key Vault 防火墙Enable the registry to bypass the Key Vault firewall
  3. 轮换客户管理的密钥Rotate the customer-managed key

配置系统分配的标识Configure system-assigned identity

可以配置注册表的系统分配的托管标识,以访问密钥保管库中的加密密钥。You can configure a registry's system-assigned managed identity to access the key vault for encryption keys. 如果你不熟悉 Azure 资源的各种托管标识,请参阅概述If you're unfamiliar with the different managed identities for Azure resources, see the overview.

若要在门户中启用注册表的系统分配的标识,请执行以下操作:To enable the registry's system-assigned identity in the portal:

  1. 在门户中导航到你的注册表。In the portal, navigate to your registry.
  2. 选择“设置” > “标识”。Select Settings > Identity.
  3. 在“系统分配”下,将“状态”设置为“开”。Under System assigned, set Status to On. 选择“保存”。Select Save.
  4. 复制标识的“对象 ID”。Copy the Object ID of the identity.

若要授予标识对密钥保管库的访问权限,请执行以下操作:To grant the identity access to your key vault:

  1. 导航到你的密钥保管库。Navigate to your key vault.
  2. 选择“设置” > “访问策略”>“+添加访问策略”。Select Settings > Access policies > +Add Access Policy.
  3. 选择“密钥权限”,然后选择“获取”、“解包密钥”和“包装密钥”。Select Key permissions, and select Get, Unwrap Key, and Wrap Key.
  4. 选择“选择主体”,并搜索系统分配的托管标识的对象 ID,或搜索注册表的名称。Choose Select principal and search for the object ID of your system-assigned managed identity, or the name of your registry.
  5. 依次选择“添加”、“保存”。Select Add, then select Save.

若要将注册表的加密设置更新为使用该标识,请执行以下操作:To update the registry's encryption settings to use the identity:

  1. 在门户中导航到你的注册表。In the portal, navigate to your registry.
  2. 在“设置”下,选择“加密” > “更改密钥”。Under Settings, select Encryption > Change key.
  3. 在“标识”中选择“系统分配”,然后选择“保存”。In Identity, select System assigned, and select Save.

启用密钥保管库绕过Enable key vault bypass

若要访问使用 Key Vault 防火墙配置的密钥保管库,注册表必须绕过防火墙。To access a key vault configured with a Key Vault firewall, the registry must bypass the firewall. 确保将密钥保管库配置为允许任何受信任的服务进行访问。Ensure that the key vault is configured to allow access by any trusted service. Azure 容器注册表是受信任的服务之一。Azure Container Registry is one of the trusted services.

  1. 在门户中导航到你的密钥保管库。In the portal, navigate to your key vault.
  2. 选择“设置” > “网络”。 Select Settings > Networking.
  3. 确认、更新或添加虚拟网络设置。Confirm, update, or add virtual network settings. 有关详细步骤,请参阅配置 Azure Key Vault 防火墙和虚拟网络For detailed steps, see Configure Azure Key Vault firewalls and virtual networks.
  4. 在“允许受信任的 Azure 服务跳过此防火墙”中选择“是”。 In Allow Azure Trusted Services to bypass this firewall, select Yes.

轮换客户管理的密钥Rotate the customer-managed key

完成以上步骤后,将密钥轮换到防火墙后面的密钥保管库中的新密钥。After completing the preceding steps, rotate the key to a new key in the key vault behind a firewall. 有关步骤,请参阅本文中的轮换密钥For steps, see Rotate key in this article.

故障排除Troubleshoot

删除用户分配的标识Removing user-assigned identity

如果你尝试从用于加密的注册表删除用户分配的标识,你可能会看到类似于以下内容的错误消息:If you try to remove a user-assigned identity from a registry that is used for encryption, you might see an error message similar to:

Azure resource '/subscriptions/xxxx/resourcegroups/myGroup/providers/Microsoft.ContainerRegistry/registries/myRegistry' does not have access to identity 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' Try forcibly adding the identity to the registry <registry name>. For more information on bring your own key, please visit 'https://aka.ms/acr/cmk'.

你还将无法更改(轮换)加密密钥。You will also be unable to change (rotate) the encryption key. 如果出现此问题,请先使用错误消息中显示的 GUID 重新分配标识。If this issue occurs, first reassign the identity using the GUID displayed in the error message. 例如:For example:

az acr identity assign -n myRegistry --identities xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx

然后,在更改密钥并分配其他标识后,可以删除原始的用户分配的标识。Then, after changing the key and assigning a different identity, you can remove the original user-assigned identity.

后续步骤Next steps