|
| 1 | +# Develpoing ConnectedKubernetes Powershell Cmdlets |
| 2 | +> 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. |
| 3 | +
|
| 4 | +# Overview |
| 5 | +## Why Custom Cmdlets? |
| 6 | +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]. |
| 7 | + |
| 8 | +For this reason, the ConnectedKubernetes cmdlets have two or more steps such as: |
| 9 | +- Interact with Azure using the REST APIs; this often involves just calling the autogenerated cmdlets |
| 10 | +- Now interact with Kubernetes using [helm]. |
| 11 | + |
| 12 | +## (Part) Autogeneration Process |
| 13 | +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: |
| 14 | + |
| 15 | +1. Carefully craft your [Swagger] definition of the REST API |
| 16 | +1. Read the [Quickstart for Azure PowerShell development using code generator] |
| 17 | +1. Clone the [azure-powershell] repo |
| 18 | +1. Create a develpoment branch based on the `generate` branch **and not based on `main`**! |
| 19 | +1. Run the [autorest] Docker image; if you have no local image for [autorest], refer to |
| 20 | +1. Run [autorest] to generate configuration and files that will result in the autogenerated cmdlets |
| 21 | +1. Run the build process (`pwsh build-module.ps1`) which completes the build process. |
| 22 | + |
| 23 | +### Building the [autorest] Docker image |
| 24 | +> 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! |
| 25 | +
|
| 26 | +- Clone the [autorest.powershell] repo |
| 27 | +- Navigate to the `tools/docker` directory |
| 28 | +- Follow the instructions in the README file in that directory |
| 29 | + |
| 30 | +## Special Aspects for ConnectedKubernetes |
| 31 | +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. |
| 32 | +> As described earlier, the custom versions often call-through to the autogenerated version to perform the ARM REST API portion of their work. |
| 33 | +
|
| 34 | +### Gotchas |
| 35 | +#### You Want a New Cmdlet? |
| 36 | +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. |
| 37 | + |
| 38 | +When we tried to add the `Set-` cmdlet, we found it never appeared but eventually we discovered these nuggets of knowledge. |
| 39 | +- [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 |
| 40 | +- The `internal` cmdlets are really just Powershell wrappers but these are not created until the `pwsh build-module-ps1` step |
| 41 | +- Between the steps above sits the [autorest] configuration found in the XML at the end of [README.md]. This does stuff like: |
| 42 | + - Stops the generation of various versions of cmdlets that are not required |
| 43 | + - **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. |
| 44 | + |
| 45 | +[autorest.powershell]: https://github.com/Azure/autorest.powershell |
| 46 | +[autorest]: https://github.com/Azure/autorest |
| 47 | +[helm]: https://helm.sh/ |
| 48 | +[Swagger]: https://swagger.io/ |
| 49 | +[README.md]: ./README.md |
| 50 | +[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 |
| 51 | +[azure-powershell]: https://github.com/azure/azure-powershell |
0 commit comments