Align automation/automation-account to AVM specs

[elanzel]

• Create the Github account and fork the bicep registry repo as described here https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/

• Choose the module you want to migrate in planned modules https://azure.github.io/Azure-Verified-Modules/indexes/bicep/bicep-resource-modules/#planned-modules

• Check there is not already an issue for that module and open the issue here https://github.com/Azure/Azure-Verified-Modules/issues

• Wait the confirmation email before start with the conversion

• Update CARML alignment tracker: [Feature Request]: AVM alignment tracker  #4020 in per-module edit checklist

• Create a new branch in your fork and start with the following code updates

To do

Checklist

1. Tests (ref)

   • Rename test folder and add nested e2e folder (ref)
   • Rename min folder to defaults
   • Rename common folder to max
   • Add waf-aligned folder (e.g., based on common). This test should not fail PSRule & show the module being deployed with best-practices
   • For each folder,
   • Update the serviceShort parameter to align with the new naming (e.g., waf for waf-aligned). For now, we should continue using min for defaults to align with PSRule.
   • Update the namePrefix input parameter value from [[namePrefix]] to #_namePrefix_# (the reason being that Bicep has a compilation issue because of the prefix & suffix in another location)
   • Remove the enableDefaultTelemetry parameter and reference in the test
   • Update the ../../main.bicep module template reference to ../../../main.bicep
   • If a resource group is deployed, update the RG parameter name to the new format that also uses the namePrefix. For example:

     @description('Optional. The name of the resource group to deploy for testing purposes.') 
     @maxLength(90)
     param resourceGroupName string = 'dep-${namePrefix}-network.privateendpoints-${serviceShort}-rg'

   • (Optionally) add a block like the following below the target scope to render a more meaningful example in the ReadMe

     metadata name = 'Using only defaults'
     metadata description = 'This instance deploys the module with the minimum set of required parameters.'

   • You should also try and test idempotency if possible. You can do this by updating the test invocation to

     @batchSize(1)
     module testDeployment '../../../main.bicep' = [for iteration in [ 'init', 'idem' ]: {
       scope: resourceGroup
       name: '${uniqueString(deployment().name, location)}-test-${serviceShort}-${iteration}'
       (...)
     }]

2. For each module that supports

   Diagnostic Settings

   Reference to AVM specs

   • Add the diagnosticSettingType described in the above reference to a // Definitions block at the bottom of the template file
   • Remove any of the current diagnosticSetting parameters & variables
   • Add the the new diagnosticSettings parameter as per the specs to the template
   • Updated the deployment block as per the specs to enable it to work with the new object type
   • Check if any of the tests must be updated. The new block may look like

     diagnosticSettings: [
       {
         name: 'customSetting'
         eventHubName: diagnosticDependencies.outputs.eventHubNamespaceEventHubName
         eventHubAuthorizationRuleResourceId: diagnosticDependencies.outputs.eventHubAuthorizationRuleId
         storageAccountResourceId: diagnosticDependencies.outputs.storageAccountResourceId
         workspaceResourceId: diagnosticDependencies.outputs.logAnalyticsWorkspaceResourceId
       }
     ]

   NOTE: ⚠️ Make sure that if the module does not support e.g. metrics, that you update the logic accordingly

   Role Assignments

   Reference to AVM specs

   • Add the roleAssignmentType described in the above reference to a // Definitions block at the bottom of the template file
   • Update the current roleAssignments parameter as per the specs (- should now reference the User-defined-type)
   • Take the current list of builtInRoleNames from the nested_roleAssignments.bicep file and add them to the variables block of the main template. The new schema does not require the nested template. Also, reduce the list of specified roles to only those that make sense for this resource (ref)/ For, for example, Cognitive Services, we should only provide the important ones as Owner, Contributor, etc. + all service specific roles such as 'Cognitive Services User'.
   • Replace the original module deployment block with the new resource deployment block
   • Check if any of the tests must be updated. The new block may look like

     roleAssignments: [
       {
         roleDefinitionIdOrName: 'Reader'
         principalId: nestedDependencies.outputs.managedIdentityPrincipalId
         principalType: 'ServicePrincipal'
       }
     ]

   Resource Locks

   Reference to AVM specs

   • Add the lockType described in the above reference to a // Definitions block at the bottom of the template file
   • Update the current lock parameter as per the specs (- should now reference the User-defined-type)
   • Updated the deployment block as per the specs to enable it to work with the new object type
   • Check if any of the tests must be updated. The new block may look like

     lock: {
       kind: 'CanNotDelete'
       name: 'myCustomLockName'
     }

   Tags

   Reference to AVM specs

   • Update the current tags parameter as per the specs
   Managed Identities

   Reference to AVM specs

   • Add the managedIdentitiesType described in the above reference to a // Definitions block at the bottom of the template file
   • Remove any of the current identity parameters & variables
   • Add the the new managedIdentities parameter as per the specs to the template
   • Updated the deployment block as per the specs to enable it to work with the new object type
   • Check if any of the tests must be updated. The new block may look like

     managedIdentities: {
       systemAssigned: true
       userAssignedResourcesIds: [
         nestedDependencies.outputs.managedIdentityResourceId
       ]
     }

   NOTE: ⚠️ Make sure that if the module does not support e.g. user-assigned-identities, that you update the logic accordingly

   Private Endpoints

   Reference to AVM specs

   • Add the privateEndpointType described in the above reference to a // Definitions block at the bottom of the template file
   • Update the current privateEndpoints parameter as per the specs (- should now reference the User-defined-type)
   • Updated the deployment block as per the specs to enable it to work with the new object type.

     Note: For any resource that only supports one service/groupID (e.g. 'vault' for KeyVault, but NOT 'blob' for StorageAccount) we can provide a default value for that property (hence there are 2 variants in the spec).

   • Check if any of the tests must be updated. The new block may look like

     privateEndpoints: [
       {
         privateDnsZoneResourceIds: [
           nestedDependencies.outputs.privateDNSZoneResourceId
         ]
         subnetResourceId: nestedDependencies.outputs.subnetResourceId
         tags: {
           'hidden-title': 'This is visible in the resource name'
           Environment: 'Non-Prod'
           Role: 'DeploymentValidation'
         }
       }
     ]

   Customer Managed Keys

   Reference to AVM specs

   • Add the customerManagedKeyType described in the above reference to a // Definitions block at the bottom of the template file
   • Remove any of the current customer-managed-key parameters & variables
   • Add the the new customerManagedKey parameter as per the specs to the template
   • Update the existing resource references as per the specs
   • Updated the deployment block as per the specs to enable it to work with the new object type
     - ⚠️ BEWARE module-specific differences
     - Note also that the new schema SHOULD support system-assigned-identities. As this cannot be done in a single deployment, you can find a reference how this would look like here
   • Check if any of the tests must be updated. The new block may look like

     customerManagedKey: {
       keyName: nestedDependencies.outputs.keyVaultKeyName
       keyVaultResourceId: nestedDependencies.outputs.keyVaultResourceId
       userAssignedIdentityResourceId: nestedDependencies.outputs.managedIdentityResourceId
     }

   NOTE: ⚠️ Make sure that if the module does not support e.g. metrics, that you update the logic accordingly

3. Other

   • Set version in version.json back to 0.1 in the main folder and remove version.json from child resources
   • NB Update DefaultTelemetry with the new telemetry in the main folder and remove telemetry from child resources
   • (Optional) Introduce the new nullable feature for parameters where-ever it makes sense to you (and ensure to test it). This enables us to simplify logic like in the following example

     // Old
     param attributesExp int = -1
     resource secret 'Microsoft.KeyVault/vaults/secrets@2022-07-01' = {
       (...)
       properties: {
         attributes: {
           exp: attributesExp != -1 ? attributesExp : null
         }
       }
     }
     
     // New
     param attributesExp int?
     resource secret 'Microsoft.KeyVault/vaults/secrets@2022-07-01' = {
       (...)
       properties: {
         attributes: {
           exp: attributesExp
         }
       }
     }

• Check if outputs can be simplified as in the following example:
  @description('The principal ID of the system assigned identity.')
  OLD: output systemAssignedMIPrincipalId string = contains(workspace.identity, 'principalId') ? workspace.identity.principalId : ''
  NEW: output systemAssignedMIPrincipalId string = workspace.?identity.?principalId ?? ''

• if your module reference other AVM modules that are already in the bicep registry, be sure to point to the published one in your code (br/public:avm/res/......).

Please use the following values explicitly as provided in the module index page:

For your module:
ModuleName - to name your module
TelemetryIdPrefix - to be used in your module's telemetry
NB Remove telemetry from child resources!
For your module's repository:
Repository name and folder path are defined in RepoURL

##Last steps before the tests:
uncomment the line of the CODEOWNERS file corresponding to your module folder

Issue template update
Ref https://azure.github.io/Azure-Verified-Modules/specs/bicep/#id-bcpnfr15---category-contributionsupport---avm-module-issue-template-file
As part of the “initial Pull Request” (that publishes the first version of the module), module owners MUST add an entry to the AVM Module Issue template file in the BRM repository (here).
###ReadMe

• Regenerate all module ReadMe's & compile all module Bicep templates from the ground up. Ideally, remove the ReadMEs and regenerate them completely. Take note of any extra content (e.g., 'considerations') that were added manually and add them to the module's description metadata in the respective main.bicep file
  To regenerate all needed files run the following commands:

     . .\bicep-registry-modules\avm\utilities\tools\Set-AVMModule.ps1
            set-avmmodule -ModuleFolderPath .\bicep-registry-modules\avm\res\_yourmodule-folder_ -Recurse
  

test your module

create the module's action in .github folder and remember to put the action either in your main branch and in the branch you created.

TEAMS

Create the GitHub teams defined in the ModuleOwnersGHTeam and ModuleContributorsGHTeam columns and grant them permissions as described here.
NB
On the interface, where you create the team, there's one field where you can provide the parent. Can you please choose avm-technical-reviewers-bicep for the owners team, and avm-module-contributors-bicep for the contributors team? Once you do this, it will come in as a request to Mate, and he can approve it.
No more need to ping Mate in chat for this!

Final steps

• Make sure you open a module proposal to AVM and follow the instructions mentioned here New Issue · Azure/Azure-Verified-Modules (github.com)

PR

• when you are ready for the PR in bicepRegistry repository, make sure you uncomment the line of the CODEOWNERS file corresponding to your module folder
• when you open the PR, put a link to AVM proposal issue, this will leave a comment on the proposal with a link to the PR

Reference repositories

Once the module is published on bicep registry,

• once the PR is merged, leave another comment on the proposal stating that it's done
  then, Mate'll come in, do some final checks, apply labels, and update the index
• add the movedtoAVM file on carml repo and run set-module to add "this module will no be updated, it's moved, etc" on the readme file on CARML. Open the PR in CARML repo