Azd CLI Extensibility

[rajeshkamal5050]

Spike to investigate on extensibility in Azd

Use Cases

The following are a list of use cases to explore during this spike

• [x] [Subscribe to azd command hooks] - DONE (https://devblogs.microsoft.com/azure-sdk/azure-developer-cli-azd-february-2023-release/#support-for-command-and-service-hooks)
• [ ] Override built-in commands #1090
• [x] Skipping built-in commands - DONE using customizable up worfklow you could also skip
• [ ] Define custom commands
• [ ] Plugin model

See details below on each use case

Customer Scenarios

• 122

Subscribe to azd command hooks

For some applications it is a requirements that developers be able to run custom scripts either before or after azd commands.

This would enable many different scenarios. For example azd does not enforce any tests to be run between provision and deploy. Using pre/post command hooks would allow custom scripts to run to validate the state of an environment before moving on to deploy commands or additional stages.

Within the azure.yaml introduce a scripts section similar to that of Node applications. Scripts could either be a single, multiline script of a reference to a script that exists within the same repo.

Configuration based approach

Script section can either be defined at the root of azure.yaml or within a single service.

Root configuration

#azure.yaml 
scripts:
  preprovision: preprovision.sh      # Run terratest script to validate resources
  postprovision: postprovision.sh    # Run script to validate state of azure infra
  postdeploy: postdeploy.sh          # Run smoke tests like playwright to validate app(s) are working as expected

Service configuration

#azure.yaml 
services:
  app1:
    scripts:
      preprovision: preprovision.sh      # Run terratest script to validate resources
      postprovision: postprovision.sh    # Run script to validate state of azure infra
      postdeploy: postdeploy.sh          # Run smoke tests like playwright to validate app(s) are working as expected

Convention based approach

Another option is to use a convention based approach where we automatically look for files within the .azure/hooks folder. If we find a file called predeploy.sh we automatically wire it up as a pre deploy command hook and execute it accordingly.

Override built-in commands

This would enable more complex use cases where azd doesn't have support for a particular service target, language or similar and the dev wants to take more granular control of the workflow.

• Custom provision commands ex) Deploy via custom script with az cli commands
• Custom build commands
• Custom package commands
• Custom deploy commands

# azure.yaml
services:
  app1:
    scripts:
      provision: ./scripts/provision.sh   #custom provision script or reference to script file
      package: ./scripts/package.sh       #custom package script or reference to script file
      deploy: ./scripts/deploy.sh         #custom deploy script or reference to script file

Define custom commands

Ability to define custom commands and execute them through azd. A dev organization likely had a bunch of other scripts involved in their products that may relate to their overall platform or a specific service. It would be good for devs to be able to define their own custom azd command groups that execute scripts against their apps & infra.

More TBD.

Plugin Model

How do we allow external contributions into AZD for things like language/framework services, application targets, provisioning/pipeline providers etc?

Options

• Direct contributions into AZD source, reviewed and maintained by team
  • Require additional time to review and accept contributions
  • Team would need to maintain contributions, fix bugs, etc
• Contributions into forked repositories following guidance from docs & code
  • Lowest cost - Devs can fork azd and author custom packages / modules
• Develop a plugin in model + extension market place for devs to discover & contribute plugins
  • Requires more maintenence and support on market place
  • Develop integration model between core azd and plugins
  • Process for accepting plugins
  • Support for issues arising from plugins

If we develop our own plug-in model the leading method for cross process communication in go is to leverage gRPC & protocol buffers. This is the same implementation used under the covers for tools like Terraform.

Protobuf establishes the interface between the client & server and communication happens via gRPC. There are well established go modules.

gRPC Go Quickstart

Technical Details

We should support a variety of script options including shell scripts & powershell.

Inputs

All scripts should be executed from azd with all values from local .env file made available.

Questions

1. Do we need to expose any project configuration data?
2. Can we simply leverage exit codes to dictate overall success or failure of an operation?
3. Do we need to support output schema that is required?

[anevjes]

DO we know if the above extensibility model will allow us to use the logged in identity context to pass to the custom scripts?

[wbreza]

DO we know if the above extensibility model will allow us to use the logged in identity context to pass to the custom scripts?

@anevjes - could you give us an example of what types of calls you would like to make? REST API calls to ARM control plan or MS Graph? az cli commands or other?

[rajeshkamal5050]

Moving to Gallium cc @savannahostrowski

[rajeshkamal5050]

Moving this to backlog for now. We can pull this back in when we have more use-cases for core command extensibility.

Addressed - Hooks, Customizable up workflow (also enables skipping commands) Pending - Defining custom commands, Plugin model

@wbreza @kristenwomack