Instalar a extensão da Grade de Eventos em um cluster do Kubernetes habilitado para o Azure Arc

Artigo
03/20/2023

Este artigo orienta você pelas etapas de instalação da grade de eventos em um cluster do Kubernetes habilitado para o Azure Arc.

Para fins de brevidade, este artigo refere-se à "grade de eventos na extensão do Kubernetes" como "grade de eventos no Kubernetes" ou apenas "grade de eventos".

Importante

A Grade de Eventos no Kubernetes com Azure Arc está atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Distribuições do Kubernetes compatíveis

A seguir estão listadas as distribuições do Kubernetes com suporte nas quais a grade de eventos pode ser implantada e executada.

Distribuições do Kubernetes compatíveis com o Serviço de Contêiner do Azure.
Plataforma de contêiner do OpenShift do RedHat.

Extensão da Grade de Eventos

A operação que instala uma instância de serviço da Grade de Eventos em um cluster do Kubernetes é a criação de uma extensão de cluster do Azure Arc. Ela implanta um agente de grade de eventos e um operador de grade de eventos. Para obter mais informações sobre a função do agente e do operador, consulte Grade de Eventos em componentes do Kubernetes. O recurso de extensão de cluster do Azure Arc fornece o gerenciamento do ciclo de vida usando operações de plano de controle do Azure Resource Manager (ARM) para a grade de eventos implantada em clusters do Kubernetes habilitados para o Azure Arc.

Observação

A versão prévia do serviço dá suporte a uma única instância da extensão da grade de eventos em um cluster do Kubernetes, visto que a extensão da grade de eventos está definida atualmente como uma extensão no escopo do cluster. Não há suporte a implantações com escopo de namespace para a grade de eventos, mas, caso houvesse, isso permitiria que várias instâncias fossem implantadas em um cluster. Para obter mais informações, consulte Escopo de extensão.

Pré-requisitos

Antes de prosseguir com a instalação da grade de eventos, verifique se os pré-requisitos a seguir foram atendidos.

Um cluster em execução em uma das distribuições do Kubernetes com suporte.
Uma assinatura do Azure.
Certificados PKI a serem usados para estabelecer uma conexão HTTPS com o agente da Grade de Eventos.
Conecte seu cluster ao Azure Arc.

Obtendo suporte

Em caso de problemas, consulte a seção Solução de problemas para ajuda nas situações mais comuns. Se continuar tendo problemas, crie uma solicitação de suporte do Azure.

Requisitos de certificado PKI

O agente da Grade de Eventos (servidor) atende a dois tipos de clientes. A autenticação do servidor é feita usando certificados. A autenticação do cliente é feita usando certificados ou chaves SAS a depender do tipo de cliente.

Os operadores da Grade de Eventos que fazem solicitações de plano de controle ao agente da Grade de Eventos são autenticados usando certificados.
Os editores da Grade de Eventos que publicam eventos em um tópico da Grade de Eventos são autenticados com as chaves SAS do tópico.

Para estabelecer uma comunicação HTTPS segura com o agente da Grade de Eventos e com o operador da Grade de Eventos, usamos Certificados PKI durante a instalação da extensão da Grade de Eventos. Estes são os requisitos gerais para os certificados PKI:

Os certificados e chaves devem ser certificadosX.509 e Privacy Enhanced Mail codificados para PEM.
Para configurar o certificado do agente da Grade de Eventos (servidor) durante a instalação, é necessário fornecer:
1. Um certificado da autoridade de certificação
2. Um certificado público
3. Uma chave privada
Para configurar o certificado do operador da Grade de Eventos (cliente), é necessário fornecer:
1. Um certificado da autoridade de certificação
2. Um certificado público
3. Uma chave privada
Os clientes de publicação podem usar o certificado da autoridade de certificação do agente da Grade de Eventos para validar o servidor ao publicarem eventos em um tópico.

Importante

Embora um domínio associado ao cliente possa ter mais de um certificado público emitido por diferentes autoridades de certificação, a Grade de Eventos no Kubernetes só permite carregar um único certificado de autoridade de certificação para clientes quando de sua instalação. Como consequência, os certificados para o operador de Grade de Eventos devem ser emitidos (assinados) pela mesma AC para que a validação da cadeia de certificados seja bem-sucedida e uma sessão TLS seja estabelecida com êxito.
Ao configurar o nome comum (CN) para certificados de servidor e cliente, verifique se eles são diferentes do CN fornecido para o certificado de autoridade de certificação.

Importante

Os certificados autoassinados podem ser uma opção nos estágios de prova de conceito iniciais, mas, via de regra, devem ser adquiridos e usados certificados PKI adequados assinados por uma autoridade de certificação (CA).

Instalar usando o portal do Azure

No portal do Azure, pesquisar (campo na parte superior) por Azure Arc
Selecionar o cluster do Kubernetes no menu do lado esquerdo na seção de Infraestrutura
Na lista de clusters, localize aquele no qual você deseja instalar a grade de eventos e selecione-o. É exibida a página de Visão geral do cluster.
Selecione Extensões no grupo de Configurações no menu do lado esquerdo.
Selecione + Adicionar. É exibida uma página mostrando as extensões disponíveis do Kubernetes para o Azure Arc.
Na página novo recurso, selecione Grade de Eventos na extensão do Kubernetes.
Selecione Criar na página da Grade de Eventos do Kubernetes.
Na guia Básico da página Instalar Grade de Eventos, siga essas etapas.
1. A seção Detalhes do projeto mostra os valores da assinatura somente leitura e do grupo de recursos, visto que as extensões do Azure Arc são implantadas na mesma assinatura do Azure e no grupo de recursos do cluster conectado no qual elas estão instaladas.
2. Forneça um nome no campo Nome da extensão da grade de eventos. Esse nome deve ser exclusivo entre outras extensões do Azure Arc implantadas no mesmo cluster conectado ao Azure Arc.
3. Para o Namespace de versão, você pode desejar fornecer o nome de um namespace do Kubernetes no qual os componentes da grade de eventos serão implantados. Por exemplo, talvez você queira ter um único namespace para todos os serviços habilitados para o Azure Arc implantados em seu cluster. O padrão é eventgrid-system. Se o namespace fornecido não existir, ele será criado para você.
4. Na seção de detalhes do agente da grade de eventos, é mostrado o tipo de serviço. O agente da grade de eventos, que é o componente que expõe os pontos de extremidade dos tópicos para os quais os eventos são enviados, é exposto como um serviço do Kubernetes de tipo ClusterIP. Portanto, os IPs atribuídos a todos os tópicos usam o espaço de IP privado configurado para o cluster.
5. Forneça o nome da classe de armazenamento que você deseja usar para o agente e que tenha suporte da distribuição do Kubernetes. Por exemplo, se estiver usando o AKS, você poderia usar oazurefile, que utiliza o Armazenamento Standard do Azure. Para obter mais informações sobre classes de armazenamento predefinidas com suporte no AKS, consulte Classes de armazenamento no AKS. Se você estiver usando outras distribuições do Kubernetes, consulte a documentação de distribuição do Kubernetes sobre classes de armazenamento predefinidas com suporte ou sobre maneiras de fornecer as suas próprias classes de armazenamento.
6. Tamanho de armazenamento. O padrão é 1 GiB. Considere a taxa de ingestão ao determinar o tamanho do armazenamento. A taxa de ingestão, medida em MiB/segundo como sendo o tamanho de seus eventos vezes a taxa de publicação (eventos por segundo) em todos os tópicos no agente da Grade de Eventos, é um fator fundamental ao alocar armazenamento. Os eventos são transitórios por natureza e, depois de entregues, não há consumo de armazenamento para esses eventos. Embora a taxa de ingestão seja um grande motivador para o uso de armazenamento, ela não é o único. Os tópico contendo metadados e as configurações das assinaturas de eventos também consomem espaço de armazenamento, mas costumam demandar uma quantidade menor de espaço de armazenamento do que os eventos ingeridos e entregues pela Grade de Eventos.
7. Limite de memória. O padrão é de 1 GiB.
8. Solicitação de memória. O padrão é de 200 miB. Esse campo não é editável.
9. Selecione Avançar: Configuração na parte inferior da página.
Na guia Configuração da página Instalar Grade de Eventos, execute as seguintes etapas:
1. Habilitar a comunicação HTTP (não segura) . Marque esta caixa se você quiser usar um canal não seguro quando os clientes se comunicarem com o agente da Grade de Eventos.
  
  Importante
  
  Habilitar essa opção faz com que a comunicação com o agente da Grade de Eventos use HTTP como transporte. Portanto, os clientes de publicação e o operador de Grade de Eventos não se comunicarão com o agente da Grade de Eventos com segurança. Você deve usar essa opção somente durante os estágios iniciais de desenvolvimento.
2. Se você não tiver habilitado a comunicação HTTP, selecione cada um dos arquivos de certificado PKI que você adquiriu e que atendem aos requisitos de certificados PKI.
3. Selecione Avançar: Marcas na parte inferior da página.
Na guia Monitoramento da página Instalar Grade de Eventos, execute as seguintes etapas:
1. Selecione Habilitar métricas (opcional). Se você selecionar essa opção, a Grade de Eventos no Kubernetes vai expor as métricas para tópicos e assinaturas de evento no formato de exposição do Prometheus.
2. Selecione Avançar: Marcas para navegar até a página Marcas.
Na página Marcações, execute as seguintes etapas:
1. Defina as marcas, se necessário.
2. Selecione Revisar + criar na parte inferior da página.
Na guia Revisar + criar, selecione Criar.

Importante

A instalação da extensão da Grade de Eventos é uma operação assíncrona que pode demorar mais para ser executada no cluster de Kubernetes do que o tempo em que você vê uma notificação no portal do Azure informando que a implantação foi concluída. Aguarde pelo menos 5 minutos depois de ver uma notificação informando que "A sua implantação foi concluída" antes de tentar criar um local personalizado (próxima etapa). Se você tiver acesso ao cluster do Kubernetes, poderá executar o seguinte comando em uma sessão de bash para validar se os pods do agente de grade de eventos e do operador de grade de eventos estão em estado de execução, o que indicaria que a instalação foi concluída:
```
kubectl get pods -n \<release-namespace-name\>
```
Veja o exemplo de saída:
```
NAME                                  READY   STATUS    RESTARTS   AGE
eventgrid-broker-568f75976-wxkd2      1/1     Running   0          2m28s
eventgrid-operator-6c4c6c675d-ttjv5   1/1     Running   0          2m28s    
```
Importante

É necessário criar um local personalizado antes de tentar implantar tópicos da grade de eventos. Para criar um local personalizado, você pode selecionar a página de Contexto na parte inferior da página 5 minutos após ter sido mostrada a notificação "A sua implantação foi concluída". Como alternativa, você pode criar um local personalizado usando o portal do Azure. Para obter mais informações, consulte a Documentação de localização personalizada.
Depois que a implantação for realizada com sucesso, você poderá ver uma entrada na página Extensões com o nome fornecido para a extensão da Grade de Eventos. Se você vir Pendente no status de Instalação , aguarde alguns minutos e selecione Atualizar na barra de ferramentas.

Instalar usando a CLI do Azure

Iniciar uma sessão de shell. Você pode iniciar uma sessão no computador ou abrir um navegador para https://shell.azure.com.

Criar arquivo de configuração protected-settings-extension.json. Esse arquivo é passado como um parâmetro ao criar a extensão da Grade de Eventos.

No comando a seguir e em cada uma das linhas de configuração, substitua filename pelo nome que contém o certificado público, certificado de AC ou chave para o operador (cliente) ou agente (servidor), de acordo. Todos os certificados fornecidos devem ser codificados em base64 sem quebra de linha. Portanto, o uso do comandobase64 --wrap=0.

echo "{ 
    \"eventgridoperator.identityCert.base64EncodedIdentityCert\":\"$(base64 <filename> --wrap=0)\",
    \"eventgridoperator.identityCert.base64EncodedIdentityKey\":\"$(base64 <filename> --wrap=0)\",
    \"eventgridoperator.identityCert.base64EncodedIdentityCaCert\":\"$(base64 <filename> --wrap=0)\",
    \"eventgridbroker.service.tls.base64EncodedServerCert\":  \"$(base64 <filename> --wrap=0)\" ,
    \"eventgridbroker.service.tls.base64EncodedServerKey\":  \"$(base64 <filename> --wrap=0)\" ,
    \"eventgridbroker.service.tls.base64EncodedServerCaCert\":  \"$(base64 <filename> --wrap=0)\" 
}" > protected-settings-extension.json

Por exemplo, se o certificado público do agente (primeiro item de configuração acima) for chamado client.cer, a primeira linha de configuração deverá ser como a seguinte:

\"eventgridoperator.identityCert.base64EncodedIdentityCert\":\"$(base64 client.cer --wrap=0)\",

Criar arquivo de configuração settings-extension.json. Esse arquivo é passado como um parâmetro ao criar a extensão da Grade de Eventos.

Importante

Você não pode alterar os valores de ServiceAccount e serviceType. Durante a versão prévia, o único tipo de serviço do Kubernetes com suporte é ClusterIP.

Para storageClassName, forneça o nome da classe de armazenamento que você deseja usar para o agente e que tenha suporte da distribuição do Kubernetes. Por exemplo, se estiver usando o AKS, você poderia usar o azurefile , que utiliza o Armazenamento Standard do Azure. Para obter mais informações sobre classes de armazenamento predefinidas com suporte no AKS, consulte Classes de armazenamento no AKS. Se você estiver usando outras distribuições do Kubernetes, consulte a documentação de distribuição do Kubernetes sobre classes de armazenamento predefinidas com suporte ou sobre maneiras de fornecer as suas próprias classes de armazenamento.

DefinareporterType como prometheus para habilitar as métricas para tópicos e assinaturas de evento usando o formato de exposição Prometheus.

Importante

Durante a versão prévia, usar um cliente Prometheus é o único mecanismo com suporte para obter métricas.
```
echo "{
    \"Microsoft.CustomLocation.ServiceAccount\":\"eventgrid-operator\",
    \"eventgridbroker.service.serviceType\": \"ClusterIP\",
    \"eventgridbroker.dataStorage.storageClassName\": \"<storage_class_name>\",
    \"eventgridbroker.diagnostics.metrics.reporterType\":\"prometheus\"
}" > settings-extension.json
```
Crie uma extensão do Kubernetes que instala componentes da Grade de Eventos no cluster.

Para os parâmetros cluster-name e resource-group, você deve usar os mesmos nomes fornecidos quando conectou o cluster ao Azure Arc.

release-namespace é o namespace no qual os componentes da Grade de Eventos serão implantados. O padrão é eventgrid-system. Talvez você queira fornecer um valor para substituir o padrão. Por exemplo, talvez você queira ter um único namespace para todos os serviços habilitados para o Azure Arc implantados em seu cluster. Se o namespace fornecido não existir, ele será criado para você.

Importante

Durante a versão prévia, cluster é o único escopo com suporte ao criar ou atualizar uma extensão da Grade de Eventos. Isso significa que o serviço dá suporte apenas a uma única instância da extensão da Grade de Eventos em um cluster do Kubernetes. Ainda não há suporte para implantações no escopo do namespace. Para obter mais informações, consulte Escopo de extensão.
```
az k8s-extension create \
    --cluster-type connectedClusters \
    --cluster-name <connected_cluster_name> \
    --resource-group <resource_group_of_connected_cluster> \
    --name <event_grid_extension_name> \
    --extension-type Microsoft.EventGrid \
    --scope cluster \
    --auto-upgrade-minor-version true \
    --release-train Stable \
    --release-namespace <namespace_name> \
    --configuration-protected-settings-file protected-settings-extension.json \
    --configuration-settings-file settings-extension.json    
```
Para saber mais sobre o comando da CLI, confira az k8s-extension create. Observe que você pode usar o parâmetro --config-file para passar o nome de um arquivo json que contém informações de configuração relacionadas à Grade de Eventos. Para dar suporte a HTTP, inclua a configuração a seguir.
```
"eventgridbroker.service.supportedProtocols[0]": "http" 
```
Confira um exemplo de settings-extension.json com a configuração acima.
```
{
    "Microsoft.CustomLocation.ServiceAccount": "eventgrid-operator",
    "eventgridbroker.service.serviceType": "ClusterIP",
    "eventgridbroker.service.supportedProtocols[0]": "http",
    "eventgridbroker.dataStorage.storageClassName": "default",
    "eventgridbroker.diagnostics.metrics.reporterType": "prometheus"
}    
```
Valide se a extensão da Grade de Eventos foi instalada com êxito.
```
az k8s-extension show  --cluster-type connectedClusters --cluster-name <connected_cluster_name> --resource-group <resource_group_of_connected_cluster> --name <event_grid_extension_name>
```
A propriedade installedState deve ser Installed se os componentes de extensão da Grade de Eventos forem implantados com êxito.

Local personalizado

Importante

É necessário criar um local personalizado antes de tentar implantar tópicos da grade de eventos. Você pode criar um local personalizado usando o portal do Azure.

Solução de problemas

Problemas de clusters de conexão do Azure Arc

Problema: quando você navega até o Azure Arc e seleciona cluster do Kubernetes no menu do lado esquerdo, a página exibida não mostra o cluster do Kubernetes onde tenha a intenção de instalar a Grade de Eventos.

Resolução: o cluster do Kubernetes não está registrado no Azure. Siga as etapas no artigo Conectar um cluster do Kubernetes existente ao Azure Arc. Caso tenha problemas durante essa etapa, abra uma solicitação de suporte para a equipe do Kubernetes habilitada para o Arc do Azure.

Problemas de extensão da Grade de Eventos

Problema: ao tentar instalar uma "extensão da Grade de Eventos", você obtém a seguinte mensagem: “Operação inválida - Uma instância da Grade de Eventos já foi instalada nesse cluster do Kubernetes conectado. A extensão da Grade de Eventos tem escopo no nível do cluster, o que significa que apenas uma instância pode ser instalada em um cluster."

Explicação: a Grade de Eventos já está instalada. A versão prévia da Grade de Eventos dá suporte apenas a uma instância de extensão da Grade de Eventos implantada em um cluster.

Próximas etapas

Crie um local personalizado e siga as instruções no início rápido Rotear eventos de nuvem para Webhooks com a Grade de Eventos do Azure no Kubernetes.