Acervo original preservado

Este conteúdo histórico pode conter propostas ou instruções anteriores ao checkout atual. Consulte Arquitetura para o comportamento documentado e Tutoriais para as ressalvas operacionais.

Ambiente e limites da evidência histórica

Configurações e medições locais não comprovam ambientes corporativos. Propostas e menções históricas a produção não foram verificadas em DEV, STAGING ou PROD. Consulte Ambientes corporativos para o que está confirmado.

Arquitetura - Catálogo de Gateways¶

Objetivo¶

Definir a arquitetura responsável pela implementação do Catálogo de Gateways, permitindo que determinados usuários publiquem gateways reutilizáveis para que outros tenants possam criar instâncias desses gateways de forma padronizada e controlada.

Visão Geral¶

O Catálogo de Gateways permitirá que usuários com permissões específicas criem um Gateway Template, que poderá ser publicado para utilização pelos demais tenants da plataforma.

Após publicado, qualquer tenant poderá assumir esse template, gerando uma instância própria do gateway em seu ambiente. A partir desse momento, o gateway passa a pertencer exclusivamente ao tenant consumidor, mantendo apenas a referência ao template de origem.

O objetivo é permitir a distribuição de integrações padronizadas, reduzindo o esforço de configuração manual e promovendo reutilização entre tenants.

Características¶

Apenas usuários com as roles apropriadas poderão criar e publicar Gateway Templates.
Templates sempre estarão associados a aplicações do iPaaS.
Nesta primeira versão não haverá associação com Diagramas.
Templates possuirão versionamento utilizando a mesma estratégia já existente para Gateways.
Além dos status existentes, será introduzido o status Deprecated (Desuso).
- Versões marcadas como Deprecated não poderão mais ser publicadas.
- Também não poderão ser utilizadas para criação de novas instâncias.
- Gateways já criados anteriormente permanecem funcionando normalmente.

Decisões de Arquitetura¶

Controle de acesso utilizando Roles no BFF¶

Objetivo¶

Centralizar no BFF toda a resolução de identidade do usuário e autorização para acesso aos endpoints do Control Plane.

Fluxo¶

Quando uma requisição chegar ao BFF:

O token JWT será validado.
Serão extraídos:
issuer
subject
tenant/company
Será consultado o cache local.
Caso não exista em cache, será realizada consulta à API do iPaaS para localizar o usuário.
Caso o usuário ainda não exista no iPaaS, ele será criado automaticamente utilizando as roles padrão configuradas.
O resultado ficará disponível para utilização durante toda a requisição.

A identidade resolvida passa a conter informações como:

{
    "tenantId": "abc",
    "issuer": "https://idp.com",
    "externalSubject": "123",
    "roles": [
        "GATEWAY_ADMIN",
        "CATALOG_MANAGER"
    ],
    "status": "ACTIVE"
}

A chave de resolução do usuário será composta por:

tenantId:issuer:subject

Autorização dos Endpoints¶

Após a resolução da identidade, os endpoints do BFF passarão a utilizar o mecanismo de segurança nativo do Quarkus.

Exemplos:

@Authenticated
@RolesAllowed
Endpoints públicos

Dessa forma a autorização deixa de ser implementada manualmente em cada endpoint, passando a utilizar um mecanismo único e padronizado.

Modelagem do Banco de Dados¶

Toda a configuração completa dos Gateway Templates permanecerá armazenada no banco de dados do tenant.

No banco do tenant serão adicionadas as seguintes collections:

gateway_templates
gateway_template_revisions
route_templates
route_template_revisions

A estrutura foi projetada para manter o máximo de compatibilidade possível com a modelagem já existente de Gateways e Rotas, reduzindo duplicação de regras de negócio e facilitando a reutilização da lógica de versionamento.

Principais diferenças entre Gateway e Gateway Template¶

Embora a maior parte da estrutura seja equivalente, existem diferenças importantes relacionadas às configurações que dependem do ambiente consumidor.

As propriedades abaixo deixam de representar configurações prontas e passam a representar definições de configuração obrigatória durante a criação da instância:

Authentication
IP Policy
Rate Limit

Em vez de armazenarem apenas a configuração definitiva, esses objetos também passam a informar como deverão ser configurados pelo usuário durante a geração da instância do gateway.

Exemplo:

tipo de autenticação permitido
necessidade de seleção pelo usuário
política de herança
obrigatoriedade da configuração

Template Setups¶

A collection gateway_template_revisions possuirá uma nova propriedade denominada:

templateSetups

Essa estrutura representa todas as configurações obrigatórias que deverão ser preenchidas durante a criação de uma instância do Gateway Template.

Cada item possui:

Campo	Descrição
targetObjectPath	Caminho do atributo que será configurado
required	Indica se a configuração é obrigatória
default	Valor padrão sugerido
type	Tipo de configuração exposto no contrato ao cliente administrativo externo

Exemplos de tipos:

AUTH
IP_POLICY
RATE_LIMIT

Essas informações integram o contrato consumido pelo cliente administrativo externo para solicitar a criação da instância.

Rastreabilidade da origem do Gateway¶

A collection gateways receberá um novo atributo:

sourceTemplateGatewayId

Esse campo identifica qual Gateway Template originou determinada instância.

Essa informação será utilizada para:

rastreabilidade
auditoria
futuras evoluções de sincronização
identificação da origem do gateway

Gateway Wizard¶

Será criada uma nova collection:

gateway_wizard

Essa collection armazenará uma cópia das configurações existentes em templateSetups no momento em que a instância do gateway for criada.

Além dos dados de configuração, serão armazenadas informações sobre o progresso do Wizard, permitindo identificar:

quais etapas já foram concluídas;
quais configurações ainda permanecem pendentes;
valores informados pelo usuário durante a criação da instância.

Essa abordagem garante rastreabilidade do processo de configuração sem depender da versão original do template.

Banco Global¶

Além das informações armazenadas em cada tenant, será mantida uma base global responsável pelo catálogo público de templates.

Serão adicionadas as seguintes collections:

gateway_template_catalog
rate_limit

gateway_template_catalog¶

Após a publicação de um Gateway Template, apenas os metadados necessários para exibição no catálogo serão sincronizados para essa collection.

Exemplos:

nome
descrição
tags
ícone
visibilidade
versão publicada
informações do publicador

O objetivo é permitir consultas ao catálogo sem necessidade de acessar a base individual de cada tenant.

rate_limit¶

Quando um Rate Limit for compartilhado entre todas as instâncias de um Gateway Template, sua configuração será persistida na base global para permitir reutilização entre diferentes tenants.

Novos Microserviços¶

gateway-template-service¶

Será criado um novo microserviço denominado:

gateway-template-service

Responsabilidades:

CRUD de Gateway Templates
Versionamento dos Templates
Persistência nas bases dos tenants
Publicação no catálogo global
Geração dos dados necessários para criação de instâncias
Comunicação com o gateway-core

Esse serviço passa a ser o responsável por todo o ciclo de vida dos Gateway Templates.

Worker de Provisionamento¶

No mesmo deployment do gateway-template-service existirá um Worker responsável pelo provisionamento assíncrono das instâncias.

Fluxo:

Usuário solicita criação de uma instância.
gateway-template-service realiza todas as validações.
É criado um Operation ID.
O serviço retorna imediatamente a resposta ao cliente administrativo externo.
O Worker inicia o provisionamento da instância.
O Worker realiza a comunicação com o gateway-core para persistência definitiva do Gateway.
O status da operação pode ser consultado utilizando o Operation ID.

Essa abordagem evita chamadas HTTP longas, melhora a experiência do usuário e permite acompanhar o progresso do provisionamento.

object-storage¶

Será criado um microserviço dedicado ao gerenciamento de arquivos de mídia.

Responsabilidades:

validação de formato da imagem;
validação de tamanho;
validação de dimensões;
armazenamento das imagens;
geração da referência persistida no banco.

Após a validação, os arquivos serão armazenados no MinIO, ficando apenas a referência persistida nas collections de Gateway Template.

gateway-global-registry¶

O microserviço gateway-global-registry passará a ser responsável pelo gerenciamento da base global utilizada pelo catálogo.

Suas responsabilidades incluem:

CRUD da collection gateway_template_catalog;
sincronização dos metadados publicados;
manutenção das informações globais utilizadas pelo catálogo;
gerenciamento dos registros globais de Rate Limit compartilhados.

Toda alteração realizada pelo gateway-template-service que impactar o catálogo será propagada para o gateway-global-registry, mantendo a base global desacoplada da persistência dos tenants.

Separação entre Gateway Core e Gateway Template Service¶

Durante o levantamento da arquitetura foi considerada a possibilidade de incorporar toda a lógica de Gateway Templates dentro do gateway-core, aproveitando a similaridade existente entre os modelos de dados de Gateways e Templates.

Após análise da arquitetura e da responsabilidade atual do Core, optou-se por criar um microserviço dedicado ao gerenciamento de Templates.

Justificativa¶

Embora Gateways e Gateway Templates compartilhem grande parte da estrutura de dados, seus casos de uso possuem objetivos diferentes.

O gateway-core atualmente já concentra responsabilidades importantes relacionadas a:

persistência de gateways;
persistência de rotas;
versionamento;
atualização de documentos complexos;
resolução de configurações para o Data Plane;
descoberta de configurações utilizadas pelo Broker e Security Checker.

A inclusão da lógica de Templates aumentaria significativamente a complexidade desse serviço, tornando-o responsável por dois domínios distintos.

Além disso, a evolução dos Templates tende a ocorrer de forma independente da evolução dos Gateways.

A separação em um microserviço próprio garante que:

alterações em Gateway Templates não impactem o funcionamento dos Gateways já existentes;
o domínio de Templates possa evoluir independentemente;
o gateway-core permaneça focado exclusivamente no ciclo de vida dos Gateways;
seja reduzido o risco de regressões em funcionalidades críticas do Data Plane.

Embora parte da lógica possa ser compartilhada futuramente através de bibliotecas comuns, a decisão foi manter a implementação dos casos de uso isolada entre os dois serviços.

Rate Limit em Gateway Templates¶

Uma das funcionalidades disponibilizadas pelos Gateway Templates será permitir que o publicador defina como o Rate Limit será aplicado para as instâncias geradas.

Serão suportados dois modelos distintos de compartilhamento.

Rate Limit Global¶

Nesse modelo todas as instâncias geradas a partir do Template compartilham o mesmo limite.

Exemplo:

100 requisições por segundo

Se um tenant consumir:

90 requisições/segundo

restarão apenas:

10 requisições/segundo

para todos os demais tenants que utilizam aquele mesmo Gateway Template.

Esse modelo permite proteger APIs cuja capacidade de processamento é compartilhada entre todos os consumidores.

Rate Limit por Tenant¶

Nesse modelo cada tenant possui sua própria instância de Rate Limit.

Exemplo:

100 requisições por segundo

Tenant A:

100 req/s

Tenant B:

100 req/s

Tenant C:

100 req/s

O consumo de um tenant não interfere no limite disponível para os demais.

Alterações na modelagem¶

Para suportar esses dois cenários serão realizadas alterações na modelagem existente.

Collection rate_limits¶

Será adicionado o atributo:

editable

Esse atributo indica se aquele Rate Limit poderá ser alterado posteriormente pelo usuário.

Quando o Template definir o modelo Rate Limit por Tenant, durante a criação da instância será criada automaticamente uma nova entrada na collection rate_limits do tenant contendo exatamente as configurações definidas pelo Template.

Entretanto, essa configuração será criada com:

editable = false

garantindo que o usuário não possa alterar os limites estabelecidos pelo publicador do Template.

Com isso, cada tenant possuirá seu próprio identificador de Rate Limit, mantendo o funcionamento atual do serviço de limitação de requisições.

Alterações em route_revisions¶

O objeto rateLimit receberá um novo atributo:

instanciedType

Valores possíveis:

TENANT
GLOBAL

Esse atributo determina onde o Rate Limit deverá ser localizado durante a execução.

TENANT¶

O rateLimitId será resolvido normalmente na base de dados do tenant.

GLOBAL¶

O rateLimitId será resolvido na base global, permitindo que todas as instâncias compartilhem exatamente o mesmo Rate Limit.

Discovery e Security Checker¶

O atributo instanciedType fará parte da resposta retornada pelo serviço de Discovery.

Durante o processamento da requisição, o Security Checker utilizará essa informação para determinar qual contexto deverá ser utilizado ao consultar o serviço de Rate Limit.

Quando o tipo for:

TENANT, o Rate Limit será resolvido utilizando a base de dados do tenant.
GLOBAL, o Rate Limit será resolvido utilizando a base global compartilhada.

Dessa forma, o serviço de Rate Limit permanece com o mesmo comportamento funcional, alterando apenas a origem da configuração consultada, conforme definido pelo Gateway Template.

Autenticação em Gateway Templates¶

Assim como ocorre com o Rate Limit, os Gateway Templates permitirão que o publicador defina como a autenticação será tratada pelas instâncias geradas.

Serão suportados dois modelos distintos de autenticação.

Autenticação Compartilhada¶

Nesse modelo todas as instâncias do Gateway Template utilizarão exatamente a mesma autenticação.

O publicador seleciona uma autenticação existente durante a criação do Template e todas as instâncias geradas passam a utilizá-la.

Exemplo:

O publicador associa ao Template uma autenticação OAuth2 corporativa.

Todas as instâncias criadas a partir desse Template exigirão que as requisições sejam autenticadas utilizando esse mesmo provedor OAuth2, independentemente do tenant que consumiu o Template.

Esse modelo é indicado quando a API protegida utiliza um mecanismo único de autenticação compartilhado entre todos os consumidores.

Autenticação por Tenant¶

Nesse modelo o publicador não define uma autenticação específica, mas determina qual tipo de autenticação deverá ser configurado pelo tenant durante a criação da instância.

Exemplo:

O Template exige uma autenticação do tipo:

BASIC

Durante o Wizard de criação da instância, o usuário deverá selecionar uma autenticação Basic previamente cadastrada em seu tenant.

Da mesma forma, um Template poderá exigir outros tipos de autenticação suportados pela plataforma, como:

OAuth2
API Key
Basic

Nesse cenário o usuário possui liberdade para escolher a autenticação que será utilizada, desde que seja do tipo definido pelo Template.

Essa abordagem garante flexibilidade para que cada tenant utilize suas próprias credenciais, sem comprometer o modelo de segurança definido pelo publicador.

Alterações na modelagem¶

Para suportar os dois modelos de autenticação serão realizadas alterações na estrutura existente.

Collection authentication¶

Será criada uma collection authentication na base global.

Essa collection armazenará as autenticações compartilhadas entre todos os tenants quando um Gateway Template utilizar o modelo de Autenticação Compartilhada.

Dessa forma, múltiplas instâncias poderão referenciar a mesma configuração sem necessidade de duplicação dos dados.

Alterações em route_revisions¶

O objeto authentication receberá um novo atributo:

instanciedType

Valores possíveis:

TENANT
GLOBAL

Esse atributo determina onde a autenticação deverá ser localizada durante o processamento da requisição.

TENANT¶

O authenticationId será resolvido normalmente na base de dados do tenant.

Esse será o comportamento utilizado quando o usuário configurar sua própria autenticação durante a criação da instância.

GLOBAL¶

O authenticationId será resolvido na base global.

Nesse cenário todas as instâncias do Gateway Template compartilharão exatamente a mesma configuração de autenticação.

Discovery e Security Checker¶

O atributo instanciedType também será retornado pelo serviço de Discovery para o objeto de autenticação.

Durante o processamento da requisição, o Security Checker utilizará essa informação para determinar em qual base deverá localizar a autenticação.

Quando o tipo for:

TENANT, a autenticação será consultada na base do tenant.
GLOBAL, a autenticação será consultada na base global.

Com isso, o fluxo de autenticação permanece o mesmo já existente na plataforma, alterando apenas a origem da configuração conforme definido pelo Gateway Template.