Skip to content

Commit da9cb08

Browse files
grizzlytheodoreTheodore Changwyunchi-ms
authored
Improve cmdlet descriptions and parameter descriptions for VM/VMSS creation. (#19583)
* Feature/cplat new az vm improvements (#19582) * update with Get-AzComputeResourceSku information in md files * update md * update * update * update md files * update * update * a * a * update * a * a * a * update * a * a * a * a * a * a * a * a * changelog * Update New-AzVM.md * a * a * a * a Co-authored-by: Theodore Chang <[email protected]> * Feature/cplat new az vm improvements (#19644) * update with Get-AzComputeResourceSku information in md files * update md * update * update * update md files * update * update * a * a * update * a * a * a * update * a * a * a * a * a * a * a * a * changelog * Update New-AzVM.md * a * a * a * a * update heading Co-authored-by: Theodore Chang <[email protected]> * update heading * Update New-AzVmss.md * Update New-AzVmss.md * suppress false static analysis example issues * Update ChangeLog.md Co-authored-by: Theodore Chang <[email protected]> Co-authored-by: Yunchi Wang <[email protected]>
1 parent 1ae17e5 commit da9cb08

File tree

7 files changed

+87
-26
lines changed

7 files changed

+87
-26
lines changed

src/Compute/Compute/ChangeLog.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
-->
2222
## Upcoming Release
2323
* Added the `TimeCreated` property to the Virtual Machine and Virtual Machine Scale Set models.
24+
* Improved cmdlet descriptions and parameter descriptions for VM/VMSS creation.
2425
* Added the 'BaseRegularPriorityCount' integer property to the following cmdlets: `New-AzVmssConfig` and `Update-AzVmssConfig`
2526
* Added the 'RegularPriorityPercentage' integer property to the following cmdlets: `New-AzVmssConfig` and `Update-AzVmssConfig`
2627
* Added Breaking Changes for Add-AzVMAdditionalUnattendContent and Get-AzGallery cmdlets

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

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,18 @@ New-AzVM [[-ResourceGroupName] <String>] [[-Location] <String>] [-EdgeZone <Stri
5757

5858
## DESCRIPTION
5959
The **New-AzVM** cmdlet creates a virtual machine in Azure.
60-
This cmdlet takes a virtual machine object as input.
61-
Use the New-AzVMConfig cmdlet to create a virtual machine object.
62-
The **New-AzVM** cmdlet will create a new storage account for boot diagnostics if one does not already exist.
63-
Other cmdlets can be used to configure the virtual machine, such as Set-AzVMOperatingSystem, Set-AzVMSourceImage, Add-AzVMNetworkInterface, and Set-AzVMOSDisk.
64-
The `SimpleParameterSet` provides a convenient method to create a VM by making common VM creation arguments optional.
60+
This cmdlet takes a virtual machine object as input. The **New-AzVM** cmdlet will create a new storage account for boot diagnostics if one does not already exist. <br> <br>
61+
Use the **[New-AzVMConfig](https://docs.microsoft.com/en-us/powershell/module/az.compute/new-azvmconfig)** cmdlet to create a virtual machine object. <br>
62+
Then use the following cmdlets to set different properties of the virtual machine object:
63+
- **[Add-AzVMNetworkInterface](https://learn.microsoft.com/en-us/powershell/module/az.compute/add-azvmnetworkinterface)** to set the network profile.<br>
64+
- **[Set-AzVMOperatingSystem](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmoperatingsystem)** to set the OS profile. <br>
65+
- **[Set-AzVMSourceImage](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmsourceimage)** to set the source image.<br>
66+
- **[Set-AzVMOSDisk](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmosdisk)** to set the OS disk(storage profile).<br>
67+
- **[Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku)** can also be used to find out available virtual machine sizes for your subscription and region.<br>
68+
<br>
69+
The `SimpleParameterSet` provides a convenient method to create a VM by making common VM creation arguments optional.<br>
70+
<br>
71+
See [Quickstart: Create a Windows virtual machine in Azure with PowerShell](https://learn.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-powershell) for tutorial. <br>
6572

6673
## EXAMPLES
6774

@@ -389,8 +396,17 @@ Accept wildcard characters: False
389396
```
390397
391398
### -Credential
392-
The administrator credentials for the VM.
393-
399+
The administrator credentials for the VM. <br><br>
400+
**Username** <br>
401+
**Restriction:** <br>
402+
Windows: Cannot contain special characters \/""[]:|<>+=;,?*@& or end in \".\" <br>
403+
Linux: Username must only contain letters, numbers, hyphens, and underscores and may not start with a hyphen or number. <br>
404+
**Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br>
405+
**Minimum-length:** 1 character <br>
406+
**Max-length:** 20 characters for Windows, 64 characters for Linux <br><br>
407+
**Password** <br>
408+
Must have 3 of the following: 1 lower case character, 1 upper case character, 1 number, and 1 special character. <br>
409+
The value must be between 12 and 123 characters long.
394410
```yaml
395411
Type: System.Management.Automation.PSCredential
396412
Parameter Sets: SimpleParameterSet
@@ -921,7 +937,8 @@ Accept wildcard characters: False
921937
```
922938

923939
### -Size
924-
The Virtual Machine Size. The Default Value is: Standard_D2s_v3.
940+
The Virtual Machine Size. [Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku) can be used to find out available sizes for your subscription and region.<br>
941+
The Default Value is: Standard_D2s_v3.
925942

926943
```yaml
927944
Type: System.String

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

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,16 @@ New-AzVMConfig [-VMName] <String> [-VMSize] <String> [[-AvailabilitySetId] <Stri
3535
```
3636

3737
## DESCRIPTION
38-
The **New-AzVMConfig** cmdlet creates a configurable local virtual machine object for Azure.
39-
Other cmdlets can be used to configure a virtual machine object, such as Set-AzVMOperatingSystem, Set-AzVMSourceImage, Add-AzVMNetworkInterface, and Set-AzVMOSDisk.
38+
The **New-AzVMConfig** cmdlet creates a configurable local virtual machine object for Azure. <br>
39+
40+
The following cmdlets are used to set different properties of the virtual machine object: <br>
41+
- **[Add-AzVMNetworkInterface](https://learn.microsoft.com/en-us/powershell/module/az.compute/add-azvmnetworkinterface)** to set the network profile.<br>
42+
- **[Set-AzVMOperatingSystem](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmoperatingsystem)** to set the OS profile. <br>
43+
- **[Set-AzVMSourceImage](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmsourceimage)** to set the source image.<br>
44+
- **[Set-AzVMOSDisk](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmosdisk)** to set the OS disk (storage profile).<br>
45+
- **[Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku)** can also be used to find out available virtual machine sizes for your subscription and region.<br>
46+
<br>
47+
See [Quickstart: Create a Windows virtual machine in Azure with PowerShell](https://learn.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-powershell) for tutorial. <br>
4048

4149
## EXAMPLES
4250

@@ -392,7 +400,7 @@ Accept wildcard characters: False
392400
```
393401
394402
### -VMSize
395-
Specifies the size for the virtual machine.
403+
Specifies the size for the virtual machine. [Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku) can be used to find out available sizes for your subscription and region.
396404
397405
```yaml
398406
Type: System.String

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

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,20 @@ New-AzVmss [[-ResourceGroupName] <String>] [-VMScaleSetName] <String> [-AsJob] [
4040

4141
## DESCRIPTION
4242
The **New-AzVmss** cmdlet creates a Virtual Machine Scale Set (VMSS) in Azure.
43-
Use the simple parameter set (`SimpleParameterSet`) to quickly create a pre-set VMSS and associated resources. Use the default parameter set (`DefaultParameter`) for more advanced scenarios when you need to precisely configure each component of the VMSS and each associated resource before creation.
43+
Use the simple parameter set (`SimpleParameterSet`) to quickly create a pre-set VMSS and associated resources. <br>
44+
45+
Use the default parameter set (`DefaultParameter`) for more advanced scenarios when you need to precisely configure each component of the VMSS and each associated resource before creation.
46+
For default parameter set, first use the **[New-AzVmssConfig](https://docs.microsoft.com/en-us/powershell/module/az.compute/new-azvmss)** cmdlet to create a virtual machine scale set object. <br> <br>
47+
48+
Then use the following cmdlets to set different properties of the virtual machine scale set object: <br>
49+
- **[Add-AzVmssNetworkInterfaceConfiguration](https://learn.microsoft.com/en-us/powershell/module/az.compute/add-azvmssnetworkinterfaceconfiguration)** to set the network profile.<br>
50+
- **[Set-AzVmssOsProfile](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmssosprofile)** to set the OS profile. <br>
51+
- **[Set-AzVmssStorageProfile](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmssstorageprofile)** to set the storage profile.<br>
52+
- **[Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku)** can also be used to find out available virtual machine sizes for your subscription and region.<br><br>
53+
54+
See other cmdlets for virtual machine scale set [here](https://learn.microsoft.com/en-us/powershell/module/az.compute/#vm-scale-sets).<br>
55+
<br>
56+
See [Quickstart: Create a virtual machine scale set with Azure PowerShell](https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/quick-create-powershell) for tutorial.
4457

4558
## EXAMPLES
4659

@@ -319,7 +332,17 @@ Accept wildcard characters: False
319332
```
320333
321334
### -Credential
322-
The administrator credentials (username and password) for VMs in this Scale Set.
335+
The administrator credentials (username and password) for VMs in this Scale Set. <br><br>
336+
**Username** <br>
337+
**Restriction:** <br>
338+
Windows: Cannot contain special characters \/""[]:|<>+=;,?*@& or end in \".\" <br>
339+
Linux: Username must only contain letters, numbers, hyphens, and underscores and may not start with a hyphen or number. <br>
340+
**Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br>
341+
**Minimum-length:** 1 character <br>
342+
**Max-length:** 20 characters for Windows, 64 characters for Linux <br>
343+
**Password** <br>
344+
Must have 3 of the following: 1 lower case character, 1 upper case character, 1 number, and 1 special character. <br>
345+
The value must be between 12 and 123 characters long.
323346
324347
```yaml
325348
Type: System.Management.Automation.PSCredential
@@ -903,7 +926,7 @@ Accept wildcard characters: False
903926
```
904927

905928
### -VmSize
906-
The size of the VM instances in this scale set. A default size (Standard_DS1_v2) will be used if no Size is specified.
929+
The size of the VM instances in this scale set. [Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku) can be used to find out available sizes for your subscription and region. A default size (Standard_DS1_v2) will be used if no Size is specified.
907930

908931
```yaml
909932
Type: System.String

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

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,11 +54,17 @@ New-AzVmssConfig [[-Overprovision] <Boolean>] [[-Location] <String>] [-EdgeZone
5454

5555
## DESCRIPTION
5656
The **New-AzVmssConfig** cmdlet creates a configurable local Virtual Manager Scale Set (VMSS)
57-
object. Other cmdlets are needed to configure the VMSS object. These cmdlets are:
58-
- Set-AzVmssOsProfile
59-
- Set-AzVmssStorageProfile
60-
- Add-AzVmssNetworkInterfaceConfiguration
61-
- Add-AzVmssExtension
57+
object. <br>
58+
59+
Use the following cmdlets to configure the VMSS object:
60+
- **[Add-AzVmssNetworkInterfaceConfiguration](https://learn.microsoft.com/en-us/powershell/module/az.compute/add-azvmssnetworkinterfaceconfiguration)** to set the network profile.<br>
61+
- **[Set-AzVmssOsProfile](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmssosprofile)** to set the OS profile. <br>
62+
- **[Set-AzVmssStorageProfile](https://learn.microsoft.com/en-us/powershell/module/az.compute/set-azvmssstorageprofile)** to set the storage profile.<br>
63+
- **[Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku)** can also be used to find out available virtual machine sizes for your subscription and region.<br><br>
64+
65+
See other cmdlets for virtual machine scale set [here](https://learn.microsoft.com/en-us/powershell/module/az.compute/#vm-scale-sets).<br>
66+
<br>
67+
See [Quickstart: Create a virtual machine scale set with Azure PowerShell](https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/quick-create-powershell) for tutorial.
6268

6369
## EXAMPLES
6470

@@ -691,7 +697,7 @@ Accept wildcard characters: False
691697
```
692698
693699
### -SkuName
694-
Specifies the size of all the instances of VMSS.
700+
Specifies the size of all the instances of VMSS. [Get-AzComputeResourceSku](https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azcomputeresourcesku) can be used to find out available sizes for your subscription and region.
695701
696702
```yaml
697703
Type: System.String

src/Compute/Compute/help/Set-AzVmssOsProfile.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -225,12 +225,13 @@ Accept wildcard characters: False
225225
226226
### -AdminUsername
227227
Specifies the administrator account name to use for all the virtual machine instances in the VMSS. <br>
228-
**Windows-only restriction:** Cannot end in \".\" <br>
228+
**Restriction:** <br>
229+
Windows: Cannot contain special characters \/""[]:|<>+=;,?*@& or end in \".\" <br>
230+
Linux: Username must only contain letters, numbers, hyphens, and underscores and may not start with a hyphen or number. <br>
229231
**Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br>
230-
**Minimum-length (Linux):** 1 character <br>
231-
**Max-length (Linux):** 64 characters <br>
232-
**Max-length (Windows):** 20 characters <br>
233-
<li> For a list of built-in system users on Linux that should not be used in this field, see [Selecting User Names for Linux on Azure](https://docs.microsoft.com/azure/devops/organizations/settings/naming-restrictions).
232+
**Minimum-length:** 1 character <br>
233+
**Max-length:** 20 characters for Windows, 64 characters for Linux <br>
234+
For a list of built-in system users on Linux that should not be used in this field, see [Selecting User Names for Linux on Azure](https://docs.microsoft.com/azure/devops/organizations/settings/naming-restrictions).
234235
235236
```yaml
236237
Type: System.String

tools/StaticAnalysis/Exceptions/Az.Compute/ExampleIssues.csv

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,9 @@
55
"Compute","New-AzGalleryImageDefinition","4","11","Invalid_Cmdlet","5000","1","????? is not a valid command name.","?????","Check the spell of ?????."
66
"Compute","New-AzGalleryImageDefinition","4","11","Invalid_Cmdlet","5000","1","?????Name='SecurityType' is not a valid command name.","?????Name='SecurityType'","Check the spell of ?????Name='SecurityType'."
77
"Compute","New-AzGalleryImageDefinition","4","11","Invalid_Cmdlet","5000","1","Value='ConfidentialVMSupported' is not a valid command name.","Value='ConfidentialVMSupported'","Check the spell of Value='ConfidentialVMSupported'."
8-
"Compute","New-AzGalleryImageVersion","9","10","Invalid_Cmdlet","5000","1","EncryptedWithCmk is not a valid command name.","EncryptedWithCmk","Check the spell of EncryptedWithCmk."
8+
"Compute","New-AzGalleryImageVersion","9","10","Invalid_Cmdlet","5000","1","EncryptedWithCmk is not a valid command name.","EncryptedWithCmk","Check the spell of EncryptedWithCmk."
9+
"Compute","New-AzVM","7","3","Invalid_Cmdlet","5000","1","New-AzResourceGroup is not a valid command name.","New-AzResourceGroup -Name $rgname -Location $loc -Force","Check the spell of New-AzResourceGroup."
10+
"Compute","New-AzVmss","2","5","Invalid_Cmdlet","5000","1","New-AzResourceGroup is not a valid command name.","New-AzResourceGroup -Name $RGName -Location $LOC -Force","Check the spell of New-AzResourceGroup."
11+
"Compute","New-AzVmss","2","10","Invalid_Cmdlet","5000","1","New-AzStorageAccount is not a valid command name.","New-AzStorageAccount -ResourceGroupName $RGName -Name $STOName -Location $LOC -Type $STOType","Check the spell of New-AzStorageAccount."
12+
"Compute","New-AzVmss","2","11","Invalid_Cmdlet","5000","1","Get-AzStorageAccount is not a valid command name.","Get-AzStorageAccount -ResourceGroupName $RGName -Name $STOName","Check the spell of Get-AzStorageAccount."
13+
"Compute","New-AzVmss","4","4","Invalid_Cmdlet","5000","1","New-AzResourceGroup is not a valid command name.","New-AzResourceGroup -Name $rgname -Location $loc -Force","Check the spell of New-AzResourceGroup."

0 commit comments

Comments
 (0)