search

Azure / bicep

Bicep is a declarative language for describing and deploying Azure resources
MIT License
3.25k stars 753 forks source link

Microsoft.Network/privateEndpoints deployment reference documantion contains unneeded information #8801

Open jikuja opened 2 years ago

jikuja commented 2 years ago

Describe the bug Deployment reference documentation for Microsoft.Network/privateEndpoints includes full subnet information.

The deployment process requires only the following information: image

The template should be really short and tidy. Documentation also states The ID of the subnet from which the private IP will be allocated. about subnet property. Therefore subnet property should contain only id property.

The bicep example on deployment reference documentation uses 151 lines of 228 lines to describe subnet property even three lines should be enough. Also huge amount of subnet typing information is populated on deployment reference documentation.

This behaviour is probably bug on provider's schema: https://github.com/Azure/azure-rest-api-specs/blob/48bb51ee0753ed56a88b3e7f989a70bf19ba96bb/specification/network/resource-manager/Microsoft.Network/stable/2022-05-01/privateEndpoint.json#L680-L682

possible solutions: instead of re-using full subnet definition simpler definition containing only the id.

Additional context My other findinds:

GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/privateEndpoints/{privateEndpointName} returns only id of the subnet instead of full subnet resource description.

I did not test if deployment of Microsoft.Network/privateEndpoints actually can be used to create a new subnet but I doubt that because of the documentation note about subnet id.

VS code intellisense will let user happily to fill all subnet properties even id is probably the only one that is required and supported

alex-frankel commented 2 years ago

This is by design. Template Reference shows all possible properties, not only what is required. I would consider it a feature request of template reference to show a "Minimum Resource Format" that only displays required properties. cc @tfitzmac / @stephaniezyen as FYI

tfitzmac commented 2 years ago

I believe this is an issue with the RP specification. It looks like they are reusing a definition when just the id property should have been defined.

We won't be adding a minimum format section because the required flag is not reliable. There are lots of properties that become required when another property is set. So, I think a minimum view would be misleading.

However, we can address this issue by displaying an example that shows an introductory usage of the resource type. It would not be strictly limited to required properties but it would show the minimum properties that are commonly set.