Merge branch 'generation' of https://github.com/Azure/azure-powershell …

…into jinpei/generation/monitor

.azure-pipelines/powershell-core.yml

@@ -7,7 +7,7 @@ variables:
   LinuxAgentPoolVMImage: ''
   MacOSName: macOS
   MacOSAgentPoolName: 'Azure Pipelines'
-  MacOSAgentPoolVMImage: macOS-13
+  MacOSAgentPoolVMImage: macOS-latest
   TestFramework: net6.0
   TestTarget: Test
   Configuration: Debug

NuGet.Config

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <configuration>
   <packageSources>
     <clear />
@@ -11,3 +11,5 @@
     <clear />
   </disabledPackageSources>
 </configuration>
+
+

src/ADDomainServices/ADDomainServices.Autorest/README.md

@@ -148,7 +148,7 @@ directive:
           - Name
           - DomainName
           - Location
-          - Sku
+          - Sku 
         labels:
           DomainName: Domain Name
 ```

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/Az.ConnectedKubernetes.psd1

@@ -1,5 +1,5 @@
 @{
-  GUID = 'd3467834-8989-4142-8c05-ab93c4bfa6eb'
+  GUID = 'efbb1325-5081-4947-8508-ab47abbf6e76'
   RootModule = './Az.ConnectedKubernetes.psm1'
   ModuleVersion = '0.1.0'
   CompatiblePSEditions = 'Core', 'Desktop'

src/ConnectedKubernetes/ConnectedKubernetes.Autorest/custom/DEVELOP.md

@@ -1,42 +1,99 @@
-# Develpoing ConnectedKubernetes Powershell Cmdlets
-> These notes are intended to compliment and extend the common instructions for this process.  If you spot a sensible common location where part of this document could live, please do move the information out of here.
+# Developing ConnectedKubernetes Powershell Cmdlets
+> These notes are intended to complement and extend the common instructions for this process.  If you spot a sensible common location where part of this document could live, please do move the information out of here.
 
 # Overview
 ## Why Custom Cmdlets?
-Powerhsll cmdlets can be created almost totally automatically for many products but ConnectedKubernetes is special.  The standard cmdlet interations are one or more ([Swagger]) REST API exchanges with Azure but ConnectedKubernetes also has to install Azure Arc support into a Kubernetes cluster and this requires work to be performed using [helm].
+Powershell cmdlets can be created almost totally automatically for many products but ConnectedKubernetes is special.  The standard cmdlet interactions are one or more ([Swagger]) REST API exchanges with Azure but ConnectedKubernetes also has to install Azure Arc support into a Kubernetes cluster and this requires work to be performed using [helm].
 
 For this reason, the ConnectedKubernetes cmdlets have two or more steps such as:
 - Interact with Azure using the REST APIs; this often involves just calling the autogenerated cmdlets
 - Now interact with Kubernetes using [helm].
 
 ## (Part) Autogeneration Process
-The autogeneration process uses [autorest.powershell], an [autorest] extension for creating Powershell cmdlets based on a (Swagger) REST API definition.  this is typically as follows:
+The autogeneration process uses [autorest.powershell], an [autorest] extension for creating Powershell cmdlets based on a (Swagger) REST API definition.  This tool is run via an [autorest] [Docker] image (you will need something like [Docker Desktop] installed).  The typical cmdlet development process is this:
 
 1. Carefully craft your [Swagger] definition of the REST API
 1. Read the [Quickstart for Azure PowerShell development using code generator]
 1. Clone the [azure-powershell] repo
-1. Create a develpoment branch based on the `generate` branch **and not based on `main`**!
-1. Run the [autorest] Docker image; if you have no local image for [autorest], refer to 
-1. Run [autorest] to generate configuration and files that will result in the autogenerated cmdlets
-1. Run the build process (`pwsh build-module.ps1`) which completes the build process.
+1. Create a development branch based on the `generate` branch **and not based on `main`**!
+1. Run the [autorest] [Docker] image; see below if you do not already have a local image for [autorest],
+1. Inside the [autorest] environment...
+   1. Run `autorest` to generate configuration and files that will result in the autogenerated cmdlets
+   1. Run the build process, `pwsh build-module.ps1`, which completes the build process
+   1. Optionally create a local package `pwsh pack-module.ps1`.
+
+---
+Note that many of the intermediate steps rely on output from a previous step.  For example `build-module.ps1` is an output from the `autorest` step. 
+
+---
 
 ### Building the [autorest] Docker image
-> Do **NOT** build an [autorest] image based on the Dockerfile contained in the `tools/autorest` directory below the [azure-powershell] repo as this does not produce a working image!
+If you do not already have an [autorest] image, do **NOT** build one using the Dockerfile contained in the `tools/autorest` directory in the [azure-powershell] - repo as this does not produce a working image!  Instead, build the image like this:
 
 - Clone the [autorest.powershell] repo
 - Navigate to the `tools/docker` directory
-- Follow the instructions in the README file in that directory 
+- Follow the instructions in the README file in that directory.
 
 ## Special Aspects for ConnectedKubernetes
 The autogenerated cmdlets are created in C# with Powershell wrappers that are placed into the `internal` folder.  This is because we are **NOT** exposing the autogenerated functions to the user, rather er export our custom versions.
 > As described earlier, the custom versions often call-through to the autogenerated version to perform the ARM REST API portion of their work.
 
-### Gotchas
-#### You Want a New Cmdlet?
+The custom cmdlets can be found in the `custom` directory.  They are written in Powershell and do some manuipulation of input parameters before interacting with Azure and then Kubernetes via [helm].
+
+## Gotchas
+### Desktop Powershell (v5.1) Back-Compatibility
+The `Az` packages are all written to work with the preinstalled Windows Desktop version of Powershell, which is obsolete!
+
+We have to maintain this compatibility and the way to prove this is to use `PSScriptAnalyzer` (invoked as `Invoke-ScriptAnalyzer`) to confirm this.  The process is below and the following references contain useful information:
+- https://devblogs.microsoft.com/powershell/using-psscriptanalyzer-to-check-powershell-version-compatibility/
+- https://learn.microsoft.com/en-gb/powershell/utility-modules/psscriptanalyzer/rules/usecompatiblecommands?view=ps-modules
+
+```Powershell
+# Run this from within the "custom" directory.
+Write-Host -ForegroundColor Green 'Linting and checking Powershell back-compatibility...'
+Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
+$settings = @{
+   # Ref: https://devblogs.microsoft.com/powershell/using-psscriptanalyzer-to-check-powershell-version-compatibility/
+   Rules = @{
+   PSUseCompatibleSyntax   = @{
+      # This turns the rule on (setting it to false will turn it off)
+      Enable         = $true
+
+      # List the targeted versions of PowerShell here
+      TargetVersions = @(
+         '5.1',
+         '7.0'
+      )
+   }
+   PSUseCompatibleCommands = @{
+      # Turns the rule on
+      Enable         = $true
+
+      # Lists the PowerShell platforms we want to check compatibility with
+      # Ref: https://learn.microsoft.com/en-gb/powershell/utility-modules/psscriptanalyzer/rules/usecompatiblecommands?view=ps-modules
+      TargetProfiles = @(
+         'win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework',
+         'win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core'
+      )
+   }
+}
+
+# Recursively find all *.ps1 files and run Invoke-ScriptAnalyzer against them.
+Get-ChildItem -Path . -Recurse -Include '*.ps1' | Invoke-ScriptAnalyzer -Settings $settings
+if ($LastExitCode -ne 0) {
+   Write-Error 'ScriptAnalyzer found (possibly back-compatibility) issues.'
+}
+```
+
+
+### Dependencies
+We have thus far been unable to make the `Az.ConnectedKubernetes` module install its dependencies (`Az.Resources` and `Az.Accounts`).  This is possible for powershell but the issue is that the configuration to do this has to somehow be passed through the [autorest] process and attempts to do this have thus far failed.
+
+### You Want a New Cmdlet?
 If you are creating a whole new command, then you need to get the [autorest] process and the build process to work together to create the underlying `internal` command for you and this is not trivial.
 
 When we tried to add the `Set-` cmdlet, we found it never appeared but eventually we discovered these nuggets of knowledge.
-- [autorest] will look at the `operationId` field in the [Swagger] for each REST API method and determine what commands to create.  So in our case `ConnectedCluster_Create` only causes `New-` cmdlets to be created and we had to update the [Swagger] to say `ConnectedCluster_CreateOrUpdate` before any `Set-` cmdlets were created
+- [autorest] will look at the `operationId` field in the [Swagger] for each REST API method and determine what commands to create.  So in our case `ConnectedCluster_Create` only causes `New-` cmdlets to be created and we had to update the [Swagger] to say `ConnectedCluster_CreateOrUpdate` before any `Set-` cmdlets were created.  Note that there are other options possible and the Swagger teams preferred `ConnectedCluster_CreateOrReplace` which works just as well for what we need and introduces no external API differences.
 - The `internal` cmdlets are really just Powershell wrappers but these are not created until the `pwsh build-module-ps1` step
 - Between the steps above sits the [autorest] configuration found in the XML at the end of [README.md].  This does stuff like:
    - Stops the generation of various versions of cmdlets that are not required
@@ -48,4 +105,6 @@ When we tried to add the `Set-` cmdlet, we found it never appeared but eventuall
 [Swagger]: https://swagger.io/
 [README.md]: ./README.md
 [Quickstart for Azure PowerShell development using code generator]: https://eng.ms/docs/cloud-ai-platform/azure-core/azure-management-and-platforms/control-plane-bburns/azure-cli-tools-azure-cli-powershell-and-terraform/azure-cli-tools/onboarding/azurepowershell/quickstart_codegen
-[azure-powershell]: https://github.com/azure/azure-powershell
+[azure-powershell]: https://github.com/azure/azure-powershell
+[Docker]: https://www.docker.com
+[Docker Desktop]: https://www.docker.com/products/docker-desktop/

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

@@ -10,8 +10,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# Code generated by Microsoft (R) AutoRest Code Generator.Changes may cause incorrect behavior and will be lost if the code
-# is regenerated.
 # ----------------------------------------------------------------------------------
 
 [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '',
@@ -374,7 +372,7 @@ function New-AzConnectedKubernetes {
         $helmClientLocation = 'helm'
 
         #Region get release namespace
-        $ReleaseNamespaces = Get-HelmReleaseNamespaces -KubeConfig $KubeConfig -KubeContext $KubeContext
+        $ReleaseNamespaces = Get-HelmReleaseNamespace -KubeConfig $KubeConfig -KubeContext $KubeContext
         $ReleaseNamespace = $ReleaseNamespaces['ReleaseNamespace']
         $ReleaseInstallNamespace = $ReleaseNamespaces['ReleaseInstallNamespace']
 
@@ -417,7 +415,7 @@ function New-AzConnectedKubernetes {
             }
         }
 
-        $RegistryPath = Set-HelmRepositoryAndModules -KubeConfig $KubeConfig -KubeContext $KubeContext -Location $Location -ProxyCert $ProxyCert -DisableAutoUpgrade $DisableAutoUpgrade -ContainerLogPath $ContainerLogPath -CustomLocationsOid $CustomLocationsOid
+        $RegistryPath = Set-HelmModulesAndRepository -KubeConfig $KubeConfig -KubeContext $KubeContext -Location $Location
 
         # Region create RSA keys
         Write-Debug "Generating RSA keys for secure communication."
@@ -641,9 +639,9 @@ 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" -AsHashTable -Depth 10
+        $Response = ConvertFrom-Json "$Response"
+        $Response = ConvertTo-Hashtable $Response
 
         # What-If processing does not create a full response so we might have
         # to create a minimal one.
@@ -660,7 +658,7 @@ function New-AzConnectedKubernetes {
         Write-Debug "PUT response: $Response"
         $ResponseStr = $Response | ConvertTo-Json -Depth 10
         Write-Debug "PUT response: $ResponseStr"
-        
+
         if ($PSCmdlet.ShouldProcess("configDP", "request Helm values")) {
             $helmValuesDp = Get-HelmValuesFromConfigDP `
                 -configDPEndpoint $configDPEndpoint `
@@ -736,8 +734,6 @@ function New-AzConnectedKubernetes {
                     --set systemDefaultValues.clusterconnect-agent.enabled=true `
                     --set global.kubernetesDistro=$Distribution `
                     --set global.kubernetesInfra=$Infrastructure (-split $options)
-
-                # $helmDebug
             }
             catch {
                 throw "Unable to install helm chart at $ChartPath"
@@ -747,15 +743,15 @@ function New-AzConnectedKubernetes {
         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."
                 }
@@ -764,7 +760,7 @@ function New-AzConnectedKubernetes {
                 }
                 else {
                     Write-Error "Cluster configuration timed out after 60 minutes."
-                }      
+                }
             }
         }
         Return $Response