Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Esquema da Release do Aggrega

Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.

ID do esquema: https://aggrega.ai/schemas/release-v1beta1.schema.json

Consulte a referência de autoria da Release para orientações em prosa sobre como escrever entidades Release; esta página documenta o esquema estrutural que essa referência descreve.

Tipo de nível superior: object

Propriedades

PropriedadeTipoObrigatóriaDescrição
apiVersionconst “aggrega.ai/v1beta1”simConstante: "aggrega.ai/v1beta1"
kindconst “Release”simConstante: "Release"
metadataobjectsim
specobjectsimO que a Release associa e roteia: o Aggregate e o Manifest que ela implanta (ou uma base extends), o atendimento dos parâmetros específico do ambiente e as fronteiras para as quais seus componentes são roteados.

Não são permitidas propriedades adicionais.

release.metadata

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 caractere.
environmentstringsim
versionstringsimVersionamento semântico estrito da release (por exemplo, 1.0.0). Padrão: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringnãoO que esta entidade é e para que serve, escrito para quem está decidindo se vai usá-la. Comece com uma frase que nomeie a coisa e depois acrescente o que um leitor precisa para escolhê-la e usá-la corretamente — o que ela espera da plataforma na qual implanta, e qualquer coisa surpreendente sobre como ela se comporta. Um parágrafo curto é o tamanho habitual.
maintainersobject[]nãoLista de mantenedores responsáveis por esta entidade.
licensestringnãoIdentificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Ele registra os termos desse software, não os termos deste arquivo.
repositorystringnãoA URL do repositório Git onde ficam os arquivos-fonte.
homestringnãoA URL da página inicial, do wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do usuário.

Não são permitidas propriedades adicionais.

release.metadata.maintainers[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnão

Não são permitidas propriedades adicionais.

release.spec

O que a Release associa e roteia: o Aggregate e o Manifest que ela implanta (ou uma base extends), o atendimento dos parâmetros específico do ambiente e as fronteiras para as quais seus componentes são roteados.

PropriedadeTipoObrigatóriaDescrição
aggregatestringnãoReferência ao Aggregate (intenção do desenvolvedor) que esta release implanta. Um token simples é resolvido por identidade — o metadata.name do Aggregate referenciado, procurado no diretório próprio da Release e depois no catálogo. Um valor que começa com ’./’ ou ’../’ é um arquivo local explícito resolvido em relação à Release (por exemplo, ’../shared/app.yaml’ para compartilhar um mesmo Aggregate entre variantes da release em um subdiretório).
manifeststringnãoReferência ao Manifest que resolve as interfaces abstratas em relação às quais esta release implanta. Um token simples é resolvido por identidade — o metadata.name do Manifest referenciado, procurado no diretório próprio da Release. Um valor que começa com ’./’ ou ’../’ é um arquivo local explícito resolvido em relação à Release. Um Manifest fica do lado da implantação e não é indexado no catálogo, portanto é resolvido apenas a partir do diretório da Release ou de um caminho explícito.
extendsstringnãoReferência a uma Release base cuja superfície de autoria esta Release herda — sua árvore de fronteiras com a infra por componente e as vinculações de Feature abaixo dela, seus parâmetros, suas anotações e seu ponteiro para o Manifest. O valor é um caminho para um arquivo ao lado desta Release, começando com ’./’ ou ’../’; um nome simples e uma coordenada de registro são ambos recusados, porque uma Release fica do lado da implantação e não é indexada no catálogo. O que é herdado pode ser substituído chave por chave, até o primeiro valor indivisível — um escalar, uma lista, um template —, que é substituído por inteiro; uma chave escrita como null remove o que foi herdado. Nenhum campo de metadados é transmitido, então um filho carrega seu próprio nome, sua própria versão e seu próprio ambiente. Declarar ‘aggregate’ junto com ‘extends’ é rejeitado por este esquema, então um filho implanta a mesma intenção do desenvolvedor que sua base; ‘manifest’ continua opcional e pode ser substituído para trocar o arquivo de bloqueio de dependências.
parametersobjectnãoContrato de atendimento de variáveis específico do ambiente com dois modos de autoria por despacho conforme o formato do conteúdo. Modo 1 (inline): um mapa YAML que carrega diretamente valores de parâmetros aninhados e estruturados. Modo 2 (importação de arquivo): um mapa YAML de exatamente uma chave, $import: ./relative/path.yaml, que aponta para um único arquivo local que fornece os valores dos parâmetros. Apenas uma fonte neste ponto — a sobreposição em vários arquivos cabe às cadeias extends: de Release (a Release pai fornece os parâmetros base; o filho estende + sobrescreve).
boundariesmapa de boundarynãoAs caixas lógicas raiz para as quais os componentes do Aggregate são roteados. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
componentsmapa de boundary_componentnãoInstâncias de componente de nível superior que carregam a infra por componente do operador, para uma Release de escopo único sem fronteiras nomeadas. Mutuamente exclusivo com boundaries: declare components para uma Release plana ou boundaries para um roteamento para vários destinos, nunca ambos. Quando components é usado, o compilador sintetiza uma fronteira default que os contém e emite seus artefatos de forma plana em dist/. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.

Não são permitidas propriedades adicionais.

Definições

boundary_component

Uma instância de componente roteada para uma fronteira, com dimensionamento físico e vinculações de funcionalidades opcionais.

PropriedadeTipoObrigatóriaDescrição
descriptionstringnãoDocumentação opcional que descreve o papel deste componente nesta fronteira da Release.
subDirectorystringnãoSubstituição do subcaminho no nível de Component, anexada ao diretório da fronteira pai. Se omitida ou vazia tanto na fronteira quanto no componente, assume por padrão ’{{ .capability }}’; uma string vazia escrita aqui é lida como omitida. Defina como ’.’, ou como um template que seja avaliado como uma string vazia, para desativar a geração de subdiretórios.
annotationsmapa de string ou object ou nullnãoAnotações do Operador específicas do Component que substituem, para este componente, as anotações no nível da fronteira. Mescladas em profundidade sobre as anotações da fronteira (o componente prevalece em caso de colisão de chaves; valores estruturados são mesclados por subchave com pais estruturados). Os valores são strings, objetos estruturados ou null. Usadas para substituições por componente das anotações bem conhecidas do provedor (por exemplo, aggrega.ai/namespace no provedor helm). Um null explícito em uma chave herdada da fronteira pai remove deste componente a associação herdada (renúncia a uma Feature guiada por anotações); os componentes irmãos mantêm a associação herdada.
infraobjectnãoDimensionamento físico estritamente local a este componente (por exemplo, réplicas, IOPS de disco).
featuresmapa de objectnãoAs Features vinculadas a este componente por meio da Release. Para funcionalidades também declaradas no Aggregate, apenas infra é fornecido (os values vêm do Aggregate). Para funcionalidades exclusivas da Release (injetadas pelo Operador), type é obrigatório. As chaves são nomes de instância de funcionalidade e podem carregar o URI completo do tipo de funcionalidade (pontos e barras permitidos). A Release NÃO DEVE fornecer values para as funcionalidades — este é o domínio do Desenvolvedor. Chaves: uma ou mais letras, dígitos, sublinhados, pontos, barras ou hifens. Padrão: ^[a-zA-Z0-9_./-]+$.
usesrelease_uses_blocknãoSuperfície de arestas do Operador. Dentro dos sockets declarados pelo Arquiteto, a Release pode conectar um socket declarado mas não associado a um componente existente (target) e/ou fornecer infra por aresta. Sem values (a proibição de values: da Release continua valendo) e sem criação de computação; redirecionar uma aresta declarada pelo desenvolvedor interrompe o build.

Não são permitidas propriedades adicionais.

release_uses_block

Superfície uses por aresta escrita na Release, indexada por socket e depois por alias (espelhando a forma da topologia uses do Aggregate). Cada conexão pode definir target (para criar uma aresta para um socket declarado mas não associado, apontando para um componente existente), infra (configuração do operador por aresta, validada em relação ao infraSchema do socket quando a Release é resolvida) e features (vinculações que preenchem os slots que o socket declara), em qualquer combinação. values é proibido (a proibição de values: da Release); redirecionar uma aresta declarada pelo desenvolvedor é uma salvaguarda bem visível no build.

Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.

Os valores são map of object.

Nenhuma outra chave é permitida.

release_connection_attachment

Uma vinculação que uma entrada de conexão de uma Release carrega: a Feature que preenche um slot declarado pelo socket da conexão, com o dimensionamento do operador para ela.

PropriedadeTipoObrigatóriaDescrição
typestringnãoO URI da Feature. Obrigatório para uma vinculação que apenas a Release faz. Deve corresponder ao type do Aggregate se ambos o declararem.
descriptionstringnãoDocumentação opcional explicando por que o Operador vinculou esta funcionalidade à conexão.
infraobjectnãoDimensionamento operacional para esta vinculação, validado pela declaração de esquema da Feature.

Não são permitidas propriedades adicionais.

aggregate_routing

Roteia para esta fronteira os componentes internos de um submódulo Aggregate aninhado. Espelha a estrutura component/aggregate da fronteira para a composição recursiva.

PropriedadeTipoObrigatóriaDescrição
componentsmapa de boundary_componentnãoInstâncias de Component dentro do agregado aninhado a serem roteadas para esta fronteira. As chaves são o nome local que cada componente carrega dentro desse submódulo — ‘main-db’ para o componente que o mapa components próprio de uma fronteira endereça como ‘data.main-db’ — porque esse é o único nome que ele tem ali. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
aggregatesmapa de aggregate_routingnãoOutros agregados aninhados dentro deste subagregado (para composição de módulos profundamente aninhados). Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.

Não são permitidas propriedades adicionais.

boundary

PropriedadeTipoObrigatóriaDescrição
descriptionstringnãoDocumentação opcional que descreve o propósito e o destino físico desta fronteira (por exemplo, ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’).
directorystringnãoCaminho de saída físico para a geração de artefatos GitOps. Suporta variáveis de template Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Combinado com subDirectory por meio de uma junção de caminhos para produzir o caminho final do artefato.
subDirectorystringnãoSubcaminho no nível da fronteira anexado a directory. Se omitido ou vazio tanto na fronteira quanto no componente, assume por padrão ’{{ .capability }}’ para o particionamento automático de CI/CD; uma string vazia escrita aqui é lida como omitida. Defina como ’.’, ou como um template que seja avaliado como uma string vazia, para desativar.
syncWaveintegernãoOnda de implantação opcional por fronteira (inteiro com sinal, padrão 0). Cada componente nesta fronteira herda em seu nó a onda da fronteira. Valores negativos são permitidos (executados antes de todo o resto); valores maiores são executados depois dos menores. No K8s e no Helm a onda é o que ordena a implantação: ela se torna uma anotação argocd.argoproj.io/sync-wave, e em um recurso que o chart já marca como hook do Helm ela também se torna o helm.sh/hook-weight desse hook. No compose a onda é ao mesmo tempo registrada como rótulo do serviço e usada para ordenar os serviços do arquivo no qual é renderizada, por meio de depends_on entre eles — portanto alcança cada serviço desse único arquivo e nada fora dele. No cloudformation a onda ordena o provisionamento da stack na qual a fronteira é montada: cada recurso de uma onda é declarado como dependente dos recursos da onda anterior, o que fixa a ordem em que são criados e, ao contrário, a ordem em que são excluídos. Trata-se apenas da ordem de criação e exclusão — um template de stack não expressa nenhuma noção de recurso pronto, então nada espera que um recurso fique utilizável. No terraform a onda ordena os blocos module da configuração raiz na qual a fronteira é montada: cada módulo de uma onda é declarado como dependente dos módulos da onda anterior, o que fixa a ordem em que o mecanismo executa suas ações. Trata-se apenas da ordem das ações — uma configuração não expressa nenhuma noção de recurso pronto, então nada espera que um recurso fique utilizável — e o valor também é registrado com a procedência de build do nó. O compilador leva o mesmo valor para cada nó da fronteira como o sync_wave desse nó, onde o comportamento por destino é descrito novamente do lado do nó. Fronteiras aninhadas não herdam implicitamente — cada uma declara a sua própria onda.
annotationsmapa de string ou object ou nullnãoAnotações do Operador válidas para toda a fronteira, que se propagam em cascata até o compartimento .context.annotations.release. Os valores são strings, objetos estruturados ou null. Um valor estruturado carrega uma configuração por subchave que é mesclada em profundidade com pais estruturados (por subchave, o filho prevalece) e flui pela expansão de Feature guiada por anotações; apenas valores escalares aparecem no contexto de renderização. Um null explícito em uma chave herdada de uma fronteira pai remove a associação herdada do conjunto efetivo de anotações desta fronteira (renúncia a uma Feature guiada por anotações), propagando-se para cada componente roteado para esta fronteira, a menos que uma substituição mais profunda reintroduza a associação.
featuresmapa de objectnãoFuncionalidades válidas para toda a fronteira aplicadas a todos os componentes aninhados (por exemplo, uma malha de segurança padrão). O bloco uses de uma funcionalidade se projeta sobre cada componente da fronteira, declarando uma dependência compartilhada uma única vez na fronteira em vez de repeti-la em cada componente. As chaves são nomes de instância de funcionalidade e podem carregar o URI completo do tipo de funcionalidade (pontos e barras permitidos). Chaves: uma ou mais letras, dígitos, sublinhados, pontos, barras ou hifens. Padrão: ^[a-zA-Z0-9_./-]+$.
boundariesmapa de boundarynãoFronteiras lógicas aninhadas (por exemplo, namespaces dentro de um cluster). Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
componentsmapa de boundary_componentnãoQuais componentes do Aggregate são colocados nesta fronteira. As chaves são nomes de instância de componente; o componente de um subagregado é endereçado pelo seu caminho qualificado com pontos (por exemplo, ‘data.main-db’ — o nome da instância do agregado, um ponto, o nome do componente). Chaves: uma ou mais letras, dígitos, sublinhados, pontos ou hifens. Padrão: ^[a-zA-Z0-9_.-]+$.
aggregatesmapa de aggregate_routingnãoRoteia para esta fronteira os componentes dos submódulos Aggregate aninhados. As chaves são nomes de instância de agregado que correspondem ao mapa spec.aggregates do Aggregate. Todas as instâncias de agregado devem ser colocadas em exatamente uma fronteira se houver fronteiras definidas. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.

Não são permitidas propriedades adicionais.

uses_block

A topologia estrutural - de propriedade do Desenvolvedor. Declara arestas de rede lógicas e dependências.

Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.

Os valores são string[] or map of object.

Nenhuma outra chave é permitida.

inject_block

Roteamento agnóstico da injeção em uma conexão. Mapeia variáveis locais para as chaves provides do destino. Cada mecanismo de entrega (env, file, arg ou personalizado) é escrito como um array de entradas {in, from} — ‘from’ explícito para referências a provides. Um mecanismo personalizado pode ter qualquer nome, exceto all: um template lê todos os mecanismos mesclados em uma única visão em .context.inject.all, portanto um mecanismo com esse nome ficaria oculto por ela, e nomear um interrompe o build.

PropriedadeTipoObrigatóriaDescrição
envinject_deliverynãoUm único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘from’ (uma chave provides a resolver) ou ‘value’. Em uma Release cada entrada fica em uma conexão, então ‘from’ é resolvido em relação aos provides do destino e uma entrada que traz ‘value’ é recusada.
fileinject_deliverynãoUm único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘from’ (uma chave provides a resolver) ou ‘value’. Em uma Release cada entrada fica em uma conexão, então ‘from’ é resolvido em relação aos provides do destino e uma entrada que traz ‘value’ é recusada.
arginject_deliverynãoUm único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘from’ (uma chave provides a resolver) ou ‘value’. Em uma Release cada entrada fica em uma conexão, então ‘from’ é resolvido em relação aos provides do destino e uma entrada que traz ‘value’ é recusada.

inject_delivery

Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘from’ (uma chave provides a resolver) ou ‘value’. Em uma Release cada entrada fica em uma conexão, então ‘from’ é resolvido em relação aos provides do destino e uma entrada que traz ‘value’ é recusada.

Tipo: object[]