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

Artigo
03/10/2024

Neste artigo, você aprenderá a configurar assinaturas de eventos do Azure Policy para enviar eventos de alteração de estado de política para um ponto de extremidade da Web. Os utilizadores do Azure Policy podem subscrever eventos emitidos quando ocorrem alterações no estado da política nos recursos. Esses eventos podem acionar ganchos da Web, Azure Functions, Filas de Armazenamento do Azure ou qualquer outro manipulador de eventos suportado pela Grade de Eventos do Azure. Normalmente, envia eventos para um ponto final que processa os dados de eventos e efetua ações. No entanto, para simplificar este tutorial, envie os eventos para um aplicativo Web que coleta e exibe as mensagens.

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Este início rápido requer que você execute a CLI do Azure versão 2.0.76 ou posterior. Para localizar a versão, execute az --version. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

Azure Cloud Shell

O Azure aloja o Azure Cloud Shell, um ambiente de shell interativo que pode utilizar através do seu browser. Pode utilizar o Bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. Você pode usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada em seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Ligação
Selecione Experimentar no canto superior direito de um código ou bloco de comandos. Selecionar Experimentar não copia automaticamente o código ou comando para o Cloud Shell.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser.
Selecione o botão Cloud Shell na barra de menus, na parte direita do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou comando.

Criar um grupo de recursos

Os tópicos do Event Grid são recursos do Azure e têm de ser colocados num grupo de recursos do Azure. Um grupo de recursos é uma coleção lógica na qual os recursos do Azure são implementados e geridos.

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

O exemplo a seguir cria um grupo de recursos nomeado <resource_group_name> no local westus. Substitua <resource_group_name> por um nome exclusivo para o seu 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 de 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 a Política do Azure e os Hubs de Eventos do Azure. Este tópico do sistema usa o tipo de tópico para alterações de estado da Microsoft.PolicyInsights.PolicyStates Política do Azure.

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

# 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

Em seguida, substitua <subscriptionId> no parâmetro scope pela ID da 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 de Grade de Eventos for aplicado ao escopo do grupo de gerenciamento, a sintaxe do parâmetro da CLI --source do Azure será um pouco diferente. Eis 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 final de mensagem

Antes de subscrever o tópico, vamos criar o ponto final para a mensagem de evento. Normalmente, o ponto final executa as ações com base nos dados do evento. Para simplificar este início rápido, vai implementar uma aplicação Web pré-criada para apresentar as mensagens de evento. A solução implementada inclui um plano do Serviço de Aplicações, uma aplicação Web do Serviço de Aplicações e o código de origem do GitHub.

Substitua <your-site-name> por um nome exclusivo para a aplicação Web. O nome da aplicação Web deve ser exclusivo, porque faz parte da 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 implementação pode demorar alguns minutos. Após a implementação ter sido concluída com êxito, verifique a aplicação Web para verificar se está em execução. Num browser, navegue para: https://<your-site-name>.azurewebsites.net

Deverá ver o site sem mensagens atualmente apresentadas.

Subscreva um tópico para comunicar ao Event Grid os eventos que pretende controlar e para onde enviar esses eventos. O exemplo a seguir se inscreve no tópico do sistema que você criou e passa a URL do seu aplicativo Web como o ponto de extremidade para receber notificações de eventos. Substitua <event_subscription_name> por um nome para a subscrição de eventos. Para <resource_group_name> e <your-site-name>, utilize o valor que criou anteriormente.

O ponto final para a aplicação Web tem de 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

Verifique a aplicação Web novamente e repare que um evento de validação de subscrição foi enviado para a mesma. Selecione o ícone do olho para expandir os dados do evento. O Event Grid envia o evento de validação para que o ponto final possa verificar que pretende receber dados de eventos. A aplicação Web inclui código para validar a subscrição.

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 Exigir uma marca em grupos de recursos . Esta definição de política identifica os grupos de recursos que não têm a marca configurada durante a atribuição da 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 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 utiliza as seguintes informações:

Nome – O nome real da atribuição. Para este exemplo, requiredtags-events foi usado.
DisplayName – O nome da atribuição de política a apresentar. Nesse caso, você está usando a tag Exigir no RG.
Âmbito – Um âmbito determina que recursos ou agrupamento de recursos em que a atribuição de política é imposta. Pode ir desde uma subscrição a grupos de recursos. Não se esqueça de substituir <âmbito> 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 na qual você está usando para criar a atribuição. Nesse caso, é a ID da definição de política Exigir uma tag em grupos de recursos. Para obter o ID de definição de 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 até que uma notificação de evento Microsoft.PolicyInsights.PolicyStateCreated apareça no aplicativo Web. O grupo de recursos que criamos mostra um data.complianceState valor de NonCompliant para iniciar.

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

Nota

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

Acionar uma alteração no grupo de recursos

Para tornar o grupo de recursos compatível, é necessária uma tag com o nome EventTest . Adicione a tag 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 data.complianceState valor agora mostra Compliant.

Resolução de Problemas

Se vir um erro semelhante a um dos seguintes, certifique-se de que registou ambos os fornecedores de recursos no âmbito em que está a subscrever (grupo de gestão ou subscrição):

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.'}]}

Clean up resources (Limpar recursos)

Se planeia continuar a trabalhar com esta aplicação Web e subscrição de eventos do Azure Policy, não limpe os recursos criados neste artigo. Se você não planeja continuar, use o comando a seguir para excluir os recursos criados neste artigo.

Substitua <resource_group_name> pelo grupo de recursos que criou acima.

az group delete --name <resource_group_name>

Próximos passos

Agora que você sabe como criar tópicos e assinaturas de eventos para a Política do Azure, saiba mais sobre eventos de alteração de estado de política e o que a Grade de Eventos pode ajudá-lo a fazer: