added verbose instructions

Nicolas Oman · Nicolas Oman · commit e5708849507d · 2020-05-14T10:09:07.000-07:00
diff --git a/articles/service-fabric/service-fabric-scale-up-node-type.md b/articles/service-fabric/service-fabric-scale-up-node-type.md
@@ -36,80 +36,163 @@ Here is the process for updating the VM size and operating system of the primary
 10. Remove the node state of the nodes from the cluster.  If the durability level of the old scale set was silver or gold, this step is done by the system automatically.
 11. If you deployed the stateful application in a previous step, verify that the application is functional.
 
-```powershell
-# Variables.
-$groupname = "sfupgradetestgroup"
-$clusterloc="southcentralus"  
-$subscriptionID="<your subscription ID>"
+## Set up the test cluster
+
+Begin by downloading the two sets of files we'll need for this tutorial, the before [template]() and [parameters]() and the after [template]() and [parameters]().
 
+Next, sign in to your Azure account.
+
+```powershell
 # sign in to your Azure account and select your subscription
-Login-AzAccount -SubscriptionId $subscriptionID 
+Login-AzAccount -SubscriptionId "<your subscription ID>"
+```
+
+This tutorial walks through the scenario of creating a self-signed certificate. To use an existing certificate from Azure Key Vault, skip the step below and instead mirror the steps in [using an existing certificate to deploy the cluster](https://docs.microsoft.com/azure/service-fabric/upgrade-managed-disks#use-an-existing-certificate-to-deploy-the-cluster).
+
+### Generate a self-signed certificate and deploy the cluster
+
+First, assign the variables you'll need for Service Fabric cluster deployment. Adjust the values for `resourceGroupName`,  `certSubjectName`, `parameterFilePath`, and `templateFilePath` for your specific account and environment:
+
+```powershell
+# Assign deployment variables
+$resourceGroupName = "sftestupgradegroup"
+$certOutputFolder = "c:\certificates"
+$certPassword = "Password!1" | ConvertTo-SecureString -AsPlainText -Force
+$certSubjectName = "sftestupgrade.southcentralus.cloudapp.azure.com"
+$templateFilePath = "C:\Deploy-2NodeTypes-2ScaleSets.json"
+$parameterFilePath = "C:\Deploy-2NodeTypes-2ScaleSets.parameters.json"
+```
+
+> [!NOTE]
+> Ensure that the `certOutputFolder` location exist on your local machine before running the command to deploy a new Service Fabric cluster.
+
+Next open the *Deploy-2NodeTypes-2ScaleSets.parameters.json* file and adjust the values for `clusterName` and `dnsName` to correspond to the dynamic values you set in PowerShell and save your changes.
+
+Then deploy the Service Fabric test cluster:
+
+```powershell
+# Deploy the initial test cluster
+New-AzServiceFabricCluster `
+    -ResourceGroupName $resourceGroupName `
+    -CertificateOutputFolder $certOutputFolder `
+    -CertificatePassword $certPassword `
+    -CertificateSubjectName $certSubjectName `
+    -TemplateFile $templateFilePath `
+    -ParameterFile $parameterFilePath
+```
+
+Once the deployment is complete, locate the *.pfx* file (`$certPfx`) on your local machine and import it to your certificate store:
+
+```powershell
+cd c:\certificates
+$certPfx = ".\sftestupgradegroup20200312121003.pfx"
 
-# Create a new resource group for your deployment and give it a name and a location.
-New-AzResourceGroup -Name $groupname -Location $clusterloc
+Import-PfxCertificate `
+     -FilePath $certPfx `
+     -CertStoreLocation Cert:\CurrentUser\My `
+     -Password (ConvertTo-SecureString Password!1 -AsPlainText -Force)
+```
+
+The operation will return the certificate thumbprint, which you'll use to connect to the new cluster and check its health status.
 
-# Deploy the two node type cluster.
-New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateParameterFile "C:\temp\cluster\Deploy-2NodeTypes-2ScaleSets.parameters.json" `
-    -TemplateFile "C:\temp\cluster\Deploy-2NodeTypes-2ScaleSets.json" -Verbose
+### Connect to the new cluster and check health status
 
-# Connect to the cluster and check the cluster health.
-$ClusterName= "sfupgradetest.southcentralus.cloudapp.azure.com:19000"
-$thumb="F361720F4BD5449F6F083DDE99DC51A86985B25B"
+Connect to the cluster and ensure that all of its nodes are healthy (replacing the `clusterName` and `thumb` variables for your cluster):
+
+```powershell
+# Connect to the cluster
+$clusterName = "sftestupgrade.southcentralus.cloudapp.azure.com:19000"
+$thumb = "BB796AA33BD9767E7DA27FE5182CF8FDEE714A70"
 
-Connect-ServiceFabricCluster -ConnectionEndpoint $ClusterName -KeepAliveIntervalInSec 10 `
+Connect-ServiceFabricCluster `
+    -ConnectionEndpoint $clusterName `
+    -KeepAliveIntervalInSec 10 `
     -X509Credential `
     -ServerCertThumbprint $thumb  `
     -FindType FindByThumbprint `
     -FindValue $thumb `
     -StoreLocation CurrentUser `
-    -StoreName My 
+    -StoreName My
 
+# Check cluster health
 Get-ServiceFabricClusterHealth
+```
+
+We are ready to begin the upgrade procedure.
+
+## Upgrade the primary node type VMs
+
+After deciding to upgrade the primary node type VMs, add a new scale set to the primary node type such that the primary node type now has two scale sets. A sample [template](https://github.com/Azure/service-fabric-scripts-and-templates/blob/master/templates/nodetype-upgrade/Deploy-2NodeTypes-3ScaleSets.json) and [parameters](https://github.com/Azure/service-fabric-scripts-and-templates/blob/master/templates/nodetype-upgrade/Deploy-2NodeTypes-3ScaleSets.parameters.json) files have been provided to show the necessary changes. The new scale set's VMs are size Standard D4_V2 and run Windows Server 2016 Datacenter with Containers. A new load balancer and public IP address are also added with the new scale set. 
 
-# Deploy a new scale set into the primary node type.  Create a new load balancer and public IP address for the new scale set.
-New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateParameterFile "C:\temp\cluster\Deploy-2NodeTypes-3ScaleSets.parameters.json" `
-    -TemplateFile "C:\temp\cluster\Deploy-2NodeTypes-3ScaleSets.json" -Verbose
+To find the new scale set in the template, search for the "Microsoft.Compute/virtualMachineScaleSets" resource named by the vmNodeType2Name parameter. The new scale set is added to the primary node type using the properties->virtualMachineProfile->extensionProfile->extensions->properties->settings->nodeTypeRef setting.
 
-# Check the cluster health again. All 15 nodes should be healthy.
+### Deploy the updated template
+
+Adjust the `parameterFilePath` and `templateFilePath` as needed and then run the following command:
+
+```powershell
+# Deploy the new scale set (upgraded to use managed disks) into the primary node type.
+$templateFilePath = "C:\Upgrade-1NodeType-2ScaleSets-ManagedDisks.json"
+$parameterFilePath = "C:\Upgrade-1NodeType-2ScaleSets-ManagedDisks.parameters.json"
+
+New-AzResourceGroupDeployment `
+    -ResourceGroupName $resourceGroupName `
+    -TemplateFile $templateFilePath `
+    -TemplateParameterFile $parameterFilePath `
+    -CertificateThumbprint $thumb `
+    -CertificateUrlValue $certUrlValue `
+    -SourceVaultValue $sourceVaultValue `
+    -Verbose
+```
+
+When the deployment completes, check the cluster health again and ensure all nodes (on the original and on the new scale set) are healthy.
+
+```powershell
 Get-ServiceFabricClusterHealth
+```
 
+## Migrate nodes to the new scale set
+
+We're now ready to start disabling the nodes of the original scale set. As these nodes become disabled, the system services and seed nodes migrate to the VMs of the new scale set because it is also marked as the primary node type.
+
+```powershell
 # Disable the nodes in the original scale set.
 $nodeNames = @("_NTvm1_0","_NTvm1_1","_NTvm1_2","_NTvm1_3","_NTvm1_4")
 
 Write-Host "Disabling nodes..."
 foreach($name in $nodeNames){
     Disable-ServiceFabricNode -NodeName $name -Intent RemoveNode -Force
 }
+```
 
-Write-Host "Checking node status..."
-foreach($name in $nodeNames){
- 
-    $state = Get-ServiceFabricNode -NodeName $name 
-
-    $loopTimeout = 50
-
-    do{
-        Start-Sleep 5
-        $loopTimeout -= 1
-        $state = Get-ServiceFabricNode -NodeName $name
-        Write-Host "$name state: " $state.NodeDeactivationInfo.Status
-    }
-
-    while (($state.NodeDeactivationInfo.Status -ne "Completed") -and ($loopTimeout -ne 0))
-    
-
-    if ($state.NodeStatus -ne [System.Fabric.Query.NodeStatus]::Disabled)
-    {
-        Write-Error "$name node deactivation failed with state" $state.NodeStatus
-        exit
-    }
-}
+Use Service Fabric Explorer to monitor the migration of seed nodes to the new scale set and the progression of nodes in the original scale set from *Disabling* to *Disabled* status.
+
+> [!NOTE]
+> It may take some time to complete the disabling operation across all the nodes of the original scale set. To guarantee data consistency, only one seed node can change at a time. Each seed node change requires a cluster update; thus replacing a seed node requires two cluster upgrades (one each for node addition and removal). Upgrading the five seed nodes in this sample scenario will result in ten cluster upgrades.
+
+## Remove the original scale set
+
+Once the disabling operation is complete, remove the scale set.
+
+```powershell
+# Remove the original scale set
+$scaleSetName = "NTvm1"
+
+Remove-AzVmss `
+    -ResourceGroupName $resourceGroupName `
+    -VMScaleSetName $scaleSetName `
+    -Force
 
-# Remove the scale set
-$scaleSetName="NTvm1"
-Remove-AzVmss -ResourceGroupName $groupname -VMScaleSetName $scaleSetName -Force
 Write-Host "Removed scale set $scaleSetName"
+```
+
+In Service Fabric Explorer, the removed nodes (and thus the *Cluster Health State*) will now appear in *Error* state.
+
+## Remove the old load balancer and update DNS settings
+
+Now, we can remove the resources related to the old primary node type, beginning with the load balancer and the old public IP. 
 
+```powershell
 $lbname="LB-sfupgradetest-NTvm1"
 $oldPublicIpName="PublicIP-LB-FE-0"
 $newPublicIpName="PublicIP-LB-FE-2"
@@ -126,16 +209,28 @@ Remove-AzLoadBalancer -Name $lbname -ResourceGroupName $groupname -Force
 
 # Remove the old public IP
 Remove-AzPublicIpAddress -Name $oldPublicIpName -ResourceGroupName $groupname -Force
+```
 
+Next, we update the DNS settings of the new public IP to mirror the settings from the old primary node type's public IP.
+
+```powershell
 # Replace DNS settings of Public IP address related to new Primary Node Type with DNS settings of Public IP address related to old Primary Node Type
 $PublicIP = Get-AzPublicIpAddress -Name $newPublicIpName  -ResourceGroupName $groupname
 $PublicIP.DnsSettings.DomainNameLabel = $primaryDNSName
 $PublicIP.DnsSettings.Fqdn = $primaryDNSFqdn
 Set-AzPublicIpAddress -PublicIpAddress $PublicIP
+```
+
+Once more, check the cluster health
 
+```powershell
 # Check the cluster health
 Get-ServiceFabricClusterHealth
+```
 
+Finally, remove the node state for each of the related nodes. If durability level of the old scale set was silver or gold, this will occur automatically.
+
+```powershell
 # Remove node state for the deleted nodes.
 foreach($name in $nodeNames){
     # Remove the node from the cluster
@@ -144,6 +239,8 @@ foreach($name in $nodeNames){
 }
 ```
 
+The cluster's primary node type has now been upgraded. Verify that any deployed applications function properly and cluster health is ok.
+
 ## Next steps
 * Learn how to [add a node type to a cluster](virtual-machine-scale-set-scale-node-type-scale-out.md)
 * Learn about [application scalability](service-fabric-concepts-scalability.md).
