Azure / Azure/bicep

Microsoft.KeyVault/vaults/accessPolicies deployment reference misses naming contrains

Open
#8,800 0 comments 0 reactions 0 assignees View on GitHub
provider bug types: swagger inaccuracy
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 21m
Merged PRs (30d)
79

Description

**Describe the bug**
[deployment reference documentation
](https://learn.microsoft.com/en-us/azure/templates/microsoft.keyvault/vaults/accesspolicies?pivots=deployment-language-bicep) does NOT contain any information about resource naming constrains. IMO deployment reference should contain most or even all information that is needed to use given resource. As far as I know key vault documentation does not mention usage of this resource type(Microsoft.KeyVault/vaults/accessPolicies ) at all.

------

[REST API](https://learn.microsoft.com/en-us/rest/api/keyvault/keyvault/vaults/update-access-policy?tabs=HTTP#accesspolicyupdatekind) states following:

image

-----

Luckily VS code manages to display an error when non-working name is being used:
![image](https://user-images.githubusercontent.com/928458/198290212-73b4ccd6-73fa-4654-b2e4-a46cde0994cb.png)

-----
# The results:
**Looks like deployment reference documentation drops all information about name constraining.**

How much naming-related documentation is missing from deployment reference documention?
How common is this issue on other resources?
Where to report naming issues?
* e.g. portal requires some hard-coded naming but REST API spec does not mention it

Luckily, at least in this case, intellisense helps users to write working Bicep files and makes the issue less important to be fixed.

-----

Minor related issue(will be splitted on its own ticket):
* REST API does not describe operation names. To find out if `add` supports upsert, user needs to read through examples and maybe even test if given operations are idempotent or not.

Contributor guide

Open the contributing guide

Research direction

Start with the linked Microsoft.KeyVault/vaults/accessPolicies deployment reference and compare its naming information with the linked Key Vault REST API documentation. Review how the VS Code error exposes the constraint, then identify the documentation changes and reporting path needed; done means the reference clearly documents the applicable naming constraint and related guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.