Cloud Service (extended support) management via PowerShell

[Yi_Yang]

In the Cloud Service (extended support) world, users usually need to manage Cloud Service (extended support) via PowerShell, since some management operations are not available in the Azure portal so far. This blog provides some common samples to manage Cloud Service (extended support) resources by PowerShell. 

Following perspectives will be introduced in this blog: 

• Environment preparation 
• CSES creation via PowerShell   
• CSES updating via PowerShell   
• CSES extensions updating via PowerShell 

• Prepare environment 

• If engineers or customers encounter the error related to Az module, it may be because the module is not successfully installed or there are some issues with this version of module. We can install/uninstall the Az module. 

  • Install-Module -Name Az 
    

  • Uninstall-Module -Name Az -AllVersions 

Reference doc:  

Install the Azure Az PowerShell module | Microsoft Docs 

Uninstall Azure PowerShell | Microsoft Docs 

• Create a new Cloud Service (extended support)
  • Create CSES with local files.
    

    $cspkgFilePath ="cspkg file path" 
    $cscfgFilePath = "cscfg file path" 
    $csdefFilePath = "csdef file path" 
    $storageAccount= "storage account name"      
     
    # Create Cloud Service    
    New-AzCloudService -Name "CSES name" -ResourceGroupName "resource group name" -Location "CSES Location" -ConfigurationFile $cscfgFilePath -DefinitionFile $csdefFilePath -PackageFile $cspkgFilePath -StorageAccount $storageAccount  

  • Create CSES with the cspkg file from the storage account.
    

    $cspkgUrl = "cspkg SAS URL" 
    $cscfgFilePath = "cscfg file path" 
    $csdefFilePath = "csdef file path" 
    
    New-AzCloudService -Name "CSES name" -ResourceGroupName "resource group name" -Location "CSES Location" -ConfigurationFile $cscfgFilePath -DefinitionFile $csdefFilePath -PackageUrl $cspkgUrl 

Note: 

In the Azure portal, you can generate SAS URL from the storage account container. 

Important: 

• Make sure the cscfg file matches the csdef in the cspkg file. Even when you meet the following message, it still maybe because you use the unmatched files. 
  

  Az.CloudService\New-AzCloudService : The CSCFG could not be parsed. Please use the documentation at https://aka.ms/cses-cscfg-schema for CSCFG schema details.  
  
  More details: Top-level XML element does not conform to schema 

• Except the above two samples, you can use the New-AzCloudService command with different groups of parameters. And you need to make sure that the pair of parameters is correct. For example, when you use the local file to create the CSES, the -StorageAccount is necessary. You can check the parameters pairs in the second reference documentation.   

Reference doc:  

Deploy a Cloud Service (extended support) - PowerShell | Microsoft Docs 

New-AzCloudService (Az.CloudService) | Microsoft Docs 

• Update existing Cloud Service (extended support)
  The update here includes the csdef, csfg or the application code change. 
  

  $cloudServiceName="CSES name" 
  $resourceGroupName="CSES resource group" 
  $cspkgUrl = "cspkg SAS URL" 
  $cscfgContent='configuration file content' 
  $cloudService = Get-AzCloudService -Name $cloudServiceName -ResourceGroupName $resourceGroupName  
  $cloudService.PackageUrl = $cspkgUrl 
  $cloudService.Configuration = $cscfgContent 
  
  $cloudService | Update-AzCloudService   

Important:

• Make sure you use the cscfg file which matches the cscdef in the cspfk file. 

Note:

• Sample of the value of $cscfgContent 

  $cscfgContent='<ServiceConfiguration serviceName="cses" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="6" osVersion="*" schemaVersion="2015-04.2.6"> 
    <Role name="WebRole1"> 
      <Instances count="1" /> 
      <ConfigurationSettings> 
        <Setting name="APPINSIGHTS_INSTRUMENTATIONKEY" value="Application Insights Instrumentation Key" /> 
      </ConfigurationSettings> 
    </Role> 
    <NetworkConfiguration> 
      <VirtualNetworkSite name="VNet name" /> 
      <AddressAssignments> 
        <InstanceAddress roleName="WebRole1"> 
          <Subnets> 
            <Subnet name="DefaultVNetSubnet" /> 
          </Subnets> 
        </InstanceAddress> 
      </AddressAssignments> 
    </NetworkConfiguration> 
  </ServiceConfiguration>' 

• Sample script for updating CSES in pipeline
  In some scenarios, you may not be able to change the command frequently, such as you put this command file in a pipeline deployment and you do not want to type $cscfgContent each time. Then the following script provides an example of how to update the values of the parameters and do not need to change most commands.
  

  $storageaccountname = "storage account name"
  $storageaccountrgname = "storage account resource group name"
  $storagecontainer = "storage container name"
  $localcspkgpath = "local cspkg path"
  $localcscfgpath = "local cscfg path"
  $cloudServiceName="cloud Service Name"
  $resourceGroupName="cloud service resource group name"
  
  Connect-AzAccount
  
  $storageaccount = Get-AzStorageAccount -Name $storageaccountname -ResourceGroupName $storageaccountrgname
  $context = $storageaccount.Context
  Set-AzStorageBlobContent -Container $storagecontainer -File $localcspkgpath -Blob $localcspkgpath.Split("\")[-1] -Context $context -Force
  $cspkgUrl = New-AzStorageBlobSASToken -Context $context -Container $storagecontainer -Blob $localcspkgpath.Split("\")[-1] -Permission racwd -FullUri
  $cscfgContent = Get-Content $localcscfgpath | Out-String
  
  $cloudService = Get-AzCloudService -Name $cloudServiceName -ResourceGroupName $resourceGroupName  
  $cloudService.PackageUrl = $cspkgUrl
  $cloudService.Configuration = $cscfgContent
  
  $cloudService | Update-AzCloudService   

Reference doc: 

Update-AzCloudService (Az.CloudService) | Microsoft Docs 

• Enable extension on the Cloud Service (extended support) 
  • Enable the Remote Desktop extension.

    # Create new RDP extension object   
    $credential = Get-Credential   
    $expiration='10/30/2021'   
    $rdpExtension = New-AzCloudServiceRemoteDesktopExtensionObject -Name "RDPextension" -Credential $credential -Expiration $expiration -TypeHandlerVersion "1.2.1"  
    $cloudService = Get-AzCloudService -ResourceGroup "Resource Group Name" -CloudServiceName "CSES Name" 
    # Add RDP extension to existing cloud service extension object   
    $cloudService.ExtensionProfile.Extension = $cloudService.ExtensionProfile.Extension + $rdpExtension   
    
    # Update cloud service   
    $cloudService | Update-AzCloudService  

  • Enable the Application Insights extension.
    

    $storageAccountKey = Get-AzStorageAccountKey -ResourceGroupName "resource group name" -Name "storage account name"
    $configFile = "Path of config.xml" 
    $extension = New-AzCloudServiceDiagnosticsExtension -Name "Microsoft.Insights.VMDiagnosticsSettings_RoleName" -ResourceGroupName "CSES resource group name" -CloudServiceName "CSES name" -StorageAccountName "storage account name" -StorageAccountKey $storageAccountKey[0].Value -DiagnosticsConfigurationPath $configFile -TypeHandlerVersion "1.21.0.1" -AutoUpgradeMinorVersion $true 
    $cloudService = Get-AzCloudService -ResourceGroup "CSES resource group name" -CloudServiceName "CSES name" 
    $cloudService.ExtensionProfile.Extension = $cloudService.ExtensionProfile.Extension + $extension
     
    $cloudService | Update-AzCloudService
    ​

    Following is a config.xml content sample.

    <PublicConfig xmlns="http://schemas.microsoft.com/ServiceHosting/2010/10/DiagnosticsConfiguration">
        <WadCfg>
            <DiagnosticMonitorConfiguration overallQuotaInMB="4096" sinks="applicationInsights.errors">
                <Directories scheduledTransferPeriod="PT1M">
                    <IISLogs containerName="wad-iis-logfiles" />
                    <FailedRequestLogs containerName="wad-failedrequestlogs" />
                </Directories>
                <WindowsEventLog scheduledTransferPeriod="PT1M">
                    <DataSource name="Application!*[System[(Level=1 or Level=2 or Level=3)]]" />
                    <DataSource name="Windows Azure!*[System[(Level=1 or Level=2 or Level=3 or Level=4)]]" />
                </WindowsEventLog>
                <CrashDumps>
                    <CrashDumpConfiguration processName="WaIISHost.exe" />
                    <CrashDumpConfiguration processName="WaWorkerHost.exe" />
                    <CrashDumpConfiguration processName="w3wp.exe" />
                </CrashDumps>
                <Metrics resourceId="CSES resource ID" />
            </DiagnosticMonitorConfiguration>
            <SinksConfig>
                <Sink name="applicationInsights">
                    <ApplicationInsights>Application Insight Instrumentation Key</ApplicationInsights>
                    <Channels>
                        <Channel logLevel="Error" name="errors" />
                    </Channels>
                </Sink>
             </SinksConfig>
        </WadCfg>
        <StorageAccount>Storage Account Name</StorageAccount>
        <StorageType>TableAndBlob</StorageType>
    </PublicConfig>

  • Remove all extensions
    

    # Get existing cloud service
    $cloudService = Get-AzCloudService -ResourceGroupName "resource group name" -CloudServiceName "CSES Name"
    # Set extension to empty list
    $cloudService.ExtensionProfile.Extension = @()
    # Update cloud service
    $cloudService | Update-AzCloudService​

Reference doc: 

Apply the Windows Azure diagnostics extension in Cloud Services (extended support) | Microsoft Docs 
Update-AzCloudService (Az.CloudService) | Microsoft Learn