Skip to content

Latest commit

 

History

History
110 lines (89 loc) · 7.34 KB

DEVELOP.md

File metadata and controls

110 lines (89 loc) · 7.34 KB

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?

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 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
  2. Read the Quickstart for Azure PowerShell development using code generator
  3. Clone the azure-powershell repo
  4. Create a development branch based on the generate branch and not based on main!
  5. Run the autorest Docker image; see below if you do not already have a local image for autorest,
  6. Inside the autorest environment...
    1. Run autorest to generate configuration and files that will result in the autogenerated cmdlets
    2. Run the build process, pwsh build-module.ps1, which completes the build process
    3. 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

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.

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.

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:

# 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. 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
    • hides the autogenerated cmdlets, which is what causes them to be created in internal; we had to add set to the list of cmdlets so hidden before the internal Set- cmdlet appeared.