Adding Automatic Zone Placement #28882

audreyttt · 2025-11-17T21:25:29Z

Description

Adding four new parameters to New-AzVmssConfig and Update-AzVmss, as requested in this design: https://github.com/Azure/azure-powershell-cmdlet-review-pr/issues/1510

Mandatory Checklist

Please choose the target release of Azure PowerShell. (⚠️Target release is a different concept from API readiness. Please click below links for details.)
- General release
- Public preview
- Private preview
- Engineering build
- No need for a release
Check this box to confirm: I have read the Submitting Changes section of CONTRIBUTING.md and reviewed the following information:

SHOULD update ChangeLog.md file(s) appropriately
- Update src/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.
  - A snippet outlining the change(s) made in the PR should be written under the ## Upcoming Release header in the past tense.
- Should not change ChangeLog.md if no new release is required, such as fixing test case only.
SHOULD regenerate markdown help files if there is cmdlet API change. Instruction
SHOULD have proper test coverage for changes in pull request.
SHOULD NOT adjust version of module manually in pull request

azure-client-tools-bot-prd · 2025-11-17T21:25:32Z

Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status.

Updated agent configuration to specify a PowerShell Pull Request Agent with detailed objectives and rules for modifying cmdlets.

This reverts commit 4027c18.

This reverts commit d3a2dce.

Copilot

Pull request overview

This pull request adds Automatic Zone Placement functionality for Virtual Machine Scale Sets (VMSS) by introducing four new parameters to New-AzVmssConfig, Update-AzVmss, and New-AzVmss cmdlets. The feature enables automatic distribution of VMSS instances across availability zones with configurable constraints, addressing the requirements outlined in the linked design document.

Key changes:

Added ZonePlacementPolicy parameter to control automatic zone selection (values: "Any" for VMs, "Auto" for VMSS)
Added MaxZoneCount parameter to limit the maximum number of zones used when policy is "Auto"
Added EnableMaxInstancePercentPerZone switch and ValueMaxInstancePercentPerZone to control the percentage distribution of VMs per zone
Implemented validation to ensure Overprovision is false when ZonePlacementPolicy is specified

Reviewed changes

Copilot reviewed 9 out of 14 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/Compute/Compute/ChangeLog.md	Added changelog entry documenting the new parameters, but with incorrect casing
src/Compute/Compute/help/New-AzVmss.md	Added documentation for ZonePlacementPolicy parameter in New-AzVmss cmdlet
src/Compute/Compute/help/New-AzVmssConfig.md	Added documentation for all four new parameters in New-AzVmssConfig cmdlet
src/Compute/Compute/help/Update-AzVmss.md	Added documentation for all four new parameters in Update-AzVmss cmdlet
src/Compute/Compute/Generated/VirtualMachineScaleSet/Config/NewAzureRmVmssConfigCommand.cs	Implemented parameter definitions and zone placement logic for config cmdlet, with nested value parameter handling
src/Compute/Compute/Generated/VirtualMachineScaleSet/VirtualMachineScaleSetUpdateMethod.cs	Implemented parameter definitions and zone placement logic for update cmdlet with critical bugs in parameter type and object assignment
src/Compute/Compute/Generated/Models/PSVirtualMachineScaleSet.cs	Added Placement property to the PowerShell model object
src/Compute/Compute/Manual/PSVirtualMachineScaleSet.cs	Added convenience ZonePlacementPolicy string property for simple parameter set
src/Compute/Compute/Manual/VirtualMachineScaleSetCreateOrUpdateMethod.cs	Added ZonePlacementPolicy parameter to New-AzVmss simple parameter set
src/Compute/Compute/Strategies/ComputeRp/VirtualMachineScaleSetStrategy.cs	Updated VMSS creation strategy to include Placement object with ZonePlacementPolicy
src/Compute/Compute.Management.Sdk/Generated/Models/VirtualMachineScaleSetUpdate.cs	Added Placement property to SDK update model
src/Compute/Compute.Test/ScenarioTests/VirtualMachineScaleSetTests.ps1	Added comprehensive test covering creation and update scenarios with zone placement parameters
src/Compute/Compute.Test/ScenarioTests/VirtualMachineScaleSetTests.cs	Added test entry point for new zone placement test

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

src/Compute/Compute/ChangeLog.md

src/Compute/Compute/Generated/VirtualMachineScaleSet/VirtualMachineScaleSetUpdateMethod.cs

src/Compute/Compute/Generated/VirtualMachineScaleSet/Config/NewAzureRmVmssConfigCommand.cs

src/Compute/Compute.Test/ScenarioTests/VirtualMachineScaleSetTests.ps1

src/Compute/Compute/Generated/VirtualMachineScaleSet/Config/NewAzureRmVmssConfigCommand.cs

src/Compute/Compute/help/Update-AzVmss.md

src/Compute/Compute/help/New-AzVmssConfig.md

src/Compute/Compute/Generated/VirtualMachineScaleSet/VirtualMachineScaleSetUpdateMethod.cs

src/Compute/Compute.Test/ScenarioTests/VirtualMachineScaleSetTests.ps1

…ngelog

…method

Copilot

Pull request overview

Copilot reviewed 9 out of 14 changed files in this pull request and generated 9 comments.

Copilot · 2025-12-11T21:15:39Z

src/Compute/Compute/help/Update-AzVmss.md

 ```

+### -MaxInstancePercentPerZoneValue
+The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set.


The help message for MaxInstancePercentPerZoneValue in Update-AzVmss documentation (line 668) uses the same generic description as New-AzVmssConfig. It should match the detailed help message from the code implementation: "Limit on the number of instances in each availability zone as a percentage of the total capacity of the virtual machine scale set. For example: if set to 50, this means that at any time, no more than 50% of the VMs in your scale set can be allocated to a single zone." The current description "The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set" is too generic and doesn't explain how the parameter works.

Suggested change

The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set.

Limit on the number of instances in each availability zone as a percentage of the total capacity of the virtual machine scale set. For example: if set to 50, this means that at any time, no more than 50% of the VMs in your scale set can be allocated to a single zone.

Copilot · 2025-12-11T21:15:39Z

src/Compute/Compute.Test/ScenarioTests/VirtualMachineScaleSetTests.ps1

+        $vmssUpdate = Update-AzVmss -ResourceGroupName $rgname -Name $vmssName2 -MaxInstancePercentPerZoneValue 60;
+
+        Assert-AreEqual $vmssUpdate.ResiliencyPolicy.ZoneAllocationPolicy.MaxInstancePercentPerZonePolicy.Value 60;
+        #>


The test function Test-VirtualMachineScaleSetAutomaticZonePlacement has a multi-line comment starting marker on line 6267 without a proper ending. The marker "#>" should be removed as it appears to be leftover from commenting out code. This will cause a syntax error in PowerShell.

Suggested change

#>

Copilot · 2025-12-11T21:15:40Z

src/Compute/Compute/Strategies/ComputeRp/VirtualMachineScaleSetStrategy.cs

+                        Placement = new Placement
+                        {
+                            ZonePlacementPolicy = zonePlacementPolicy,
+                            IncludeZones = includeZone,
+                            ExcludeZones = excludeZone
+                        }


The Placement object is always created even when all its properties (zonePlacementPolicy, includeZone, excludeZone) are null. This could result in an empty Placement object being sent to the API. Consider only creating the Placement object if at least one of the properties has a non-null value, similar to how other optional properties like ScaleInPolicy and SkuProfile are handled on lines 197-205.

Copilot · 2025-12-11T21:15:40Z

src/Compute/Compute/Strategies/ComputeRp/VirtualMachineScaleSetStrategy.cs

+                        Placement = new Placement
+                        {
+                            ZonePlacementPolicy = zonePlacementPolicy,
+                            IncludeZones = includeZone,
+                            ExcludeZones = excludeZone
+                        }


The Placement object is always created even when all its properties (zonePlacementPolicy, includeZone, excludeZone) are null. This could result in an empty Placement object being sent to the API. Consider only creating the Placement object if at least one of the properties has a non-null value, similar to how other optional properties like ScaleInPolicy and SkuProfile are handled on lines 358-366.

Suggested change

Placement = new Placement

{

ZonePlacementPolicy = zonePlacementPolicy,

IncludeZones = includeZone,

ExcludeZones = excludeZone

}

Placement = (zonePlacementPolicy != null || includeZone != null || excludeZone != null) ? new Placement

{

ZonePlacementPolicy = zonePlacementPolicy,

IncludeZones = includeZone,

ExcludeZones = excludeZone

} : null

Copilot · 2025-12-11T21:15:40Z

src/Compute/Compute/help/New-AzVmss.md

+
+```yaml
+Type: System.String
+Parameter Sets: (All)


The ZonePlacementPolicy parameter documentation incorrectly lists "Parameter Sets: (All)" but the implementation shows it should be "Parameter Sets: SimpleParameterSet" to match the code on line 304 of VirtualMachineScaleSetCreateOrUpdateMethod.cs. This should be corrected to accurately reflect which parameter sets support this parameter.

Suggested change

Parameter Sets: (All)

Parameter Sets: SimpleParameterSet

Copilot · 2025-12-11T21:15:41Z

src/Compute/Compute.Management.Sdk/Generated/Models/VirtualMachineScaleSetUpdate.cs

+        /// <summary>
+        /// Gets or sets the placement of a vmss. Placement section specifies 
+        /// the user-defined constraints for virtual machine scale set hardware placement. 
+        /// This property cannot be changed once VMSS is provisioned.
+        /// </summary>
+        [JsonProperty(PropertyName = "placement")]
+        public Placement Placement { get; set; }


The comment on lines 247-249 states "This property cannot be changed once VMSS is provisioned" but the Placement property is being added to VirtualMachineScaleSetUpdate, which is used for updating existing VMSS. If the property truly cannot be changed after provisioning, it should not be in the Update model. If it can be changed, the comment is misleading. Please verify the Azure API behavior and either remove the property from the Update model or update the comment to accurately reflect whether this property is mutable.

Suggested change

/// <summary>

/// Gets or sets the placement of a vmss. Placement section specifies

/// the user-defined constraints for virtual machine scale set hardware placement.

/// This property cannot be changed once VMSS is provisioned.

/// </summary>

[JsonProperty(PropertyName = "placement")]

public Placement Placement { get; set; }

Copilot · 2025-12-11T21:15:41Z

src/Compute/Compute/ChangeLog.md

 * Added `-InstantAccessDurationMinutes` parameter to New-AzSnapshotConfig.
 * Added `SecureVMGuestStateSAS` parameter to `Grant-AzSnapshotAccess`.
 * Updated SDK to use 2025-04-01 version of the ComputeRP API for Compute related cmdlets.
+* Added new parameters `ZonePlacementPolicy`, `maxZoneCount`, `enableMaxInstancePercentPerZone`, and `maxInstancePercentPerZoneValue` to `New-AzVmssConfig` and `Update-AzVmss` cmdlets for VMSS Automatic Zone Placement. 


The parameter names in the ChangeLog entry on line 50 use inconsistent casing. They use camelCase (maxZoneCount, enableMaxInstancePercentPerZone, maxInstancePercentPerZoneValue) instead of PascalCase used in the actual parameter names (MaxZoneCount, EnableMaxInstancePercentPerZone, MaxInstancePercentPerZoneValue). Parameter names in ChangeLog entries should match the actual parameter names exactly, including casing.

Suggested change

* Added new parameters `ZonePlacementPolicy`, `maxZoneCount`, `enableMaxInstancePercentPerZone`, and `maxInstancePercentPerZoneValue` to `New-AzVmssConfig` and `Update-AzVmss` cmdlets for VMSS Automatic Zone Placement.

* Added new parameters `ZonePlacementPolicy`, `MaxZoneCount`, `EnableMaxInstancePercentPerZone`, and `MaxInstancePercentPerZoneValue` to `New-AzVmssConfig` and `Update-AzVmss` cmdlets for VMSS (Virtual Machine Scale Set) Automatic Zone Placement.

Copilot · 2025-12-11T21:15:41Z

src/Compute/Compute/help/New-AzVmssConfig.md

 ```

+### -MaxInstancePercentPerZoneValue
+The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set.


The help message for MaxInstancePercentPerZoneValue in the generated code (line 431) is more detailed and user-friendly than the help documentation (line 724 in the .md file). The documentation should match the detailed help message from the code: "Limit on the number of instances in each availability zone as a percentage of the total capacity of the virtual machine scale set. For example: if set to 50, this means that at any time, no more than 50% of the VMs in your scale set can be allocated to a single zone." The current documentation description "The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set" is too generic and doesn't explain how the parameter works.

Suggested change

The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set.

Limit on the number of instances in each availability zone as a percentage of the total capacity of the virtual machine scale set. For example: if set to 50, this means that at any time, no more than 50% of the VMs in your scale set can be allocated to a single zone.

audreyttt added 3 commits October 10, 2025 11:17

Implement new parameters and adding tests for Auto Zone Placement

a8427c8

Fix update method

cd16ab3

Merge branch 'main' into audreyt/autoZonePlacement

fa5fac2

audreyttt added 8 commits November 19, 2025 14:10

Add ZonePlacementPolicy param to New-AzVmss

dee4887

Add test for New-AzVmss

7893add

Define PowerShell Pull Request Agent with guidelines

d3a2dce

Updated agent configuration to specify a PowerShell Pull Request Agent with detailed objectives and rules for modifying cmdlets.

Rename my-agent.agent.md to ps-cmdlet.agent.md

4027c18

Merge branch 'main' of https://github.com/audreyttt/azure-powershell

4439dd0

Revert "Rename my-agent.agent.md to ps-cmdlet.agent.md"

e7364fd

This reverts commit 4027c18.

Revert "Define PowerShell Pull Request Agent with guidelines"

94e5b2b

This reverts commit d3a2dce.

Merge branch 'main' into audreyt/autoZonePlacement

79338fa

Copilot AI review requested due to automatic review settings December 1, 2025 19:51

Copilot started reviewing on behalf of audreyttt December 1, 2025 19:53 View session

Copilot finished reviewing on behalf of audreyttt December 1, 2025 19:57

Copilot AI reviewed Dec 1, 2025

View reviewed changes

audreyttt added 8 commits December 1, 2025 16:09

Rename ValueMaxInstancePercentPerZone to MaxInstancePercentPerZoneValue

7e4c455

Add IncludeZone and ExcludeZone properties

3fa0bb7

Add IncludeZone and Exclude Zone to vmss update method and update cha…

3ef7128

…ngelog

Update help docs

7478986

Add testing for new parameters

2fef2ce

Merge branch 'main' of https://github.com/audreyttt/azure-powershell

22a973e

Merge branch 'main' into audreyt/autoZonePlacement

bd880d4

Remove ZonePlacementPolicy, InlcudeZone, and ExcludeZone from Update …

23d89c3

…method

Copilot AI review requested due to automatic review settings December 11, 2025 21:03

Copilot started reviewing on behalf of audreyttt December 11, 2025 21:06 View session

Copilot AI reviewed Dec 11, 2025

View reviewed changes

	The configuration parameters used to limit the number of virtual machines per availability zone in the virtual machine scale set.
	Limit on the number of instances in each availability zone as a percentage of the total capacity of the virtual machine scale set. For example: if set to 50, this means that at any time, no more than 50% of the VMs in your scale set can be allocated to a single zone.

	* Added new parameters `ZonePlacementPolicy`, `maxZoneCount`, `enableMaxInstancePercentPerZone`, and `maxInstancePercentPerZoneValue` to `New-AzVmssConfig` and `Update-AzVmss` cmdlets for VMSS Automatic Zone Placement.
	* Added new parameters `ZonePlacementPolicy`, `MaxZoneCount`, `EnableMaxInstancePercentPerZone`, and `MaxInstancePercentPerZoneValue` to `New-AzVmssConfig` and `Update-AzVmss` cmdlets for VMSS (Virtual Machine Scale Set) Automatic Zone Placement.

Adding Automatic Zone Placement #28882

Are you sure you want to change the base?

Adding Automatic Zone Placement #28882

Uh oh!

Conversation

audreyttt commented Nov 17, 2025

Description

Mandatory Checklist

Uh oh!

azure-client-tools-bot-prd bot commented Nov 17, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant