Esquema da base de infraestrutura do Aggrega (FeatureRecipe)
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
Definições escritas por Ops que mapeiam uma Feature abstrata do catálogo para uma implementação concreta e versionada para uma capacidade de fornecedor. Estritamente 1:1 com um fornecedor físico e uma funcionalidade do catálogo.
Consulte-se a referência de autoria da FeatureRecipe para orientações em prosa sobre como escrever entidades FeatureRecipe; 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 “FeatureRecipe” | sim | Constante: "FeatureRecipe" |
metadata | objeto | sim | |
spec | objeto | sim | A associação à capacidade do fornecedor, o mapeamento, o pipeline e o mapeamento de injeção de uma FeatureRecipe. Contém os mesmos três tipos de entrada que uma Recipe (com fonte, sintetizado, artifacts) mais o injectMapping exclusivo da FeatureRecipe; uma FeatureRecipe de pura cablagem que declara apenas capability e implements é válida e não renderiza nada. |
Não são permitidas propriedades adicionais.
featurerecipe.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 carácter. |
version | string | sim | Versionamento semântico estrito da FeatureRecipe (por exemplo, 1.2.5). 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 Release que a 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.
featurerecipe.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.
featurerecipe.spec
A associação à capacidade do fornecedor, o mapeamento, o pipeline e o mapeamento de injeção de uma FeatureRecipe. Contém os mesmos três tipos de entrada que uma Recipe (com fonte, sintetizado, artifacts) mais o injectMapping exclusivo da FeatureRecipe; uma FeatureRecipe de pura cablagem que declara apenas capability e implements é válida e não renderiza nada.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capability | string | sim | A capacidade explícita do fornecedor à qual esta receita se associa (por exemplo, ‘helm’, ‘terraform’, ‘compose’) — o tipo de fornecedor que a renderiza. |
implements | string | sim | Declara que tipo de Feature do catálogo esta receita é capaz de implementar (incluindo Features de credenciais etiquetadas com feature.aggrega.ai/kind: secret; versão exata, intervalo compatível com a versão principal ’^’ ou sem versão). O compilador usa-o para verificar os mapeamentos do Manifest e para sugerir candidatos nos diagnósticos e no preenchimento automático do editor; nunca resolve uma compilação. O mapeamento do Manifest é a escolha explícita de implementação do utilizador, fixada no ficheiro de bloqueio da Release. |
locals | mapa de string | não | O estado privado de Ops. Resultados de computação internos disponíveis apenas dentro dos templates desta FeatureRecipe como ‘.locals.*’. Cada entrada é ela própria um template Go, avaliado face a um contexto autónomo: ‘.context.instance_id’ (o COMPONENTE ANFITRIÃO para o qual este anexo está a ser resolvido, que é o que essa referência denota em todas as superfícies de template), ‘.attachment_name’ (a instância de anexo a ser resolvida, e o único caminho para esse nome a partir de um local), os ‘.values’ e ‘.infra’ próprios do anexo, e as entradas deste mesmo bloco resolvidas até então. As entradas são resolvidas pela ordem em que são escritas, e uma entrada PODE ler uma entrada irmã definida ACIMA dela, recebendo o valor resolvido dessa entrada em vez do texto do seu template. A ordem do autor faz parte do contrato sempre que uma entrada lê outra: mover uma definição para baixo da entrada que a lê quebra a compilação, e o bloco nunca é reordenado para que uma referência seja resolvida. Uma referência ‘.locals. |
provides | mapa de string | não | A API pública do Programador. Variáveis de saída contratuais disponíveis para a resolução do inject do Chamador a jusante. Quando executionScope é boundary, os provides são avaliados uma vez para o anexo à fronteira, face ao contexto de template com âmbito boundary, e cada componente alcançado pelo anexo lê essa única avaliação em ‘.features. |
source | string ou object | não | Caminho opcional para código de infraestrutura. Aceita uma string URI ou um objeto estruturado aberto. Se for fornecido juntamente com valuesMapping, o compilador renderiza-o, e os documentos renderizados juntam-se à saída da FeatureRecipe antes de os passos do seu pipeline serem executados. |
valuesMapping | string ou object | não | Conteúdo do mapeamento de values com três modos de autoria através de despacho conforme a forma do conteúdo. Modo 1 (inline): um escalar string de template Go que produz o formato de values esperado pelo fornecedor. Modo 2 (importação de ficheiro): um mapa YAML de exatamente uma chave, $import: ./relative/path.tmpl, que aponta para um ficheiro de template Go local. Modo 3 (importação de biblioteca): um mapa YAML de exatamente uma chave, $import: <Library>#/mappings/<entry>, que referencia uma entrada de uma MappingLibrary por identidade de nome simples (a versão é fornecida pelo ficheiro de bloqueio de cada Release; nenhum host de registo aparece na referência). Na forma de objeto, $import não pode corresponder a ^oci://; um valor que corresponda é recusado. |
workload | string ou object | não | Produtor de YAML de Workload com três modos de autoria através de despacho conforme a forma do conteúdo. Modo 1 (inline): um escalar string de template Go cuja saída é analisada como ‘aggrega.ai/v1beta1 Workload’. Modo 2 (importação de ficheiro): um mapa YAML de exatamente uma chave, $import: ./relative/path.yaml, que aponta para um ficheiro de template Go local. Modo 3 (importação de biblioteca): um mapa YAML de exatamente uma chave, $import: <Library>#/workloads/<entry>, que referencia uma entrada de uma WorkloadLibrary por identidade de nome simples (a versão é fornecida pelo ficheiro de bloqueio de cada Release; nenhum host de registo aparece na referência). O Provider de destino tem de suportar a síntese de cargas de trabalho; o catálogo da biblioteca padrão declara workloadSchema nesses fornecedores como o contrato documentado. Uma FeatureRecipe com workload: associada a um fornecedor que não consegue sintetizar é interrompida de forma explícita no momento da renderização. Uma carga de trabalho sintetizada de uma FeatureRecipe emite os seus manifestos nativos do fornecedor no diretório de saída da funcionalidade. Na forma de objeto, $import não pode corresponder a ^oci://; um valor que corresponda é recusado. |
artifacts | mapa de string ou object | não | Mapa do nome da entrada para a autoria do conteúdo do artefacto. O valor de cada entrada contém um de três modos através de despacho conforme a forma do conteúdo. Modo 1 (inline): um escalar string de template Go cuja saída é o corpo do artefacto. Modo 2 (importação de ficheiro): um mapa YAML de exatamente uma chave, $import: ./relative/path.yaml, que aponta para um ficheiro de template Go local. Modo 3 (importação de biblioteca): um mapa YAML de exatamente uma chave, $import: <Library>#/artifacts/<entry>, que referencia um bundle de uma ArtifactLibrary por identidade de nome simples (a versão é fornecida pelo ficheiro de bloqueio de cada Release; nenhum host de registo aparece na referência). Um bundle expande-se numa saída por ficheiro, cada uma aninhada sob a chave da entrada como <key>/<filename>. A chave nomeia a saída da entrada: a chave de uma entrada de modo 1 ou 2 é o nome do seu ficheiro de saída, usado tal como está escrito, e o ficheiro importado de uma entrada de modo 2 fornece o conteúdo sem nomear a saída, pelo que duas entradas que importam ficheiros diferentes que partilham um nome são duas saídas distintas. Os recursos auxiliares que uma FeatureRecipe geradora de recursos emite (ConfigMap, ServiceMonitor, NetworkPolicy, CRD ExternalSecret, etc.) têm a forma de artefactos; artifacts: é o principal mecanismo de geração de recursos. As colisões entre entradas de artefactos, ficheiros de bundle, saída da fonte e síntese de cargas de trabalho interrompem a compilação quando o nó é renderizado. O bloco artifacts é escrito de forma idêntica numa Recipe e numa FeatureRecipe — os mesmos três modos, a mesma regra de chave para saída e o mesmo comportamento em caso de colisão —, e é por isso que essa parte desta descrição se lê da mesma forma em ambos os tipos; um exemplo escrito para um transfere-se para o outro sem alterações. Na forma de objeto, $import não pode corresponder a ^oci://; um valor que corresponda é recusado. Chaves: a chave nomeia a saída da entrada, pelo que está limitada a um único nome de ficheiro: começa com uma letra ou um algarismo e continua com letras, algarismos, pontos, hífenes ou sublinhados. Os pontos após o primeiro carácter preservam as extensões que as chaves de artefacto têm (main.tf, template.yaml, serviceaccount.yaml). Uma / faria uma chave nomear um caminho em vez de um ficheiro, e um . inicial admitiria .., que nomeia uma localização fora do diretório de saída — a classe do primeiro carácter recusa ambos. Para uma importação de biblioteca, a chave nomeia o diretório sob o qual os ficheiros do bundle são aninhados, pelo que se aplica o mesmo limite. Padrão: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | não | O que deixar de fora do que a fonte desta FeatureRecipe renderiza — para uma fonte usada tal como está que renderiza algo que a Release não deve entregar: um documento que um chart obtido renderiza, como um Secret que contém uma chave que o chart gera de novo a cada renderização, um serviço, um volume ou uma configuração que um ficheiro compose obtido inclui, ou um recurso que um template do CloudFormation obtido declara. A maioria das FeatureRecipes nunca precisa disto. Cada entrada nomeia uma unidade que a fonte renderiza pelo seu tipo, pelo seu nome e, onde a entrada os indica, pelo seu namespace e pelo subchart de onde veio, cada um no vocabulário do fornecedor que renderiza a fonte — para um chart, um documento pelo seu próprio kind e pelo seu metadata.name; para um ficheiro compose, um service, um volume ou um config pela sua chave sob services:, volumes: ou configs:; para um template do CloudFormation, um recurso pelo seu Type e pelo seu ID lógico. Esse fornecedor deixa de fora cada unidade a que uma entrada corresponde, e aquilo a que uma entrada corresponde, e o que o fornecedor recusa por causa de uma entrada, é o contrato documentado do próprio fornecedor. Um fornecedor que não consegue deixar nada de fora recusa uma FeatureRecipe que declare esta chave antes de qualquer coisa ser renderizada. Só é filtrado o que source: renderiza — uma entrada de workload: ou de artifacts: nunca o é —, pelo que a chave exige source. Cada valor é um template, avaliado face ao contexto face ao qual valuesMapping é avaliado. O when de uma entrada é avaliado primeiro, e uma entrada cujo when renderiza um valor falsy é descartada. Cada entrada que permanece ativa tem de deixar algo de fora: uma entrada ativa que não corresponde a nada do que a fonte renderizou interrompe a compilação, nomeando a entrada. A fonte continua a ser renderizada por completo — cada template de um chart continua a ser executado, pelo que um template que falha continua a fazer falhar a compilação — e só a sua saída é deixada de fora. A chave é escrita de forma idêntica numa Recipe e numa FeatureRecipe. Pelo menos 1 entrada. |
injectMapping | string | não | Template Go inline opcional avaliado durante a fase de interceção pré-renderização, uma vez para cada componente alcançado pelo anexo, face ao contexto de template desse componente: lê ‘.context’ e ‘.features’ do componente e ‘.attachment_name’, ‘.values’, ‘.infra’ e ‘.locals’ do anexo, diga o que disser executionScope, e uma referência a ‘.boundary’, que o contexto de nenhum componente contém, interrompe a compilação. Produz um dicionário JSON/YAML que o compilador Go funde em profundidade de forma nativa sobre o pipe de memória ‘.context.inject’ do Chamador. Usado para a mutação do lado do Chamador, sem Wasm, de variáveis de ambiente e contratos de entrega. |
pipeline | object[] | não | Lista sequencial de passos de pipeline Wasm executados após a renderização sobre o conjunto de documentos renderizados, cada um devolvendo patches RFC 6902 e efeitos secundários. |
executionScope | string (enum) | não | Se a Geração de recursos desta FeatureRecipe é executada por componente (a predefinição) ou uma vez por anexo a uma fronteira. As FeatureRecipes com âmbito boundary são deduplicadas por (boundary_path, instância de FeatureRecipe) e todos os templates exceto o injectMapping leem um contexto de template com âmbito boundary: os pilares .boundary.* em vez dos pilares .context.* por componente, e uma referência a estes interrompe a compilação. O injectMapping é executado uma vez para cada componente alcançado pelo anexo independentemente de executionScope, pelo que lê o contexto desse componente e nunca .boundary. Valores permitidos: "component", "boundary" Predefinição: "component" |
readsCallerRenderFacts | booleana | não | Declara que os templates desta FeatureRecipe leem o que renderizaram os Components que se ligam àquele a que ela está anexada: os factos de renderização que o fornecedor de cada um desses chamadores reporta sobre a sua própria saída. Quando é true e a FeatureRecipe renderiza por componente, cada anexo dela é renderizado depois de cada Component da compilação ter sido renderizado, em vez de logo após o Component a que está anexada, pelo que a renderização de cada chamador está concluída antes de o anexo ser avaliado. Quando é false ou está ausente, a entrada de nenhum chamador em ‘.context.used_by’ contém factos de renderização, o anexo é renderizado logo após o seu Component, a menos que readsTargetRenderFacts seja true, e a compilação é interrompida perante um template escrito inline nesta FeatureRecipe que lê os factos de renderização de um chamador sob ‘.context.used_by’. Predefinição: false |
readsTargetRenderFacts | booleana | não | Declara que os templates desta FeatureRecipe leem o que renderizaram os Components aos quais está ligado aquele a que está anexada: os factos de renderização que o fornecedor de cada um desses destinos reporta sobre a sua própria saída, em cada entrada de ‘.context.uses’. Quando é true e a FeatureRecipe renderiza por componente, cada anexo dela é renderizado depois de cada Component da compilação ter sido renderizado, em vez de logo após o Component a que está anexada, pelo que a renderização de cada destino está concluída antes de o anexo ser avaliado. É a mesma renderização posterior que readsCallerRenderFacts provoca, pelo que definir qualquer uma das chaves, ou ambas, faz com que o anexo seja renderizado nesse momento. Quando é false ou está ausente, nenhuma entrada em ‘.context.uses’ contém factos de renderização, o anexo é renderizado logo após o seu Component, a menos que readsCallerRenderFacts seja true, e a compilação é interrompida perante um template escrito inline nesta FeatureRecipe que lê os factos de renderização de um destino sob ‘.context.uses’. Predefinição: false |
assertions | mapa de string | não | Validação entre campos em tempo de compilação. Cada entrada é uma asserção com nome: a chave é um identificador de regra estável que surge nas mensagens de erro; o valor é uma string de template Go com semântica de interrupção {{ fail "message" }}. Várias asserções com nome por entidade são avaliadas por instância pela ordem declarada pelo autor; a primeira asserção que falha interrompe a compilação. As asserções de FeatureRecipe são avaliadas após a associação da receita e após a avaliação dos provides, antes da renderização, e exprimem invariantes de implementação do chart ou módulo específico que a FeatureRecipe usa como fonte. Contexto do template: .values / .infra / .uses / .features / .metadata mais .provides / .locals / .recipe. O avaliador usa missingkey=error: as referências a chaves não definidas provocam uma interrupção com um diagnóstico no-such-key. Como a referência simples provoca a interrupção antes de qualquer fallback poder ser executado, um default simples não fornece um fallback de campo opcional nesta superfície — convém proteger a referência com hasKey, ou usar o helper optional, que realiza diretamente a verificação de presença. Ler a chave através de index também não fornece um: index provoca uma interrupção perante uma chave de mapa que o mapa não contém, nomeando a chave. |
Não são permitidas propriedades adicionais.
featurerecipe.spec.omits[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
kind | string | sim | O tipo da unidade a deixar de fora, no vocabulário do fornecedor que renderiza a fonte: para um chart, o kind próprio de um documento renderizado, como Secret; para um ficheiro compose, service, volume ou config; para um template do CloudFormation, o Type de um recurso, como AWS::S3::Bucket. Nomeia um tipo que a fonte renderiza e não tem relação com o kind: que um source: estruturado contém. Um template. |
name | string | sim | O nome da unidade a deixar de fora, no vocabulário do fornecedor que renderiza a fonte: para um chart, o metadata.name próprio de um documento renderizado; para um ficheiro compose, a chave da unidade sob services:, volumes: ou configs:; para um template do CloudFormation, o ID lógico do recurso, a sua chave sob Resources. Um template. |
namespace | string | não | O namespace em que se encontra a unidade a deixar de fora, quando a entrada deve corresponder apenas a uma unidade nesse namespace — para um fornecedor cuja saída tem namespaces, como acontece com os documentos renderizados de um chart. Se estiver ausente, ou se for renderizado como a string vazia, a entrada corresponde a uma unidade do seu tipo e nome, seja qual for o seu namespace. Um ficheiro compose e um template do CloudFormation não têm namespaces, e os seus fornecedores recusam uma entrada que nomeie um. Um template. |
subchart | string | não | O subchart de onde provém a unidade a deixar de fora, quando a entrada deve corresponder apenas à cópia que um subchart renderiza — para uma fonte montada a partir de fontes aninhadas, como um chart o é a partir dos seus subcharts. Para um chart, o nome próprio do subchart, ou o alias que a dependência do seu pai lhe atribui, com os nomes de um subchart aninhado unidos por / a partir do mais exterior: operator, ou operator/webhooks. A entrada corresponde então a um documento renderizado a partir dos templates/ ou dos crds/ próprios desse subchart, e nem a um que o próprio chart renderiza nem a um que um subchart aninhado dentro dele renderiza. Se estiver ausente, ou se for renderizado como a string vazia, a entrada corresponde a uma unidade do seu tipo e nome, seja qual for a sua origem. Um chart que não renderiza nenhum subchart com esse nome interrompe a compilação, nomeando a entrada. Um ficheiro compose e um template do CloudFormation não têm subcharts, e os seus fornecedores recusam uma entrada que nomeie um. Um template. |
when | string | não | Template Go inline avaliado antes dos restantes campos da entrada. Quando renderiza um valor falsy, a entrada é descartada: os seus restantes campos não são avaliados, nada é deixado de fora por causa dela e não tem de corresponder a nada. Um when vazio ou ausente mantém a entrada. A veracidade segue a convenção habitual para a saída de template do tipo booleano: as strings true/True/TRUE, qualquer número diferente de zero e qualquer outra string não vazia são verdadeiros, enquanto false/False/FALSE, a string vazia e o zero são falsos. Um when cuja renderização falha interrompe a compilação. |
Não são permitidas propriedades adicionais.
featurerecipe.spec.pipeline[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
id | string | sim | Um identificador programático para este passo, único entre os passos deste pipeline: um documento que declara um mesmo id em dois dos seus passos é recusado quando é lido. Um passo posterior do mesmo pipeline lê as saídas deste passo como .steps.<id>.outputs. Padrão: ^[a-zA-Z0-9_]+$. |
plugin | string | sim | A referência à entidade Plugin que este passo executa, sempre qualificada pelo tipo de socket próprio do plugin: <pluginType>/<name> com uma versão opcional, como em parser/yaml ou parser/yaml:1.0.0. A qualificação é obrigatória, e não uma forma entre várias — um name:version sem qualificação é recusado, porque dois sockets podem conter um plugin com o mesmo nome e é a qualificação que torna a entidade resolúvel. A compilação resolve a entidade para o seu artefacto .wasm endereçado por conteúdo — localizado a partir da identidade do plugin e do registo configurado, com o seu digest fixado no ficheiro de bloqueio — e carrega os bytes. Uma simples referência a um .wasm ou a um artefacto não é aceite aqui. |
function | string | sim | A função Wasm exportada a invocar. |
with | string | não | Template Go inline avaliado como um mapa JSON/YAML que satisfaz estritamente o esquema de entrada explícito deste plugin. |
optional | booleana | não | Quando true, uma falha deste passo (um trap do guest, um patch dirigido a um documento ausente do conjunto, um patch malformado ou um diagnóstico com gravidade de interrupção) é despromovida a um aviso bem visível: o conjunto de documentos anterior ao passo é reposto, a saída deste passo é descartada e o pipeline continua. Quando false ou ausente, qualquer falha de um passo interrompe a compilação depois de repor o conjunto de documentos anterior ao passo. |
when | string | não | Template Go inline avaliado no momento de percorrer o pipeline. Quando renderiza um valor falsy, o passo é ignorado — uma passagem direta: o conjunto de documentos segue inalterado para o passo seguinte, sem contribuir com patches, efeitos secundários ou registo do passo. Um when vazio ou ausente executa sempre o passo. A veracidade segue a convenção habitual para a saída de template do tipo booleano: as strings true/True/TRUE, qualquer número diferente de zero e qualquer outra string não vazia são verdadeiros, enquanto false/False/FALSE, a string vazia e o zero são falsos. when e optional são independentes: um passo pode declarar ambos. |
Não são permitidas propriedades adicionais.