Adding help doc and changelog for New-AzVmss DisableIntegrityMonitoring new parameter (#18829)

* Update VirtualMachineTests.ps1

* Update ChangeLog.md

* Update New-AzVM.md

* Update New-AzVmss.md

* Update New-AzVM.md

* Update New-AzVmss.md

Co-authored-by: Yabo Hu <[email protected]>

Author: Sandido

src/Compute/Compute.Test/ScenarioTests/VirtualMachineTests.ps1

@@ -5798,7 +5798,13 @@ function Test-VirtualMachinePlatformFaultDomain
 
 <#
 .SYNOPSIS
-Test GuestAttestation
+Test GuestAttestation defaulting behavior.
+1) SecurityType is TrustedLaunch.
+2) EnableVtpm is true.
+3) EnabledSecureBoot is true.
+4) DisableIntegrityMonitoring is not true.
+Then this test removes the VM and recreates it with -DisableIntegrityMonitoring set to true so the
+Guest Attestation extension is not installed.
 #>
 function Test-VirtualMachineGuestAttestation
 {
@@ -5872,4 +5878,4 @@ function Test-VirtualMachineGuestAttestation
         # Cleanup
         Clean-ResourceGroup $rgname;
     }
-}
+}

src/Compute/Compute/ChangeLog.md

@@ -22,12 +22,13 @@
 ## Upcoming Release
 * Added image alias 'Win2022AzureEditionCore'
 * Added the `-DisableIntegrityMonitoring` switch parameter to the `New-AzVM` cmdlet. 
-  Changed the default behavior for `New-AzVM` when these conditions are met:
+  Changed the default behavior for `New-AzVM` and `New-AzVmss` when these conditions are met:
   1) `-DisableIntegrityMonitoring` is not true.
   2) `SecurityType` on the SecurityProfile is `TrustedLaunch`.
   3) `VTpmEnabled` on the SecurityProfile is true.
   4) `SecureBootEnabled` on the SecurityProfile is true. 
   Now `New-AzVM` will install the `Guest Attestation` extension to the new VM when these conditions are met.
+  Now `New-AzVmss` will install the `Guest Attestation` extension to the new Vmss when these conditions are met and installed to all VM instances in the Vmss.
 * Added `-UserAssignedIdentity` and `-FederatedClientId` to the following cmdlets:
     - `New-AzDiskEncryptionSetConfig`
     - `Update-AzDiskEncryptionSet`

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

@@ -241,6 +241,70 @@ $vmss = New-AzVmss -ResourceGroupName $resourceGroupName -Name $vmssName -Virtua
 $vm = New-AzVM -ResourceGroupName $resourceGroupName -Name $vmname -Credential $cred -DomainNameLabel $domainNameLabel -PlatformFaultDomain $platformFaultDomainVMDefaultSet -VmssId $vmss.Id
 ```
 
+### Example 7: Creating a new VM with the GuestAttestation extension installed by default, then recreating the VM with DisableIntegrityMonitoring to prevent this.
+```
+$rgname = <RESOURCE GROUP NAME>;
+$loc = <AZURE REGION>;
+New-AzResourceGroup -Name $rgname -Location $loc -Force;
+
+# VM Profile & Hardware
+$vmname = 'vm' + $rgname;
+$domainNameLabel = "d1" + $rgname;
+$vnetname = "myVnet";
+$vnetAddress = "10.0.0.0/16";
+$subnetname = "slb" + $rgname;
+$subnetAddress = "10.0.2.0/24";
+$OSDiskName = $vmname + "-osdisk";
+$NICName = $vmname+ "-nic";
+$NSGName = $vmname + "-NSG";
+$OSDiskSizeinGB = 128;
+$VMSize = "Standard_DS2_v2";
+$PublisherName = "MicrosoftWindowsServer";
+$Offer = "WindowsServer";
+$SKU = "2019-DATACENTER-GENSECOND";
+$securityType = "TrustedLaunch";
+$secureboot = $true;
+$vtpm = $true;
+
+# Default extension and identity values.
+$extDefaultName = "GuestAttestation";
+$vmGADefaultIDentity = "SystemAssigned";
+
+# Credential
+$password = <PASSWORD>;
+$securePassword = $password | ConvertTo-SecureString -AsPlainText -Force;  
+$user = <USER NAME>;
+$cred = New-Object System.Management.Automation.PSCredential ($user, $securePassword);
+
+# Network resources
+$frontendSubnet = New-AzVirtualNetworkSubnetConfig -Name $subnetname -AddressPrefix $subnetAddress;
+$vnet = New-AzVirtualNetwork -Name $vnetname -ResourceGroupName $rgname -Location $loc -AddressPrefix $vnetAddress -Subnet $frontendSubnet;
+$nsgRuleRDP = New-AzNetworkSecurityRuleConfig -Name RDP  -Protocol Tcp  -Direction Inbound -Priority 1001 -SourceAddressPrefix * -SourcePortRange * -DestinationAddressPrefix * -DestinationPortRange 3389 -Access Allow;
+$nsg = New-AzNetworkSecurityGroup -ResourceGroupName $RGName -Location $loc -Name $NSGName  -SecurityRules $nsgRuleRDP;
+$nic = New-AzNetworkInterface -Name $NICName -ResourceGroupName $RGName -Location $loc -SubnetId $vnet.Subnets[0].Id -NetworkSecurityGroupId $nsg.Id -EnableAcceleratedNetworking;
+
+# VM creation
+$vmConfig = New-AzVMConfig -VMName $vmName -VMSize $VMSize;
+Set-AzVMOperatingSystem -VM $vmConfig -Windows -ComputerName $vmName -Credential $cred;
+Set-AzVMSourceImage -VM $vmConfig -PublisherName $PublisherName -Offer $Offer -Skus $SKU -Version latest;
+Add-AzVMNetworkInterface -VM $vmConfig -Id $nic.Id;
+$vmConfig = Set-AzVMSecurityProfile -VM $vmConfig -SecurityType $securityType;
+$vmConfig = Set-AzVmUefi -VM $vmConfig -EnableVtpm $vtpm -EnableSecureBoot $secureboot;
+New-AzVM -ResourceGroupName $RGName -Location $loc -VM $vmConfig;
+
+# Verify values
+$vm = Get-AzVm -ResourceGroupName $rgname -Name $vmName;
+$vmExt = Get-AzVMExtension -ResourceGroupName $rgname -VMName $vmName -Name $extDefaultName;
+# Check the default extension has been installed, and the Identity.Type defaulted to SystemAssigned.
+# $vmExt.Name
+# $vm.Identity.Type
+
+# Use the DisableIntegrityMonitoring parameter
+Remove-AzVm -ResourceGroupName $rgname -Name $vmname -Force;
+New-AzVM -ResourceGroupName $rgname -Location $loc -VM $vmConfig -DisableIntegrityMonitoring;
+# This VM does not have the Guest Attestation extension installed on it, and the Identity is not set to SystemAssigned by default.
+```
+
 ## PARAMETERS
 
 ### -AddressPrefix

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

@@ -16,7 +16,7 @@ Creates a VMSS.
 ### DefaultParameter (Default)
 ```
 New-AzVmss [-ResourceGroupName] <String> [-VMScaleSetName] <String>
- [-VirtualMachineScaleSet] <PSVirtualMachineScaleSet> [-AsJob] [-EdgeZone <String>]
+ [-VirtualMachineScaleSet] <PSVirtualMachineScaleSet> [-DisableIntegrityMonitoring] [-AsJob] [-EdgeZone <String>]
  [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
@@ -147,25 +147,6 @@ $VMSS = New-AzVmssConfig -Location $LOC -SkuCapacity 2 -SkuName "Standard_E4-2ds
 New-AzVmss -ResourceGroupName $RGName -Name $VMSSName -VirtualMachineScaleSet $VMSS;
 ```
 
-### Example 3: Create a VMSS with a UserData value
-```powershell
-$ResourceGroupName = 'RESOURCE GROUP NAME';
-$vmssName = 'VMSSNAME';
-$domainNameLabel = "dnl" + $ResourceGroupName;
-# Create credentials, I am using one way to create credentials, there are others as well. 
-# Pick one that makes the most sense according to your use case.
-$vmPassword = ConvertTo-SecureString 'PASSWORD' -AsPlainText -Force;
-$vmCred = New-Object System.Management.Automation.PSCredential('USERNAME', $vmPassword);
-
-$text = "UserData value to encode";
-$bytes = [System.Text.Encoding]::Unicode.GetBytes($text);
-$userData = [Convert]::ToBase64String($bytes);
-
-#Create a VMSS
-New-AzVmss -ResourceGroupName $ResourceGroupName -Name $vmssName -Credential $vmCred -DomainNameLabel $domainNameLabel -Userdata $userData;
-$vmss = Get-AzVmss -ResourceGroupName $ResourceGroupName -VMScaleSetName $vmssName -InstanceView:$false -Userdata;
-```
-
 The complex example above creates a VMSS, following is an explanation of what is happening:
 * The first command creates a resource group with the specified name and location.
 * The second command uses the **New-AzStorageAccount** cmdlet to create a storage account.
@@ -186,6 +167,74 @@ The complex example above creates a VMSS, following is an explanation of what is
 * The eighteenth command uses the **New-AzVmssConfig** cmdlet to create a VMSS configuration object and stores the result in the variable named $VMSS.
 * The nineteenth command uses the **New-AzVmss** cmdlet to create the VMSS.
 
+### Example 3: Create a VMSS with a UserData value
+```powershell
+$ResourceGroupName = 'RESOURCE GROUP NAME';
+$vmssName = 'VMSSNAME';
+$domainNameLabel = "dnl" + $ResourceGroupName;
+# Create credentials, I am using one way to create credentials, there are others as well. 
+# Pick one that makes the most sense according to your use case.
+$vmPassword = ConvertTo-SecureString 'PASSWORD' -AsPlainText -Force;
+$vmCred = New-Object System.Management.Automation.PSCredential('USERNAME', $vmPassword);
+
+$text = "UserData value to encode";
+$bytes = [System.Text.Encoding]::Unicode.GetBytes($text);
+$userData = [Convert]::ToBase64String($bytes);
+
+#Create a VMSS
+New-AzVmss -ResourceGroupName $ResourceGroupName -Name $vmssName -Credential $vmCred -DomainNameLabel $domainNameLabel -Userdata $userData;
+$vmss = Get-AzVmss -ResourceGroupName $ResourceGroupName -VMScaleSetName $vmssName -InstanceView:$false -Userdata;
+```
+
+### Example 4: Create a VMSS with the Guest Attestation extension installed with the TrustedLaunch security type.
+```powershell
+# Common setup
+$rgname = <RESOURCE GROUP NAME>;
+$loc = <AZURE REGION>;
+New-AzResourceGroup -Name $rgname -Location $loc -Force;
+$vmssSize = 'Standard_DS3_v2';
+$PublisherName = "MicrosoftWindowsServer";
+$Offer = "WindowsServer";
+$SKU = "2019-DATACENTER-GENSECOND";
+$securityType = "TrustedLaunch";
+$secureboot = $true;
+$vtpm = $true;
+
+# NRP
+$subnet = New-AzVirtualNetworkSubnetConfig -Name ('subnet' + $rgname) -AddressPrefix "10.0.0.0/24";
+$vnet = New-AzVirtualNetwork -Force -Name ('vnet' + $rgname) -ResourceGroupName $rgname -Location $loc -AddressPrefix "10.0.0.0/16" -Subnet $subnet;
+$vnet = Get-AzVirtualNetwork -Name ('vnet' + $rgname) -ResourceGroupName $rgname;
+$subnetId = $vnet.Subnets[0].Id;
+
+# New VMSS Parameters
+$vmssName = 'vmss' + $rgname;
+$vmssType = 'Microsoft.Compute/virtualMachineScaleSets';
+$adminUsername = <USER NAME>;
+$adminPassword = <PASSWORD> | ConvertTo-SecureString -AsPlainText -Force;
+$imgRef = New-Object -TypeName 'Microsoft.Azure.Commands.Compute.Models.PSVirtualMachineImage';
+$imgRef.PublisherName = $PublisherName;
+$imgRef.Offer = $Offer;
+$imgRef.Skus = $SKU;
+$imgRef.Version = "latest";
+$ipCfg = New-AzVmssIPConfig -Name 'test' -SubnetId $subnetId;
+
+$vmss = New-AzVmssConfig -Location $loc -SkuCapacity 2 -SkuName $vmssSize -UpgradePolicyMode 'Manual' `
+| Add-AzVmssNetworkInterfaceConfiguration -Name 'test' -Primary $true -IPConfiguration $ipCfg `
+| Set-AzVmssOSProfile -ComputerNamePrefix 'test' -AdminUsername $adminUsername -AdminPassword $adminPassword `
+| Set-AzVmssStorageProfile -OsDiskCreateOption 'FromImage' -OsDiskCaching 'ReadOnly' `
+    -ImageReferenceOffer $imgRef.Offer -ImageReferenceSku $imgRef.Skus -ImageReferenceVersion $imgRef.Version `
+    -ImageReferencePublisher $imgRef.PublisherName ;
+    
+# Requirements for the Guest Attestation defaulting behavior.  
+# SecurityType is TrustedLaunch, EnableVtpm is true, EnableSecureBoot is true, DisableIntegrityMonitoring is not true.
+$vmss = Set-AzVmssSecurityProfile -VirtualMachineScaleSet $vmss -SecurityType $securityType;
+$vmss = Set-AzVmssUefi -VirtualMachineScaleSet $VMSS -EnableVtpm $vtpm -EnableSecureBoot $secureboot;
+
+# Create Vmss
+$result = New-AzVmss -ResourceGroupName $rgname -Name $vmssName -VirtualMachineScaleSet $vmss;
+# This Vmss and its Vm instances has the GuestAttestation extension installed, and the Identity of SystemAssigned.
+```
+
 ## PARAMETERS
 
 ### -AllocationMethod
@@ -877,6 +926,20 @@ Default value: None
 Accept pipeline input: True (ByPropertyName)
 Accept wildcard characters: False
 ```
+ 
+### -DisableIntegrityMonitoring
+This flag disables the default behavior to install the Guest Attestation extension to the virtual machine scale set and its vm instances if: 1) SecurityType is TrustedLaunch, 2) SecureBootEnabled on the SecurityProfile is true, 3) VTpmEnabled on the SecurityProfile is true.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: DefaultParameter
+Aliases:
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 
 ### -Confirm
 Prompts you for confirmation before running the cmdlet.