Azure
[Updated] Module Readmes - Workout a testable solution for the description of array and object parameters
Description
As most of the usage for object and array parameters are difficult to map out how to use, we should make it mandatory that these are in the readme files. Examples of what goes into an array, and what properties to use on a object parameter. Of course this only applies to the params we do not cover with child modules.
A suggestion would be to add a placeholder block such as below for all parameters of type array and object, excluding where we have a subfolder (child module) for it:
### Parameter Usage: `<ParameterName>`
```bicep
```
Started the implementation in branch users/alsehr/1096_paramUsage.
- It detects which parameter usage examples should exist
- For all but the default ones (e.g. role assignments) it generates a Parameter Usage section as per the following rules
- If the parameter was used in any of the top-level module's parameter files, the longest example is used (if it is used in multiple parameter files) - Should maybe be a combination of all - or multiple examples?
- If no example exists, a default placeholder is added
- In each case both a Bicep & Parameter JSON example is generated
It has however the issue that existing examples that are not in the parameter files may be overwritten & that comments are not translated into the generated example.
For example:
Further, fetching usage examples for child modules requires further engineering as it requires a dynamic drill down into the top-level module's parameter file.
Placeholder are not helping and manually written examples may be outdated. The team decides to have a preferably automated way to have working examples per complex parameter (or array parameter).
I'd strongly suggest to remove manually implemented parameter usage examples which are already used in deployment examples from the readme files until a good solution is found to automate them.
Not all parameter objects/arrays can be validated and for them the manually updated parameter usage snippets are for now good to be kept. Instead, the ones already used by deployment examples should be removed.
The reason is we may easily end up having two different snippets for the same parameter object/array: one in the parameter usage section (manually implemented once and usually never updated) and one in deployment examples (automatically retrieved and aligned with deployment validation tests).
An example is what we currently have for KeyVault networkAcls, which is quite error prone. From parameter usage:
networkAcls: {
bypass: 'AzureServices'
defaultAction: 'Deny'
virtualNetworkRules: [
{
subnetId: '/subscriptions/<<subscriptionId>>/resourceGroups/validation-rg/providers/Microsoft.Network/virtualNetworks/sxx-az-vnet-x-001/subnets/sxx-az-subnet-x-001'
}
]
ipRules: []
}
From deployment examples:
networkAcls: {
bypass: 'AzureServices'
defaultAction: 'Deny'
ipRules: []
virtualNetworkRules: [
{
action: 'Allow'
id: '<id>'
}
]
}
What showed in deployment examples should be the primary reference, as that gets continuously tested through module valitdation pipelines.
This will potentially go away with the future introduction of the user-defined types. cc: @eriqua
I'd suggest to not invest work into this issue until the feature is implemented as it may render it redundant.