BUG: roleDefinitions() documentation does not contain exact information about displayName usage
- Dominant language
- Bicep
- Stars
- 3.6k
- Forks
- 830
- Avg merge
- 1d 21m
- Merged PRs (30d)
- 79
Description
**Bicep version**
N/A: Documentation bug
**Describe the bug**
Current documentation for `roleDefinitions()` is following:
```
Returns information about the specified role definition, including id and roleDefinitionId. It's a name-based helper for Azure RBAC role assignments. Instead of requiring you to hardcode the GUID of a built-in role definition (like Contributor, Reader, and others), it lets you provide the built-in role’s display name, and the function resolves the corresponding role definition information at deployment time.
Parameter | Required | Type | Description
-- | -- | -- | --
roleName | Yes | string | The display name of the role definition.
```
Documentation does mention how role changes are handled (on ARM backend):
* displayname changes
* role removals
-----
Azadvertizer lists 65(looks like it does not list all displayname changes) historical displayname changes and ATM there is 20 roles with preview suffix that will be renamed sooner or later
Examples of displayname changes:
```
New DisplayName: 'Azure Kubernetes Application Network Contributor Role'
Old DisplayName: 'Managed Mesh for AKS Contributor Role'
New DisplayName: 'Key Vault Reader'
Old DisplayName: 'Key Vault Reader (preview)'
New DisplayName: 'Azure Device Registry Onboarding'
Old DisplayName: 'Azure Device Registry Onboarding Role'
New DisplayName: 'Defender Serverless Scanner'
Old DisplayName: 'Agentless scanning for Serverless Scanner Service Role'
New DisplayName: 'Azure Red Hat OpenShift Image Registry Operator'
Old DisplayName: 'Azure RedHat OpenShift Image Registry Operator Role'
--
```
Contributor guide
Research direction
Start from the current roleDefinitions() documentation and review the documented handling of Azure RBAC role display-name changes and removals. Update the parameter description and surrounding explanation so the displayName behavior and its limitations are exact, including the examples raised in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure
- Domain
- authorization, cloud, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100