[Feature]: Az.Compute - Add and improve PowerShell cmdlet support for Community Galleries

[purbch]

Description of the new feature

PowerShell cmdlets in the Az.Compute module need improvements to fully support Azure Compute Community Galleries. While the existing Get-AzGallery* cmdlets have Community Gallery parameter sets (via -GalleryPublicName and -Community parameters), there are gaps in VM creation workflows and documentation that prevent users from easily working with Community Gallery images.

Related Issues

• How does one launch a VM from a Community Gallery ? #28448 - How does one launch a VM from a Community Gallery?
• [Bug] Az.Compute - New-AzGalleryImageVersion fails when GalleryImageDefinition's SecurityType=ConfidentialVM #28657 - New-AzGalleryImageVersion fails when GalleryImageDefinition's SecurityType=ConfidentialVM

References

• ADO Work Item: PS onboarding for Community Galleries
• Cmdlet Review PR: https://github.com/Azure/azure-powershell-cmdlet-review-pr/issues/1541

Proposed implementation details (optional)

Existing Cmdlets with Community Gallery Support

The following cmdlets already support Community Gallery via the -GalleryPublicName parameter and -Community switch:

Cmdlet	Community Gallery Usage
Get-AzGallery	Get-AzGallery -Location <location> -GalleryPublicName <name> -Community
Get-AzGalleryImageDefinition	Get-AzGalleryImageDefinition -Location <location> -GalleryPublicName <name>
Get-AzGalleryImageVersion	Get-AzGalleryImageVersion -Location <location> -GalleryPublicName <name> -GalleryImageDefinitionName <image>

Cmdlets That Need Updates

Cmdlet	Change Required
New-AzVM	No -CommunityGalleryImageId parameter exists at all. The only workaround is using -ImageReferenceId with a /CommunityGalleries/... path, which relies on undocumented internal path detection in VirtualMachineStrategy.cs. A first-class -CommunityGalleryImageId parameter should be added.
New-AzVmss	Same gap as New-AzVM — needs a -CommunityGalleryImageId parameter for VMSS creation from community gallery images
Set-AzVMSourceImage	The -Id parameter always sets ImageReference.Id on the SDK model. It has no community gallery support — it needs a -CommunityGalleryImageId parameter that correctly sets ImageReference.CommunityGalleryImageId instead. Currently users cannot use the advanced New-AzVMConfig pipeline for community gallery images.
New-AzGalleryImageVersion	Does not properly serialize TargetRegion encryption/securityProfile for ConfidentialVM scenarios. The hashtable-based TargetRegion produces "osDiskImage": {} — the securityProfile is silently dropped during serialization (see #28657).

Example Workflows

Discover and use a Community Gallery image to create a VM:

# List community gallery
Get-AzGallery -Location "eastus" -GalleryPublicName "myGallery-GUID" -Community

# List community gallery images
Get-AzGalleryImageDefinition -Location "eastus" -GalleryPublicName "myGallery-GUID"

# List community gallery image versions
Get-AzGalleryImageVersion -Location "eastus" -GalleryPublicName "myGallery-GUID" -GalleryImageDefinitionName "myImage"

# Create VM from community gallery image (proposed - parameter does not exist yet)
$communityImageId = "/CommunityGalleries/myGallery-GUID/Images/myImage/Versions/1.0.0"
New-AzVM -ResourceGroupName "myRG" -Name "myVM" -Location "eastus" -CommunityGalleryImageId $communityImageId

# Advanced pipeline (proposed - Set-AzVMSourceImage needs -CommunityGalleryImageId)
$vmConfig = New-AzVMConfig -VMName "myVM" -VMSize "Standard_D2s_v3"
$vmConfig = Set-AzVMSourceImage -VM $vmConfig -CommunityGalleryImageId "/CommunityGalleries/myGallery-GUID/Images/myImage/Versions/1.0.0"
New-AzVM -ResourceGroupName "myRG" -Location "eastus" -VM $vmConfig

Create gallery image version with ConfidentialVM encryption (currently broken - see #28657):

# This should work but currently fails because the TargetRegion hashtable's
# encryption.osDiskImage.securityProfile is silently dropped during serialization,
# producing "osDiskImage": {} in the REST request body.
New-AzGalleryImageVersion -ResourceGroupName "myRG" `
  -GalleryName "myGallery" `
  -GalleryImageDefinitionName "myConfidentialImage" `
  -Name "1.0.0" `
  -Location "eastus" `
  -SourceImageId "/subscriptions/.../images/myImage" `
  -TargetRegion @(
    @{
      Name                    = "eastus"
      RegionalReplicaCount    = 1
      StorageAccountType      = "Standard_LRS"
      Encryption              = @{
        OSDiskImage = @{
          SecurityProfile = @{
            confidentialVMEncryptionType = "EncryptedVMGuestStateOnlyWithPmk"
            secureVMDiskEncryptionSetId  = "/subscriptions/.../diskEncryptionSets/myDES"
          }
        }
      }
    }
  )

Current Gaps

1. No -CommunityGalleryImageId on New-AzVM — There is no first-class parameter for community gallery images on New-AzVM. The only workaround is -ImageReferenceId with a /CommunityGalleries/... path, which relies on undocumented internal path prefix detection in VirtualMachineStrategy.cs. This forces users to discover the workaround through trial and error.
2. Set-AzVMSourceImage has no community gallery support — The -Id parameter always sets ImageReference.Id, not ImageReference.CommunityGalleryImageId. This means the advanced New-AzVMConfig pipeline cannot be used for community gallery images at all.
3. New-AzGalleryImageVersion ConfidentialVM serialization bug — The hashtable-based TargetRegion encryption is not properly serialized. encryption.osDiskImage.securityProfile is silently dropped, producing empty JSON ("osDiskImage": {}) sent to the API ([Bug] Az.Compute - New-AzGalleryImageVersion fails when GalleryImageDefinition's SecurityType=ConfidentialVM #28657). The documentation also has incorrect property names (e.g., CVMEncryptionType instead of confidentialVMEncryptionType).
4. Documentation gaps — Community Gallery usage with Get-AzGallery* cmdlets via -GalleryPublicName / -Community is poorly documented. Examples and help text need improvement.

[github-actions]

Here are some similar issues that might help you. Please check if they can solve your problem.

• [Feature Request] Az.Compute - Add PowerShell cmdlet support for Community Galleries #29454

Powered by issue-sentinel

[purbch]

Closing to recreate with corrected cmdlet names and examples.