Enable customer-managed keys for Azure managed disks with PowerShell

Applies to: ✔️ Windows VMs ✔️ Flexible scale sets ✔️ Uniform scale sets

Azure Disk Storage supports server-side encryption (SSE) with customer-managed keys for managed disks. For conceptual information about customer-managed keys and other managed disk encryption types, see Customer-managed keys.

Restrictions

For now, customer-managed keys have the following restrictions:

• If this feature is enabled for a disk with incremental snapshots, it can't be disabled on that disk or its snapshots. To work around this, copy all the data to an entirely different managed disk that isn't using customer-managed keys. You can do that with either the Azure CLI or the Azure PowerShell module.
• A disk and all of its associated incremental snapshots must have the same disk encryption set.
• Only software and HSM RSA keys of sizes 2,048-bit, 3,072-bit and 4,096-bit are supported, no other keys or sizes.
  • HSM keys require the premium tier of Azure Key vaults.
• For Ultra Disks and Premium SSD v2 disks only:
  • (Preview) User-assigned managed identities are available for Ultra Disks and Premium SSD v2 disks encrypted with customer-managed keys.
• Most resources related to your customer-managed keys (disk encryption sets, VMs, disks, and snapshots) must be in the same subscription and region.
  • Azure Key Vaults may be used from a different subscription but must be in the same region as your disk encryption set.
• Disks encrypted with customer-managed keys can only move to another resource group if the VM they're attached to is deallocated.
• Disks, snapshots, and images encrypted with customer-managed keys can't be moved between subscriptions.
• Managed disks currently or previously encrypted using Azure Disk Encryption can't be encrypted using customer-managed keys.
• Can only create up to 5000 disk encryption sets per region per subscription.
• For information about using customer-managed keys with shared image galleries, see Preview: Use customer-managed keys for encrypting images.

Set up Azure Key Vault and a disk encryption set with automatic key rotation

To use customer-managed keys with server-side encryption, set up an Azure Key Vault and a disk encryption set.

1. Install the latest Azure PowerShell version, and sign in to your Azure account with Connect-AzAccount.

2. Create an instance of Azure Key Vault and encryption key.

   When creating the Key Vault instance, you must enable purge protection. Purge protection ensures that a deleted key cannot be permanently deleted until the retention period lapses. These settings protect you from losing data due to accidental deletion. These settings are mandatory when using a Key Vault for encrypting managed disks.

   $ResourceGroupName="yourResourceGroupName"
   $LocationName="chinaeast2"
   $keyVaultName="yourKeyVaultName"
   $keyName="yourKeyName"
   $keyDestination="Software"
   $diskEncryptionSetName="yourDiskEncryptionSetName"
   
   $keyVault = New-AzKeyVault -Name $keyVaultName `
   -ResourceGroupName $ResourceGroupName `
   -Location $LocationName `
   -EnablePurgeProtection
   
   $key = Add-AzKeyVaultKey -VaultName $keyVaultName `
         -Name $keyName `
         -Destination $keyDestination
   
   Set-AzKeyVaultKeyRotationPolicy -VaultName $keyVaultName -KeyName $keyName -ExpiresIn P2Y -KeyRotationLifetimeAction @{Action="Rotate";TimeBeforeExpiry = "P18M"}
   

3. Create a disk encryption set. This script sets RotationToLatestKeyVersionEnabled equal to $true to enable automatic rotation of the key. When you enable automatic rotation, the system automatically updates all managed disks, snapshots, and images referencing the disk encryption set to use the new version of the key within one hour.

   $desConfig=New-AzDiskEncryptionSetConfig -Location $LocationName `
       -SourceVaultId $keyVault.ResourceId `
       -KeyUrl $key.Key.Kid `
       -IdentityType SystemAssigned `
       -RotationToLatestKeyVersionEnabled $true
   
   $des=New-AzDiskEncryptionSet -Name $diskEncryptionSetName `
          -ResourceGroupName $ResourceGroupName `
          -InputObject $desConfig
   

4. Grant the disk encryption set access to the key vault.

   Note

   It might take a few minutes for Azure to create the identity of your disk encryption set in Microsoft Entra ID. If you get an error like "Cannot find the Active Directory object" when running the following command, wait a few minutes and try again.

   Set-AzKeyVaultAccessPolicy -VaultName $keyVaultName -ObjectId $des.Identity.PrincipalId -PermissionsToKeys wrapkey,unwrapkey,get
   

Use a key vault in a different subscription

Alternatively, you can manage your Azure Key Vaults centrally from a single subscription, and use the keys stored in the Key Vault to encrypt managed disks and snapshots in other subscriptions in your organization. This allows your security team to enforce and easily manage a robust security policy to a single subscription.

The following script is an example of how you would configure a disk encryption set to use a key from a Key Vault in a different subscription, but same region:

$sourceSubscriptionId="<sourceSubID>"
$sourceKeyVaultName="<sourceKVName>"
$sourceKeyName="<sourceKeyName>"

$targetSubscriptionId="<targetSubID>"
$targetResourceGroupName="<targetRGName>"
$targetDiskEncryptionSetName="<targetDiskEncSetName>"
$location="<targetRegion>"

Set-AzContext -Subscription $sourceSubscriptionId

$key = Get-AzKeyVaultKey -VaultName $sourceKeyVaultName -Name $sourceKeyName

Set-AzContext -Subscription $targetSubscriptionId

$desConfig=New-AzDiskEncryptionSetConfig -Location $location `
-KeyUrl $key.Key.Kid `
-IdentityType SystemAssigned `
-RotationToLatestKeyVersionEnabled $true

$des=New-AzDiskEncryptionSet -Name $targetDiskEncryptionSetName `
-ResourceGroupName $targetResourceGroupName `
-InputObject $desConfig

Manage customer-managed keys for Azure managed disks with PowerShell

After you create and configure the required resources, use the following example Azure PowerShell scripts to create encrypted VMs and disks, encrypt existing managed disks and scale sets, rotate a disk encryption set key, and check a disk's server-side encryption status.

Create a VM using a Marketplace image, encrypting the OS and data disks with customer-managed keys

Before you run the script, provide an existing resource group and disk encryption set, along with values for the VM administrator credentials, region, VM size, and virtual network. The script creates the virtual network, network interface, and VM from a Windows Server Marketplace image. It uses Get-AzDiskEncryptionSet to retrieve the disk encryption set and New-AzVM to create the VM with an encrypted OS disk and a 128-GiB encrypted data disk. Replace the example values with your own parameters, and then run the script.

$VMLocalAdminUser = "yourVMLocalAdminUserName"
$VMLocalAdminSecurePassword = ConvertTo-SecureString <password> -AsPlainText -Force
$LocationName = "yourRegion"
$ResourceGroupName = "yourResourceGroupName"
$ComputerName = "yourComputerName"
$VMName = "yourVMName"
$VMSize = "yourVMSize"
$diskEncryptionSetName="yourdiskEncryptionSetName"

$NetworkName = "yourNetworkName"
$NICName = "yourNICName"
$SubnetName = "yourSubnetName"
$SubnetAddressPrefix = "10.0.0.0/24"
$VnetAddressPrefix = "10.0.0.0/16"

$SingleSubnet = New-AzVirtualNetworkSubnetConfig -Name $SubnetName -AddressPrefix $SubnetAddressPrefix
$Vnet = New-AzVirtualNetwork -Name $NetworkName -ResourceGroupName $ResourceGroupName -Location $LocationName -AddressPrefix $VnetAddressPrefix -Subnet $SingleSubnet
$NIC = New-AzNetworkInterface -Name $NICName -ResourceGroupName $ResourceGroupName -Location $LocationName -SubnetId $Vnet.Subnets[0].Id

$Credential = New-Object System.Management.Automation.PSCredential ($VMLocalAdminUser, $VMLocalAdminSecurePassword);

$VirtualMachine = New-AzVMConfig -VMName $VMName -VMSize $VMSize
$VirtualMachine = Set-AzVMOperatingSystem -VM $VirtualMachine -Windows -ComputerName $ComputerName -Credential $Credential -ProvisionVMAgent -EnableAutoUpdate
$VirtualMachine = Add-AzVMNetworkInterface -VM $VirtualMachine -Id $NIC.Id
$VirtualMachine = Set-AzVMSourceImage -VM $VirtualMachine -PublisherName 'MicrosoftWindowsServer' -Offer 'WindowsServer' -Skus '2012-R2-Datacenter' -Version latest

$diskEncryptionSet=Get-AzDiskEncryptionSet -ResourceGroupName $ResourceGroupName -Name $diskEncryptionSetName

$VirtualMachine = Set-AzVMOSDisk -VM $VirtualMachine -Name $($VMName +"_OSDisk") -DiskEncryptionSetId $diskEncryptionSet.Id -CreateOption FromImage

$VirtualMachine = Add-AzVMDataDisk -VM $VirtualMachine -Name $($VMName +"DataDisk1") -DiskSizeInGB 128 -StorageAccountType Premium_LRS -CreateOption Empty -Lun 0 -DiskEncryptionSetId $diskEncryptionSet.Id 

New-AzVM -ResourceGroupName $ResourceGroupName -Location $LocationName -VM $VirtualMachine -Verbose

Create an empty disk encrypted using server-side encryption with customer-managed keys and attach it to a VM

The script uses Add-AzVMDataDisk to add the encrypted data disk to the VM configuration and Update-AzVM to apply the configuration. Replace the example values with your own parameters, and then run the script.

$vmName = "yourVMName"
$LocationName = "chinaeast2"
$ResourceGroupName = "yourResourceGroupName"
$diskName = "yourDiskName"
$diskSKU = "Premium_LRS"
$diskSizeinGiB = 30
$diskLUN = 1
$diskEncryptionSetName="yourDiskEncryptionSetName"


$vm = Get-AzVM -Name $vmName -ResourceGroupName $ResourceGroupName 

$diskEncryptionSet=Get-AzDiskEncryptionSet -ResourceGroupName $ResourceGroupName -Name $diskEncryptionSetName

$vm = Add-AzVMDataDisk -VM $vm -Name $diskName -CreateOption Empty -DiskSizeInGB $diskSizeinGiB -StorageAccountType $diskSKU -Lun $diskLUN -DiskEncryptionSetId $diskEncryptionSet.Id 

Update-AzVM -ResourceGroupName $ResourceGroupName -VM $vm

Encrypt existing managed disks

Your existing disks must not be attached to a running VM. The script uses New-AzDiskUpdateConfig and Update-AzDisk to configure customer-managed keys for the disk.

$rgName = "yourResourceGroupName"
$diskName = "yourDiskName"
$diskEncryptionSetName = "yourDiskEncryptionSetName"

$diskEncryptionSet = Get-AzDiskEncryptionSet -ResourceGroupName $rgName -Name $diskEncryptionSetName

New-AzDiskUpdateConfig -EncryptionType "EncryptionAtRestWithCustomerKey" -DiskEncryptionSetId $diskEncryptionSet.Id | Update-AzDisk -ResourceGroupName $rgName -DiskName $diskName

Encrypt an existing virtual machine scale set (uniform orchestration mode) by using server-side encryption and customer-managed keys

This script will work for scale sets in uniform orchestration mode only. For scale sets in flexible orchestration mode, follow the Encrypt existing managed disks for each VM.

The script uses Get-AzVmss to retrieve the scale set and Update-AzVmss to apply the disk encryption set. Replace the example values with your own parameters, and then run the script.

#set variables 
$vmssname = "name of the vmss that is already created"
$diskencryptionsetname = "name of the diskencryptionset already created"
$vmssrgname = "vmss resourcegroup name"
$diskencryptionsetrgname = "diskencryptionset resourcegroup name"

#get vmss object and create diskencryptionset object attach to vmss os disk
$ssevmss = get-azvmss -ResourceGroupName $vmssrgname -VMScaleSetName $vmssname
$ssevmss.VirtualMachineProfile.StorageProfile.OsDisk.ManagedDisk.DiskEncryptionSet = New-Object -TypeName Microsoft.Azure.Management.Compute.Models.DiskEncryptionSetParameters

#get diskencryption object and retrieve the resource id
$des = Get-AzDiskEncryptionSet -ResourceGroupName $diskencryptionsetrgname -Name $diskencryptionsetname
write-host "the diskencryptionset resource id is:" $des.Id

#associate DES resource id to os disk and update vmss 
$ssevmss.VirtualMachineProfile.StorageProfile.OsDisk.ManagedDisk.DiskEncryptionSet.id = $des.Id
$ssevmss | update-azvmss

Create a virtual machine scale set using a Marketplace image, encrypting the OS and data disks with customer-managed keys

Before you run the script, provide an existing resource group and disk encryption set, along with values for the administrator credentials, region, VM size, and virtual network. The script creates the virtual network and uses New-AzVmss to create a two-instance uniform virtual machine scale set from a Windows Server Marketplace image. The scale set's OS disks and 128-GiB data disks use the disk encryption set. Replace the example values with your own parameters, and then run the script.

$VMLocalAdminUser = "yourLocalAdminUser"
$VMLocalAdminSecurePassword = ConvertTo-SecureString Password@123 -AsPlainText -Force
$LocationName = "chinaeast2"
$ResourceGroupName = "yourResourceGroupName"
$ComputerNamePrefix = "yourComputerNamePrefix"
$VMScaleSetName = "yourVMSSName"
$VMSize = "Standard_DS3_v2"
$diskEncryptionSetName="yourDiskEncryptionSetName"

$NetworkName = "yourVNETName"
$SubnetName = "yourSubnetName"
$SubnetAddressPrefix = "10.0.0.0/24"
$VnetAddressPrefix = "10.0.0.0/16"

$SingleSubnet = New-AzVirtualNetworkSubnetConfig -Name $SubnetName -AddressPrefix $SubnetAddressPrefix

$Vnet = New-AzVirtualNetwork -Name $NetworkName -ResourceGroupName $ResourceGroupName -Location $LocationName -AddressPrefix $VnetAddressPrefix -Subnet $SingleSubnet

$ipConfig = New-AzVmssIpConfig -Name "myIPConfig" -SubnetId $Vnet.Subnets[0].Id 

$VMSS = New-AzVmssConfig -Location $LocationName -SkuCapacity 2 -SkuName $VMSize -UpgradePolicyMode 'Automatic' -OrchestrationMode 'Uniform'

$VMSS = Add-AzVmssNetworkInterfaceConfiguration -Name "myVMSSNetworkConfig" -VirtualMachineScaleSet $VMSS -Primary $true -IpConfiguration $ipConfig

$diskEncryptionSet=Get-AzDiskEncryptionSet -ResourceGroupName $ResourceGroupName -Name $diskEncryptionSetName

# Enable encryption at rest with customer managed keys for OS disk by setting DiskEncryptionSetId property 

$VMSS = Set-AzVmssStorageProfile $VMSS -OsDiskCreateOption "FromImage" -DiskEncryptionSetId $diskEncryptionSet.Id -ImageReferenceOffer 'WindowsServer' -ImageReferenceSku '2012-R2-Datacenter' -ImageReferenceVersion latest -ImageReferencePublisher 'MicrosoftWindowsServer'

$VMSS = Set-AzVmssOsProfile $VMSS -ComputerNamePrefix $ComputerNamePrefix -AdminUsername $VMLocalAdminUser -AdminPassword $VMLocalAdminSecurePassword

# Add a data disk encrypted at rest with customer managed keys by setting DiskEncryptionSetId property 

$VMSS = Add-AzVmssDataDisk -VirtualMachineScaleSet $VMSS -CreateOption Empty -Lun 1 -DiskSizeGB 128 -StorageAccountType Premium_LRS -DiskEncryptionSetId $diskEncryptionSet.Id

$Credential = New-Object System.Management.Automation.PSCredential ($VMLocalAdminUser, $VMLocalAdminSecurePassword);

New-AzVmss -VirtualMachineScaleSet $VMSS -ResourceGroupName $ResourceGroupName -VMScaleSetName $VMScaleSetName

Change the key of a disk encryption set to rotate the key for referenced resources

The script uses Update-AzDiskEncryptionSet to change the key referenced by the disk encryption set. Replace the example values with your own parameters, and then run the script.

$ResourceGroupName="yourResourceGroupName"
$keyVaultName="yourKeyVaultName"
$keyName="yourKeyName"
$diskEncryptionSetName="yourDiskEncryptionSetName"

$keyVault = Get-AzKeyVault -VaultName $keyVaultName -ResourceGroupName $ResourceGroupName

$keyVaultKey = Get-AzKeyVaultKey -VaultName $keyVaultName -Name $keyName

Update-AzDiskEncryptionSet -Name $diskEncryptionSetName -ResourceGroupName $ResourceGroupName -SourceVaultId $keyVault.ResourceId -KeyUrl $keyVaultKey.Id

Find the status of server-side encryption of a disk

The script uses Get-AzDisk to retrieve the disk's server-side encryption type.

$ResourceGroupName="yourResourceGroupName"
$DiskName="yourDiskName"

$disk=Get-AzDisk -ResourceGroupName $ResourceGroupName -DiskName $DiskName
$disk.Encryption.Type

For disks configured by the preceding examples, EncryptionAtRestWithCustomerKey indicates server-side encryption with a customer-managed key. EncryptionAtRestWithPlatformAndCustomerKeys indicates double encryption with both customer-managed and platform-managed keys.

Next steps

• Explore the Azure Resource Manager templates for creating encrypted disks with customer-managed keys

• Set up disaster recovery of VMware VMs to Azure with PowerShell

• Set up disaster recovery to Azure for Hyper-V VMs using PowerShell and Azure Resource Manager