Início Rápido: Criar uma atribuição de política para identificar recursos sem conformidade com a API REST

Artigo
04/09/2024

A primeira etapa para compreender a conformidade no Azure é identificar o status de seus recursos. Nesse início rápido, você irá criar uma atribuição de política para identificar recursos não compatíveis usando a API REST. A política é atribuída a um grupo de recursos e audita as máquinas virtuais que não usam discos gerenciados. Depois de criar a atribuição de política, você identifica máquinas virtuais não compatíveis.

Este guia usa a API REST para criar uma atribuição de política e para identificar recursos sem conformidade em seu ambiente do Azure. Os exemplos neste artigo usam o PowerShell e os comandos az rest da CLI do Azure. Você também pode executar os comandos az rest a partir de um shell Bash, como o Git Bash.

Pré-requisitos

Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.
Versão mais recente do PowerShell ou um shell Bash, como o Git Bash.
Versão mais recente da CLI do Azure.
Visual Studio Code.
Um grupo de recursos com pelo menos uma máquina virtual que não usa discos gerenciados.

Revisar a sintaxe da API REST

Há dois elementos para executar comandos da API REST: o URI da API REST e o corpo da solicitação. Para obter informações, acesse Atribuições de Política – Criar.

O exemplo a seguir mostra a sintaxe do URI da API REST para criar uma definição de política.

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/policyAssignments/{policyAssignmentName}?api-version=2023-04-01

scope: um escopo determina em quais recursos ou agrupamento de recursos a atribuição de política é imposta. Ele pode variar de um grupo de gerenciamento a um recurso individual. Substitua {scope} por um dos seguintes padrões:
- Grupo de gerenciamento: /providers/Microsoft.Management/managementGroups/{managementGroup}
- Assinatura: /subscriptions/{subscriptionId}
- Grupo de recursos: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}
- Recurso: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/[{parentResourcePath}/]{resourceType}/{resourceName}
policyAssignmentName: cria o nome da atribuição de política da sua atribuição. O nome está incluído na propriedade policyAssignmentId da atribuição de política.

O exemplo a seguir é o JSON para criar um arquivo de corpo da solicitação.

{
  "properties": {
    "displayName": "",
    "description": "",
    "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/11111111-1111-1111-1111-111111111111",
    "nonComplianceMessages": [
      {
        "message": ""
      }
    ]
  }
}

displayName: nome de exibição da atribuição de política.
description: pode ser usado para adicionar contexto sobre a atribuição de política.
policyDefinitionId: a ID da definição de política que criará a atribuição.
nonComplianceMessages: define a mensagem a ser usada quando um recurso for avaliado como não compatível. Para obter mais informações, confira Mensagens de não conformidade de atribuição.

Conectar-se ao Azure

Em uma sessão de terminal do Visual Studio Code, conecte-se ao Azure. Se você tiver mais de uma assinatura, execute os comandos para definir o contexto para sua assinatura. Substitua <subscriptionID> por sua ID da assinatura do Azure.

az login

# Run these commands if you have multiple subscriptions
az account list --output table
az account set --subscription <subscriptionID>

Use az login mesmo se você estiver usando o PowerShell porque os exemplos usam comandos az rest da CLI do Azure.

Criar uma atribuição de política

Neste exemplo, você cria uma atribuição de política e atribui a definição Auditar VMs que não usam discos gerenciados.

Um corpo da solicitação é necessário para criar a atribuição. Salve o JSON a seguir em um arquivo chamado request-body.json.

{
  "properties": {
    "displayName": "Audit VM managed disks",
    "description": "Policy assignment to resource group scope created with REST API",
    "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
    "nonComplianceMessages": [
      {
        "message": "Virtual machines should use managed disks"
      }
    ]
  }
}

Para criar sua atribuição de política em um escopo de grupo de recursos existente, use o URI da API REST a seguir com um arquivo para o corpo da solicitação. Substitua {subscriptionId} e {resourceGroupName} por seus valores. O comando exibe a saída JSON no shell.

az rest --method put --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01 --body `@request-body.json

No PowerShell, o acento grave (`) é necessário para escapar o at sign (@) para especificar um nome de arquivo. Em um shell Bash, como o Git Bash, omita o acento grave.

Para obter informações, acesse Atribuições de Política – Criar.

Identificar recursos fora de conformidade

O estado de conformidade de uma nova atribuição de política leva alguns minutos para se tornar ativo e fornecer resultados sobre o estado da política. Você usa a API REST para exibir os recursos não compatíveis para essa atribuição de política e a saída está em JSON.

Para identificar recursos sem conformidade, execute o comando a seguir. Substitua {subscriptionId} e {resourceGroupName} pelos valores usados quando você criou a atribuição de política.

az rest --method post --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01 --uri-parameters `$filter="complianceState eq 'NonCompliant' and PolicyAssignmentName eq 'audit-vm-managed-disks'"

As consultas filter para recursos que são avaliados como não compatíveis com a definição de política chamada audit-vm-managed-disks que você criou com a atribuição de política. Novamente, observe que o acento grave é usado para escapar o sinal de cifrão ($) no filtro. Para um cliente Bash, uma barra invertida (\) é um caractere de escape comum.

Seus resultados devem se parecer com o exemplo a seguir:

{
  "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest",
  "@odata.count": 1,
  "@odata.nextLink": null,
  "value": [
    {
      "@odata.context": "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyStates/$metadata#latest/$entity",
      "@odata.id": null,
      "complianceReasonCode": "",
      "complianceState": "NonCompliant",
      "effectiveParameters": "",
      "isCompliant": false,
      "managementGroupIds": "",
      "policyAssignmentId": "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.authorization/policyassignments/audit-vm-managed-disks",
      "policyAssignmentName": "audit-vm-managed-disks",
      "policyAssignmentOwner": "tbd",
      "policyAssignmentParameters": "",
      "policyAssignmentScope": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
      "policyAssignmentVersion": "",
      "policyDefinitionAction": "audit",
      "policyDefinitionCategory": "tbd",
      "policyDefinitionGroupNames": [
        ""
      ],
      "policyDefinitionId": "/providers/microsoft.authorization/policydefinitions/06a78e20-9358-41c9-923c-fb736d382a4d",
      "policyDefinitionName": "06a78e20-9358-41c9-923c-fb736d382a4d",
      "policyDefinitionReferenceId": "",
      "policyDefinitionVersion": "1.0.0",
      "policySetDefinitionCategory": "",
      "policySetDefinitionId": "",
      "policySetDefinitionName": "",
      "policySetDefinitionOwner": "",
      "policySetDefinitionParameters": "",
      "policySetDefinitionVersion": "",
      "resourceGroup": "{resourceGroupName}",
      "resourceId": "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/microsoft.compute/virtualmachines/{vmName}>",
      "resourceLocation": "westus3",
      "resourceTags": "tbd",
      "resourceType": "Microsoft.Compute/virtualMachines",
      "subscriptionId": "{subscriptionId}",
      "timestamp": "2024-03-26T02:19:28.3720191Z"
    }
  ]
}

Para obter mais informações, vá para Estados de política – Listar resultados da consulta para o grupo de recursos.

Limpar os recursos

Para remover a atribuição de política, use o comando a seguir. Substitua {subscriptionId} e {resourceGroupName} pelos valores usados quando você criou a atribuição de política. O comando exibe a saída JSON no shell.

az rest --method delete --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01

Você pode verificar que a atribuição de política foi excluída com o seguinte comando. Uma mensagem é exibida em seu shell.

az rest --method get --uri https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/policyAssignments/audit-vm-managed-disks?api-version=2023-04-01

The policy assignment 'audit-vm-managed-disks' is not found.

Para obter mais informações, acesse Atribuições de Política – Excluir e Atribuições de Política – Obter.

Próximas etapas

Neste guia de início rápido, você atribuiu uma definição de política para identificar recursos sem conformidade em seu ambiente do Azure.

Para saber mais sobre como atribuir políticas que validam a conformidade dos recursos, prossiga para o tutorial.

Tutorial: Criar e gerenciar políticas para impor a conformidade