Clarification for 'deployment().name'

[unique-dominik]

Sorry if that was asked before but I fear I did not find a similar question/issue (and if I ask in the correct place).

It is about the Deployment functions.

What are actual real world use cases to leverage the deployment().name?

I see that e.g. br/public:network/virtual-network uses it to identify virtual networks (or tries to).

But when I do that, every time I run the code the name changes (which kind of makes no sense).

I also tried to name the deployments via the command line but somehow that does not get reflected well into the bicep deployment (where bicep seems to attach a random string at the end).

location="switzerlandnorth"
deployment_stack_name="my-stack"
subscription_id="XXXXXXXX-cd38-4990-b2a1-XXXXXXXXXXXX"

# plan
az deployment sub create --name $deployment_stack_name --template-file main.bicep --location $location  --subscription $subscription_id --parameters params.bicepparam --what-if

# apply
az stack sub create --name $deployment_stack_name --template-file main.bicep --location $location --subscription $subscription_id --deny-settings-mode none --cs --delete-all --parameters params.bicepparam --yes

Using my config above, the plan results in my-stack as name, where as the apply results in my-stack-{randomString}.

The use case is just as the example of the VNet:

module vnet 'br/public:network/virtual-network:1.1.3' = {
  name: 'vnet-${uniqueString(fullName(context), location)}'
  scope: rgNet
  params: {
    name: 'vnet-${uniqueString(deployment().name, location)}'
    ...
  }
}

I am also happy to contribute to the docs once I understood what it should do. Or I am just flat out using it wrong but also then the docs needs some love ❤️

[SimonWahlin]

I primarily use deployment().name when I have multiple levels of nested modules to avoid naming conflicts.

For example, imagine a scenario where I want to deploy an API manager and a function app to the same resource group. They both need a key vault and to not have to copy/paste the definition of a key vault resource in two places I have a generic module for a Key Vault (preferably published to an Azure Container Registry). I also have a module for an API manager as well as a module for a function app (again preferably in an ACR).

If I (or anyone else) decides to deploy my API Manger module and my function app module to the same resource group, the KeyVault deployment in each module must have different names to not risk conflicting. To minimise the risk of conflicts I prepend the deployment name of the Key Vault with the deployment name of the parent deployment.

module keyVault 'br:myacr.azurecr.io/keyvault:1.7.0' = {
  name: '${deployment().name}-keyvault'

There is an experimental solution to this implemented in #12600