Azure / Azure/azure-powershell
[Feature]: Az.Compute - Add and improve PowerShell cmdlet support for Community Galleries
- Dominant language
- C#
- Stars
- 4.8k
- Forks
- 4.3k
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 54
Description
## 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
- #28448 - How does one launch a VM from a Community Gallery?
- #28657 - New-AzGalleryImageVersion fails when GalleryImageDefinition's SecurityType=ConfidentialVM
### References
- ADO Work Item: [PS onboarding for Community Galleries](https://msazure.visualstudio.com/One/_workitems/edit/36807077)
- 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 -GalleryPublicName -Community` |
| `Get-AzGalleryImageDefinition` | `Get-AzGalleryImageDefinition -Location -GalleryPublicName ` |
| `Get-AzGalleryImageVersion` | `Get-AzGalleryImageVersion -Location -GalleryPublicName -GalleryImageDefinitionName ` |
### 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:**
```powershell
# 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):**
```powershell
# 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 (#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.
Contributor guide
Research direction
Start with VirtualMachineStrategy.cs and the New-AzVM, New-AzVmss, Set-AzVMSourceImage, and New-AzGalleryImageVersion entry points named in the issue. Review related issue #28657 and the existing -ImageReferenceId and -GalleryPublicName/-Community behavior. Done means first-class community image parameters, correct ConfidentialVM TargetRegion serialization, and updated cmdlet documentation and examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, csharp, powershell
- Domain
- cli, cloud
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100