Azure Policy Visual Studio Code Extension

Azure Policy enforces standards and evaluates compliance at scale for your Azure environment. This extension is to help streamline the management and authoring of Resource Manager mode policy definitions and assignments.

Overview

Azure Policy Visual Studio Code extension simplifies the experience of finding, understanding, and authoring policies by putting your policy definitions, assignments, and initiatives, and your resources, in JSON format into a convenient tree view allowing fast navigation. You are able to see aliases that apply to a resource, discover available aliases, and even evaluate your policies against a resource. You are able to quickly run a resource compliance evaluation by selecting a definition, assignment and deployed azure resource.

Note: the Azure Policy Visual Studio Code extension supports evaluation of ++Resource Manager mode++ policies only. Some namespaces also support Resource Provider mode policies, but evaluation of those types of policies is not supported by the extension at this time. We are working on an approach to support this scenario.

What's New

We have been working hard to make VSCode an indespensible tool for policy authors. With this release, we are very excited to be bringing you something that many of you have been asking for: live policy evaluation right from VSCode! Using the new Evaluation area in the lower left of the policy extension, you can select a policy definition and a resource and perform policy evaluation with a few mouse clicks.

Another major enhancement in this release is full completion lists for policy aliases. One difficulty faced by policy authors is discovering policy aliases. Previously, you had to have an instance of a given resource type containing the specific property in order to discover the alias for one of its properties or run a Powershell cmdlet from the command line. Now you can discover aliases inline while editing your policy definition. Just start typing after the "field": keywoard and and completion lists will show available matching fields, including aliases.

How to Use the Azure Policy Extension

The Azure Policy VSCode extension is a generally useful tool to help with developing policy definitions. The two primary scenarios are to view the JSON contents of a resource or a policy object, and to see the result of evaluating a policy definition against a resource.

View resources

In the top left 'Resources' tree view, under each subscription there are two folders: 'Resource Providers' and 'Resource Groups'. Under 'Resource Providers', resources are divided by resource provider such as 'Microsoft.Compute' or 'Microsoft.Network' that are registered to that subscription. This view shows all resources, including proxy resources, organized by Resource Provider namespace and resource type hierarchy. Under 'Resource Groups', resources are divided by resource group. The 'Resource Groups' view shows only tracked resources (resources that are members of a resource group). To see proxy resources, you need to browse to the resource type under the 'Resource Providers' folder.

Selecting a resource will display its JSON contents in an editor tab on the right. By default it will be opened in Preview mode, which means that when another node in the treeview is selected, the new resource contents will replace the previous contents in the same editor tab. If you want to keep a tab open to a particular resource even after you navigate away, select the Pin this resource in a tab command on the item in the treeview. If you want to save and/or edit a copy of the resource, use the Save this resource as... command on the item. Editing a resource is useful as a fast way to test policy compliance evaluation on different resource values.

View policy definitions, assignments, and initiatives

In the middle left 'Policies' tree view, under each subscription there are four folders: 'Assignments', 'Built-in Definitions', 'Custom Definitions', and 'Initiatives'. This view shows all of the policy objects for the given subscription divided by those types.

Similar to viewing resources above, select a policy item in the treeview to display its JSON contents in a tab on the right. The policy treeview items have similar commands: Pin this policy item in a tab, and Save this policy item as... for keeping the item in its tab or saving the item to a file for separate storage or editing. When you are satisfied with the contents of a policy definition, you can copy to the clipboard and paste it into the portal to create a new policy or update an existing one.

View the result of evaluating a policy against a resource

In the bottom left 'Evaluation' view, you will see a list of currently open resources and policy items. Commands within that view allow you to select a policy definition and a resource for evaluation. If the policy definition requires parameter values, you will also need to select an assignment to provide the parameter values. If the policy definition effect is DeployIfNotExists or AuditIfNotExists, you will also need to select a related resource for the existence check. After you have selected these items, run the Evaluate policy selection against resource selection command at the top right corner of the Evaluation pane to get the evaluation results.

Test local changes to policy definitions or resources

You can use Save As commands to save any policy item or resource to a local file and continue to use it for policy inner loop testing. As you make changes to a policy definition or resource, you can immediately reevaluate compliance of the resource without needing to update the policy in Azure and wait for the Azure Policy service to perform a compliance evaluation each time.

This can be particularly helpful for trying different parameter values. First save a policy assignment to a file, then use it in evaluations after manually editing it to try different values. This is also an easy way to add and remove parameter values without needing to create a new policy assignment for testing.

After your are satisfied with the operation of your policy definition, you can copy-paste it to the Azure Policy portal to update it in Azure.

Understanding evaluation results

The evaluation results contain the same JSON information that evaluations in the real service return. The main thing to look for is the "policyEvaluations" array, which normally contains 0 or 1 object. No policy evaluations means the policy didn't apply to the resource. One policy evaluation can be expected to contain an "evaluationResult" value of Compliant or NonCompliant and some details about the policy that was evaluated. The "modifiedFields" indicates which fields, if any, would be updated by the policy and "updatedRequestContent" gives the full resource as updated by the policy. The messages array is for internal debugging and can be ignored. If the evaluation fails with an error, the message field contains all available information about the failure.

Summary of Features

• View resource and policy contents
  • Select a tree view node to view the contents of a resource or policy object in a read-only tab on the right.
  • 'Save as' treeview commands to save a read-write copy of any item to a file.
  • Pin treeview commands to keep the item in its own editor tab.
• Test compliance evaluation of policy definitions against a resource
  • Evaluation pane shows currently open items.
  • Select a policy definition and a resource for evaluation.
  • Also select a policy assignment if the definition requires parameter values.
  • Also select a related resource if the definition's effect is DeployIfNotExists or AuditIfNotExists.
  • Run the Evaluate command to see evaluation results right in VSCode.
• Quick view of aliases
  • Hover over resource property or value to discover a property's alias.
• Tree view
  • View resources and policy definitions, assignments, and initiatives in hierarchical views at subscription level.
  • Search for resources and policies in the Command Palette.
• Settings to select four different filtered views for resources
  • Filter By Any Aliases: Under 'Resource Providers' show only namespaces and resource types that have published policy aliases. This is faster than filtering by existing resource, but includes empty folders for types no instances in the subscription.
  • Filter By Existing Resources: In the 'Resources' tree view show only namespaces, resource types, and resource groups that actually contain resources (no empty folders). When only this setting is enabled, opening the 'Resource Providers' folder the first time in a session requires each resource type to be queried for instances. This may take a long time depending on the number and types of resources present in the subscription.
  • Both filters combined together: This is the default setting that shows all namespaces and types with published aliases and instances in the subscription. With both filters enabled, the time to open the 'Resource Providers' folder is likely to fall between applying either filter by itself, since fewer resource types must be queried.
  • Neither of the above filters: With all filtering disabled, the 'Resource Providers' folder will open quickly, but will contain many empty folders. This may be preferrable when looking for resources of known namespace and type.

Notes

• After installing the extension, it is critical that you reload. There are occasional reports of evaluation failures, or other partial failures in the extension that are corrected after uninstalling and reinstalling. If you encounter issues like this and reinstalling doesn't correct the issue, try these steps:
  • Uninstall the extension
  • Quit VSCode (all instances)
  • Make sure there are no running Server or PolicyLanguageServer processes
  • Launch VSCode
  • Install the extension
  • Reload when prompted or quit and re-launch VSCode if not prompted
  • Retry the extension
• This extension only displays the objects shown in the tree view, it does not support creating objects or updating existing objects in Azure. In some cases, the contents displayed can be used in other Azure interfaces to create or modify resources. For example, policy definition contents can be pasted into the Azure portal or a command line with some modification to create or update existing policies.
• Treeview nodes that refer to a resource will open in a tab when selected. Others are structural and can be expanded or closed. Below the 'Resource Providers' folder, many nodes do both, since they represent a resource, but may also contain sub types.
• If you haven’t previously signed into Azure from Visual Studio Code, you will need to sign in. After signing in, you may also filter by subscriptions. To sign in, select 'View' -> 'Command Palette' and select 'Azure: Sign in'. To filter subscriptions select 'Azure: Select Subscriptions' command.
• The Evaluation pane tracks open tabs. While navigating either treeview, when you select an item in the evaluation area for evaluation, it is also pinned, so navigating to a different tree node won't close it.
• Sometimes closing a tab will not remove it from the evaluation area immediately. This is because VSCode keeps the document open (but hidden) for a while even after all tabs have closed. This behavior cannot be overridden from an extension.

Compatibility

This extension requires VSCode build 1.52.0 or newer. Supported operating systems (architectures):

• Windows (x64)
• macOS (x64)
• Linux (x64)

however, see Known issues below for current limitations.

Related links

Visual Studio Code extension documentation: https://docs.microsoft.com/azure/governance/policy/how-to/extension-for-vscode

What we're working on...

• Policy structure syntax highlighting
• Policy and alias validation
• Additional evaluation features
  • Evaluate initiatives
  • Evaluate policies against resource groups

Ideas, feature requests and bugs: Email policy-vscode@microsoft.com! We are open to all ideas and we want to get rid of bugs!

Release History

See the changelog for this extension

Telemetry

Visual Studio Code collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you don’t wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. Learn more in our FAQ.

License

This extension is licensed under the MIT license. By downloading and using the Visual Studio Azure Policy extension and its related components, you agree to the product license terms and privacy statement.