Azure Developer CLI Template Guidelines

[charris-msft]

Azure Developer CLI Template Guidelines

These requirements are for samples that are using azd for deployment.

Code

Infra Folder

• Bicep Format - Bicep files should be formatted with bicep format. Can possibly be automated with pre-commit or GitHub actions.

• Core Modules - main.bicep should reference modules from core, copied from azure-dev.

  cp -r ../azure-dev/templates/common/infra/bicep/core/* infra/core/.

• Dashboard - Resources should include a dashboard so that azd monitor works, either by referencing the monitoring.bicep module or creating a dashboard separately. See main.bicep

• Monitoring - Application code should include either OpenCensus or OpenTelemetry so that the monitor is populated. See todo/app.py.

• Managed Identity - Application must use Managed Identity instead of keys wherever possible.

Elsewhere

• AZD Telemetry - azure.yaml should include metadata for telemetry including version number. See azure.yaml

• Service Source - In azure.yaml, the project property for each service should point at a subfolder, not at root (.). Typically the subfolder is labeled src but that may vary. See azure.yaml

• azd Pipeline Config - .github/workflows should include azure-dev.yaml to support azd pipeline config.

• Devcontainer - .devcontainer should contain a devcontainer.json and Dockerfile/docker-compose.yaml in order to create a full local dev environment. Start with azure-dev versions and modify as needed. See docker-compose.yaml for example that includes a local database service.

• security-devops-action - The application must run microsoft/security-devops-action. Example

  • If unfamiliar with setting up GH Actions, then you can follow the instructions here: defender-for-cloud/quickstart-onboard-github

• ** Hook Scripts** - all hook scripts (pre-/post- provisioning and deployment scripts) shall include both sh and pwsh versions.

README.md

• Short Description - a must description should be included. Example

• Prerequisites - a Prerequisites section should be included. Example

• Architecture - an architecture diagram and description must be included. Example

• 'Open In __' buttons - must use same "Open in " buttons as the TODO samples. Example

• Cost Estimation - a Cost Estimation section should be included. Example

Publicizing

• Awesome AZD - Add the project to Awesome Azure Developer CLI. Instructions: Contributor Guide | Awesome Azure Developer CLI

• Learn Sample Browser - Onboard the project to the Learn Sample Browser. Instructions: Onboarding Samples to learn.microsoft.com/samples - Documentation contributor guide

  • Note: May need to request access here.