Merge remote-tracking branch 'origin/main' into vidai/release-2024-11-19

Author: vidai-msft

.azure-pipelines/code-gen.yml

@@ -21,8 +21,7 @@ jobs:
   pool: pool-windows-2019
   steps:
   - checkout: self
-    persistCredentials: true
-  - template: util/get-github-token-steps.yml
+  - template: util/get-github-pat-steps.yml
   - task: NodeTool@0
     displayName: Use Node 14.15.5
     inputs:

.azure-pipelines/util/get-github-token-steps.yml

@@ -15,3 +15,5 @@
 
 
 
+
+

NuGet.Config

@@ -0,0 +1,36 @@
+## Example Analysis
+
+### What is the purpose of example analysis?
+As we know, our cmdlet help markdown is handwritten, which is an error-prone process. Example analysis is one of steps of static analysis, which checks the syntax correctness and completeness of cmdlet help markdown, especially for code blocks in example sections. 
+
+### What will be checked by example analyzer?
+Example analyzer will check 
+- if there are any missing section heading, like '## EXAMPLES', '## PARAMETERS' and so on.
+- if code block type is defined clearly like ```powershell
+- if code block is separated into two parts: ```powershell and ```output
+- if customized rules are violated. Customized rules include
+   - Invalid_Cmdlet
+   - Is_Alias
+   - Capitalization_Conventions_Violated
+   - Unknown_Parameter_Set
+   - Invalid_Parameter_Name
+   - Duplicate_Parameter_Name
+   - Unassigned_Parameter
+   - Unassigned_Variable
+   - Unbinded_Expression
+   - Mismatched_Parameter_Value_Type
+
+### What will be ignore by example analyzer?
+ - If the example begins with `<!-- Aladdin Generated Example -->` or matches with regex `<!-- Skip.*-->`, its scan will be skipped.
+
+### How to run example analyzer locally to debug issues reported in CIs
+Run following script in PowerShell console, which requires PSScriptAnalyzer installed on local
+```powershell
+tools/StaticAnalysis/ExampleAnalyzer/Measure-MarkdownOrScript.ps1 -MarkdownPaths {your-help-folder} -RulePaths tools/StaticAnalysis/ExampleAnalyzer/AnalyzeRules/*.psm1
+```
+
+### TroubleShooting
+ - If a cmdlet is recognized as Invalid_Cmdlet, most likely its module is not imported correctly. Check its import process and configuration. If it's correct, it may be caused by parallel importing all psd1 files. Currently, the workaround is suppressing false positive. Maybe only importing changed modules are one of potential solutions. 
+
+### Miscellaneous
+ - Storage module has not been separated into ```powershell and ```output as their examples contain many outputs. They skips scan by regex `<!-- Skip.*-->` at the beginning of code block.

documentation/tooling/example-analyzer.md

@@ -24,5 +24,5 @@
 [assembly: ComVisible(false)]
 [assembly: CLSCompliant(false)]
 [assembly: Guid("57c436a1-0e82-42cb-a1a6-f727667af406")]
-[assembly: AssemblyVersion("0.12.0")]
-[assembly: AssemblyFileVersion("0.12.0")]
+[assembly: AssemblyVersion("0.13.0")]
+[assembly: AssemblyFileVersion("0.13.0")]

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/Properties/AssemblyInfo.cs

@@ -411,7 +411,7 @@ function New-AzConnectedKubernetes {
             catch {
                 # This is attempting to delete Azure Arc resources that are orphaned.
                 # We are catching and ignoring any messages here.
-                $null = helm delete azure-arc --ignore-not-found --namespace $ReleaseNamespace --kubeconfig $KubeConfig --kube-context $KubeContext
+                $null = helm delete azure-arc --ignore-not-found --namespace $ReleaseNamespace --kubeconfig $KubeConfig --kube-context $KubeContext | Out-Null
             }
         }
 
@@ -622,11 +622,11 @@ function New-AzConnectedKubernetes {
 
         $PSBoundParameters.Add('ArcAgentryConfiguration', $arcAgentryConfigs)
 
-        Write-Output "Creating 'Kubernetes - Azure Arc' object in Azure"
+        Write-Verbose "Creating 'Kubernetes - Azure Arc' object in Azure"
         Write-Debug "PSBoundParameters: $PSBoundParameters"
-        $Response = Az.ConnectedKubernetes.internal\New-AzConnectedKubernetes @PSBoundParameters
+        $CCResponse = Az.ConnectedKubernetes.internal\New-AzConnectedKubernetes @PSBoundParameters
 
-        if ((-not $WhatIfPreference) -and (-not $Response)) {
+        if ((-not $WhatIfPreference) -and (-not $CCResponse)) {
             Write-Error "Failed to create the 'Kubernetes - Azure Arc' resource."
             return
         }
@@ -639,8 +639,8 @@ function New-AzConnectedKubernetes {
             -Debug:($PSCmdlet.MyInvocation.BoundParameters["Debug"].IsPresent -eq $true)
 
         # Convert the $Response object into a nested hashtable.
-        Write-Debug "PUT response: $Response"
-        $Response = ConvertFrom-Json "$Response"
+        Write-Debug "PUT response: $CCResponse"
+        $Response = ConvertFrom-Json "$CCResponse"
         $Response = ConvertTo-Hashtable $Response
 
         # What-If processing does not create a full response so we might have
@@ -716,7 +716,7 @@ function New-AzConnectedKubernetes {
             $options += " --debug"
         }
         if ($PSCmdlet.ShouldProcess($ClusterName, "Update Kubernetes cluster with Azure Arc")) {
-            Write-Output "Executing helm upgrade command, this can take a few minutes...."
+            Write-Verbose "Executing helm upgrade command, this can take a few minutes...."
             try {
                 helm upgrade `
                     --install azure-arc `
@@ -733,7 +733,7 @@ function New-AzConnectedKubernetes {
                     --set global.azureEnvironment=AZUREPUBLICCLOUD `
                     --set systemDefaultValues.clusterconnect-agent.enabled=true `
                     --set global.kubernetesDistro=$Distribution `
-                    --set global.kubernetesInfra=$Infrastructure (-split $options)
+                    --set global.kubernetesInfra=$Infrastructure (-split $options) | Out-Null
             }
             catch {
                 throw "Unable to install helm chart at $ChartPath"
@@ -744,7 +744,7 @@ function New-AzConnectedKubernetes {
             if ($PSBoundParameters.ContainsKey('OidcIssuerProfileEnabled') -or $PSBoundParameters.ContainsKey('WorkloadIdentityEnabled') ) {
                 $ExistConnectedKubernetes = Get-AzConnectedKubernetes -ResourceGroupName $ResourceGroupName -ClusterName $ClusterName @CommonPSBoundParameters
 
-                Write-Output "Cluster configuration is in progress..."
+                Write-Verbose "Cluster configuration is in progress..."
                 $timeout = [datetime]::Now.AddMinutes(60)
 
                 while (($ExistConnectedKubernetes.ArcAgentProfileAgentState -ne "Succeeded") -and ($ExistConnectedKubernetes.ArcAgentProfileAgentState -ne "Failed") -and ([datetime]::Now -lt $timeout)) {
@@ -753,7 +753,7 @@ function New-AzConnectedKubernetes {
                 }
 
                 if ($ExistConnectedKubernetes.ArcAgentProfileAgentState -eq "Succeeded") {
-                    Write-Output "Cluster configuration succeeded."
+                    Write-Verbose "Cluster configuration succeeded."
                 }
                 elseif ($ExistConnectedKubernetes.ArcAgentProfileAgentState -eq "Failed") {
                     Write-Error "Cluster configuration failed."
@@ -763,6 +763,6 @@ function New-AzConnectedKubernetes {
                 }
             }
         }
-        Return $Response
+        Return $CCResponse
     }
 }

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/custom/New-AzConnectedKubernetes.ps1

@@ -675,12 +675,46 @@ function Set-AzConnectedKubernetes {
 
         $PSBoundParameters.Add('ArcAgentryConfiguration', $arcAgentryConfigs)
 
-        Write-Output "Updating the connected cluster resource...."
-        $Response = Az.ConnectedKubernetes.internal\Set-AzConnectedKubernetes @PSBoundParameters
-        if ((-not $WhatIfPreference) -and (-not $Response)) {
+        Write-Verbose "Updating the connected cluster resource...."
+        $CCResponse = Az.ConnectedKubernetes.internal\Set-AzConnectedKubernetes @PSBoundParameters
+        if ((-not $WhatIfPreference) -and (-not $CCResponse)) {
             Write-Error "Failed to update the 'Kubernetes - Azure Arc' resource"
             return
         }
+
+        # Wait for the agent state to settle before proceeding.  If it doesn't,
+        # we'll continue anyway - but remember and throw an error at the end.
+        $agentsInTerminalState = $true
+        if ($PSCmdlet.ShouldProcess($ClusterName, "Check agent state of the connected cluster")) {
+
+            $timeout = [datetime]::Now.AddMinutes(60)
+
+            for (;;) {
+                $CCResponse = Get-AzConnectedKubernetes -ResourceGroupName $ResourceGroupName -ClusterName $ClusterName @CommonPSBoundParameters
+
+                if ($null -eq $CCResponse.ArcAgentProfileAgentState) {
+                    Write-Verbose "No agent configuration in progress."
+                    break
+                }
+                if ($CCResponse.ArcAgentProfileAgentState -eq "Succeeded") {
+                    Write-Verbose "Cluster agent configuration succeeded."
+                    break
+                }
+                if ($CCResponse.ArcAgentProfileAgentState -eq "Failed") {
+                    Write-Error "Cluster agent configuration failed."
+                    break
+                }
+                if ([datetime]::Now -ge $timeout) {
+                    Write-Error "Cluster agent configuration timed out after 60 minutes."
+                    $agentsInTerminalState = $false
+                    break
+                }
+
+                Write-Verbose "Cluster agent configuration is in progress..."
+                Start-Sleep -Seconds 30
+            }
+        }
+
         $arcAgentryConfigs = ConvertTo-ArcAgentryConfiguration `
             -ConfigurationSetting $ConfigurationSetting `
             -RedactedProtectedConfiguration $RedactedProtectedConfiguration `
@@ -690,8 +724,8 @@ function Set-AzConnectedKubernetes {
 
 
         # Convert the $Response object into a nested hashtable.
-        Write-Debug "PUT response: $Response"
-        $Response = ConvertFrom-Json "$Response"
+        Write-Debug "PUT response: $CCResponse"
+        $Response = ConvertFrom-Json "$CCResponse"
         $Response = ConvertTo-Hashtable $Response
 
         # Whatif may return empty response
@@ -709,7 +743,7 @@ function Set-AzConnectedKubernetes {
         $ResponseStr = $Response | ConvertTo-Json -Depth 10
         Write-Debug "PUT response: $ResponseStr"
 
-        Write-Output "Preparing helm ...."
+        Write-Verbose "Preparing helm ...."
 
         if ($PSCmdlet.ShouldProcess('configDP', 'get helm values from config DP')) {
             $helmValuesDp = Get-HelmValuesFromConfigDP `
@@ -774,7 +808,7 @@ function Set-AzConnectedKubernetes {
                 -Debug:($PSCmdlet.MyInvocation.BoundParameters["Debug"].IsPresent -eq $true)
         }
 
-        Write-Output "Executing helm upgrade, this can take a few minutes ...."
+        Write-Verbose "Executing helm upgrade, this can take a few minutes ...."
         Write-Debug $options -ErrorAction Continue
         if ($DebugPreference -eq "Continue") {
             $options += " --debug"
@@ -786,37 +820,18 @@ function Set-AzConnectedKubernetes {
                     $ChartPath `
                     --namespace $ReleaseInstallNamespace `
                     -f $userValuesLocation `
-                    --wait (-split $options)
+                    --wait (-split $options) | Out-Null
             }
             catch {
                 throw "Unable to install helm release"
             }
-            Return $Response
         }
 
-        if ($PSCmdlet.ShouldProcess($ClusterName, "Check agent state of the connected cluster")) {
-            if ($PSBoundParameters.ContainsKey('OidcIssuerProfileEnabled') -or $PSBoundParameters.ContainsKey('WorkloadIdentityEnabled') ) {
-                $ExistConnectedKubernetes = Get-AzConnectedKubernetes -ResourceGroupName $ResourceGroupName -ClusterName $ClusterName @CommonPSBoundParameters
-
-                Write-Output "Cluster configuration is in progress..."
-                $timeout = [datetime]::Now.AddMinutes(60)
-
-                while (($ExistConnectedKubernetes.ArcAgentProfileAgentState -ne "Succeeded") -and ($ExistConnectedKubernetes.ArcAgentProfileAgentState -ne "Failed") -and ([datetime]::Now -lt $timeout)) {
-                    Start-Sleep -Seconds 30
-                    $ExistConnectedKubernetes = Get-AzConnectedKubernetes -ResourceGroupName $ResourceGroupName -ClusterName $ClusterName @CommonPSBoundParameters
-                }
-
-                if ($ExistConnectedKubernetes.ArcAgentProfileAgentState -eq "Succeeded") {
-                    Write-Output "Cluster configuration succeeded."
-                }
-                elseif ($ExistConnectedKubernetes.ArcAgentProfileAgentState -eq "Failed") {
-                    Write-Error "Cluster configuration failed."
-                }
-                else {
-                    Write-Error "Cluster configuration timed out after 60 minutes."
-                }
-            }
+        # If there was a problem with agent state, throw the error now.
+        if ($agentsInTerminalState -eq $false) {
+                throw "Timed out waiting for Agent State to reach terminal state."
         }
+        Return $CCResponse
     }
 }
 

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/custom/Set-AzConnectedKubernetes.ps1

@@ -248,7 +248,16 @@ function New-MetadataForParameterSet()
     $cmdletName = Get-MappedCmdletFromFunctionName $ParameterSetInfo.Name
     $description = (Get-CmdletAttribute -CmdletInfo $ParameterSetInfo -AttributeName "DescriptionAttribute").Description
     [object[]]$example = New-ExampleForParameterSet $ParameterSetInfo
+    if ($Null -eq $example)
+    {
+        $example = @()
+    }
+    
     [string[]]$signature = New-ParameterArrayInParameterSet $ParameterSetInfo
+    if ($Null -eq $signature)
+    {
+        $signature = @()
+    }
 
     return @{
         Path = $httpPath

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/generate-portal-ux.ps1

@@ -3,7 +3,7 @@
 #
 # Generated by: Microsoft Corporation
 #
-# Generated on: 11/8/2024
+# Generated on: 11/14/2024
 #
 
 @{
@@ -12,7 +12,7 @@
 # RootModule = ''
 
 # Version number of this module.
-ModuleVersion = '0.12.0'
+ModuleVersion = '0.13.0'
 
 # Supported PSEditions
 CompatiblePSEditions = 'Core', 'Desktop'
@@ -112,8 +112,7 @@ PrivateData = @{
         # IconUri = ''
 
         # ReleaseNotes of this module
-        ReleaseNotes = '* Corrected function that only worked on Windows.
-* Prevented unexpected value changes where parameters that were never set are unchanged but replayed back as part of Set-AzConnectedKubernetes processing.'
+        ReleaseNotes = '* Fixed output type of cmdlet'
 
         # Prerelease string of this module
         # Prerelease = ''

src/ConnectedKubernetes/ConnectedKubernetes/Az.ConnectedKubernetes.psd1

@@ -19,6 +19,9 @@
 -->
 ## Upcoming Release
 
+## Version 0.13.0
+* Fixed output type of cmdlet
+
 ## Version 0.12.0
 * Corrected function that only worked on Windows.
 * Prevented unexpected value changes where parameters that were never set are unchanged but replayed back as part of Set-AzConnectedKubernetes processing.