Ways of improving readability in AzOps repositories

[Xitric]

The challenge

We have noticed that the readability of large AzOps repositories deteriorates to the point where unfamiliar developers feel overwhelmed. Non-technical and semi-technical stakeholders in our team similarly find that the transparency of the repository and its files is sub-optimal. Let me explain.

Hard to understand the scope of directories

The way that directories are named in the repository makes it hard to determine what is a management group and what is a subscription. This effectively requires locating the microsoft.subscription_subscriptions-<guid>.json or microsoft.management_managementgroups-<guid>.json files, which can become hidden as the number of policies, role definitions, and module deployments in that scope grows.

Furthermore, the names of the files are rather verbose, causing the navigation tree to resemble a wall-of-text, thus overwhelming unfamiliar developers.

Lack of transparency of role assignments

Role assignments, when pulled from Azure via the Pull pipeline, are named as microsoft.authorization_roleassignments-<name>.json, where <name> is a GUID. This does not really tell the reader anything about what the role assignment represents. Furthermore, opening the file reveals limited additional value:

• name: A non-human-readable GUID
• principalId: A non-human-readable object ID
• roleDefinitionId: A non-human-readable resource ID
• description: A properly readable and understandable explanation of the role assignment

As such, the reader cannot at a glance understand to whom the role assignment applies, or what privileges it provides. Only by browsing the contents of every role assignment template there is a chance that one might understand what is going on, but this relies on the quality of the free-form description field.

What can be done about this?

We have considered looking into building an extension for VS Code that can provide a context-aware navigation tree, which is able to render directories and files in a custom manner.

For instance, standardized icons could be used to enhance the visibility of management groups, subscriptions, and resource groups.

Furthermore, by rendering role assignments using display names of role definitions and principals, and perhaps even grouping them by role definition, it becomes easier to understand the role assignments being defined at a glance. Tooltips could be used to show descriptions without having to open the files.

And much more...

We would like to hear what others do to approach this challenge, as well as alternative ideas for improving the readability of large AzOps repositories!

[daltondhcp]

Hi Xitric,

Really appreciate you starting this dialogue on improving readability in AzOps repositories. Part of this is that we do little to enhance what is returned from ARM for the autogenerated templates.

There's definitely room for improvement, and your VS Code extension idea is a step in the right direction. Do you think that allowing prefix/suffix in the folder names would simplify navigation?

Curious to hear what others think and any other suggestions for making these repositories more user-friendly!

[Xitric]

I think that prefixes on directory names could definitely improve readability without needing extra tooling.

However, at least for my team, it is probably the role assignment templates that cause the most confusion. We perform pretty much all access management via AzOps and the Push pipeline, and being able to easily identify which template assigns which role to which groups or principals is highly valuable to us. I understand that this can be difficult to improve much, since role assignment names are GUIDs.

Do you think that it would be viable to move in the direction of enriching the role assignment templates further, or would it be preferable to stick with the existing resource and object IDs, and enrich the files via extensions instead? One option we are considering is using CodeLens in VS Code to provide contextual information on roleDefinitionId and principalId among other things. If the role definition is custom and located elsewhere in the repository, we could link to the role definition template directly. For built-in roles, we could link to something like https://www.azadvertizer.net/. Of course, this is a lot of work, so anything simpler that could make role assignment templates easier to interpret is valuable as well.

[daltondhcp]

For role assignments, we actually used to rely on Get-RoleAssignment that makes a supplementary Graph call to enrich the roleAssignments with displayNames etc. To improve performance 2-3X, we made a call to do native ARM GETs instead, which doesn't contain this data. We could certainly take a look at this again, as an option.

[Xitric]

Display names would be quite valuable in role assignment templates. Would this be display names for only the role definition, or for the principal as well?

We have experimented a bit with contextual visualization in VS Code, and I think we are settling on a tree view such as this for displaying role assignments at each scope, complete with display names and descriptions:

• my-management-group
  • my-subscription
    • Owner (Grants full access to manage all resources...)
      • /subscriptions/id
        • principal-id-a (Enables principal A to...)
        • principal-id-b (Enables principal B to...)
        • principal-id-c (Enables principal C to...)
    • Log Analytics Reader (Log Analytics Reader can view and search...)
      • /subscriptions/id
        • principal-id (Enables principal A to...)

In each management group, subscription, or resource group, we are effectively grouping the role assignment templates by role definition, then by scope, and lastly we write out each principal to which the role is assigned. This enables us to quickly review, for instance, all Owner assignments for a specific subscription. For resource groups, scopes might cover individual resources in addition to the resource group itself.

• my-subscription
  • my-resource-group
    • Owner (Grants full access to manage all resources...)
      • my-resource-group
        • principal-id-a (Enables principal A to...)
    • AcrPull (acr pull)
      • Microsoft.ContainerRegistry/registries/my-registry
        • principal-id-a (Enables developers to pull images from the registry.)

In addition to this, we experimented with adding better visualization of the directories in an AzOps repository using icons, which is similar to your proposal of using directory prefixes. Unfortunately I cannot share any screenshots since we don't yet have permission to use the Azure icons outside of documentation purposes. But we have so far implemented a POC of a tree view provider in a VS Code extension that can visualize the contents of an AzOps repository as explained above.

I think that we will continue experimenting a bit to see what features bring the most value to us.