Esquema da Release do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/release-v1beta1.schema.json
Consulte-se 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
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sim | Constante: "aggrega.ai/v1beta1" |
kind | const “Release” | sim | Constante: "Release" |
metadata | objeto | sim | |
spec | objeto | sim | O que a Release associa e encaminha: o Aggregate e o Manifest que implementa (ou uma base extends), a satisfação dos parâmetros específica do ambiente e as fronteiras para as quais os seus componentes são encaminhados. |
Não são permitidas propriedades adicionais.
release.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 carácter. |
environment | string | sim | |
version | string | sim | Versionamento 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-]+)*))?$. |
description | string | não | O que esta entidade é e para que serve, escrito para quem está a decidir se a vai usar. Convém começar por uma frase que nomeie a coisa e acrescentar depois o que um leitor precisa para a escolher e usar corretamente — o que espera da plataforma na qual implementa, e tudo o que seja surpreendente no seu comportamento. Um parágrafo curto é a extensão habitual. |
maintainers | object[] | não | Lista dos responsáveis pela manutenção desta entidade. |
license | string | não | Identificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Regista os termos desse software, não os termos deste ficheiro. |
repository | string | não | O URL do repositório Git onde se encontram os ficheiros de origem. |
home | string | não | O URL da página inicial, da wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador. |
Não são permitidas propriedades adicionais.
release.metadata.maintainers[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | |
email | string | não | |
url | string | não |
Não são permitidas propriedades adicionais.
release.spec
O que a Release associa e encaminha: o Aggregate e o Manifest que implementa (ou uma base extends), a satisfação dos parâmetros específica do ambiente e as fronteiras para as quais os seus componentes são encaminhados.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
aggregate | string | não | Referência ao Aggregate (intenção do programador) que esta release implementa. Um token simples resolve-se por identidade — o metadata.name do Aggregate referenciado, procurado no diretório próprio da Release e depois no catálogo. Um valor que comece por ’./’ ou ’../’ é um ficheiro local explícito resolvido em relação à Release (por exemplo, ’../shared/app.yaml’ para partilhar um mesmo Aggregate entre variantes da release num subdiretório). |
manifest | string | não | Referência ao Manifest que resolve as interfaces abstratas em relação às quais esta release implementa. Um token simples resolve-se por identidade — o metadata.name do Manifest referenciado, procurado no diretório próprio da Release. Um valor que comece por ’./’ ou ’../’ é um ficheiro local explícito resolvido em relação à Release. Um Manifest fica do lado da implementação e não é indexado no catálogo, pelo que só se resolve a partir do diretório da Release ou de um caminho explícito. |
extends | string | não | Referência a uma Release base cuja superfície de autoria esta Release herda — a sua árvore de fronteiras com a infra por componente e os anexos de Feature abaixo dela, os seus parâmetros, as suas anotações e o seu ponteiro para o Manifest. O valor é um caminho para um ficheiro ao lado desta Release, que começa por ’./’ ou ’../’; um nome simples e uma coordenada de registo são ambos recusados, porque uma Release fica do lado da implementação e não é indexada no catálogo. O que é herdado pode ser substituído chave a chave, até ao 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, pelo que um filho tem o seu próprio nome, a sua própria versão e o seu próprio ambiente. Declarar ‘aggregate’ juntamente com ‘extends’ é rejeitado por este esquema, pelo que um filho implementa a mesma intenção do programador que a sua base; ‘manifest’ continua opcional e pode ser substituído para trocar o ficheiro de bloqueio de dependências. |
parameters | objeto | não | Contrato de satisfação de variáveis específico do ambiente com dois modos de autoria através de despacho conforme a forma do conteúdo. Modo 1 (inline): um mapa YAML que contém diretamente valores de parâmetros aninhados e estruturados. Modo 2 (importação de ficheiro): um mapa YAML de exatamente uma chave, $import: ./relative/path.yaml, que aponta para um único ficheiro local que fornece os valores dos parâmetros. Apenas uma fonte neste ponto — a sobreposição em vários ficheiros cabe às cadeias extends: de Release (a Release pai fornece os parâmetros base; o filho estende + substitui). |
boundaries | mapa de boundary | não | As caixas lógicas de raiz para as quais os componentes do Aggregate são encaminhados. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
components | mapa de boundary_component | não | Instâncias de componente de nível superior que contêm a infra por componente do operador, para uma Release de âmbito único sem fronteiras com nome. Mutuamente exclusivo com boundaries: declara-se components para uma Release plana ou boundaries para um encaminhamento para vários destinos, nunca ambos. Quando se usa components, o compilador sintetiza uma fronteira default que os contém e emite os seus artefactos de forma plana em dist/. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.
Definições
boundary_component
Uma instância de componente encaminhada para uma fronteira, com dimensionamento físico e anexos de funcionalidades opcionais.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
description | string | não | Documentação opcional que descreve o papel deste componente nesta fronteira da Release. |
subDirectory | string | não | Substituição do subcaminho ao nível de Component, acrescentada ao diretório da fronteira pai. Se for omitida ou estiver vazia tanto na fronteira como no componente, assume por predefinição ’{{ .capability }}’; uma string vazia escrita aqui é lida como omitida. Para desativar a geração de subdiretórios, define-se como ’.’, ou como um template que seja avaliado como uma string vazia. |
annotations | mapa de string ou object ou null | não | Anotações do Operador específicas do Component que substituem, para este componente, as anotações ao nível da fronteira. Fundidas em profundidade sobre as anotações da fronteira (o componente prevalece em caso de colisão de chaves; os valores estruturados são fundidos 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 fornecedor (por exemplo, aggrega.ai/namespace no fornecedor helm). Um null explícito numa chave herdada da fronteira pai remove deste componente a associação herdada (renúncia a uma Feature orientada por anotações); os componentes irmãos mantêm a associação herdada. |
infra | objeto | não | Dimensionamento físico estritamente local a este componente (por exemplo, réplicas, IOPS do disco). |
features | mapa de object | não | As Features anexadas a este componente através da Release. Para as funcionalidades também declaradas no Aggregate, só é fornecido infra (os values vêm do Aggregate). Para as funcionalidades exclusivas da Release (injetadas pelo Operador), type é obrigatório. As chaves são nomes de instância de funcionalidade e podem conter o URI completo do tipo de funcionalidade (pontos e barras permitidos). A Release NÃO PODE fornecer values para as funcionalidades — este é o domínio do Programador. Chaves: uma ou mais letras, algarismos, sublinhados, pontos, barras ou hífenes. Padrão: ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | não | Superfície de arestas do Operador. Dentro dos sockets declarados pelo Arquiteto, a Release pode ligar 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 mantém-se) e sem criação de computação; redirecionar uma aresta declarada pelo programador interrompe a compilação. |
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 (espelha a forma da topologia uses do Aggregate). Cada ligação pode definir target (para criar uma aresta para um socket declarado mas não associado, que aponta para um componente existente), infra (configuração do operador por aresta, validada face ao infraSchema do socket quando a Release é resolvida) e features (anexos 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 programador é uma salvaguarda bem visível na compilação.
Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são map of object.
Nenhuma outra chave é permitida.
release_connection_attachment
Um anexo que uma entrada de ligação de uma Release transporta: a Feature que preenche um slot declarado pelo socket da ligação, com o dimensionamento do operador para ela.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | string | não | O URI da Feature. Obrigatório para um anexo que só a Release faz. Tem de corresponder ao type do Aggregate se ambos o declararem. |
description | string | não | Documentação opcional que explica por que motivo o Operador anexou esta funcionalidade à ligação. |
infra | objeto | não | Dimensionamento operacional para este anexo, validado pela declaração de esquema da Feature. |
Não são permitidas propriedades adicionais.
aggregate_routing
Encaminha para esta fronteira os componentes internos de um submódulo Aggregate aninhado. Espelha a estrutura component/aggregate da fronteira para a composição recursiva.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
components | mapa de boundary_component | não | Instâncias de Component dentro do agregado aninhado a encaminhar para esta fronteira. As chaves são o nome local que cada componente tem 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 é o único nome que tem aí. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
aggregates | mapa de aggregate_routing | não | Outros agregados aninhados dentro deste subagregado (para a composição de módulos profundamente aninhados). Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.
boundary
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
description | string | não | Documentaçã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’). |
directory | string | não | Caminho de saída físico para a geração de artefactos GitOps. Suporta variáveis de template Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Combinado com subDirectory através de uma junção de caminhos para produzir o caminho final do artefacto. |
subDirectory | string | não | Subcaminho ao nível da fronteira acrescentado a directory. Se for omitido ou estiver vazio tanto na fronteira como no componente, assume por predefinição ’{{ .capability }}’ para o particionamento automático de CI/CD; uma string vazia escrita aqui é lida como omitida. Para o desativar, define-se como ’.’, ou como um template que seja avaliado como uma string vazia. |
syncWave | integer | não | Wave de implementação opcional por fronteira (inteiro com sinal, predefinição 0). Cada componente nesta fronteira herda no seu nó a wave da fronteira. São permitidos valores negativos (executados antes de tudo o resto); os valores maiores são executados depois dos menores. No K8s e no Helm, a wave é o que ordena a implementação: torna-se uma anotação argocd.argoproj.io/sync-wave e, num recurso que o chart já marca como hook do Helm, torna-se também o helm.sh/hook-weight desse hook. No compose, a wave é registada como etiqueta do serviço e ordena também os serviços do ficheiro em que é renderizada, através de depends_on entre eles — pelo que chega a todos os serviços desse único ficheiro e a nada fora dele. No cloudformation, a wave ordena o aprovisionamento da stack em que a fronteira é montada: cada recurso de uma wave é declarado dependente dos recursos da wave anterior, o que fixa a ordem pela qual são criados e, inversamente, a ordem pela qual são eliminados. Trata-se apenas da ordem de criação e de eliminação — um template de stack não exprime nenhuma noção de recurso pronto, pelo que nada espera que um recurso fique utilizável. No terraform, a wave ordena os blocos module da configuração raiz em que a fronteira é montada: cada módulo de uma wave é declarado dependente dos módulos da wave anterior, o que fixa a ordem pela qual o motor executa as suas ações. Trata-se apenas da ordem das ações — uma configuração não exprime nenhuma noção de recurso pronto, pelo que nada espera que um recurso fique utilizável — e o valor é também registado com a proveniência de compilação 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ó. As fronteiras aninhadas não herdam implicitamente — cada uma declara a sua própria wave. |
annotations | mapa de string ou object ou null | não | Anotações do Operador válidas para toda a fronteira, que se propagam em cascata até ao compartimento .context.annotations.release. Os valores são strings, objetos estruturados ou null. Um valor estruturado contém uma configuração por subchave que é fundida em profundidade com pais estruturados (por subchave, o filho prevalece) e passa pela expansão de Feature orientada por anotações; só os valores escalares aparecem no contexto de renderização. Um null explícito numa chave herdada de uma fronteira pai remove a associação herdada do conjunto efetivo de anotações desta fronteira (renúncia a uma Feature orientada por anotações), propagando-se a todos os componentes encaminhados para esta fronteira, a menos que uma substituição mais profunda reintroduza a associação. |
features | mapa de object | não | Funcionalidades válidas para toda a fronteira aplicadas a todos os componentes aninhados (por exemplo, uma malha de segurança predefinida). O bloco uses de uma funcionalidade projeta-se sobre cada componente da fronteira, declarando uma dependência partilhada uma única vez na fronteira em vez de a repetir em cada componente. As chaves são nomes de instância de funcionalidade e podem conter o URI completo do tipo de funcionalidade (pontos e barras permitidos). Chaves: uma ou mais letras, algarismos, sublinhados, pontos, barras ou hífenes. Padrão: ^[a-zA-Z0-9_./-]+$. |
boundaries | mapa de boundary | não | Fronteiras lógicas aninhadas (por exemplo, namespaces dentro de um cluster). Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
components | mapa de boundary_component | não | Que 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, algarismos, sublinhados, pontos ou hífenes. Padrão: ^[a-zA-Z0-9_.-]+$. |
aggregates | mapa de aggregate_routing | não | Encaminha 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 têm de ser colocadas em exatamente uma fronteira se houver fronteiras definidas. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.
uses_block
A topologia estrutural - propriedade do Programador. Declara arestas de rede lógicas e dependências.
Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são string[] or map of object.
Nenhuma outra chave é permitida.
inject_block
Encaminhamento agnóstico da injeção numa ligação. Associa variáveis locais às 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 combinados numa única vista em .context.inject.all, pelo que um mecanismo com esse nome ficaria oculto por ela, e nomear um interrompe o build.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
env | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’. Numa Release, cada entrada fica numa ligação, pelo que ‘from’ se resolve face aos provides do destino e uma entrada que tenha ‘value’ é recusada. |
file | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’. Numa Release, cada entrada fica numa ligação, pelo que ‘from’ se resolve face aos provides do destino e uma entrada que tenha ‘value’ é recusada. |
arg | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’. Numa Release, cada entrada fica numa ligação, pelo que ‘from’ se resolve face aos provides do destino e uma entrada que tenha ‘value’ é recusada. |
inject_delivery
Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’. Numa Release, cada entrada fica numa ligação, pelo que ‘from’ se resolve face aos provides do destino e uma entrada que tenha ‘value’ é recusada.
Tipo: object[]