Skip to main content
O Systemplane é o plano de controle para configuração em tempo de execução compartilhado pelas aplicações Lerian. Essas aplicações o expõem para que você possa inspecionar e alterar configurações operacionais em um serviço em execução, sem reiniciar. Em ambientes financeiros regulados, derrubar um serviço para aplicar uma mudança de configuração é ao mesmo tempo um risco de compliance e uma interrupção operacional. Com o Systemplane, você ajusta os valores que um serviço aceita com segurança enquanto ele continua atendendo ao tráfego. Essa é a mesma superfície administrativa em todas as aplicações que a montam. Cada produto documenta suas próprias chaves configuráveis, mas as rotas, os formatos de requisição e resposta, e o modelo de autorização descritos aqui são comuns a todas elas.

​
O que é o Systemplane

O Systemplane não é um serviço independente. Cada aplicação monta o mesmo conjunto de rotas em seu próprio host e porta HTTP, sob um prefixo de caminho específico da aplicação. O Systemplane não tem host nem porta próprios, e não tem porta administrativa dedicada. O prefixo canônico documentado aqui é /system, mas ele varia conforme a aplicação (veja a tabela de aplicabilidade abaixo). As aplicações registram as rotas de forma programática, e nenhum gerador de código as produz. Por isso, elas não aparecem na referência de API gerada de cada produto. Esta referência documenta a superfície manualmente, para que você possa operá-la de forma consistente entre os produtos. Toda a superfície fica desativada por padrão. Uma aplicação apenas a disponibiliza quando você ativa a configuração SYSTEMPLANE_ENABLED. Caso contrário, a aplicação roda no modo apenas variáveis de ambiente e não monta essas rotas.

​
Namespaces

A configuração vive em namespaces, cada um com entradas simples e indexadas por chaves de texto. Trilhos e plugins usam três namespaces canônicos: Algumas aplicações registram um único namespace com o nome da própria aplicação, em vez desses três. O Matcher, por exemplo, mantém todas as suas chaves em um único namespace matcher. O valor de cada entrada não tem tipo na camada de transporte. Cada chave registrada aceita seu próprio escalar, objeto ou array JSON, e um validador próprio do lado do servidor verifica o valor. Nem toda configuração pode ser alterada em tempo de execução. A aplicação lê as configurações apenas de bootstrap uma única vez, na inicialização. Essas configurações não aparecem no Systemplane e ainda exigem um reinício para mudar.

​
Endpoints

Todos os caminhos são relativos ao prefixo da aplicação (padrão /system).
/system/-/catalog nomeia um caminho de metadados reservado. A aplicação o atende antes das rotas de namespace. O segmento - não é um namespace real, e você não pode usá-lo como um. Os erros usam um envelope simples {"code": <int>, "title": "<string>", "message": "<string>"}.

​
Autenticação e permissões

A autorização nega tudo por padrão. Uma aplicação apenas disponibiliza a superfície depois que você configura um autorizador. Sem um autorizador, a aplicação nega toda requisição. Quando você habilita a autenticação, a aplicação aplica controle de acesso baseado em papéis por namespace, sobre uma identidade válida com escopo de plataforma (não de tenant). Leituras exigem a permissão de leitura do namespace, e gravações exigem a permissão de escrita correspondente: A ação de leitura cobre GET. A ação de escrita cobre PUT e DELETE. Os endpoints de descoberta do catálogo exigem permissão de leitura em pelo menos um namespace.
As strings exatas de permissão podem variar por aplicação. O Matcher, que usa um único namespace, protege toda a sua superfície com a permissão system-runtime-config:admin (recurso system-runtime-config, ação admin), em vez das strings por namespace acima. Consulte a documentação do próprio produto para saber seu modelo de autorização.
Os tokens são JWTs do tipo bearer emitidos pelo Access Manager da plataforma. Chamadores automatizados obtêm um token pelo fluxo de client credentials.
Quando uma aplicação opta pela superfície de catálogo, GET /system/-/catalog lista todas as chaves que ela registra. A rota de detalhe GET /system/-/catalog/{namespace}/{key} retorna o contrato de gravação completo de uma chave. O contrato cobre seu tipo, escopo de tenant, classe de tempo de execução, política de redação, JSON schema, regras de validação, exemplos válidos, valor padrão e o caminho PUT correspondente. Use o catálogo para saber o que um serviço expõe antes de mudar qualquer coisa. O catálogo descreve o contrato de gravação. Para ler o valor configurado atual, chame GET /system/{namespace}/{key}.

​
Quais produtos expõem o Systemplane

O Systemplane é opcional por produto. A tabela abaixo lista os produtos que o montam. Para cada produto, ela indica o prefixo de caminho, a porta HTTP padrão e se o produto também disponibiliza a superfície de descoberta do catálogo. O prefixo e a porta são padrões. Um deploy pode sobrescrevê-los.
Produtos que não estão nesta lista não montam o Systemplane. Você os configura apenas por variáveis de ambiente.