Documentation: Resource Arguments (argument reference) that don't obviously align with the Azure setting name

Terraform Providers Azure
1

This is something that I struggle with and makes writing Terraform configuration a bit of a pain, as a non-expert, with Terraform. When I go through the process of updating existing terraform code, I might do a terraform plan, I’ll see drift and make decisions of including parameters/settings of a Azure resource in our IaC.

For example, my Terraform Plan reveals that my storage account wants to set allow_nested_items_to_be_public. Okay - I dont know what that is, so I go to Azure Portal and see what this is. I assume its in the Configuration of the storage account, but I don’t see any setting with the verbiage “nested” there. I then go to the AzureRM documentation to read about this argument, and its the most bland description that does not help me correlate to the setting in Azure portal. At this point, I can only take a wild guess its something to do with “Allow Blob Public Access”…but thats not a lot of confidence and I don’t really enjoy taking shots in the dark, updating code, running terraform plan over and over just to see if it is indeed related. I can’t even find anything that matches “allow_nested_items_to_be_public” when I look at the raw template that interacts with Azure’s api to generate these resource.

I think the AzureRM documentation for resources and their arguments should closely match what is in the Portal UI / template definition.

2

So, I found some history about this particular argument for the azurerm_storage_account resource. This blog post actually discusses the renaming of the argument, and the related PR.

I think its strange that the AzureRM team made the decision that they would call argument by a different name when Microsoft uses the older term. Why not just have the argument match what Microsoft calls it, since it toggles the same switch?

Another possible solution to the confusion of correlating AzureRM resource arguments to the proper Azure setting would be a hyperlink to the schema definition of that resource. For example, in the AzureRM documentation for allow_nested_items_to_be_public, a hyper link to Microsoft.Storage/storageAccounts - Bicep, ARM template & Terraform AzAPI reference | Microsoft Learn would clear things up. Making this standard to all the arguments defined, would be a good process.