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

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

PropriedadeTipoObrigatóriaDescrição
apiVersionconst “aggrega.ai/v1beta1”simConstante: "aggrega.ai/v1beta1"
kindconst “Release”simConstante: "Release"
metadataobjetosim
specobjetosimO 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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 carácter.
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á 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.
maintainersobject[]nãoLista dos responsáveis pela manutenção desta entidade.
licensestringnãoIdentificador 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.
repositorystringnãoO URL do repositório Git onde se encontram os ficheiros de origem.
homestringnãoO URL da página inicial, da wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador.

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 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.

PropriedadeTipoObrigatóriaDescrição
aggregatestringnãoReferê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).
manifeststringnãoReferê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.
extendsstringnãoReferê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.
parametersobjetonãoContrato 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).
boundariesmapa de boundarynãoAs 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_-]+$.
componentsmapa de boundary_componentnãoInstâ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.

PropriedadeTipoObrigatóriaDescrição
descriptionstringnãoDocumentação opcional que descreve o papel deste componente nesta fronteira da Release.
subDirectorystringnãoSubstituiçã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.
annotationsmapa de string ou object ou nullnãoAnotaçõ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.
infraobjetonãoDimensionamento físico estritamente local a este componente (por exemplo, réplicas, IOPS do disco).
featuresmapa de objectnãoAs 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_./-]+$.
usesrelease_uses_blocknãoSuperfí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.

PropriedadeTipoObrigatóriaDescrição
typestringnãoO URI da Feature. Obrigatório para um anexo que só a Release faz. Tem de corresponder ao type do Aggregate se ambos o declararem.
descriptionstringnãoDocumentação opcional que explica por que motivo o Operador anexou esta funcionalidade à ligação.
infraobjetonãoDimensionamento 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.

PropriedadeTipoObrigatóriaDescrição
componentsmapa de boundary_componentnãoInstâ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_-]+$.
aggregatesmapa de aggregate_routingnãoOutros 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

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 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.
subDirectorystringnãoSubcaminho 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.
syncWaveintegernãoWave 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.
annotationsmapa de string ou object ou nullnãoAnotaçõ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.
featuresmapa de objectnãoFuncionalidades 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_./-]+$.
boundariesmapa de boundarynãoFronteiras 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_-]+$.
componentsmapa de boundary_componentnãoQue 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_.-]+$.
aggregatesmapa de aggregate_routingnãoEncaminha 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.

PropriedadeTipoObrigatóriaDescrição
envinject_deliverynãoUm ú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.
fileinject_deliverynãoUm ú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.
arginject_deliverynãoUm ú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[]