From 441e6b9c1d4d18a09e9eb224de93671536d5cadb Mon Sep 17 00:00:00 2001 From: Dan Rios <36534747+riosengineer@users.noreply.github.com> Date: Thu, 11 Jan 2024 14:53:38 +0000 Subject: [PATCH] Metadata & description decorators example (#13) * Metadata & description decorators example merge * syntax and spelling fixes --- bicep-examples/consuming-modules/README.md | 4 +- bicep-examples/dependencies/README.md | 4 +- .../metadata-and-descriptions/README.md | 39 +++++++++++++++++++ .../metadata-example.bicep | 20 ++++++++++ .../metadata-example.bicepparam | 8 ++++ .../shared-variable-file-pattern/README.md | 6 +-- 6 files changed, 74 insertions(+), 7 deletions(-) create mode 100644 bicep-examples/metadata-and-descriptions/README.md create mode 100644 bicep-examples/metadata-and-descriptions/metadata-example.bicep create mode 100644 bicep-examples/metadata-and-descriptions/metadata-example.bicepparam diff --git a/bicep-examples/consuming-modules/README.md b/bicep-examples/consuming-modules/README.md index c514cf2..d348920 100644 --- a/bicep-examples/consuming-modules/README.md +++ b/bicep-examples/consuming-modules/README.md @@ -24,7 +24,7 @@ module public_registry 'br/public:compute/function-app:2.0.1' = { } ``` -## Prviate Registry +## Private Registry Creating your own Azure Container Registry can be a great way to consume Bicep modules for internal use only. @@ -89,7 +89,7 @@ module inline_module 'modules/inline/customModule.bicep' = { } ``` -## Azure Verified Modules +## Azure Verified Modules / Azure Bicep Public Registry [AVM](https://azure.github.io/Azure-Verified-Modules/faq/#what-is-happening-to-existing-initiatives-like-carml-and-tfvm) diff --git a/bicep-examples/dependencies/README.md b/bicep-examples/dependencies/README.md index 09d028e..f1f3b89 100644 --- a/bicep-examples/dependencies/README.md +++ b/bicep-examples/dependencies/README.md @@ -78,7 +78,7 @@ CLI ```bash az login -az set --subscription 'your subscription name' +az account set --subscription 'your subscription name' az deployment create --confirm-with-what-if -g 'your resource group name' -f .\main.bicep ``` @@ -86,6 +86,6 @@ or PowerShell ```powershell Connect-AzAccount -Set-AzContext -Subsription "your subsription name" +Set-AzContext -Subscription "your subscription name" New-AzResourceGroupDeployment -Confirm -ResourceGroup "your resource group name" -TemplateFile "main.bicep" ``` diff --git a/bicep-examples/metadata-and-descriptions/README.md b/bicep-examples/metadata-and-descriptions/README.md new file mode 100644 index 0000000..85e1b67 --- /dev/null +++ b/bicep-examples/metadata-and-descriptions/README.md @@ -0,0 +1,39 @@ +# Azure Bicep - Metadata & Descriptions + +## Introduction + +Whether you're starting your Azure Bicep journey and want to align to best practice methods straight from the get go, or you have existing templates that could do with a freshen up - descriptions and metadata has a place in your Azure Bicep templates. + +## 📃 Benefits of using metadata and descriptions in your Azure Bicep files + +1. ✅ Reusability. By defining the `@description` for the parameters other engineers can quickly understand the template and what function each parameter and variable is + +2. ✅ Accountability. By defining the `metadata =` information we're able to define the Azure Bicep name, description and business/team ownership for maintain the module (if applicable. Otherwise this is good just to describe the modules purpose) + +3. ✅ Best practice. It's good practice to have metadata and descriptions in your Azure Bicep files. It offers a consistent experience for everyone, and incorporates the above benefits that align into the best practice model + +> [!TIP] +> You can hover over parameters in your .bicepparam file to get the parameter description information. + +## 🚀 Deployment + +> [!NOTE] +> Metadata and descriptions decorators are just for the Azure Bicep file and have no bearing on deployment resources, however, as with all the examples there is a real world example deployment to accommodate the concept to bring the picture full circle. + +In VisualStudio Code open a terminal and run: + +CLI + +```bash +az login +az account set --subscription 'subscription name or id' +az deployment sub create --confirm-with-what-if -l 'uksouth' -f .\metadata-example.bicep -p .\metadata-example.bicepparam +``` + +or PowerShell + +```powershell +Connect-AzAccount +Set-AzContext -Subscription "subscription name or id" +New-AzDeployment -Confirm -Location "UKSouth" -TemplateFile ".\metadata-example.bicep" -TemplateParameterFile ".\metadata-example.bicepparam" +``` diff --git a/bicep-examples/metadata-and-descriptions/metadata-example.bicep b/bicep-examples/metadata-and-descriptions/metadata-example.bicep new file mode 100644 index 0000000..f1ddca1 --- /dev/null +++ b/bicep-examples/metadata-and-descriptions/metadata-example.bicep @@ -0,0 +1,20 @@ +targetScope = 'subscription' + +metadata name = 'Resource Group Azure Bicep module' +metadata description = 'Module used to create Resource Groups' +metadata owner = 'ops@example.com' + +@description('Azure Region where the Resource Group will be created.') +param parLocation string + +@description('Name of Resource Group to be created.') +param parResourceGroupName string + +@description('Azure Tags you would like to be applied to the Resource Group.') +param parTags object = {} + +resource resResourceGroup 'Microsoft.Resources/resourceGroups@2022-09-01' = { + location: parLocation + name: parResourceGroupName + tags: parTags +} diff --git a/bicep-examples/metadata-and-descriptions/metadata-example.bicepparam b/bicep-examples/metadata-and-descriptions/metadata-example.bicepparam new file mode 100644 index 0000000..aba30ea --- /dev/null +++ b/bicep-examples/metadata-and-descriptions/metadata-example.bicepparam @@ -0,0 +1,8 @@ +using 'metadata-example.bicep' + +// Hover over the param to see their descriptions pulled from the main bicep file +param parLocation = 'uksouth' +param parResourceGroupName = 'rg-uks-test-prod' +param parTags = { + metadata: 'test' +} diff --git a/bicep-examples/shared-variable-file-pattern/README.md b/bicep-examples/shared-variable-file-pattern/README.md index 8cc05ce..259c55e 100644 --- a/bicep-examples/shared-variable-file-pattern/README.md +++ b/bicep-examples/shared-variable-file-pattern/README.md @@ -1,6 +1,6 @@ # Using shared variable file pattern in Azure Bicep - Examples -## [Blog post](https://rios.engineer/harness-shared-variable-file-patterns-with-azure-bicep) +## [Blog post](https://rios.engineer/harness-shared-variable-file-patterns-with-bicep/) Building on the Microsoft Documentation on this I've expanded and created some more examples where this can be useful for you or your organisation. I've broken these down into three example chunks. I would advise first going over the documentation to familiarise yourself with the concept here: @@ -18,7 +18,7 @@ CLI ```bash az login -az set --subscription 'your subscription name' +az account set --subscription 'your subscription name' az deployment create --confirm-with-what-if -g 'your resource group name' -f .\file.bicep ``` @@ -26,7 +26,7 @@ or PowerShell ```powershell Connect-AzAccount -Set-AzContext -Subsription "your subsription name" +Set-AzContext -Subscription "your subscription name" New-AzResourceGroupDeployment -Confirm -ResourceGroup "your resource group name" -TemplateFile "file.bicep" ```