Azure / Azure/azure-powershell

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

Open
#29,455 2 comments 0 reactions 0 assignees View on GitHub
feature-request Similar-Issue
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.