README.md

Bicep deploy

A pipeline to plan and deploy Azure infrastructure.

Overview

1. The user creates a new branch, then commits and push the code.
2. The user creates a pull request.
3. The pipeline is automatically triggered and starts the plan job.
4. If the plan job was successful, the pipeline will wait for a required reviewer to approve the deploy job.
5. When a reviewer has approved, the pipeline starts the deploy job to deploy the code.

Get started

To use the pipeline, several prerequisite steps are required:

1. Install the PSRule Azure DevOps extension.

2. Create an environment.

3. To prevent unapproved deployments, add the "Approvals" check to the environment.

4. Create a Azure Resource Manager workload identity service connection.

5. Assign Azure roles to the application so it can deploy Azure infrastructure. For example, give it the "Owner" role on the target Azure subscription.

6. If needed, create a repo.

7. In the repo settings, ensure the build service has "Contribute to pull requests" permission.

8. Add the ms.azure.deploy.yml to a repo folder, e.g. ".pipelines".

9. Customize the variable values in the "ms.azure.deploy.yml" file and commit the changes.

10. If needed, add bicep code to the repo.

11. Add a ps-rule.yaml file to the same folder as the main bicep/template file or in the repository root.

12. Go to the Azure DevOps Pipelines page. Then choose the action to create a New pipeline.

13. Select Azure Repos Git as the location of the source code.

14. When the list of repositories appears, select the repository.

15. Select Existing Azure Pipelines YAML file and choose the YAML file: "/.pipelines/ms.azure.deploy.yml".

16. Save the pipeline without running it.

17. Configure branch policies for the default/main branch.

18. Add a build validation branch policy.

Pipeline

The pipeline is designed to run when a pull request is created or updated.

The jobs in this pipeline has been tested on a standard Microsoft-hosted agent with YAML VM Image Label "ubuntu-22.04".

The following tools are used:

• Azure CLI
  • az bicep build
  • az bicep build-params
  • az provider register
  • az deployment {SCOPE} create
  • az deployment {SCOPE} validate
  • az deployment {SCOPE} what-if
• Azure Cost Estimator
• curl
• Azure Pipelines task:
  • AzureCLI@2
  • checkout
  • ps-rule-assert
  • publish
• GNU bash
• GNU bc
• GNU core utilities
• GNU find utilities
• jq
• sed
• unzip

Plan job

The plan job will build and test the code. If no issues are found in the code, a what-if report is generated.

The PSRule steps will only run if "rule_option" is specified and points to a file that exist.

For more information about PSRule configuration, see:

• Sample ps-rule.yaml
• Configuring options
• Configuring rule defaults
• Available Options
• Available Rules by resource type

Deploy job

The deploy job will only run when the plan job was successful.

It targets a specific environment.

If the environment is configured with Approvers, the job will require manual approval.

Variable Group

When using a variable group, make sure the pipeline has permissions to get the values.

Update the pipeline and replace the variables: with section to only include the name of the variable group, for example:

trigger: none
pr:
  autoCancel: true
  drafts: false

name: Azure Deploy

pool:
  vmImage: ubuntu-latest

variables:
  - group: PROD_GROUP

stages:
  - stage: Plan

Variables

• ARTIFACT_IDENTIFIER: A unique identifier added to artifact name in case of multiple runs within one workflow.

• COST_THRESHOLD: Max acceptable estimated cost. Exceeding threshold causes plan to fail.

• ENVIRONMENT: Name of the environment to use for the deploy job.

• IN_CURRENCY: Currency code to use for estimations. See allowed values at https://github.com/TheCloudTheory/arm-estimator/wiki/Options#currency

• IN_LOCATION: The Azure location to store the deployment metadata.

• IN_MANAGEMENT_GROUP: Management group to create deployment at for mg scope.

• IN_PROVIDERS: A comma separated list of Azure resource providers.

  The pipeline create job will try to register the specified providers in addition to the providers that is detected in code by deployment validate.

  Use the value "disable" to prevent the pipeline from trying to register Azure resource providers.

• IN_RESOURCE_GROUP: Resource group to create deployment at for group scope.

• IN_TEMPLATE: The template address. A path or URI to a file or a template spec resource id.

• IN_TEMPLATE_PARAMS: Deployment parameter values. Either a path, URI, JSON string, or <KEY=VALUE> pairs.

• IN_SCOPE: The deployment scope. Accepted: tenant, mg, sub, group.

• IN_SEVERITY: The log verbosity. Can be one of:

  • ERROR - Only show errors, suppressing warnings.
  • INFO - Standard log level.
  • VERBOSE - Increase logging verbosity.
  • DEBUG - Show all debug logs.

• PSRULE_AZURE_RESOURCE_MODULE_NOWARN: Suppresses a warning when the minimum version of Az.Resources module is not installed.

• RULE_BASELINE: The name of a PSRule baseline to use. For a list of baseline names for module PSRule.Rules.Azure see https://azure.github.io/PSRule.Rules.Azure/en/baselines/Azure.All/

• RULE_MODULES: A comma separated list of modules to use for analysis. For a list of modules see https://www.powershellgallery.com/packages?q=Tags%3A%22PSRule-rules%22

• RULE_OPTION: The path to an options file. If empty, PSRule will be skipped.

• SERVICE_CONNECTION: The Azure Resource Manager service connection name.

• SUBSCRIPTION_ID: The subscription ID in which to deploy the resources.

• VERSION_ACE: Azure Cost Estimator version. If empty, cost estimator will be skipped. See versions at https://github.com/TheCloudTheory/arm-estimator/releases.

• WAIT_SECONDS: Seconds to wait between each provider status check.

• WAIT_COUNT: Times to check provider status before giving up.

• WORKFLOW_VERSION: The version of the bicep-action scripts to use. See https://github.com/innofactororg/bicep-action/tags.

License

The code and documentation in this project are released under the BSD 3-Clause License.