Neste artigo você vai configurar o Schema Registry no Azure Event Hubs com Terraform, criando um schema group Avro com compatibilidade Forward. O Schema Registry no Azure Event Hubs garante que todos os produtores e consumidores concordem com o formato das mensagens — sem schema registry, um produtor que muda o formato de um campo pode quebrar silenciosamente todos os consumidores.
Sumário
- O que é Schema Registry
- Schema Registry no Azure Event Hubs
- Avro vs JSON Schema
- Modos de compatibilidade: Forward e Backward
- Pré-requisitos
- Passo 1 — main.tf: módulo de schema registry
- Passo 2 — Executar o Terraform
- Resultado do apply
- Registrar um schema Avro
- Limitações do SKU Standard
- Troubleshooting
- Próximos passos
O que é Schema Registry
Schema Registry é um serviço centralizado que armazena e valida os schemas (formatos) das mensagens que trafegam em um sistema de mensageria. Sem schema registry, cada produtor e consumidor precisa concordar informalmente sobre o formato das mensagens — e qualquer mudança no produtor pode quebrar consumidores existentes sem aviso. Com schema registry, o schema é um contrato formal: quando um produtor tenta publicar uma mensagem com schema incompatível, o registro rejeita a publicação antes que a mensagem chegue ao event hub.
O Schema Registry no Azure Event Hubs é um serviço nativo do namespace — sem custo adicional no SKU Standard — que suporta dois formatos: Avro (binário, compacto, tipado) e JSON Schema (texto, legível, mais flexível). Para o nosso sistema de pedidos, Avro é a escolha mais eficiente: as mensagens são menores (sem nomes de campos repetidos como em JSON) e o schema garante que o campo pedido_id seja sempre um inteiro.
Schema Registry no Azure Event Hubs
O Schema Registry no Azure Event Hubs é organizado em schema groups — agrupamentos lógicos de schemas relacionados. Um schema group define o tipo de schema (Avro ou JSON) e o modo de compatibilidade que se aplica a todos os schemas dentro do grupo. No SKU Standard, cada namespace suporta até 1 schema group. No SKU Premium, o limite é 10 schema groups.
Para o nosso lab, criamos um único schema group Avro com compatibilidade Forward — adequado para a maioria dos cenários de evolução de schema em produção. O Terraform provisiona o schema group; os schemas individuais (como o schema do evento de pedido) são registrados via REST API após o deploy.
Avro vs JSON Schema
Avro é um formato de serialização binário desenvolvido pelo Apache que usa um schema para descrever a estrutura dos dados. Ao contrário do JSON, as mensagens Avro não incluem os nomes dos campos — apenas os valores binários, na ordem definida pelo schema. Isso resulta em mensagens muito menores: um evento de pedido com 5 campos em Avro tem tipicamente 40-60% do tamanho equivalente em JSON. Para o Schema Registry no Azure Event Hubs, Avro é recomendado quando o throughput de mensagens é alto.
JSON Schema é uma opção mais acessível para equipes que já trabalham com JSON: as mensagens continuam legíveis sem ferramentas especiais e o schema define apenas os tipos e restrições. Use JSON Schema quando a legibilidade e a facilidade de debug são prioridade e o overhead de tamanho das mensagens é aceitável.
Modos de compatibilidade: Forward e Backward
O modo de compatibilidade define o contrato de evolução de schemas no Schema Registry no Azure Event Hubs:
| Modo | Definição | Caso de uso |
|---|---|---|
| Forward | Novo schema é legível por consumidores com schema antigo | Produtores atualizam antes dos consumidores |
| Backward | Schema antigo é legível por consumidores com schema novo | Consumidores atualizam antes dos produtores |
| Full | Compatível em ambas as direções | Restrição mais conservadora, permite atualizações em qualquer ordem |
| None | Sem verificação de compatibilidade | Labs e experimentos |
Para o nosso sistema de e-commerce, Forward é a escolha certa: quando adicionamos um novo campo opcional (como canal_venda) ao schema de pedidos, os consumidores com schema antigo simplesmente ignoram o campo desconhecido. O produtor pode ser atualizado com segurança antes dos consumidores.
Pré-requisitos
O Schema Registry no Azure Event Hubs deste artigo requer o Art. 02 aplicado — o namespace evhns-kafka-blog-castilho-eus deve existir. O módulo faz referência ao ID do namespace via data source.
Passo 1 — main.tf: módulo de schema registry
O módulo terraform-eventhub-schema-modules cria os schema groups dentro do namespace. No SKU Standard, apenas 1 schema group é suportado — o módulo já trata essa limitação:
data "azurerm_eventhub_namespace" "kafka" {
name = "evhns-kafka-blog-castilho-eus"
resource_group_name = "rg-kafka-blog-castilho-eus"
}
module "schema_registry" {
source = "../../terraform-eventhub-schema-modules"
namespace_id = data.azurerm_eventhub_namespace.kafka.id
schema_groups = [
{
name = "sg-avro-blog-castilho-eus"
schema_type = "Avro"
schema_compatibility = "Forward"
},
]
}O argumento namespace_id (e não o nome do namespace) é necessário para o recurso azurerm_eventhub_schema_group. O data source do namespace resolve o ID automaticamente.
Passo 2 — Executar o Terraform
cp backend.hcl.example backend.hcl
terraform init -backend-config=backend.hcl
terraform plan
terraform applyResultado do apply
Após o apply, o Schema Registry no Azure Event Hubs está disponível no namespace:
| Recurso | Nome | Detalhe |
|---|---|---|
| Schema Group | sg-avro-blog-castilho-eus | Tipo: Avro, Compatibilidade: Forward |
Verifique via CLI:
az eventhubs namespace schema-registry list \
--resource-group rg-kafka-blog-castilho-eus \
--namespace-name evhns-kafka-blog-castilho-eus \
--output tableRegistrar um schema Avro
Com o schema group criado, registre o schema do evento de pedido via REST API do Schema Registry no Azure Event Hubs. O endpoint usa a mesma autenticação SAS do namespace:
NAMESPACE="evhns-kafka-blog-castilho-eus"
SCHEMA_GROUP="sg-avro-blog-castilho-eus"
SCHEMA_NAME="Pedido"
# Obter token SAS
SAS_TOKEN=$(az eventhubs namespace authorization-rule keys list \
--resource-group rg-kafka-blog-castilho-eus \
--namespace-name $NAMESPACE \
--name RootManageSharedAccessKey \
--query primaryKey -o tsv)
# Registrar schema
curl -X PUT \
"https://$NAMESPACE.servicebus.windows.net/$SCHEMA_GROUP/schemas/$SCHEMA_NAME?api-version=2021-10" \
-H "Authorization: SharedAccessSignature $SAS_TOKEN" \
-H "Content-Type: application/json; serialization=Avro" \
-d '{
"type": "record",
"name": "Pedido",
"namespace": "com.castilho.kafka",
"fields": [
{"name": "pedido_id", "type": "int"},
{"name": "produto", "type": "string"},
{"name": "quantidade","type": "int"},
{"name": "timestamp", "type": "long"}
]
}'Limitações do SKU Standard
O SKU Standard impõe algumas limitações importantes ao Schema Registry no Azure Event Hubs: (1) máximo de 1 schema group por namespace — se você precisar de grupos separados para Avro e JSON, faça upgrade para o SKU Premium; (2) o limite de schemas por grupo é 25 no Standard e 1000 no Premium; (3) não há suporte a schema groups com tipo JSON no SKU Standard de algumas regiões — verifique a disponibilidade antes de escolher JSON Schema em vez de Avro.
No Terraform do Art. 05 dessa série, o schema group JSON foi removido justamente por essa limitação — o SKU Standard só permite 1 grupo, e escolhemos Avro por ser o formato mais eficiente para o caso de uso.
Troubleshooting
Erro: SchemaGroupQuotaExceeded — o SKU Standard já tem 1 schema group. Execute terraform destroy no schema group existente antes de criar um novo, ou faça upgrade do namespace para Premium.
Schema incompatível rejeitado — se tentar registrar uma versão nova do schema que viola a compatibilidade Forward (ex: remover um campo obrigatório), o registro retorna 409 Conflict. Revise as mudanças — campos novos devem ter valores default em Avro para manter compatibilidade Forward.
Próximos passos
Com o Schema Registry no Azure Event Hubs configurado e o schema Avro de pedidos registrado, o último artigo da série configura o monitoramento completo com Azure Managed Grafana e Log Analytics — dashboards de throughput, latência e consumer group lag em tempo real.
Interessado em saber mais sobre artigos relacionados ao Microsoft Azure CLIQUE AQUI
🚀 Vamos nos conectar?
Não perca nenhuma oportunidade! Cadastre-se nas minhas redes e no canal do YouTube para receber conteúdos de TI, Cloud, Azure, Kubernetes e DevOps em primeira mão.
Dica: No Facebook, todos os artigos do blog são publicados automaticamente. Vale a pena curtir!
💬 Dúvidas ou Problemas?
Com o intuito de ajudar a comunidade, caso você tenha dúvidas ou encontre problemas na execução dos comandos deste artigo, deixe um comentário abaixo. Responderei o mais breve possível!
Muito obrigado pela visita e até o próximo post!
Jefferson Castilho Especialista em Cloud & DevOps.Este guia técnico é exclusivo do Blog do Castilho. Explore nossa para mais conteúdos sobre IA e Cloud.