O que a compatibilidade com versões anteriores significa para a API do dashboard do Kibana

Durante a prévia técnica, a configuração da API pode mudar entre os lançamentos.[1] Esse não é mais o caso. Disponibilidade geral (GA) significa:

• Compatibilidade retrógrada completa. Novos campos e tipos de painel serão adicionados ao longo do tempo, mas os campos e comportamentos existentes permanecem inalterados. Quaisquer mudanças futuras que quebrem a compatibilidade seriam cuidadosamente consideradas e só seriam introduzidas em uma nova versão principal da pilha.

• Pronto para produção com suporte completo. A API oferece todas as garantias de compatibilidade da Elastic. Você pode usá-lo com segurança em ambientes de produção para implantações automatizadas, promoção de ambiente e gerenciamento programático do dashboard.

Novos endpoints da API Kibana para os painéis Tags, Markdown e Links

O Elastic 9.5 também introduz um novo  endpoint independente para Tags, que permite categorizar e filtrar painéis. Agora, você pode gerenciá-los programaticamente por meio de endpoints CRUD dedicados, facilitando a organização de painéis em escala entre ambientes.

Os novos endpoints para os painéis Markdown e Links já estão disponíveis no Serverless e serão lançados na próxima versão do stack (9.6).

Com quais tipos de painel a API do dashboard do Kibana é compatível?

A API do dashboard é compatível com todos os painéis definidos por valor na versão 9.5 (aqueles definidos diretamente em um dashboard, em oposição aos painéis da biblioteca salvos para reutilização). Cada tipo de painel compatível possui um esquema tipado e validado.

Tipo de painel

Status

Gráficos XY

Compatível

Métricas

Compatível

Pizza

Compatível

Medidor

Compatível

Heatmap

Compatível

Tabelas de dados

Compatível

Mapa de árvore

Compatível

Discover sessões

Compatível

Controles

Compatível

Markdown

Compatível

Links

Compatível

Painéis de ML

Compatível

Painéis de observabilidade

Compatível

Mapas

Em breve

Vega

Em breve

Como gerenciar dashboards do Kibana como código

A API de dashboards permite um fluxo de trabalho completo de dashboards como código: exportar um dashboard como JSON limpo e passível de comparação, enviá-lo ao Git como fonte de verdade, revisar mudanças em pull requests e implantar a mesma definição em desenvolvimento, staging e produção. Depois que um dashboard for gerenciado como código, trate o Git como a única fonte da verdade: as alterações feitas diretamente na UI serão substituídas na próxima vez que você implantar.

O principal desafio ao mover um dashboard entre espaços, clusters ou estágios é que os dashboards referenciam objetos como data view e visualizações da biblioteca por ID. Como esses IDs são gerados automaticamente e diferem entre ambientes, um dashboard exportado de um ambiente pode apontar para objetos que não existem em outro. Existem três maneiras de lidar com isso, listadas aqui da mais automatizada à menos automatizada:

• Use Terraform. O provedor Terraform do Elastic Stack acompanha cada recurso e mapeia os IDs automaticamente por ambiente, para que as referências permaneçam consistentes enquanto você promove um dashboard do desenvolvimento para a produção.

• Defina por-valor a Linguagem de Consulta Elasticsearch (ES|QL). A maneira mais portátil de construir um painel é definir sua visualização com o ES|QL diretamente no dashboard. Uma consulta ES|QL lê os índices que você especificar nela; portanto, o painel não contém referências externas a data views ou objetos de biblioteca. O resultado é um dashboard portátil e totalmente independente.

• Atribua IDs correspondentes. Se você fizer referência a objetos salvos, como visualizações de dados ou visualizações de bibliotecas, crie-os com um ID escolhido usando PUT (upsert) em vez de POST (que gera automaticamente um ID). Use IDs legíveis por humanos, como logs-prod, para que sejam fáceis de reutilizar e reconhecer em diferentes ambientes.

Para obter uma descrição detalhada desses padrões de portabilidade e do fluxo de trabalho completo de dashboards como código, consulte a documentação Gerenciar dashboards como código.

Crie um dashboard do Kibana com a API Dashboards usando PUT

Aqui está um exemplo rápido de criação de um dashboard com uma métrica usando PUT em vez de POST para atribuir um ID personalizado com o nome do dashboard (service-health-overview). A mesma lógica funciona para criar visualizações independentes salvas na biblioteca.

Roadmap da API do dashboard do Kibana: Maps, Vega e endpoints independentes

Estamos expandindo ativamente o escopo da API. Na sequência, compatibilidade com mapas e painéis Vega, adicionando esquemas tipados para eles. Também estamos construindo pontos finais CRUD independentes para sessões Discover (além do suporte existente como painéis de dashboard), Vega, maps e anotações, desacoplados do ciclo de vida do dashboard.

Para as definições completas de esquema, visite a documentação da API dos Dashboards. Para usuários do Terraform, o provedor Terraform do Elastic Stack é compatível com a API GA Dashboards.

Nota

1. Os endpoints núcleos permanecem inalterados em relação à prévia técnica. Se você construiu integrações contra a 9.4, elas funcionam na 9.5. As únicas alterações que quebram a compatibilidade são duas pequenas que afetam os formatos de listagem do dashboard e dos formatos da unidade de duração, documentadas aqui.

Hoje, essa história fica muito mais simples. Chaves de API do Elastic Cloud agora podem ser usadas para autenticar diretamente em comparação a APIs do Elasticsearch e Kibana no Elastic Cloud Serverless. Agora você pode usar uma única credencial para gerenciar os recursos da sua organização e executar operações de dados, como a Elasticsearch Query Language (ES|QL), ingestão de dados e alertas.

Vamos ver por que construímos isso, como projetamos uma camada de identidade distribuída globalmente para possibilitar o recurso e como ele estabelece a base para a busca entre projetos.

O ônus da gestão de segredos

Construir pipelines confiáveis de CI/CD, fluxos de trabalho GitOps ou automação Terraform em plataformas de dados tem um custo oculto: a proliferação de segredos.

No modelo anterior, os desenvolvedores lidavam com uma história de autenticação desarticulada:

• Plano de controle (chaves da API do Elastic Cloud): chaves com escopo organizacional usadas para criar projetos, convidar usuários e gerenciar as cobranças via API do Elastic Cloud.

• Plano de dados (chaves da API do Elasticsearch): Chaves com escopo de projeto criadas dentro de um projeto Serverless específico para interagir com as APIs do Elasticsearch e do Kibana.

Nesse caso, seu script de implantação precisava se autenticar no Elastic Cloud, provisionar um projeto Serverless, extrair uma chave de API do Elasticsearch recém-criada desse projeto específico e, em seguida, inserir essa segunda chave na aplicação ou na ferramenta de automação mais adiante, o que resultava em pipelines complexos, logs de auditoria fragmentados e maior risco de vazamento de credenciais.

Autenticação unificada no Elastic Cloud Serverless

Com este lançamento, a separação para projetos Serverless foi eliminada. Agora você pode criar uma chave de API do Elastic Cloud explicitamente autorizada para nuvem, Elasticsearch e Kibana APIs.

• Antes: a chave de API do Elastic Cloud era estritamente um token do plano de controle. Ela podia criar projetos, gerenciar cobranças e convidar usuários, mas tinha um limite rígido; não podia ser usada para chamar as APIs do Elasticsearch nem Kibana dentro desses projetos. Você sempre precisava de uma segunda chave específica do projeto para operações de dados.

• Agora: ao ter acesso a nuvem, Elasticsearch e a API Kibana ao criar uma chave de API do Elastic Cloud, o limite rígido é retirado para o Serverless. Essa chave de API se torna uma credencial verdadeiramente unificada. Ela mantém a capacidade de gerenciar a infraestrutura da sua organização, ao mesmo tempo que ganha acesso nativo para consultar, ingerir e analisar dados em qualquer projeto Serverless autorizado.

Ao unificar tudo sob uma única chave de API do Elastic Cloud, você ganha uma única identidade que pode ter escopo definido, ser auditada, rotacionada e revogada como uma unidade. Cada chamada de API, seja para provisionar um novo projeto ou executar uma consulta ES|QL, aparece sob a mesma credencial nos seus logs de auditoria, fornecendo um único rastro a ser seguido durante investigações de incidentes ou revisões de conformidade. A rotação de credenciais agora é feita em uma etapa em vez de ser uma atualização coordenada em segredos separados do plano de controle e do plano de dados. E, como as alocações de função são por projeto, uma só chave pode abranger vários projetos, gerenciando a ingestão no seu projeto de observabilidade e executando consultas no seu projeto de segurança, sem precisar lidar com credenciais separadas para cada um.

Importante: unificado não significa todo-poderoso. Ao usar a carga útil role_assignments, você pode definir uma chave unificada estritamente para um único projeto e uma função específica (como somente leitura), garantindo que o raio de explosão continue totalmente contido caso uma credencial seja exposta. Se um desenvolvedor sair ou uma aplicação for desativada, você pode revogar uma única chave do console Elastic Cloud, encerrando imediatamente o acesso tanto no plano de controle quanto em todos os projetos Elasticsearch associados.

(Atenção: nas implantações Elastic Cloud Hosted/gerenciadas, as chaves da API da nuvem ainda gerenciam apenas o plano de controle. O suporte para estender isso às APIs de pilha hospedada está planejado para uma versão futura.)

Automatizando seus fluxos de trabalho

Começar é simples. Você pode configurar inteiramente no console Elastic Cloud ou automatizar usando a API do Elastic Cloud.

O processo da IU não muda, mas agora você pode selecionar Nuvem, Elasticsearch e API Kibana na alocação de função do projeto.

Veja como criar uma chave unificada programaticamente usando a API do Elastic Cloud. Observe o application_roles conjunto, pois é o que concede ao principal acesso nativo ao plano de dados do Elasticsearch:

Uma vez criado, você passa exatamente essa mesma chave no cabeçalho Authorization: ApiKey tanto para api.elastic-cloud.com quanto para seus endpoints específicos do Serverless Elasticsearch.

Nos bastidores: construindo uma camada de identidade distribuída

Fazer uma chave da API da nuvem funcionar tanto no plano de controle quanto no plano de dados não é tão simples como passar um token. É preciso resolver um desafio fundamental nos sistemas distribuídos.

Historicamente, as chaves de API da nuvem ficavam em um cluster de segurança global centralizado. Isso funciona nas operações de plano de controle cuja latência mais alta é aceitável. No entanto, requisições de dados do Elasticsearch exigem latência ultrabaixa. Não podemos viajar pelo globo até um plano de controle central para validar cada busca ou solicitação de ingestão.

Para resolver, introduzimos uma nova arquitetura de autenticação apoiada por um datastore distribuído globalmente. O diagrama sequencial a seguir mostra um cliente enviando uma consulta Elasticsearch, usando uma chave API do Elastic Cloud, ilustrando como a autenticação ocorre inteiramente dentro da região, sem a viagem por todo o plano de controle global. O Elasticsearch delega a autenticação ao Serviço IAM Regional, que valida a chave e resolve as alocações de função em uma réplica local do banco de dados distribuído globalmente. Uma vez autorizado, o Elasticsearch executa a consulta e retorna os resultados ao cliente.

Persistência distribuída globalmente

Em vez de depender exclusivamente de um cluster de segurança centralizado, as chaves de API do Elastic Cloud e as respectivas definições de função agora ficam em um banco de dados globalmente distribuído e de alta disponibilidade. Esse banco de dados sincroniza os dados de gerenciamento de identidade e acesso (IAM) no plano de controle global e nos planos de dados regionais onde seus projetos Serverless são executados.

Validação local com IAM regional

Quando seu cliente envia uma requisição para o Elasticsearch usando uma chave API do Elastic Cloud, a solicitação não retorna ao plano de controle global. Em vez disso, ela é encaminhada para o novo serviço regional IAM. Ele valida a chave em relação à réplica do banco de dados local, garantindo que a autenticação ocorra com latência quase zero e completamente isolada de interrupções no plano de controle global.

Mapeamento dinâmico de funções

A autenticação é metade do caminho; o sistema também precisa autorizar a solicitação. O serviço IAM regional traduz na hora suas alocações de função no nível da nuvem, por exemplo, application_roles), em privilégios nativos do Elasticsearch. O Elasticsearch pode então autorizar e executar a solicitação no local, sem precisar de um .security índice local.

A base para a busca entre projetos

Essa arquitetura de identidade distribuída é um elemento fundamental para o futuro da plataforma Elastic.

Como a identidade e o acesso agora estão unificados e sincronizados globalmente, temos o framework necessário para transmitir sua identidade com segurança entre diferentes projetos. Isso possibilita as futuras capacidades de Busca Cruzada por Projetos (CPS) para Serverless.

Com o CPS, você poderá consultar dados que abrangem vários projetos Serverless remotos, como combinar cargas de trabalho de segurança e observabilidade, como se fossem um único conjunto de dados. Ao depender de chaves de API unificadas, o sistema pode avaliar automaticamente suas permissões simultaneamente em todos os projetos, sem exigir que você configure relacionamentos de confiança complexos, certificados ou credenciais duplicadas em cada projeto-alvo.

Saiba mais

Pronto para simplificar sua pilha?

• Leia a documentação das chaves de API do Elastic Cloud para aprender como atribuir acesso ao stack.

• Confira a referência Criar chave de API (Elastic Cloud API) para automatizar a geração de chaves.

• Consulte Chaves de API Elastic para uma comparação completa dos tipos de chave em toda a plataforma Elastic.

Comece ou continue construindo no Elastic Cloud hoje.

Aviso de isenção

O lançamento e o tempo de amadurecimento de todos os recursos ou funcionalidades descritos neste artigo permanecem a exclusivo critério da Elastic. Os recursos ou funcionalidades não disponíveis no momento poderão não ser entregues ou não chegarem no prazo previsto.

O Elastic Workflows é um mecanismo de automação integrado dentro do Kibana que permite definir processos de várias etapas usando uma simples configuração YAML. Cada fluxo de trabalho pode ser acionado em um cronograma ou evento ou como uma ferramenta no Elastic Agent Builder, e cada etapa pode chamar APIs do Kibana, consultar o Elasticsearch ou transformar dados.

Vamos usar as contagens de visualização de dashboards como um exemplo concreto, mas o mesmo padrão se aplica a qualquer métrica exposta pela API de objetos salvos do Kibana.

Pré-requisitos

• Elastic Cloud ou cluster autogerenciado executando a versão 9.3

• Fluxos de trabalho ativados (Configurações avançadas)

Passo 1: explorar os dados brutos no Dev Tools

Antes de construir qualquer coisa, vamos entender quais dados temos. O Kibana armazena a maior parte de sua configuração e metadados como objetos salvos em um índice interno dedicado. Uma das coisas que o Kibana monitora dessa forma são as contagens de visualizações do dashboard, usando um tipo especial de objeto salvo chamado contadores de uso. Você pode consultá-los diretamente pelas Ferramentas de Desenvolvimento:

A resposta tem aparência semelhante a esta:

O campo counterName é o ID do dashboard, e count é a contagem cumulativa de visualizações para aquele dashboard naquele dia específico. Kibana cria um objeto contador por dashboard por dia; você pode ver o sufixo de data no ID do objeto (... visualizado:servidor:20260310). A contagem cresce ao longo do dia à medida que os usuários abrem o dashboard.

Em vez de replicar esse modelo de documento diário em nosso índice, criaremos um documento por execução de fluxo de trabalho. Cada documento registra quantas visualizações aquele dashboard acumulou no dia no momento da captura.

Passo 2: criar o índice de destino

Precisamos de um índice para armazenar os snapshots da vista do nosso dashboard. O comando a seguir cria com mapeamentos explícitos para que possamos agregar e visualizar depois. Execute isso nas ferramentas de desenvolvimento:

O uso de mapeamentos keyword para IDs e nomes permite agregações. Usar integer para view_count é um padrão seguro, já que o Kibana reinicia o contador diariamente e atingir o limite de 32 bits (mais de 2 bilhões de visualizações em um único dia) não é uma preocupação realista. Ainda permite operações numéricas, como max, avg e min, entre outras.

Passo 3: Crie o fluxo de trabalho

Acesse Stack Management > Fluxo de trabalho > Novo Fluxo de Trabalho e cole a seguinte configuração YAML do fluxo de trabalho:

Na próxima seção, vamos analisar o fluxo de trabalho passo a passo.

Como funciona o fluxo de trabalho

Gatilhos

O fluxo de trabalho é executado com um gatilho programado a cada 30 minutos. Isso nos fornece dados de séries temporais sem sobrecarregar a API.

buscar_visualizações_do_painel

Usa kibana.request para chamar a API de objetos salvos do Kibana. Não é necessário configurar autenticação: o motor de fluxo de trabalho anexa automaticamente os cabeçalhos corretos com base no contexto de execução.

index_each_dashboard (foreach)

Itera sobre o array saved_objects retornado pela etapa anterior. O item atual em cada iteração está disponível como foreach.item. Dentro do loop, executamos duas etapas aninhadas para cada dashboard.

1. fetch_dashboard_name:

Resolve o título do dashboard legível por humanos chamando GET /api/saved_objects/dashboard/{id}. Adicionamos on-failure: continue: true para que, se um dashboard for excluído mas ainda tiver contadores de visualização, o loop continue em vez de falhar toda a execução.

2. index_doc:

Indexa cada documento usando POST /dashboard-views/_doc (sem um ID explícito), o que permite que o Elasticsearch gere IDs automaticamente. Isso cria um novo documento a cada execução, construindo um histórico de contagens de visualizações ao longo do tempo, em vez de sobrescrever o snapshot anterior.

Duas coisas que valem a pena notar:

• O campo captured_at usa o filtro de data para formatar o carimbo de data/hora como ISO 8601. Sem isso, o valor aparece como uma string de data em JavaScript, como Tue Mar 10 2026 05:03:47 GMT+0000, que o Elasticsearch não mapeia como data.

• O view_count usa a sintaxe ${{ }} com | plus: 0 para preservar o tipo numérico. Usar {{ }} o renderizaria como uma string, o que impediria operações matemáticas no dashboard.

A UI permite que você depure cada uma das etapas do fluxo de trabalho.

Etapa 4: Crie o dashboard de estatísticas

Depois que o fluxo de trabalho for executado algumas vezes e os dados forem coletados, crie um novo dashboard no Kibana usando a Data view dashboard-views.

Alguns painéis para começar:

• Principais dashboards por visualizações: use um gráfico de barras com dashboard_name no eixo X e last_value(view_count) no eixo Y. Isso mostra a contagem diária atual de visualizações por dashboard.

• Visualizações ao longo do tempo: use um gráfico de linhas com captured_at no eixo X e last_value(view_count) no eixo Y, dividido por dashboard_name. Como cada execução adiciona um novo documento, use o último valor para obter a contagem de picos por buckets, em vez de somar duplicados.

• Snapshot atual: use uma tabela de dados com os captured_at mais recentes para mostrar as contagens de visualizações mais recentes em todos os dashboards.

Como cada fluxo de trabalho cria um novo documento, você pode filtrar por faixa de tempo para analisar a atividade em períodos específicos, comparar semana a semana ou criar alertas quando um dashboard cair abaixo de um limite de visualização.

Conclusão

O Elastic Workflows é uma boa opção para esse tipo de coleta periódica de dados porque tanto a fonte (Kibana API) quanto o destino (Elasticsearch) são nativos, o que significa zero gerenciamento de credenciais. O motor de fluxo de trabalho lida automaticamente com autenticação para kibana.request e elasticsearch.request etapas, então a única coisa que você escreve é a lógica.

Recursos

• Elastic Workflows

• API do Kibana

Gerenciamento de dependências no Elastic

Na Elastic, precisamos gerenciar centenas ou até milhares de repositórios, tanto privados quanto públicos. Quando um CVE crítico é descoberto, precisamos de respostas e ações imediatas: quais repositórios são vulneráveis? Com que rapidez podemos corrigir os problemas? Além da segurança, também surgem questões de produtividade: como podemos propagar de forma rápida o lançamento de uma nova versão do pacote em todos os repositórios que dependem dela sem gastar muito tempo em tarefas manuais?

O gatilho inicial para pesquisar maneiras de fazer o gerenciamento de dependências foi a necessidade de estabelecer uma base segura com atualizações automatizadas para reduzir os CVEs. Após considerar cuidadosamente soluções para gerenciamento de dependências, começamos a trabalhar em uma infraestrutura auto-hospedada. Estávamos usando nosso próprio cluster Kubernetes para executar o Mend Renovate Community Self-Hosted. A ideia era fornecer uma plataforma de gerenciamento de dependências que nossos usuários pudessem acessar de forma autônoma.

O experimento inicial foi bem-sucedido, então mais e mais equipes começaram a integrar nossa plataforma e usá-la no ciclo de vida diário dos repositórios para atualizações e patches de CVE. Isso aconteceu tão rápido que logo chegamos ao limite da nossa instalação auto-hospedada.

O desafio: como podemos redimensionar uma plataforma de gerenciamento de dependências em uma grande organização com um número significativo de repositórios?

Nossa plataforma de gerenciamento de dependências estava processando um repositório por vez e o modelo de processamento sequencial não conseguia acompanhar, devido ao grande número de repositórios que possuímos. Já havíamos identificado que o problema residia no conceito de que uma única instância de nossa ferramenta de gerenciamento de dependências poderia processar nossa grande e crescente lista de repositórios. Repositórios aguardavam em uma fila, às vezes por muitas horas. Mais de 50% dos nossos repositórios nem sequer eram processados diariamente. Isso significa que mais de 50% dos nossos repositórios esperaram mais de 24 horas entre as varreduras.

Repositórios grandes criavam gargalos maiores, devido às bases de código consideráveis e aos múltiplos PRs abertos. Eventos do webhook do GitHub interromperam a sequência. O Automerge tornou-se não confiável porque o tempo de varredura era imprevisível. Fizemos uma promessa aos nossos usuários sobre a frequência dos escaneamentos, mas não conseguimos cumpri-la.

A decisão de criar internamente: atendendo às necessidades únicas de escala e segurança da Elastic

Enquanto considerávamos opções comerciais, incluindo a edição Mend's Renovate Self-Hosted Enterprise Self-Hosted, internamente na Elastic tivemos algumas iniciativas-chave em desenvolvimento.

Nossa decisão de criar uma plataforma interna foi motivada pelo reconhecimento de que somente uma solução personalizada poderia atender aos requisitos específicos e inegociáveis da Elastic:

1. Investindo em nossa plataforma interna de desenvolvedores: naquela época, já tínhamos começado a investir fortemente em nossa plataforma interna de desenvolvedores. Estávamos discutindo e projetando formas de como cada um dos nossos serviços poderia se encaixar nisso. Isso significava que queríamos testar nossas próprias regras e práticas para nossa plataforma de gerenciamento de dependências. Além disso, novas diretrizes estavam entrando em ação e queríamos projetar a plataforma antes dos eventos.

2. Integração nativa e personalização do fluxo de trabalho: precisávamos de uma integração direta com nossas ferramentas e processos internos. Por exemplo, queríamos centralizar a configuração como código com nosso Catálogo de serviços (Backstage). Temos necessidades específicas relacionadas ao uso do Backstage que queríamos tornar compatíveis com nossa plataforma. Portanto, embora fosse possível usar as APIs Renovate Self-Hosted junto com nossa automação Backstage, isso não cobriria totalmente nossos processos internos.

3. Segurança de defesa em profundidade específica da Elastic: nossa rigorosa conformidade de segurança exigiu mecanismos de segurança personalizados, adaptados ao nosso ecossistema. Estávamos trabalhando para fortalecer nosso uso de "identidades não humanas". A forma como esse reforço de acesso funcionava significava que os métodos não padronizados de autenticação no GitHub não funcionariam com uma ferramenta comercial que não suportasse essa implementação interna. Nosso fluxo de trabalho incluía a implementação de um padrão de criptografia secreta de fluxo de trabalho pai-filho e o uso de tokens transitórios e de uso único do GitHub. Criar internamente foi a única maneira prática de incorporar essas camadas de segurança exclusivas e minimizar a superfície de ataque em nosso complexo ambiente multinuvem.

A solução: orquestração de fluxo de trabalho para gerenciamento de dependências

Nossa solução começou com o fato de queríamos criar sobre a ferramenta de gerenciamento de dependências que já usávamos e não substituí-la, buscando outras soluções. Ela já demonstrava sinais de potencial, e a flexibilidade é importante para diferentes necessidades em toda a organização. Consideramos diferentes soluções, e o que nos ajudou a decidir foram as necessidades, às vezes grandes e especiais, que precisamos cobrir. Decidimos criar uma plataforma de gerenciamento de dependências confiável e escalável, na qual cada repositório será processado por conta própria, removendo gargalos e nos preparando para o crescimento.

Projetamos a plataforma seguindo três princípios fundamentais:

1. Processamento paralelo

Cada repositório recebe o próprio ambiente de processamento de gerenciamento de dependências. Não há mais filas. Nossa concorrência é limitada apenas pelo número de recursos que gastamos. Também aplicamos o agendamento distribuído inteligente para evitar que o GitHub limite a taxa.

2. Autoatendimento

Usamos nosso Catálogo de serviços (Backstage) para integrar e gerenciar automaticamente qualquer novo repositório. Usamos nossa própria definição de recursos para dar ao usuário final a opção de selecionar com que frequência um repositório será processado, quantos recursos deseja alocar para os cronogramas e se deseja desligar ou reativar o processamento por qualquer motivo. Planejamos adicionar mais opções assim conforme as necessidades dos nossos usuários evoluem e eles se familiarizam com a nova instalação.

3. Redução do escopo secreto e isolamento do espaço de nome

Para mais segurança, fornecemos aos nossos pods de gerenciamento de dependências tokens efêmeros do GitHub que são gerados no início de cada fluxo de trabalho. Além disso, isolamos nossas cargas de trabalho em espaços de nome específicos para que possam receber apenas os segredos necessários. Controlamos quais segredos podem ser acessados em cada fluxo de trabalho de gerenciamento de dependências usando o Kubernetes RBAC. Também usamos criptografia para propagar o token do GitHub do fluxo de trabalho pai para o filho.

Reconstruímos nossa plataforma usando e aproveitando o melhor de Kubernetes, do Argo Workflows que alimenta a lógica dos nossos processos, e a CLI do Renovate que está configurado para escanear e processar um repositório de cada vez.

A beleza: estamos utilizando projetos open source testados de forma inovadora, fornecendo novos exemplos práticos para todos esses projetos e, ao mesmo tempo, ampliando a velocidade de desenvolvimento e consolidando a redução de CVE para nossas equipes.

Arquitetura de gerenciamento de dependências: quatro microsserviços

A plataforma é composta por quatro componentes personalizados:

Operador de fluxos de trabalho (Go/Kubebuilder)

Um operador do Kubernetes gerenciando o ciclo de vida do fluxo de trabalho por meio de três definições de recursos personalizadas (CRDs):

• RepoConfig CRD: fonte única de verdade para configuração de repositórios.

É assim que o RepoConfig é definido no operador:

E essa é a aparência de uma instância do RepoConfig:

• CRD pai: gerencia os fluxos de trabalho do CronWorkflows para varreduras agendadas.

Dentro do loop de reconciliação do controlador principal, garantimos que as configurações de fluxo de trabalho sejam criadas e mantidas atualizadas ou até mesmo excluídas, se necessário.

Primeiro, ele recebe algumas configurações globalmente configuradas para fluxos de trabalho:

Ele garante que um mutex configmap esteja atualizado para evitar fluxos de trabalho semelhantes rodando juntos:

Depois, cria um Gerenciador de fluxo de trabalho que é a estrutura que criará ou atualizará os CronWorkflows e os Modelos de fluxo de trabalho:

• Child CRD: gerencia WorkflowTemplates com recursos por repositório.

O controlador filho tem uma função de reconciliação semelhante à do controlador pai, mas desta vez é responsável pelos modelos de fluxo de trabalho no espaço de nome filho que serão acionados pelos fluxos de trabalho pai.

O padrão multicontrolador proporciona separação clara: o RepoConfig Controller cuida do onboarding/offboarding, o Parent Controller gerencia o escalonamento e o Child Controller gerencia os templates de execução.

GitHub Events Gateway (Go)

Um proxy seguro de webhook que recebe webhooks do GitHub, verifica assinaturas, filtra por organização/repositório e direciona para os eventos do Argo. Criamos 10 sensores distintos que respondem a interações com dashboards de dependência, eventos de PR e atualizações de pacotes.

Esse gateway permite a integração com os apps do GitHub por meio de:

• Verificação de assinaturas de webhooks do GitHub recebidas para fins de segurança.

• Encaminhando eventos válidos para o Argo Events EventSource com todos os cabeçalhos e autenticação relevantes.

• Nós também configuramos um authSecret no EventSource e fornecemos isso como um cabeçalho Bearer nas requisições encaminhadas.

• Fornecer loggings, métricas e lógica de repetição.

Ele realiza diversas validações em cada solicitação de evento do GitHub.

Ele garante que alguns atributos HTTP estejam presentes:

Embora também valide a assinatura de cada solicitação e da organização.

Por fim, ele direciona para Argo Events com base no tipo de evento:

Do lado da Argo Events, 10 sensores observam o Argo Events EventBus para novos eventos:

Então, o script aplica a lógica de cada sensor:

Sincronizador de Backstage (Go)

Este procedimento consulta nosso Catálogo de serviços (Backstage) em busca de Entidades de recursos reais do repositório, transforma-as em CRDs do RepoConfig e mantém a plataforma sincronizada com as alterações de configuração. As alterações são aplicadas em três minutos.

Por fim, ele grava esses dados nas instâncias do RepoConfig.

Base de fluxos de trabalho (Misto: JavaScript, Go, Helm)

A camada fundamental contém gráficos Helm, configurações JavaScript, um wrapper Go para a CLI do Renovate com suporte a criptografia e um indexador de APK personalizado para pacotes Alpine.

Configuração de autoatendimento

As equipes configuram os repositórios de forma declarativa através do Backstage:

Grupos de recursos alocam CPU e memória com base no tamanho do repositório:

• PEQUENA: CPU de 500m, memória de 1Gi.

• MÉDIA: CPU de 1000m, memória 2Gi.

• GRANDE: CPU de 2000 m, memória de 4Gi.

A configuração é controlada por versão, auditável e aplicada automaticamente.

O padrão pai-filho

O modelo de execução utiliza um padrão de fluxo de trabalho pai-filho:

• Fluxo de trabalho pai: CronWorkflow leve executando conforme programado. Criptografa segredos, determina se uma verificação deve ser executada, passa a configuração para o filho.

• Fluxo de trabalho filho: pod efêmero onde a CLI do Renovate executa. Recursos alocados dinamicamente, descriptografam segredos isoladamente, encerram após a conclusão.

Essa separação oferece segurança (segredos criptografados no nível dos pais), otimização de recursos (os pais utilizam recursos mínimos) e escalabilidade (os filhos executam em paralelo).

Os resultados

Transformação de desempenho

• Antes: um repositório por vez, alguns repositórios não seriam processados, possivelmente nem mesmo por um dia ou mais, menos de 1.000 digitalizações por dia.

• Após: mais de 100 varreduras simultâneas, geralmente 8.000 varreduras e até 10.000 varreduras registradas por dia, limitadas apenas pela quantidade de recursos que estamos dispostos a investir e por como lidamos com os limites de taxa do GitHub.

Eficiência de custos

Por mais estranho que pareça, rodar 8.000 pods por dia pode te dar o mesmo resultado muito mais barato do que ter um pod de longa duração tentando alcançar os mesmos resultados.

Na configuração anterior, estávamos executando uma única instância que, em um bom dia, realizaria de 500 a 600 verificações. Ao mesmo tempo, devido ao fato de que diferentes tipos de repositórios seriam executados no mesmo pod, precisávamos dimensionar o pod para os maiores. Esse tamanho seria muito maior do que nossa oferta extra grande atual, usando 8 CPUs para o pod e 16G de memória.

Para atender à saída diária atual, o pod único precisaria executar por 12 dias. Então, comparando o custo desse único pod funcionando por 12 dias com 8.000 pods do nosso tamanho “MÉDIO” funcionando todos os dias, nosso novo design é muito mais eficiente para a mesma saída de escaneamentos:

Métrica

Cenário A (Fluxos de trabalho)

Cenário B (O único pod de longa duração)

Configuração

8.000 pods (1 vCPU / 2 GB)

1 pod (8 vCPU / 16 GB)*

Duração

10 minutos cada

12 dias contínuos

Tempo total de trabalho

1.333 horas de computação

288 horas de computação

Custo total

$ 65,83

$ 113,75

No entanto, vamos levar em consideração que nossa configuração padrão para nossas cargas de trabalho está definida como "PEQUENA", com a grande maioria funcionando com sucesso com 0,5 CPU e 1 GB de RAM, e apenas algumas precisam ser alteradas para média ou grande. Vamos ver o que acontece se 60% das nossas cargas de trabalho rodarem em "PEQUENA", 30% em "MÉDIA" e 10% em "GRANDE", o que está mais próximo da verdade.

Métrica

Cenário A (Enxame misto)

Cenário B (O de longa duração)

Estratégia

8.000 pods (tamanhos variados)

1 pod (8 vCPU / 16 GB)*

Duração

10 minutos cada

12 dias contínuos

Custo total

$ 52,66

$ 113,75

Economia

$ 61,09 (54% mais barato)

—

Podemos ver que, para a mesma saída, somos muito mais econômicos em nosso sistema atual.

Segurança aprimorada

• Tokens efêmeros do GitHub (minutos de exposição versus dias).

• Isolamento de espaço de nome com limites de Controle de acesso por função (RBAC).

• Criptografia de segredos em repouso nos fluxos de trabalho principais.

• Acesso direto ao cofre removido.

Desempenho previsível

Com frequência de varredura garantida, finalmente podemos definir Objetivos de nível de serviço (SLOs). A automerge funciona de forma confiável. As equipes confiam que a plataforma vai entregar o que é prometido.

Principais decisões arquitetônicas

Aqui estão algumas das principais decisões de design que moldaram a aparência da plataforma.

• Por que fluxos de trabalho pai-filho?

Adotamos esse padrão para implementar uma estratégia de defesa em profundidade. Ao restringir credenciais de alto valor (como segredos de app GitHub) a um espaço de nome dedicado e bloqueado, utilizamos RBAC para garantir que pods de execução efêmeros não possam acessar arbitrariamente dados sensíveis. Vulnerabilidades recentes na cadeia de suprimentos (por exemplo, os ataques de integração contínua/entrega contínua [CI/CD] "Shai Hulud") demonstraram a importância crítica de isolar os ambientes de execução que executam scripts dinâmicos do repositório de credenciais.

Ao mesmo tempo, essa dissociação permite a otimização granular de recursos. Os fluxos de trabalho "pai" atuam como orquestradores leves com um espaço mínimo, enquanto os fluxos de trabalho "filho" lidam com a verificação de dependências com uso intensivo de computação. Essa separação simplifica gestão de ciclo de vida, permitindo aplicar uma lógica de reconciliação distinta a cada camada, concedendo aos usuários controle sobre os parâmetros de execução (camada filha) e, ao mesmo tempo, mantendo o controle administrativo sobre a infraestrutura de agendamento e segurança (camada pai).

• Por que é do tipo autoatendimento?

Eliminar nossa equipe como gargalo para a configuração do repositório era uma exigência crítica. Nossa missão era arquitetar uma plataforma escalável e de autoatendimento compatível com diversos casos de uso. Reconhecemos que atuar como guardiões de cada alteração de configuração era insustentável, dado o grande volume de repositórios. Em vez disso, adotamos uma filosofia de capacitação: fornecer os "trilhos" (infraestrutura e proteções) e capacitar os usuários a conduzir os "trens" (execução e personalização). Acreditamos que essa mudança em direção à autonomia da equipe aumenta significativamente a produtividade, permitindo que os usuários adaptem o sistema às suas necessidades operacionais específicas.

• Por que o padrão Operator do Kubernetes?

Como mencionado acima, um princípio fundamental de design era garantir que a plataforma fosse totalmente autoatendida. Precisávamos de um mecanismo automatizado para capturar a intenção do usuário (como alternar varreduras, ajustar a frequência de agendamento ou ajustar limites de recursos em tempo de execução) e propagar instantaneamente essas mudanças para os fluxos de trabalho subjacentes. Antecipando requisitos futuros, o sistema também precisava ser facilmente extensível.

Para alcançar esse objetivo, desenvolvemos um operador Kubernetes personalizado para gerenciamento de dependências. Ao usar CRDs como interface de configuração, estabelecemos um ciclo de reconciliação nativo do Kubernetes. Este operador monitora continuamente o estado desejado definido pelo usuário e orquestra automaticamente as atualizações necessárias na infraestrutura do fluxo de trabalho. Isso garante uma operação perfeita e orientada a eventos, onde a lógica da plataforma lida com toda a complexidade nos bastidores.

• Por que projetar um GitHub Events Gateway?

Adotar uma arquitetura orientada a eventos (EDA) foi essencial para a capacidade de resposta da plataforma. Embora os fluxos de trabalho do CronWorkflows fornecessem uma programação de linha de base confiável, precisávamos de agilidade para lidar com execuções ad hoc, como usuários acionando varreduras manualmente por meio do dashboard. Para isso, precisávamos de um gateway de ingestão dedicado para validar a integridade da carga útil e rotear as solicitações de forma inteligente.

Avaliamos as soluções existentes, incluindo o EventSource nativo do GitHub para Argo, mas identificamos riscos significativos relacionados à sobrecarga operacional e às rígidas cotas da API do GitHub (por exemplo, limites de webhook por repositório). Consequentemente, construímos um gateway personalizado para desacoplar nossa infraestrutura dessas limitações.

Fundamentalmente, esse gateway serviu como um ponto estratégico de controle de tráfego durante nossa migração. Ele funcionou como um switch, permitindo que realizássemos uma implementação gradual e granular (mudança de tráfego) do sistema legado para a nova infraestrutura. Isso garantiu que a integração de milhares de repositórios fosse um processo controlado e sem riscos, e não uma transição de "big bang".

Lições aprendidas

Algumas lições que aprendemos andam de mãos dadas com o Elastic Source Code:

1. O cliente em primeiro lugar: as plataformas são criadas para os usuários. Por isso, é importante ter as necessidades dos usuários como prioridade. Isso molda a plataforma em infraestrutura e aplicativos projetados de forma eficiente, que reduzem o atrito com os usuários, simplificam a escalabilidade da plataforma e facilitam a adoção.

2. Espaço, tempo: às vezes, o caminho de menor resistência leva a areias movediças. Inicialmente, tentamos otimizar o modelo de processamento sequencial existente, mas isso não resolveu nossos problemas; na verdade, ele apenas introduziu mais complexidade e pontas soltas. A ousada decisão de reestruturar a plataforma com processamento paralelo exigiu um esforço inicial significativo. No entanto, isso acabou abrindo caminho para um crescimento sustentável da plataforma e praticamente eliminou o trabalho administrativo diário tedioso.

3. TI, depende: uma plataforma não pode operar isoladamente; o sucesso depende de quão bem ela se integra ao ecossistema mais amplo. Em nosso caso, a integração com o Backstage foi fundamental, pois ele serve como a fonte da verdade para a integração perfeita de serviços. Da mesma forma, a conexão com o Artifactory nos permitiu gerenciar com eficiência as atualizações de pacotes privados, e a lista de integrações essenciais continua.

4. Progresso, perfeição SIMPLES: durante toda a implementação, testamos constantemente nossas suposições iniciais e nos adaptamos a novas barreiras à medida que elas surgiam. Em vez de ficarmos paralisados pelo perfeccionismo, adotamos uma abordagem iterativa, enfrentando desafios um a um e ajustando nossa estratégia migratória para atender às condições do mundo real.

O que vem a seguir

A entrega da plataforma nos permite realizar trabalhos mais significativos que ajudarão a melhorar a experiência do usuário e a eficiência da nossa plataforma. Alguns exemplos são:

• Aumentar e colocar proteções na adoção do auto-merge

O recurso de auto-merge acelera significativamente a velocidade da equipe ao eliminar tarefas manuais tediosas. No entanto, precisamos nos certificar de que existam proteções rígidas para garantir que esse aumento de velocidade não prejudique a segurança.

• Melhorar a observabilidade da experiência do usuário final

Uma prioridade crítica para nosso roadmap é aprimorar a observabilidade, não apenas no nível da plataforma, mas também especificamente da perspectiva do usuário final. Embora a captura de métricas de infraestrutura seja simples, entender a experiência real do usuário exige insights mais profundos. Estamos trabalhando para definir os indicadores-chave de desempenho centrados no usuário do núcleo (KPIs) para que nossa telemetria possa detectar pontos de atrito e problemas de desempenho antes que eles se transformem em reclamações dos usuários.

• Remova obstáculos para a adoção

Vislumbrando o futuro, nossa prioridade é identificar e remover quaisquer barreiras que dificultem a adoção da plataforma. Seja desenvolvendo novas integrações ou implantando conjuntos específicos de recursos, estamos comprometidos com o planejamento orientado por dados. Criamos uma plataforma projetada para escalabilidade; nosso foco agora se volta para maximizar o potencial.

O panorama maior

O projeto de fluxos de trabalho de gerenciamento de dependências demonstra um princípio mais amplo: quando você precisa redimensionar ferramentas open source além do modelo de implantação padrão, os padrões nativos do Kubernetes fornecem um caminho a seguir.

Ao adotar:

• CRDs para configuração.

• Operadores para gestão de ciclo de vida.

• Arquitetura orientada por eventos para capacidade de resposta

• GitOps para implantação.

Criamos uma orquestração que se redimensiona independentemente do número de repositórios que gerencia. O desempenho da varredura de um repositório é o mesmo, independentemente de estarmos gerenciando 100 ou 1.000.

Quando um CVE crítico é anunciado, agora temos respostas em minutos, não em horas. Essa é a diferença entre um gargalo e uma vantagem competitiva.

Agradecimentos

Esta plataforma utiliza excelentes ferramentas open source:

• Kubebuilder: o framework open source que usamos para iniciar nossos operadores Kubernetes que inicializam e orquestram nossos fluxos de trabalho. [1][2]

• Backstage: o open source framework no qual construímos nosso Catálogo de serviços e que usamos como nossa versão final. [1][2]

• Argo Workflows e Argo Events: a open source suíte que usamos para orquestrar processos complexos e adicionar processamento dinâmico baseado em eventos. [1][2][3][4]

• CLI do Renovate: a ferramenta de gerenciamento de dependências de open source que processa nossos repositórios. [1][2]

* O modelo de preços do AWS Fargate foi usado como referência para o custo de um único pod, embora nossas cargas de trabalho não estejam necessariamente sendo executadas na AWS, mas sim em clusters Kubernetes completos.

Além disso, esses casos de uso geralmente são sensíveis ao tempo, e passar pelas etapas típicas de desenvolvimento (criar uma ramificação de código e depois esperar por um novo lançamento) é um processo demorado.

E se pudéssemos realizar todo esse processo com apenas uma chamada de API, ou melhor ainda, com apenas alguns cliques no Kibana?

Interface do usuário de regras de consulta

O Elasticsearch 8.10 introduziu as Regras de Consulta e o Recuperador de Regras. São ferramentas projetadas para inserir resultados fixados nas consultas sem afetar a classificação dos resultados orgânicos com base em regras. Eles apenas adicionam lógica de negócios aos resultados de forma declarativa e simples.

Alguns casos de uso comuns para regras de consulta são:

• Destacar anúncios ou promoções: Exibir itens em promoção ou patrocinados no topo.

• Exclusão por contexto ou geolocalização: Ocultar determinados itens quando as regulamentações locais não permitem que você os mostre.

• Priorizar resultados-chave: Garantir que as pesquisas populares ou fixas estejam sempre no topo, independentemente do ranking orgânico.

Para acessar a interface e interagir com essas ferramentas, você precisa clicar no menu lateral do Kibana e ir para Regras de Consulta, em Relevância:

Assim que o menu de regras de consulta aparecer, clique em Criar seu primeiro conjunto de regras:

Em seguida, você precisa dar um nome ao seu conjunto de regras.

O formulário para definir cada regra possui três componentes principais:

• Critérios: As condições que devem ser cumpridas para que a regra se aplique. Por exemplo, “quando o campo query_string contém o valor Christmas” ou “quando o campo country é CO”.

• Ação: Isto é o que você deseja que aconteça quando as condições forem atendidas. Ele pode ser fixado (fixando um documento nos primeiros resultados) ou excluído (ocultando um documento).

• Metadados: São os campos que acompanham a consulta quando ela é executada. Podem incluir informações do usuário (como localização ou idioma), bem como dados de pesquisa (query_string). Esses são os valores usados pelos critérios para decidir se uma regra deve ou não ser aplicada.

Exemplo: itens populares

Vamos imaginar que temos um site de comércio eletrônico com diversos itens. Ao analisarmos as métricas, notamos que um dos itens mais vendidos na categoria de consoles é o "Controle sem fio DualShock 4", especialmente quando os usuários pesquisam pelas palavras-chave "PS4" ou "PlayStation 4". Assim, decidimos colocar este produto no topo dos resultados, sempre que um usuário pesquisar por essas palavras-chave.

Primeiro, vamos indexar os documentos de cada item usando uma solicitação de API em lote:

Se não intervirmos na consulta, o item geralmente aparece em quarto lugar. Eis a pergunta:

E aqui estão os resultados.

Vamos criar uma regra de consulta para alterar isso. Primeiro, vamos adicioná-lo ao conjunto de regras assim:

Ou solicitação de API equivalente:

Para usar o conjunto de regras em nossa consulta, devemos usar um tipo de regra de consulta. Esse tipo de consulta é composto por duas partes principais:

• match_criteria: São os metadados usados para comparar com a consulta do usuário. Neste exemplo, o conjunto de regras é ativado quando o campo query_string tem o valor “PlayStation 4”.

• consulta: a consulta propriamente dita que será usada para pesquisar e obter os resultados orgânicos.

Dessa forma, primeiro você executa a consulta orgânica e, em seguida, o Elasticsearch aplica as regras do seu conjunto de regras:

Exemplo: metadados baseados no usuário

Outra aplicação interessante das Regras de Consulta é usar metadados para exibir documentos específicos com base em informações contextuais do usuário ou da página da web.

Por exemplo, vamos supor que queremos destacar itens ou ofertas personalizadas com base no nível de fidelidade do usuário, representado por um valor numérico.

Podemos fazer isso inserindo esses metadados diretamente na consulta, de forma que as regras sejam ativadas quando o valor atender a determinados critérios.

Primeiro, vamos indexar um documento que somente usuários com um alto nível de fidelidade podem ver:

Agora, vamos criar uma nova regra dentro do mesmo conjunto de regras para que, quando o nível de lealdade for igual ou superior a 80, o item apareça no topo dos resultados.

Salve a regra e o conjunto de regras.

Aqui está a solicitação REST equivalente:

Agora, ao executar uma consulta, precisamos incluir o novo parâmetro loyalty_level nos metadados. Se a condição da regra for atendida, o novo documento aparecerá no topo dos resultados.

Por exemplo, ao enviar uma consulta onde o nível de lealdade é 80:

Veremos o documento de fidelidade acima dos resultados:

No caso abaixo, como o nível de fidelidade é 70, a regra não é atendida e o item não deve aparecer no topo:

Aqui estão os resultados:

Exemplo: exclusão imediata

Vamos supor que nosso Controle Sem Fio DualShock 4 (ID 2) esteja temporariamente indisponível e não possa ser vendido. Assim, em vez de excluir o documento manualmente ou esperar que algum processamento de dados seja iniciado, a equipe comercial decide removê-lo dos resultados da pesquisa enquanto isso.

Usaremos um processo semelhante ao que acabamos de aplicar aos itens populares, mas desta vez, em vez de selecionar "Fixados", escolheremos "Excluir". Essa regra funciona como uma espécie de lista negra. Altere os critérios para "Sempre" para que a exclusão funcione sempre que a consulta for executada.

A regra deve ser assim:

Salve a regra e o conjunto de regras para aplicar as alterações. Aqui está a solicitação REST equivalente:

Agora, ao executar a consulta novamente, você verá que o item não está mais nos resultados, mesmo que a regra anterior fosse fixá-lo. Isso ocorre porque as exclusões têm prioridade sobre a fixação dos resultados.

Conclusão

As regras de consulta tornam muito fácil ajustar a relevância sem qualquer alteração de código. A nova interface do Kibana permite que vocêPara fazer essas alterações em questão de segundos, você e sua equipe terão mais controle sobre os resultados da pesquisa.

Além do comércio eletrônico, as Regras de Consulta podem ser aplicadas em muitos outros cenários: destacar guias de solução de problemas em portais de suporte, exibir documentos internos importantes em bases de conhecimento, promover notícias de última hora em sites de notícias ou filtrar anúncios de emprego ou conteúdo expirados. Eles podem até mesmo impor regras de conformidade, como ocultar material restrito por função de usuário ou região.

Neste blog, usaremos o Mastra para construir um agente de conhecimento que memoriza o que os usuários dizem e consegue recuperar informações relevantes posteriormente, utilizando o Elasticsearch como backend de memória e recuperação. Você pode facilmente estender esse mesmo conceito a casos de uso do mundo real, como agentes de suporte que conseguem se lembrar de conversas e soluções anteriores, permitindo que eles personalizem as respostas para usuários específicos ou apresentem soluções mais rapidamente com base no contexto prévio.

Acompanhe aqui como construir isso passo a passo. Se você se perder ou simplesmente quiser executar um exemplo finalizado, confira o repositório aqui.

O que é Mastra?

Mastra é um framework TypeScript de código aberto para a construção de agentes de IA com componentes intercambiáveis para raciocínio, memória e ferramentas. Seu recurso de recuperação semântica permite que os agentes se lembrem e recuperem interações passadas, armazenando mensagens como representações vetoriais em um banco de dados vetorial. Isso permite que os agentes mantenham o contexto e a continuidade da conversa a longo prazo. O Elasticsearch é um excelente armazenamento de vetores para habilitar esse recurso, pois oferece suporte a buscas vetoriais densas e eficientes. Quando a recuperação semântica é acionada, o agente extrai mensagens relevantes do passado para a janela de contexto do modelo, permitindo que o modelo use esse contexto recuperado como base para seu raciocínio e respostas.

O que você precisa para começar

• Node v18+

• Elasticsearch (versão 8.15 ou mais recente)

• Chave da API do Elasticsearch

• Chave da API OpenAI

Observação: você precisará disso porque a demonstração usa o provedor OpenAI, mas o Mastra é compatível com outros SDKs de IA e provedores de modelos da comunidade, então você pode facilmente trocá-lo dependendo da sua configuração.

Construindo um projeto Mastra

Usaremos a CLI integrada do Mastra para fornecer a estrutura básica do nosso projeto. Execute o comando:

Você receberá uma série de instruções, começando com:

1. Dê um nome ao seu projeto.

2. Podemos manter esta opção padrão; fique à vontade para deixar este campo em branco.

3. Para este projeto, usaremos um modelo fornecido pela OpenAI.

4. Selecione a opção “Ignorar por enquanto”, pois armazenaremos todas as nossas variáveis de ambiente em um arquivo `.env` que configuraremos em uma etapa posterior.

5. Também podemos ignorar esta opção.

Assim que a inicialização estiver concluída, podemos passar para a próxima etapa.

Instalando dependências

Em seguida, precisamos instalar algumas dependências:

• ai - Pacote Core AI SDK que fornece ferramentas para gerenciar modelos de IA, prompts e fluxos de trabalho em JavaScript/TypeScript. O Mastra é construído sobre o SDK de IA da Vercel, portanto, precisamos dessa dependência para permitir as interações do modelo com o seu agente.

• @ai-sdk/openai - Plugin que conecta o SDK de IA aos modelos da OpenAI (como GPT-4, GPT-4o, etc.), permitindo chamadas à API usando sua chave de API da OpenAI.

• @elastic/elasticsearch - Cliente oficial do Elasticsearch para Node.js, Utilizado para conectar-se ao seu Elastic Cloud ou cluster local para indexação, pesquisa e operações vetoriais.

• dotenv - Carrega variáveis de ambiente de um arquivo .env arquivo em process.env, permitindo que você insira credenciais com segurança, como chaves de API e endpoints do Elasticsearch.

Configurando variáveis de ambiente

Crie um arquivo .env no diretório raiz do seu projeto, caso ainda não exista um. Alternativamente, você pode copiar e renomear o exemplo .env que eu forneci no repositório. Neste arquivo, podemos adicionar as seguintes variáveis:

Isso conclui a configuração básica. A partir daqui, você já pode começar a construir e orquestrar agentes. Vamos dar um passo além e adicionar o Elasticsearch como camada de armazenamento e busca vetorial.

Adicionando o Elasticsearch como armazenamento vetorial.

Crie uma nova pasta chamada stores e, dentro dela, adicione este arquivo. Antes que a Mastra e a Elastic lancem uma integração oficial de armazenamento vetorial do Elasticsearch, Abhi Aiyer(CTO da Mastra) compartilhou esta classe protótipo inicial chamada ElasticVector. Em termos simples, ele conecta a abstração de memória do Mastra aos recursos de vetores densos do Elasticsearch, permitindo que os desenvolvedores utilizem o Elasticsearch como banco de dados de vetores para seus agentes.

Vamos analisar mais detalhadamente as partes importantes da integração:

Ingestão do cliente Elasticsearch

Esta seção define a classe ElasticVector e configura a conexão do cliente Elasticsearch com suporte para implantações padrão e sem servidor.

• ElasticVectorConfig extends ClientOptionsIsso cria uma nova interface de configuração que herda todas as opções do cliente Elasticsearch (como node, auth, requestTimeout) e adiciona nossas propriedades personalizadas. Isso significa que os usuários podem passar qualquer configuração válida do Elasticsearch juntamente com nossas opções específicas para ambientes sem servidor.

• extends MastraVectorIsso permite que ElasticVector herde da classe base MastraVector do Mastra, que é uma interface comum à qual todas as integrações de armazenamento vetorial estão em conformidade. Isso garante que o Elasticsearch se comporte como qualquer outro backend vetorial do Mastra da perspectiva do agente.

• private client: ClientEsta é uma propriedade privada que contém uma instância do cliente JavaScript do Elasticsearch. Isso permite que a classe se comunique diretamente com o seu cluster.

• isServerless e deploymentChecked: Essas propriedades funcionam em conjunto para detectar e armazenar em cache se estamos conectados a uma implantação do Elasticsearch sem servidor ou padrão. Essa detecção ocorre automaticamente no primeiro uso ou pode ser configurada explicitamente.

• constructor(config: ClientOptions): Este construtor recebe um objeto de configuração (contendo suas credenciais do Elasticsearch e configurações opcionais sem servidor) e o usa para inicializar o cliente na linha this.client = new Client(config).

• super()Isso chama o construtor base do Mastra, portanto, ele herda o registro de logs, os auxiliares de validação e outros recursos internos.

Neste ponto, Mastra sabe que existe uma nova loja de vetores chamada ElasticVector

Detecção do tipo de implantação

Antes de criar os índices, o adaptador detecta automaticamente se você está usando o Elasticsearch padrão ou o Elasticsearch Serverless. Isso é importante porque as implantações sem servidor não permitem a configuração manual de shards.

O que está acontecendo:

• Primeiro verifica se você definiu explicitamente isServerless na configuração (ignora a detecção automática).

• Chama a API info() do Elasticsearch para obter informações do cluster.

• Verifica o build_flavor field (implantações sem servidor retornam serverless)

• Se a opção de build não estiver disponível, a solução é verificar a descrição da versão.

• Armazena o resultado em cache para evitar chamadas repetidas à API.

• Se a detecção falhar, a implantação padrão será utilizada por padrão.

Exemplo de uso:

Criando o armazenamento de “memória” no Elasticsearch

A função abaixo configura um índice Elasticsearch para armazenar embeddings. Verifica se o índice já existe. Caso contrário, cria um com o mapeamento abaixo que contém um campo dense_vector para armazenar embeddings e métricas de similaridade personalizadas.

Algumas coisas a ter em conta:

• O parâmetro dimension representa o comprimento de cada vetor de incorporação, que depende do modelo de incorporação que você está usando. Em nosso caso, geraremos embeddings usando o modelo text-embedding-3-small da OpenAI, que produz vetores de tamanho 1536. Usaremos esse valor como padrão.

• A variável similarity usada no mapeamento abaixo é definida pela função auxiliar const similarity = this.mapMetricToSimilarity(metric), que recebe o valor do parâmetro metric e o converte em uma palavra-chave compatível com o Elasticsearch para a métrica de distância escolhida.

  • Por exemplo: Mastra usa termos gerais para similaridade de vetores como cosine, euclidean e dotproduct. Se passássemos a métrica euclidean diretamente para o mapeamento do Elasticsearch, ele geraria um erro porque o Elasticsearch espera que a palavra-chave l2_norm represente a distância euclidiana.

• Compatibilidade com ambientes sem servidor: o código omite automaticamente as configurações de shard e réplica para implantações sem servidor, pois estas são gerenciadas automaticamente pelo Elasticsearch Serverless.

Armazenar uma nova memória ou anotação após uma interação.

Esta função recebe novos embeddings gerados após cada interação, juntamente com os metadados, e os insere ou atualiza no índice usando a API bulk do Elastic. A API bulk agrupa várias operações de gravação em uma única solicitação; essa melhoria no desempenho de indexação garante que as atualizações permaneçam eficientes à medida que a memória do nosso agente continua a crescer.

Consultar vetores semelhantes para recuperação semântica

Essa função é o núcleo do recurso de recuperação semântica. O agente utiliza a busca vetorial para encontrar incorporações armazenadas semelhantes em nosso índice.

Por dentro do capô:

• Executa uma consulta kNN (k-vizinhos mais próximos) usando a API knn no Elasticsearch.

• Recupera os K vetores mais semelhantes ao vetor de consulta de entrada.

• Opcionalmente, aplica filtros de metadados para refinar os resultados (por exemplo, pesquisar apenas dentro de uma categoria ou intervalo de tempo específico).

• Retorna resultados estruturados, incluindo o ID do documento, a pontuação de similaridade e os metadados armazenados.

Criando o agente de conhecimento

Agora que vimos a conexão entre Mastra e Elasticsearch por meio da integração ElasticVector , vamos criar o próprio Agente de Conhecimento.

Dentro da pasta agents, crie um arquivo chamado knowledge-agent.ts. Podemos começar conectando nossas variáveis de ambiente e inicializando o cliente Elasticsearch.

Aqui, nós:

• Use dotenv para carregar nossas variáveis do nosso arquivo .env .

• Verifique se as credenciais do Elasticsearch estão sendo inseridas corretamente e, em seguida, poderemos estabelecer uma conexão bem-sucedida com o cliente.

• Passe o endpoint do Elasticsearch e a chave da API para o construtor ElasticVector para criar uma instância do nosso armazenamento de vetores que definimos anteriormente.

• Opcionalmente, especifique isServerless: true se estiver usando o Elasticsearch Serverless. Isso elimina a etapa de detecção automática e melhora o tempo de inicialização. Caso seja omitido, o adaptador detectará automaticamente o seu tipo de implantação na primeira utilização.

Em seguida, podemos definir o agente usando a classe Agent do Mastra.

Os campos que podemos definir são:

• name e instructions: Dê a ele uma identidade e uma função primária.

• modelEstamos usando o gpt-4o da OpenAI por meio do pacote @ai-sdk/openai .

• memory:

  • vector: Aponta para o nosso armazenamento Elasticsearch, de onde os embeddings são armazenados e recuperados.

  • embedderQual modelo usar para gerar embeddings?

  • semanticRecall As opções definem como funciona o recall:

    • topKQuantas mensagens semanticamente semelhantes devem ser recuperadas?

    • messageRange: Qual a extensão da conversa a ser incluída em cada interação?

    • scopeDefine o limite da memória.

Quase pronto. Basta adicionarmos esse agente recém-criado à nossa configuração do Mastra. No arquivo chamado index.ts, importe o agente de conhecimento e insira-o no campo agents .

Os outros campos incluem:

• storageEste é o repositório de dados interno do Mastra para histórico de execuções, métricas de observabilidade, pontuações e caches. Para obter mais informações sobre o sistema de armazenamento Mastra, visite aqui.

• loggerO Mastra utiliza o Pino, que é um registrador JSON estruturado e leve. Ele registra eventos como início e término de agentes, chamadas e resultados de ferramentas, erros e tempos de resposta do LLM.

• observabilityControla o rastreamento de IA e a visibilidade da execução de agentes. Ele rastreia:

  • Início/fim de cada etapa de raciocínio.

  • Qual modelo ou ferramenta foi utilizada?

  • Entradas e saídas.

  • Pontuações e avaliações

Testando o agente com o Mastra Studio

Parabéns! Se você chegou até aqui, está pronto para executar este agente e testar suas capacidades de recuperação semântica. Felizmente, o Mastra oferece uma interface de chat integrada, então não precisamos criar a nossa própria.

Para iniciar o servidor de desenvolvimento do Mastra, abra um terminal e execute o seguinte comando:

Após a inicialização e o empacotamento iniciais do servidor, você deverá receber um endereço para o Playground.

Cole este endereço no seu navegador e você será direcionado para o Mastra Studio.

Selecione a opção knowledgeAgent e comece a conversar.

Para um teste rápido para verificar se tudo está conectado corretamente, forneça algumas informações como: "A equipe anunciou que o desempenho de vendas em outubro aumentou 12%, impulsionado principalmente por renovações de contratos corporativos." O próximo passo é expandir o alcance aos clientes de médio porte.” Em seguida, inicie um novo bate-papo e faça uma pergunta como: "Em qual segmento de clientes dissemos que precisamos nos concentrar a seguir?" O agente de conhecimento deve ser capaz de recordar as informações que você lhe forneceu na primeira conversa. Você deverá ver uma resposta semelhante a esta:

Ao recebermos uma resposta como essa, significa que o agente armazenou com sucesso nossa mensagem anterior como embeddings no Elasticsearch e a recuperou posteriormente usando a busca vetorial.

Inspecionando o armazenamento de memória de longo prazo do agente.

Acesse a aba memory na configuração do seu agente no Mastra Studio. Isso permite que você veja o que seu agente aprendeu ao longo do tempo. Cada mensagem, resposta e interação que é incorporada e armazenada no Elasticsearch passa a fazer parte dessa memória de longo prazo. Você pode realizar buscas semânticas em interações passadas para encontrar rapidamente informações ou contextos que o agente aprendeu anteriormente. Este é essencialmente o mesmo mecanismo que o agente usa durante a recuperação semântica, mas aqui você pode inspecioná-lo diretamente. No exemplo abaixo, estamos pesquisando o termo "vendas" e obtendo como resultado todas as interações que incluíram algo relacionado a vendas.

Conclusão

Ao conectar o Mastra e o Elasticsearch, podemos fornecer memória aos nossos agentes, o que é uma camada fundamental na engenharia de contexto. Com a recuperação semântica, os agentes podem construir contexto ao longo do tempo, fundamentando suas respostas no que aprenderam. Isso significa interações mais precisas, confiáveis e naturais.

Essa integração inicial é apenas o ponto de partida. O mesmo padrão pode permitir que agentes de suporte se lembrem de chamados anteriores, bots internos recuperem documentação relevante ou assistentes de IA consigam recordar detalhes do cliente no meio da conversa. Também estamos trabalhando para uma integração oficial com o Mastra, tornando essa combinação ainda mais perfeita em um futuro próximo.

Estamos ansiosos para ver o que você vai construir em seguida. Experimente, explore o Mastra e seus recursos de memória e sinta-se à vontade para compartilhar suas descobertas com a comunidade.