Sample - Approved virtual machine images

This policy requires that only approved custom images are deployed in your environment. You specify an array of approved image IDs.

You can deploy this sample policy using:

If you don't have an Azure subscription, create a free account before you begin.

Sample policy

Policy definition

The complete composed JSON policy definition, used by the REST API, 'Deploy to Azure' buttons, and manually in the portal.

{
    "type": "Microsoft.Authorization/policyDefinitions",
    "name": "allowed-custom-images", 
    "properties": {
        "displayName": "Approved VM images",
        "description": "This policy governs the approved VM images",
        "parameters": {
            "imageIds": {
                "type": "array",
                "metadata": {
                    "description": "The list of approved VM images. Example values: '/subscriptions/<subscriptionId>/resourceGroups/YourResourceGroup/providers/Microsoft.Compute/images/ContosoStdImage' or /Subscriptions/<subscriptionId>/Providers/Microsoft.Compute/Locations/centralus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2016.127.20180510'",
                    "displayName": "Approved VM images"
                }
            }
        },
        "policyRule": {
            "if": {
                "allOf": [
                    {
                        "field": "type",
                        "equals": "Microsoft.Compute/virtualMachines"
                    },
                    {
                        "not": {
                            "field": "Microsoft.Compute/imageId",
                            "in": "[parameters('imageIds')]"
                        }
                    }
                ]
            },
            "then": {
                "effect": "deny"
            }
        }
    }   
}

Note

If manually creating a policy in the portal, use the properties.parameters and properties.policyRule portions of the above. Wrap the two sections together with curly braces {} to make it valid JSON.

Policy rules

The JSON defining the rules of the policy, used by Azure CLI and Azure PowerShell.

{
    "if": {
        "allOf": [
            {
                "field": "type",
                "equals": "Microsoft.Compute/virtualMachines"
            },
            {
                "not": {
                    "field": "Microsoft.Compute/imageId",
                    "in": "[parameters('imageIds')]"
                }
            }
        ]
    },
    "then": {
        "effect": "deny"
    }
}

Policy parameters

The JSON defining the policy parameters, used by Azure CLI and Azure PowerShell.

{
    "imageIds": {
        "type": "array",
        "metadata": {
            "description": "The list of approved VM images",
            "displayName": "Approved VM images"
        }
    }
}

Parameters

Name Type Field Description
imageIds Array Microsoft.Compute/imageIds The list of approved VM images

When creating an assignment via PowerShell or Azure CLI, the parameter values can be passed as JSON in either a string or via a file using -PolicyParameter (PowerShell) or --params (Azure CLI). PowerShell also supports -PolicyParameterObject which requires passing the cmdlet a Name/Value hashtable where Name is the parameter name and Value is the single value or array of values being passed during assignment.

In this example parameter, only the ContosoStdImage in resource group YourResourceGroup or the May 2018 image version of Windows Server 2016 Datacenter located in 'Central US' will be allowed.

{
    "imageIds": {
        "value": [
            "/subscriptions/<subscriptionId>/resourceGroups/YourResourceGroup/providers/Microsoft.Compute/images/ContosoStdImage",
            "/Subscriptions/<subscriptionId>/Providers/Microsoft.Compute/Locations/centralus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2016.127.20180510"
        ]
    }
}

Azure portal

Deploy the Policy sample to Azure Deploy the Policy sample to Azure Gov

Azure PowerShell

This sample requires Azure PowerShell. Run Get-Module -ListAvailable Az to find the version. If you need to install or upgrade, see Install Azure PowerShell module.

Run the Connect-AzAccount cmdlet to connect to Azure.

Deploy with Azure PowerShell

# Create the Policy Definition (Subscription scope)
$definition = New-AzPolicyDefinition -Name 'allowed-custom-images' -DisplayName 'Approved VM images' -description 'This policy governs the approved VM images' -Policy 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/Compute/allowed-custom-images/azurepolicy.rules.json' -Parameter 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/Compute/allowed-custom-images/azurepolicy.parameters.json' -Mode All

# Set the scope to a resource group; may also be a resource, subscription, or management group
$scope = Get-AzResourceGroup -Name 'YourResourceGroup'

# Set the Policy Parameter (JSON format)
$policyparam = '{ "imageIds": { "value": [ "/subscriptions/<subscriptionId>/resourceGroups/YourResourceGroup/providers/Microsoft.Compute/images/ContosoStdImage", "/Subscriptions/<subscriptionId>/Providers/Microsoft.Compute/Locations/centralus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2016.127.20180510" ] } }'

# Create the Policy Assignment
$assignment = New-AzPolicyAssignment -Name 'allowed-custom-images-assignment' -DisplayName 'Approved VM images Assignment' -Scope $scope.ResourceId -PolicyDefinition $definition -PolicyParameter $policyparam

Remove with Azure PowerShell

Run the following commands to remove the previous assignment and definition:

# Remove the Policy Assignment
Remove-AzPolicyAssignment -Id $assignment.ResourceId

# Remove the Policy Definition
Remove-AzPolicyDefinition -Id $definition.ResourceId

Azure PowerShell explanation

The deploy and remove scripts use the following commands. Each command in the following table links to command-specific documentation:

Command Notes
New-AzPolicyDefinition Creates a new Azure Policy definition.
Get-AzResourceGroup Gets a single resource group.
New-AzPolicyAssignment Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
Remove-AzPolicyAssignment Removes an existing Azure Policy assignment.
Remove-AzPolicyDefinition Removes an existing Azure Policy definition.

Azure CLI

To run this sample, install the latest version of the Azure CLI. To start, run az login to create a connection with Azure.

Samples for the Azure CLI are written for the bash shell. To run this sample in Windows PowerShell or Command Prompt, you may need to change elements of the script.

Deploy with Azure CLI

# Create the Policy Definition (Subscription scope)
definition=$(az policy definition create --name 'allowed-custom-images' --display-name 'Approved VM images' --description 'This policy governs the approved VM images' --rules 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/Compute/allowed-custom-images/azurepolicy.rules.json' --params 'https://raw.githubusercontent.com/Azure/azure-policy/master/samples/Compute/allowed-custom-images/azurepolicy.parameters.json' --mode All)

# Set the scope to a resource group; may also be a resource, subscription, or management group
scope=$(az group show --name 'YourResourceGroup')

# Set the Policy Parameter (JSON format)
policyparam='{ "imageIds": { "value": [ "/subscriptions/<subscriptionId>/resourceGroups/YourResourceGroup/providers/Microsoft.Compute/images/ContosoStdImage", "/Subscriptions/<subscriptionId>/Providers/Microsoft.Compute/Locations/centralus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2016.127.20180510" ] } }'

# Create the Policy Assignment
assignment=$(az policy assignment create --name 'allowed-custom-images-assignment' --display-name 'Approved VM images Assignment' --scope `echo $scope | jq '.id' -r` --policy `echo $definition | jq '.name' -r` --params "$policyparam")

Remove with Azure CLI

Run the following commands to remove the previous assignment and definition:

# Remove the Policy Assignment
az policy assignment delete --name `echo $assignment | jq '.name' -r`

# Remove the Policy Definition
az policy definition delete --name `echo $definition | jq '.name' -r`

Azure CLI explanation

Command Notes
az policy definition create Creates a new Azure Policy definition.
az group show Gets a single resource group.
az policy assignment create Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
az policy assignment delete Removes an existing Azure Policy assignment.
az policy definition delete Removes an existing Azure Policy definition.

REST API

There are several tools that can be used to interact with the Resource Manager REST API such as ARMClient or PowerShell. An example of calling REST API from PowerShell can be found in the Aliases section of Policy definition structure.

Deploy with REST API

  • Create the Policy Definition (Subscription scope). Use the policy definition JSON for the Request Body.

    PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/allowed-custom-images?api-version=2016-12-01
    
  • Create the Policy Assignment (Resource Group scope)

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/YourResourceGroup/providers/Microsoft.Authorization/policyAssignments/allowed-custom-images-assignment?api-version=2017-06-01-preview
    

    Use the following JSON example for the Request Body:

    {
        "properties": {
            "displayName": "Approved VM images Assignment",
            "policyDefinitionId": "/subscriptions/<subscriptionId>/providers/Microsoft.Authorization/policyDefinitions/allowed-custom-images",
            "parameters": {
                "imageIds": {
                    "value": [
                        "/subscriptions/<subscriptionId>/resourceGroups/YourResourceGroup/providers/Microsoft.Compute/images/ContosoStdImage",
                        "/Subscriptions/<subscriptionId>/Providers/Microsoft.Compute/Locations/centralus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2016.127.20180510"
                    ]
                }
            }
        }
    }
    

Remove with REST API

  • Remove the Policy Assignment

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyAssignments/allowed-custom-images-assignment?api-version=2017-06-01-preview
    
  • Remove the Policy Definition

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/allowed-custom-images?api-version=2016-12-01
    

REST API explanation

Service Group Operation Notes
Resource Management Policy Definitions Create Creates a new Azure Policy definition at a subscription. Alternative: Create at management group
Resource Management Policy Assignments Create Creates a new Azure Policy assignment. In this example, we provide it a definition, but it can also take an initiative.
Resource Management Policy Assignments Delete Removes an existing Azure Policy assignment.
Resource Management Policy Definitions Delete Removes an existing Azure Policy definition. Alternative: Delete at management group

Next steps