Tutorial: Rotear eventos de alteração de estado da política para a Grade de Eventos com a CLI do Azure

  • Artigo

Neste artigo, você aprende a configurar assinaturas de evento do Azure Policy para enviar eventos de alteração de estado de política a um ponto de extremidade da Web. Usuários do Azure Policy podem assinar eventos emitidos quando ocorrem alterações de estado da política em recursos. Esses eventos podem disparar webhooks, Azure Functions, Filas do Armazenamento do Azure ou qualquer outro manipulador de eventos que seja compatível com a Grade de Eventos do Azure. Normalmente, você envia eventos para um ponto de extremidade que processa os dados de evento e realiza ações. No entanto, para simplificar este tutorial, você enviará os eventos para um aplicativo Web que coleta e exibe as mensagens.

Pré-requisitos

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

  • Este guia de início rápido exige que você execute a CLI do Azure versão 2.0.76 ou posterior. Para saber qual é a versão, execute az --version. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Button to launch Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Screenshot that shows the Cloud Shell button in the Azure portal

Para usar o Azure Cloud Shell:

  1. Inicie o Cloud Shell.

  2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.

  3. Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.

  4. Pressione Enter para executar o código ou comando.

Criar um grupo de recursos

Os tópicos de Grade de Eventos são recursos do Azure e devem ser colocados em um grupo de recursos do Azure. O grupo de recursos do Azure é uma coleção lógica na qual os recursos do Azure são implantados e gerenciados.

Crie um grupo de recursos com o comando az group create.

O exemplo a seguir cria um grupo de recursos chamado <resource_group_name> na localização westus. Substitua <resource_group_name> por um nome exclusivo para o grupo de recursos.

# Log in first with az login if you're not using Cloud Shell

az group create --name <resource_group_name> --location westus

Criar um tópico do sistema da Grade de Eventos

Agora que temos um grupo de recursos, criamos um tópico do sistema. Um tópico do sistema na Grade de Eventos representa um ou mais eventos publicados pelos serviços do Azure, como o Azure Policy e os Hubs de Eventos do Azure. Este tópico do sistema usa o tipo de tópico Microsoft.PolicyInsights.PolicyStates para alterações de estado do Azure Policy.

Primeiro, você precisará registrar os RPs (provedores de recursos) PolicyInsights e EventGrid no escopo de gerenciamento apropriado. Enquanto o portal do Azure registra automaticamente todos os RPs invocados pela primeira vez, a CLI do Azure não o faz.

# Log in first with az login if you're not using Cloud Shell

# Register the required RPs at the management group scope
az provider register --namespace Microsoft.PolicyInsights -m <managementGroupId>
az provider register --namespace Microsoft.EventGrid -m <managementGroupId>

# Alternatively, register the required RPs at the subscription scope (defaults to current subscription context)
az provider register --namespace Microsoft.PolicyInsights
az provider register --namespace Microsoft.EventGrid

Substitua <subscriptionId> no parâmetro scope pela ID de sua assinatura e <resource_group_name> no parâmetro resource-group pelo grupo de recursos criado anteriormente.

az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/subscriptions/<subscriptionId>" --resource-group "<resource_group_name>"

Se o tópico do sistema da Grade de Eventos for aplicado ao escopo do grupo de gerenciamento, a sintaxe do parâmetro --source da CLI do Azure será um pouco diferente. Veja um exemplo:

az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/tenants/<tenantID>/providers/Microsoft.Management/managementGroups/<management_group_name>" --resource-group "<resource_group_name>"

Criar um ponto de extremidade de mensagem

Antes de assinar o tópico, vamos criar o ponto de extremidade para a mensagem do evento. Normalmente, o ponto de extremidade executa ações com base nos dados de evento. Para simplificar este início rápido, você implanta um aplicativo Web criado previamente que exibe as mensagens de eventos. A solução implantada inclui um plano do Serviço de Aplicativo, um aplicativo Web do Aplicativo do Serviço de e o código-fonte do GitHub.

Substitua <your-site-name> por um nome exclusivo para o aplicativo Web. O nome do aplicativo Web deve ser exclusivo, pois é parte de uma entrada DNS.

# Log in first with az login if you're not using Cloud Shell

az deployment group create \
  --resource-group <resource_group_name> \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=<your-site-name> hostingPlanName=viewerhost

A implantação pode levar alguns minutos para ser concluída. Depois que a implantação for bem-sucedida, exiba seu aplicativo Web para garantir que ele esteja em execução. Em um navegador da Web, navegue até: https://<your-site-name>.azurewebsites.net

Você deve ver o site sem mensagens exibidas no momento.

Assinar o tópico do sistema

Assine um tópico para indicar à Grade de Eventos quais eventos você deseja acompanhar e para onde enviar esses eventos. O exemplo a seguir assina o tópico do sistema que você criou e transmite a URL do aplicativo Web como o ponto de extremidade para receber notificação de eventos. Substitua <event_subscription_name> por um nome para a assinatura de evento. Em <resource_group_name> e <your-site-name>, use os valores criados anteriormente.

O ponto de extremidade para seu aplicativo Web deve incluir o sufixo /api/updates/.

# Log in first with az login if you're not using Cloud Shell

# Create the subscription
az eventgrid system-topic event-subscription create \
  --name <event_subscription_name> \
  --resource-group <resource_group_name> \
  --system-topic-name PolicyStateChanges \
  --endpoint https://<your-site-name>.azurewebsites.net/api/updates

Exiba novamente o seu aplicativo Web e observe que um evento de validação de assinatura foi enviado a ele. Selecione o ícone de olho para expandir os dados de evento. A Grade de Eventos envia o evento de validação de modo que o ponto de extremidade possa verificar se ele deseja receber os dados de evento. O aplicativo Web inclui o código para validar a assinatura.

Screenshot of the Event Grid subscription validation event in the pre-built web app.

Criar uma atribuição de política

Neste início rápido, você cria uma atribuição de política e atribui a definição Rxigir uma marca em grupos de recursos. Essa definição de política identifica grupos de recursos que não têm a marca configurada durante a atribuição de política.

Execute o seguinte comando para criar uma atribuição de política com escopo para o grupo de recursos criado para manter o tópico da Grade de Eventos:

# Log in first with az login if you're not using Cloud Shell

az policy assignment create --name 'requiredtags-events' --display-name 'Require tag on RG' --scope '<resourceGroupScope>' --policy '<policy definition ID>' --params '{ \"tagName\": { \"value\": \"EventTest\" } }'

O comando anterior usa as seguintes informações:

  • Nome - O nome real da atribuição. Neste exemplo, foi usado requiredtags-events.
  • DisplayName - O nome de exibição da atribuição de política. Nesse caso, você está usando Exigir marca no RG.
  • Escopo: um escopo determina em quais recursos ou agrupamento de recursos a atribuição de política é imposta. Pode variar de uma assinatura a grupos de recursos. Substitua o <escopo> pelo nome do seu grupo de recursos. O formato do escopo de um grupo de recursos é /subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>.
  • Política: a ID de definição de política, com base naquela que você está usando para criar a atribuição. Nesse caso, a ID da definição de política Exigir uma marca em grupos de recursos. Para obter a ID de definição da política, execute este comando: az policy definition list --query "[?displayName=='Require a tag on resource groups']"

Depois de criar a atribuição de política, aguarde a exibição de uma notificação de evento Microsoft.PolicyInsights.PolicyStateCreated no aplicativo Web. O grupo de recursos que criamos mostra um valor data.complianceState de NonCompliant para iniciar.

Screenshot of the Event Grid subscription Policy State Created event for the resource group in the pre-built web app.

Observação

Se o grupo de recursos herdar outras atribuições de política da assinatura ou da hierarquia do grupo de gerenciamento, eventos para cada uma também serão exibidos. Confirme se o evento é referente à atribuição neste tutorial avaliando a propriedade data.policyDefinitionId.

Disparar uma alteração no grupo de recursos

Para tornar o grupo de recursos compatível, uma marca com o nome EventTest é necessária. Adicione a marca ao grupo de recursos com o seguinte comando substituindo <subscriptionId> pela sua ID de assinatura e <resourceGroup> pelo nome do grupo de recursos:

# Log in first with az login if you're not using Cloud Shell

az tag create --resource-id '/subscriptions/<SubscriptionID>/resourceGroups/<resourceGroup>' --tags EventTest=true

Depois de adicionar a marca necessária ao grupo de recursos, aguarde até que uma notificação de evento Microsoft.PolicyInsights.PolicyStateChanged apareça no aplicativo Web. Expanda o evento e o valor data.complianceState agora mostra Compliant.

Solução de problemas

Se você vir um erro semelhante a um dos seguintes, verifique se registrou ambos os provedores de recursos no escopo que você está assinando (grupo de gerenciamento ou assinatura):

  • Deployment has failed with the following error: {"code":"Publisher Notification Error","message":"Failed to enable publisher notifications.","details":[{"code":"Publisher Provider Error","message":"GET request for <uri> failed with status code: Forbidden, code: AuthorizationFailed and message: The client '<identifier>' with object id '<identifier>' does not have authorization to perform action 'microsoft.policyinsights/eventGridFilters/read' over scope '<scope>/providers/microsoft.policyinsights/eventGridFilters/_default' or the scope is invalid. If access was recently granted, please refresh your credentials.."}]}
  • Deployment has failed with the following error: {'code':'Publisher Notification Error','message':'Failed to enable publisher notifications.','details':[{'code':'ApiVersionNotSupported','message':'Event Grid notifications are currently not supported by microsoft.policyinsights in global. Try re-registering Microsoft.EventGrid provider if this is your first event subscription in this region.'}]}

Limpar recursos

Se você planeja continuar trabalhando com esse aplicativo Web e essa assinatura de evento do Azure Policy, não limpe os recursos criados neste artigo. Caso contrário, use os comandos a seguir para excluir os recursos criados neste artigo.

Substitua <resource_group_name> pelo recurso de grupo criado acima.

az group delete --name <resource_group_name>

Próximas etapas

Agora que você sabe como criar tópicos e assinaturas de eventos para o Azure Policy, saiba mais sobre os eventos do alteração do estado da política e como a Grade de Eventos pode ajudar você: