|
| 1 | +--- |
| 2 | +title: Preview - Create an image version encrypted with your own keys |
| 3 | +description: Create a an image version in a Shared Image Gallery, using customer-managed encryption keys. |
| 4 | +author: cynthn |
| 5 | +ms.service: virtual-machines |
| 6 | +ms.workload: infrastructure-services |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 05/06/2020 |
| 9 | +ms.author: cynthn |
| 10 | +--- |
| 11 | + |
| 12 | +# Preview: Use customer-managed keys for encrypting images |
| 13 | + |
| 14 | +Gallery images are stored as managed disks, so they are automatically encrypted using server-side encryption. Server-side encryption uses 256-bit [AES encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard), one of the strongest block ciphers available, and is FIPS 140-2 compliant. For more information about the cryptographic modules underlying Azure managed disks, see [Cryptography API: Next Generation](https://docs.microsoft.com/windows/desktop/seccng/cng-portal) |
| 15 | + |
| 16 | +You can rely on platform-managed keys for the encryption of your images, or you can manage encryption using your own keys. If you choose to manage encryption with your own keys, you can specify a *customer-managed key* to use for encrypting and decrypting all disks in your images. |
| 17 | + |
| 18 | +Server-side encryption using customer-managed keys uses Azure Key Vault. You can either import [your RSA keys](../key-vault/keys/hsm-protected-keys.md) to your Key Vault or generate new RSA keys in Azure Key Vault. |
| 19 | + |
| 20 | +To use customer managed keys for images, you first need an Azure Key Vault. You then create a disk encryption set. The disk encryption set is then used when creating you image versions. |
| 21 | + |
| 22 | +For more information about creating and using disk encryption sets, see [Customer managed keys](https://docs.microsoft.com/azure/virtual-machines/windows/disk-encryption#customer-managed-keys). |
| 23 | + |
| 24 | +## Limitations |
| 25 | + |
| 26 | +There are several limitations when using customer managed keys for encrypting shared image gallery images: |
| 27 | + |
| 28 | +- Encryption key sets must be in the same subscription and region as you image. |
| 29 | + |
| 30 | +- You cannot share images that use customer managed keys. |
| 31 | + |
| 32 | +- You cannot replicate images that use customer managed keys to other regions. |
| 33 | + |
| 34 | +- Once you have used your own keys to encrypt a disk or image, you cannot go back to using platform-managed keys for encrypting those disks or images. |
| 35 | + |
| 36 | + |
| 37 | +> [!IMPORTANT] |
| 38 | +> Encryption using customer-managed keys is currently in public preview. |
| 39 | +> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. |
| 40 | +> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). |
| 41 | +
|
| 42 | + |
| 43 | +## PowerShell |
| 44 | + |
| 45 | +For the public preview, you first need to register the feature. |
| 46 | + |
| 47 | +```azurepowershell-interactive |
| 48 | +Register-AzProviderFeature -FeatureName SIGEncryption -ProviderNamespace Microsoft.Compute |
| 49 | +``` |
| 50 | + |
| 51 | +It takes a few minutes for the registration to complete. Use Get-AzProviderFeature to check on the status of the feature registration. |
| 52 | + |
| 53 | +```azurepowershell-interactive |
| 54 | +Get-AzProviderFeature -FeatureName SIGEncryption -ProviderNamespace Microsoft.Compute |
| 55 | +``` |
| 56 | + |
| 57 | +When RegistrationState returns Registered, you can move on to the next step. |
| 58 | + |
| 59 | +Check your provider registration. Make sure it returns `Registered`. |
| 60 | + |
| 61 | +```azurepowershell-interactive |
| 62 | +Get-AzResourceProvider -ProviderNamespace Microsoft.Compute | Format-table -Property ResourceTypes,RegistrationState |
| 63 | +``` |
| 64 | + |
| 65 | +If it doesn't return `Registered`, use the following to register the providers: |
| 66 | + |
| 67 | +```azurepowershell-interactive |
| 68 | +Register-AzResourceProvider -ProviderNamespace Microsoft.Compute |
| 69 | +``` |
| 70 | + |
| 71 | +To specify a disk encryption set to for an image version, use [New-AzGalleryImageDefinition](https://docs.microsoft.com/powershell/module/az.compute/new-azgalleryimageversion) with the `-TargetRegion` parameter. |
| 72 | + |
| 73 | +```azurepowershell-interactive |
| 74 | +
|
| 75 | +$sourceId = <ID of the image version source> |
| 76 | +
|
| 77 | +$osDiskImageEncryption = @{DiskEncryptionSetId='subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Compute/diskEncryptionSets/myDESet'} |
| 78 | +
|
| 79 | +$dataDiskImageEncryption1 = @{DiskEncryptionSetId='subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Compute/diskEncryptionSets/myDESet1';Lun=1} |
| 80 | +
|
| 81 | +$dataDiskImageEncryption2 = @{DiskEncryptionSetId='subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Compute/diskEncryptionSets/myDESet2';Lun=2} |
| 82 | +
|
| 83 | +$dataDiskImageEncryptions = @($dataDiskImageEncryption1,$dataDiskImageEncryption2) |
| 84 | +
|
| 85 | +$encryption1 = @{OSDiskImage=$osDiskImageEncryption;DataDiskImages=$dataDiskImageEncryptions} |
| 86 | +
|
| 87 | +$region1 = @{Name='West US';ReplicaCount=1;StorageAccountType=Standard_LRS;Encryption=$encryption1} |
| 88 | +
|
| 89 | +$targetRegion = @{$region1} |
| 90 | +
|
| 91 | +
|
| 92 | +# Create the image |
| 93 | +New-AzGalleryImageVersion ` |
| 94 | + -ResourceGroupName $rgname ` |
| 95 | + -GalleryName $galleryName ` |
| 96 | + -GalleryImageDefinitionName $imageDefinitionName ` |
| 97 | + -Name $versionName -Location $location ` |
| 98 | + -SourceImageId $sourceId ` |
| 99 | + -ReplicaCount 2 ` |
| 100 | + -StorageAccountType Standard_LRS ` |
| 101 | + -PublishingProfileEndOfLifeDate '2020-12-01' ` |
| 102 | + -TargetRegion $targetRegion |
| 103 | +``` |
| 104 | + |
| 105 | +### Create a VM |
| 106 | + |
| 107 | +You can create a VM from a shared image gallery and use customer-managed keys to encrypt the disks. The syntax is the same as creating a [generalized](vm-generalized-image-version-powershell.md) or [specialized](vm-specialized-image-version-powershell.md) VM from an image, you need to use the extended parameter set and add `Set-AzVMOSDisk -Name $($vmName +"_OSDisk") -DiskEncryptionSetId $diskEncryptionSet.Id -CreateOption FromImage` to the VM configuration. |
| 108 | + |
| 109 | +For data disks, You need to add the `-DiskEncryptionSetId $setID` parameter when you use [Add-AzVMDataDisk](/powershell/module/az.compute/add-azvmdatadisk). |
| 110 | + |
| 111 | + |
| 112 | +## CLI |
| 113 | + |
| 114 | +For the public preview, you first need to register the feature. |
| 115 | + |
| 116 | +```azurecli-interactive |
| 117 | +az feature register --namespace Microsoft.Compute --name SIGEncryption |
| 118 | +``` |
| 119 | + |
| 120 | +Check the status of the feature registration. |
| 121 | + |
| 122 | +```azurecli-interactive |
| 123 | +az feature show --namespace Microsoft.Compute --name SIGEncryption | grep state |
| 124 | +``` |
| 125 | + |
| 126 | +When this returns `"state": "Registered"`, you can move on to the next step. |
| 127 | + |
| 128 | +Check your registration. |
| 129 | + |
| 130 | +```azurecli-interactive |
| 131 | +az provider show -n Microsoft.Compute | grep registrationState |
| 132 | +``` |
| 133 | + |
| 134 | +If it doesn't say registered, run the following: |
| 135 | + |
| 136 | +```azurecli-interactive |
| 137 | +az provider register -n Microsoft.Compute |
| 138 | +``` |
| 139 | + |
| 140 | + |
| 141 | +To specify a disk encryption set to for an image version, use [az image gallery create-image-version](/cli/azure/sig/image-version#az-sig-image-version-create) with the `--target-region-encryption` parameter. The format for `--target-region-encryption` is a space-separated list of keys for encrypting the OS and data disks. It should look like this: `<encryption set for the OS disk>,<Lun number of the data disk>, <encryption set for the data disk>, <Lun number for the second data disk>, <encryption set for the second data disk>`. |
| 142 | + |
| 143 | +If the source for the OS disk is a managed disk or a VM, use `--managed-image` to specify the source for the image version. In this example, the source is a managed image that has an OS disk as well as a data disk at LUN 0. The OS disk will be encrypted with DiskEncryptionSet1 and the data disk will be encrypted with DiskEncryptionSet2. |
| 144 | + |
| 145 | +```azurecli-interactive |
| 146 | +az sig image-version create \ |
| 147 | + -g MyResourceGroup \ |
| 148 | + --gallery-image-version 1.0.0 \ |
| 149 | + --target-regions westus=2=standard_lrs \ |
| 150 | + --target-region-encryption DiskEncryptionSet1,0,DiskEncryptionSet2 \ |
| 151 | + --gallery-name MyGallery \ |
| 152 | + --gallery-image-definition MyImage \ |
| 153 | + --managed-image "/subscriptions/<subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.Compute/images/myImage" |
| 154 | +``` |
| 155 | + |
| 156 | +If the source for the OS disk is a snapshot, use `--os-snapshot` to specify the OS disk. If there are data disk snapshots that should also be part of the image version, add those using `--data-snapshot-luns` to specify the LUN, and `--data-snapshots` to specify the snapshots. |
| 157 | + |
| 158 | +In this example, the sources are disk snapshots. There is an OS disk, and also a data disk at LUN 0. The OS disk will be encrypted with DiskEncryptionSet1 and the data disk will be encrypted with DiskEncryptionSet2. |
| 159 | + |
| 160 | +```azurecli-interactive |
| 161 | +az sig image-version create \ |
| 162 | + -g MyResourceGroup \ |
| 163 | + --gallery-image-version 1.0.0 \ |
| 164 | + --target-regions westus=2=standard_lrs \ |
| 165 | + --target-region-encryption DiskEncryptionSet1,0,DiskEncryptionSet2 \ |
| 166 | + --os-snapshot "/subscriptions/<subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.Compute/snapshots/myOSSnapshot" |
| 167 | + --data-snapshot-luns 0 |
| 168 | + --data-snapshots "/subscriptions/<subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.Compute/snapshots/myDDSnapshot" |
| 169 | + --gallery-name MyGallery \ |
| 170 | + --gallery-image-definition MyImage |
| 171 | + |
| 172 | +``` |
| 173 | + |
| 174 | +### Create the VM |
| 175 | + |
| 176 | +You can create a VM from a shared image gallery and use customer-managed keys to encrypt the disks. The syntax is the same as creating a [generalized](vm-generalized-image-version-cli.md) or [specialized](vm-specialized-image-version-cli.md) VM from an image, you just need to add the `--os-disk-encryption-set` parameter with the ID of the encryption set. For data disks, add `--data-disk-encryption-sets` with a space delimited list of the disk encryption sets for the data disks. |
| 177 | + |
| 178 | + |
| 179 | +## Portal |
| 180 | + |
| 181 | +When you create your image version in the portal, you can use the **Encryption** tab to enter the information about your storage encryption sets. |
| 182 | + |
| 183 | +1. In the **Create an image version** page, select the **Encryption** tab. |
| 184 | +2. In **Encryption type**, select **Encryption at-rest with a customer-managed key**. |
| 185 | +3. For each disk in the image, select the **Disk encryption set** to use from the drop-down. |
| 186 | + |
| 187 | +### Create the VM |
| 188 | + |
| 189 | +You can create a VM from a shared image gallery and use customer-managed keys to encrypt the disks. When you create the VM in the portal, on the **Disks** tab, select **Encryption at-rest with customer-managed keys** for the **Encryption type**. You can then select the encryption set from the drop-down. |
| 190 | + |
| 191 | +## Next steps |
| 192 | + |
| 193 | +Learn more about [server-side disk encryption](/windows/disk-encryption.md)). |
0 commit comments