Feature
O papel conceitual da entidade Feature (o traço operacional modular do Domínio 2) é descrito em architecture/04-entity-taxonomy.md. A distinção entre Features operacionais e Features de credenciais (aquelas rotuladas com feature.aggrega.ai/kind: secret) é descrita em architecture/08-credential-model.md. O vocabulário de rótulos semânticos usado pelos seletores de Feature está em entities/component. Esta página trata da superfície de autoria do catálogo de Feature.
Localização no catálogo
Ao contrário dos Components (que usam URIs de três segmentos com subdiretórios por categoria), as Features são organizadas de forma plana: um diretório por Feature sob seu publicador, contendo um diretório por versão.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (por exemplo, hub.aggrega.ai/feature/core/data-masking:1.0.0).
Contrato de autoria
As Features declaram:
metadata.labels: usefeature.aggrega.ai/kind: secretpara marcar uma Feature como Feature de credencial. O label é um metadado descritivo para o autor, para o site do catálogo e para os seletores de labels; nenhum ramo do compilador o lê, e o que uma anexação produz é decidido pela FeatureRecipe para a qual o Manifest mapeia o seu tipo, não pelo label. Uma Feature de credencial e uma Feature comum são anexadas da mesma forma, na mesma superfície de anexação, em qualquer escopo. A família de credenciais da biblioteca padrão se divide por resultado:core/secret-valueentrega um valor no pipe de injeção;core/referenced-secretnomeia um recurso secreto referenciável (um Secret do Kubernetes, um segredo do AWS Secrets Manager, uma entrada do Vault), criado pela saída de sua FeatureRecipe ou já existente, e declara um contrato de saídaschema.provides—name(o localizador do recurso, neutro quanto ao provider) ekey(o campo de dados dentro dele) — que um consumidor lê como.features.<slot>.provides.<key>para referenciar o recurso sem derivar novamente seu nome;core/referenced-secret-setmaterializa um recurso que carrega um conjunto de chaves de dados fornecido pelo chamador e publica apenas o localizador, para um consumidor cujo destino já conhece os nomes das chaves que lê;core/secret-providedexpõe o valor de um segredo preexistente;core/generated-secretnão produz nada, porque o mecanismo de destino gera e gerencia a credencial por conta própria, portanto não declara nemvaluesnemprovidese suas FeatureRecipes são pura fiação que não renderiza nenhum byte. Dois eixos separam os membros: quem fornece o material — um autor o escreve ou indica onde buscá-lo, ou o mecanismo de destino é inteiramente dono dele, como emcore/generated-secret— e o que a anexação produz: um valor injetado, um recurso referenciável ou nada renderizado. Cada membro é par dos demais na mesma superfície de anexação, de modo que um slot de credencial está sempre vinculado e o que varia entre Releases é o que o vincula. Uma Feature de credencial que declara um contratoschema.providesobriga toda FeatureRecipe que a implementa a publicar essas chaves — caso contrário, o build é interrompido — e oselectorde um slot defeaturesSchemaaponta para o membro da família de que precisa.usesSchema(opcional): declara os sockets topológicos que a Feature pode consumir (por exemplo, o socketpath/keyde uma Feature de credencial que aponta para um vault). Consulte architecture/13-catalog-and-registry.md §2 para o mecanismo de Split Schema.schema: valida os blocosvalueseinfrada anexação da Feature — a intenção cognitiva que o desenvolvedor configura em cada anexação no Aggregate (valuessão o domínio do desenvolvedor, e o schema da Release proíbevalues:em anexações de Feature) e a capacidade que o operador decide por ambiente na Release (infra). Um campo que declara umdefault:é tanto validado contra ele quanto preenchido no pilar renderizado quando nada o define; consulte Escopo da Feature e forma de autoria. Aceita JSON Schema 2020-12 expresso na abreviação YAML em forma compacta (o padrão; consultevocabulary/compact-form-authoring.md) ou em YAML de JSON Schema completo, com$ref:entre documentos para entradas de SchemaLibrary para formas compartilhadas (consultevocabulary/cross-document-ref.md). Uma folha que carrega material secreto declarasensitive: true— as Features de credencial da biblioteca padrão marcam a folha que contém o material e deixam deliberadamente sem marcação os localizadores que publicam, já que um nome de recurso e uma chave de dados são ambos públicos. A palavra-chave, e o limite do que declará-la alcança, estão emvocabulary/compact-form-authoring.md“Declarando uma folha como sensível”.featuresSchema(opcional): declara os slots de anexação de que a Feature precisa para seu próprio funcionamento — uma Feature declara slots exatamente como um Component, de modo que uma Feature que precisa ela mesma de uma credencial (a chave de API de uma Feature sidecar do Datadog, por exemplo) nomeia o ponto de vinculação em vez de recorrer aos slots do Component hospedeiro. Consulte A credencial própria de uma Feature para ver uma Feature que declara seu próprio slot e uma FeatureRecipe que lê o que o preenche. Cada slot aceita os mesmos campos que um slotfeaturesSchemade um Component, com a mesma semântica — incluindo umselectoropcional (um seletor de labels no estilo Kubernetes que restringe qual Feature pode preencher o slot, o análogo para slots de um seletor de socketusesSchema; um preenchimento cujos labels não o satisfazem interrompe o build, e o seletor é avaliado em relação aos labels da Feature anexada e a nada mais), umsensitiveopcional (que declara que o que quer que vincule o slot lida com material secreto — uma afirmação sobre o ponto de vinculação, e não sobre um preenchimento específico) e a mesma abertura: declarar um slot nunca proíbe uma anexação sob um nome que nenhum slot declara. A tabela completa de campos, a declaração de sensibilidade no nível do slot e como ela difere da de uma folha do schema, e as duas formas em que uma entidade que declara slots é implantada estão todas em entities/component.md “Slots de anexação”.appliesTo/appliesToAnyOf: seletores de labels que controlam a quais Components a Feature pode ser anexada. São avaliados pelo mecanismo nativo de correspondência de labels do compilador durante a etapa de análise estática. Consulte Anexação baseada em labels abaixo e architecture/13-catalog-and-registry.md §2 “Seletores no estilo Kubernetes” para a referência da sintaxe de seletores.interoperability(opcional): um bloco aninhado que carregaconflictsWith— as Features ao lado das quais esta Feature não pode alcançar um componente. O build é interrompido antes da renderização quando um componente acaba carregando ambas, qualquer que seja o escopo em que cada uma foi anexada. Consulte O blocointeroperabilityabaixo para a explicação completa.
A renderização estrutural de uma Feature está vinculada à sua FeatureRecipe correspondente, que mapeia a interface da Feature para uma implementação de infraestrutura concreta.
Anexação baseada em labels
Os dois seletores applies do schema da Feature controlam a quais Components a Feature é anexada, avaliados pelo mecanismo nativo de correspondência de labels do compilador durante a etapa de análise estática:
appliesTo— uma string de seletor de labels no estilo Kubernetes; a superfície de composição AND. Todos os requisitos separados por vírgula precisam valer, com o vocabulário completo de operadores:key=value,key!=value,key in (v1, v2),key notin (v1, v2),keysozinho (label presente),!key(label ausente). Uma Feature que declaraappliesTo: "datastore.aggrega.ai/engine=vector"é anexada apenas a Components marcados com esse exato par chave-valor;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"expressa “qualquer server ou worker que não contenha dados restritos” em uma única string de seletor.appliesToAnyOf— a superfície de composição OR. Uma lista de itens de seletor em que basta que um único item corresponda. Cada item é ou um seletor em forma de string (mesma gramática deappliesTo; os requisitos dentro da string são combinados com AND) ou um mapa chave-valor plano para correspondência apenas por igualdade. É usado quando uma Feature se encaixa em várias formas de componente não relacionadas — por exemplo, uma Feature de observabilidade que se aplica a{ component.aggrega.ai/type: worker }OU a{ component.aggrega.ai/type: task }sem forçar as duas em uma única string de seletor.
Sem a forma any-of, os arquitetos precisariam duplicar o mesmo YAML de Feature para cada forma de componente não relacionada em que a Feature se encaixa. As duas formas se compõem: uma Feature pode declarar ambas, e os resultados são combinados com AND entre as formas — a string appliesTo precisa valer e pelo menos um item de appliesToAnyOf precisa corresponder. Um seletor omitido ou vazio não declara nenhuma restrição e corresponde a qualquer conjunto de labels.
Uma string de seletor é lida em relação às seis formas sempre que uma anexação da Feature é avaliada, e um requisito fora delas interrompe o build em vez de ser lido como algum outro seletor: um requisito vazio (uma vírgula inicial, final ou duplicada, ou uma string só de separadores), uma chave que contém espaço em branco ou qualquer um de =, !, (, ) e a vírgula, e um conjunto in ( ou notin ( que não está fechado. É isso que captura os erros que, de outra forma, selecionariam silenciosamente o oposto do pretendido: appliesTo: "!tier=frontend", escrito para manter uma Feature fora dos frontends, é recusado porque ! nomeia uma chave de label e nada mais — tier!=frontend é como se exclui um valor — e tier in frontend é recusado em favor de tier in (frontend). Um valor é o texto após seu operador, quaisquer que sejam os caracteres que contenha, então tier==frontend pede um label cujo valor é =frontend. A interrupção nomeia a Feature, seu seletor e o requisito que não pôde ser lido. Uma Feature que nada anexa nunca é avaliada, então um seletor malformado nela não é relatado até que uma anexação a nomeie.
Consulte architecture/13-catalog-and-registry.md §2 “Seletores no estilo Kubernetes” para a referência da sintaxe de seletores — a gramática que um seletor de Feature aceita é a mesma que os seletores de socket usesSchema aceitam, a forma de string que os usuários de Kubernetes conhecem de kubectl get -l.
O bloco interoperability
O schema da Feature declara um bloco spec.interoperability opcional que carrega um único controle: com quais outras Features esta Feature pode coexistir em um componente.
interoperability.conflictsWith — uma lista das Features mutuamente exclusivas com a Feature que está sendo definida, cada uma escrita da forma como o type de uma anexação nomeia uma Feature. Ela evita gerar configurações incompatíveis — anexar ao mesmo componente tanto uma mesh somente TCP quanto um proxy com reconhecimento de HTTP, por exemplo.
O build é interrompido antes de renderizar qualquer coisa quando um componente acaba carregando esta Feature e uma Feature que sua lista nomeia. O que conta é o alcance: uma anexação alcança o componente em que está escrita, e todo componente dentro do subsistema ou da fronteira em que está escrita, incluindo fronteiras aninhadas; uma anexação escrita em uma entrada de componente da Release, ou produzida pela expansão orientada por anotações, alcança seu componente da mesma forma. Assim, um conflito declarado interrompe o build quando as duas Features estão anexadas ao mesmo componente, quando uma está em uma fronteira e a outra em um componente dentro dela, quando uma está em uma fronteira externa e a outra em uma fronteira aninhada dentro dela que contém um componente, e quando uma está em um subsistema e a outra em um componente desse subsistema. Duas Features anexadas a fronteiras irmãs que não compartilham nenhum componente nunca se encontram, e uma fronteira que não contém nenhum componente não alcança nada — nenhum dos casos interrompe o build.
- Uma declaração basta. O build é interrompido quando a lista de qualquer uma das duas Feature nomeia a outra; a segunda Feature não precisa listar a primeira de volta.
- Nomes, quaisquer que sejam as versões. Cada entrada e o tipo de cada anexação são comparados com qualquer versão removida, de modo que uma entrada
core/fixed-replica-controllercorresponde a uma anexação decore/fixed-replica-controller:2.0.0, e uma entrada que carrega uma versão corresponde a todas as versões da Feature que nomeia. - Nomes são tudo o que ele lê. O compilador compara os nomes que o autor da Feature declarou com as Features que um componente carrega — o mesmo tipo de avaliação de
appliesTo, sobre dados que o autor escreveu. Se duas Features são incompatíveis é julgamento do autor, e a lista é onde isso fica registrado.
A interrupção nomeia a Feature cuja lista nomeia a outra, cada lugar em que cada uma das duas foi anexada — no componente no Aggregate, em um subsistema, em uma fronteira da Release com seu caminho, em uma entrada de componente da Release, ou pela expansão orientada por anotações de uma anotação nomeada — e o componente em que elas se encontram. Um par que se encontra em vários componentes é relatado uma vez para cada um. Consulte errors/fatal-halts.md para a mensagem.
Exemplo:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerEsta Feature é anexada apenas a Components do tipo server e declara incompatibilidade com outra Feature de controle de réplicas: um build em que qualquer componente acaba carregando ambas é interrompido antes da renderização. Uma FeatureRecipe que precisa do nome do componente ao qual está anexada — para apontar um autoscaler para seu alvo, por exemplo — o lê de seu contexto de template e o escreve onde quer que sua saída precise: .context.instance_id é a identidade do componente, e .context.rendered_name é o nome que o próprio provider do componente dá aos recursos que renderiza para ele, que é o nome pelo qual direcionar um recurso — com helm, o nome do Deployment que uma carga de trabalho sintetizada emite, e o nome de release a partir do qual um chart constrói seus próprios nomes.
Herança via extends
Uma Feature pode declarar spec.extends: <feature-name> apontando para uma Feature base cuja superfície de autoria ela herda. A referência nomeia a base pelo seu metadata.name, não pela coordenada de registro sob a qual a Feature é publicada, e aceita as mesmas três formas de versão que toda referência de catálogo: sem versão (core/queue) para a versão disponível mais alta, exata (core/queue:1.0.0) ou um intervalo caret (core/queue:^1.0.0). O compilador percorre a cadeia de pais no carregamento do catálogo, valida que a cadeia é acíclica e então mescla as specs dos pais no filho para produzir uma única Feature resolvida. Os campos escritos pelo filho têm precedência em caso de colisão de chaves; os metadata.labels e metadata.annotations do pai, os seletores appliesTo / appliesToAnyOf, o bloco interoperability, usesSchema, featuresSchema e as declarações de JSON Schema 2020-12 em schema são mesclados automaticamente para baixo. Todo outro campo de metadata é o do filho, literalmente, de modo que identidade e procedência nunca são herdadas.
O que o metadata: de uma Feature herda. labels e annotations são mesclados chave por chave ao longo da cadeia, a base primeiro, com o valor da Feature que estende prevalecendo em uma chave compartilhada — a mesma regra que os Components seguem. O resto de metadata: não é transmitido: name, version, description, maintainers, license, repository, home e keywords são os da própria Feature que estende, exatamente como escritos.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }O core/kafka-queue mesclado herda appliesTo do pai, herda as propriedades values.qos e infra.partition_count, e acrescenta values.compression_codec por cima. Um filho que declara explicitamente appliesTo substitui por inteiro o seletor do pai (a mesclagem de seletores de labels não é profunda — o seletor do filho substitui o do pai). O schema.values.qos de um filho substitui a declaração do pai para essa propriedade.
Como cada parte da superfície de anexação é herdada. As duas formas de seletor são herdadas independentemente uma da outra, porque se compõem em vez de se substituírem: cada forma presente precisa valer — a string appliesTo precisa corresponder, e pelo menos um item de appliesToAnyOf precisa corresponder — enquanto uma forma ausente não restringe nada. Assim, uma Feature pode herdar o seletor AND de sua base enquanto declara um conjunto OR próprio. O bloco interoperability é herdado campo a campo — um filho que declara o bloco sem uma lista conflictsWith ainda carrega a lista que sua base declarou, enquanto um filho que declara seu próprio conflictsWith substitui a lista da base em vez de acrescentar a ela. Uma Feature que não declara nenhum dos três é anexada exatamente onde sua base é anexada.
Herança é mesclagem de schema, não vinculação de interface. Uma cadeia extends: de Feature produz uma única Feature resolvida, não uma família polimórfica. A URI da Feature base da cadeia não é o que o campo feature: de uma vinculação do Manifest referencia — os Manifests vinculam pela URI da Feature folha, e o schema resolvido inclui as propriedades herdadas. O contrato de Feature que uma FeatureRecipe implements: é igualmente a URI folha; as FeatureRecipes não navegam pela cadeia de herança.
aggrega pull busca a base. Uma Feature base é uma dependência de toda Release que anexa uma Feature que a estende, quer algo mais a nomeie ou não. aggrega pull segue cada extends: até o fim da cadeia, busca no registry uma base que nenhum diretório de catálogo contém e registra cada base no lockfile da Release, referenciada a partir do spec.extends da Feature que a nomeia; um build lê a base dali.
Modos de erro. Uma cadeia extends: cíclica, e um pai que nenhuma entidade do catálogo fornece, interrompem o build, nomeando a Feature a partir da qual a resolução começou, a Feature cuja linha extends: deve ser aberta e a referência que ela declara. As mensagens estão em Cyclic extends on Components or Features (extends cíclico em Components ou Features) e An extends: chain cannot be assembled (Não é possível montar uma cadeia).
Para o vocabulário mais amplo de herança / interface entre Components, Features e Features de credencial, consulte vocabulary/inheritance-and-interface.md.
Componibilidade: o contrato social de pureza
A convenção da biblioteca padrão é uma Feature, uma função interna — um sidecar de observabilidade é uma Feature de observabilidade; um sidecar de proxy de rede é uma Feature de proxy de rede; eles não se combinam em um único composto com duas preocupações não relacionadas. A convenção mantém as Features individuais componíveis, versionadas de forma independente e anexáveis de forma independente.
O compilador Go central não impõe essa convenção. Definições de Feature com preocupações misturadas são sintaticamente válidas e compilam sem erros. A imposição é opcional:
- Empresas que criam catálogos internos podem escrever um plugin de linter personalizado que inspeciona definições de Feature em CI/CD e emite um aviso quando os labels
appliesTode uma única Feature abrangem domínios de capacidade não relacionados. - Um autor de Feature que registra, em
interoperability.conflictsWith, que duas Features se sobreporiam opta por uma verificação em tempo de build: o compilador interrompe o build onde quer que as duas alcancem um mesmo componente. Ele compara os nomes declarados e nada mais, portanto impõe a declaração que um autor escreveu, e não a própria convenção de pureza.
As Features de código aberto da biblioteca padrão seguem a convenção de pureza por disciplina de autoria; os catálogos corporativos são livres para se desviar quando um composto fortemente acoplado realmente se encaixa no modelo de implantação.
O que justifica uma Feature, e onde fica o ajuste próprio de um produto
Uma Feature é uma anexação: ela traz algo que o desenvolvedor ou o operador anexa deliberadamente — recursos, uma etapa de pipeline, cabeamento — e a convenção da biblioteca padrão é que ela possa ser honrada por pelo menos dois produtos independentes. Essa segunda metade é o teste a aplicar antes de criar uma, porque a portabilidade é o que a palavra anexação promete. Uma anexação diz que a capacidade viaja: anexe-a a um componente, anexe-a a outro, e a realização de cada produto a honra nos próprios termos.
Uma capacidade que apenas um produto no mercado tem é um ajuste próprio desse produto, e não uma Feature. Ela pertence como valor escrito na superfície própria desse produto, que o autor que decide sobre ela define no próprio pilar e lê ao lado de tudo o mais que configura o mesmo produto. Publicá-la em vez disso como Feature oferece uma portabilidade que nenhum outro produto pode entregar: a anexação nomeia um único produto por construção, de modo que um autor que a anexa ao próximo produto que escolher encontra um build que é interrompido nomeando o tipo, e a Feature ensinou uma capacidade que nunca teve.
O teste conta produtos no mercado, não componentes neste catálogo, cada um lido em sua própria referência de configuração atual. Dois produtos independentes que implementam uma capacidade a tornam portável, não importa quantos deles sejam distribuídos aqui, de modo que uma Feature pode ser declarada antes que algo no catálogo a realize — anexá-la então interrompe o build nomeando o tipo — e cada realização distribuída é uma FeatureRecipe para um único produto, que honra a anexação da forma como esse produto a configura.
O pinning de certificados upstream é o caso prático. Um pin é um controle sobre qual chave um upstream pode apresentar: aceitar apenas um certificado cuja chave pública corresponda a uma que a Release fornece. Essa é uma asserção diferente de exigir que o certificado de um upstream se encadeie a uma âncora de confiança que a Release fornece, e diferente ainda de afirmar o que diz o sujeito de um certificado — ambas declaram o que um certificado deve dizer, enquanto um pin declara qual chave ele deve ser. Vários gateways aqui podem verificar em relação a uma âncora, e é por isso que dataplane.aggrega.ai/upstream-tls: trust-anchor é um valor ao qual um seletor pode corresponder. O pinning é uma capacidade separada, e pelo menos dois produtos independentes o implementam para as conexões que abrem para um upstream: o Tyk recebe a chave pública do upstream em formato PEM, e o Envoy recebe um hash dela. Portanto é uma Feature, core/upstream-key-pinning, cujo seletor nomeia dataplane.aggrega.ai/upstream-pinning: public-key, e o que este catálogo realiza é respondido produto a produto: core/gateway/tyk carrega o valor e uma FeatureRecipe para cada um de seus destinos, enquanto os gateways aqui que incorporam o Envoy expõem a configuração de pin dele apenas para os certificados que os clientes apresentam, ou nem a expõem, de modo que não carregam valor algum e uma anexação a eles é interrompida no seletor. Um pin restringe o que um upstream pode apresentar; é um controle, não uma garantia de que a conexão seja de resto sólida.
Dois limites para o teste, e o segundo é a metade mais facilmente descartada:
- É disciplina de autoria, não uma verificação do compilador. Uma Feature que declara opções que nenhum produto implementa passa igualmente pela validação de schema, pelo linter de publicação e por uma renderização — o compilador não interpreta o que uma Feature promete. O julgamento fica com o autor do catálogo.
- A incapacidade de um produto de honrar uma opção não é motivo para remover essa opção. Onde dois ou mais produtos oferecem uma capacidade sob nomes que se agrupam, a capacidade é portável e a Feature a mantém; o produto que não consegue honrá-la a recusa. Uma Feature reduzida ao que todo produto suporta quase não tem mais nada a dizer.
Escopo da Feature e forma de autoria
O spec.schema de uma Feature define as formas values: e infra: próprias da Feature — a intenção cognitiva que o desenvolvedor configura por anexação da Feature no Aggregate (values), distinta dos números de capacidade que o operador decide por ambiente (infra). Os pilares da Feature vivem em seus próprios namespaces e são validados independentemente dos pilares do Component hospedeiro. Quando o desenvolvedor anexa uma Feature autoscaler a um Component web-server no Aggregate, o Aggregate carrega os values: do Component (forma do hospedeiro) mais os values: da Feature (a forma da intenção de escalonamento — qual métrica conduz o escalonamento); os números de capacidade voltados ao operador (min_replicas / max_replicas) fluem pelo bloco infra: da Release na anexação da Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10O schema: da Feature valida os blocos values: e infra: próprios da anexação da Feature. O schema: do Component valida os próprios do Component. Os dois são avaliados independentemente na etapa de análise estática; um pilar da anexação que não corresponde ao schema: da Feature interrompe o build com um erro restrito ao local da anexação da Feature, não ao Component hospedeiro. O que é validado é a configuração efetiva da anexação — o resultado de compor cada escopo que a configurou —, de modo que um valor tornado conforme em um escopo e depois sobrescrito por algo ilegal em um mais restrito é detectado.
Os padrões declarados se materializam nos pilares renderizados da anexação. Além da validação, um default: declarado em um campo values ou infra de uma Feature é preenchido no pilar renderizado dessa anexação no momento do build para cada chave que ninguém escreveu — assim, um template de FeatureRecipe que lê {{ .infra.tier }} recebe o valor declarado no schema em vez de um vazio. Os valores fornecidos pelo autor sempre prevalecem, e um padrão preenche apenas as chaves que eles omitem: uma anexação que escreve uma chave do schema da Feature ainda recebe os padrões declarados para as outras chaves desse schema, e um objeto aninhado parcialmente escrito mantém o que foi escrito e ganha os irmãos que não foram.
Vale a pena conhecer três propriedades do preenchimento ao escrever:
- Um padrão nunca desloca um valor fornecido por algum escopo. Onde uma Feature é anexada em mais de um escopo — um limite de Release e um de seus componentes, por exemplo —, o valor do escopo mais restrito prevalece e o padrão preenche apenas o que nenhum escopo escreveu.
- Um padrão preenche uma anexação; nunca cria uma. Declarar padrões em uma Feature que nada anexa não contribui em nada para a saída, de modo que o schema de uma Feature não pode adicionar configuração que nenhum autor pediu.
- Uma anexação declarada em um limite de Release em vez de em um único componente preenche apenas
infra, porque essa superfície não carrega nenhum blocovalues:para preencher.
Como a materialização usa a mesma resolução de schema que a validação, um padrão declarado em uma Feature pai alcança as anexações de um filho extends:, e padrões alcançados por meio de um $ref: entre documentos para uma SchemaLibrary também se materializam. Padrões declarados apenas dentro de uma referência local no documento #/$defs/, ou sob um ramo allOf / oneOf / anyOf, não são materializados.
Uma consequência merece ser dita com clareza, porque a validação sozinha não a revelará: um campo required: que também carrega um default: é satisfeito por esse padrão, então omiti-lo é legal — e o valor com base no qual a verificação aceitou é o valor que a saída renderizada carrega.
O contexto de template do compilador expõe o estado da instância da Feature à FeatureRecipe associada por meio do campo .features.<alias> (que contém .type, .resolved_version, .labels, .values, .infra e .provides por anexação). Os templates dentro da FeatureRecipe leem os próprios values: da Feature por meio de .values.<field> no escopo de template da própria FeatureRecipe; os values: do Component hospedeiro não são diretamente visíveis para os templates da FeatureRecipe, a menos que a Feature declare explicitamente um socket uses: para o Component hospedeiro.
Essa separação de escopos torna as Features componíveis: uma Feature autoscaler não depende do Component ao qual é anexada; seu schema: descreve a intenção de autoescalonamento independentemente do hospedeiro. Os values: do Component hospedeiro são assunto do hospedeiro; os values: da Feature são assunto da Feature; os dois pilares se compõem sem vazar nomes de campos através do limite.
Destinos de bindings de anotação
Uma Feature não declara ela mesma bindings de anotação; o mapa mappings.features.annotations do Manifest os carrega. Uma Feature participa indiretamente da relação de binding como destino de roteamento: cada binding nomeia um tipo de Feature por meio de seu campo feature:, e as listas maps.infra e maps.values do binding declaram caminhos pontuados para as propriedades spec.schema.infra.<path> e spec.schema.values.<path> da Feature nomeada.
No carregamento do catálogo, o compilador verifica se cada caminho pontuado nas listas maps de um binding corresponde a uma propriedade que o spec.schema da Feature de destino realmente declara no pilar nomeado. Um binding que roteia para um caminho que o schema da Feature não declara interrompe o carregamento do catálogo com um OPS_ERROR claro, nomeando o binding, a Feature de destino e o pilar e o caminho pelos quais roteou — o binding é escrito no Manifest, que é o documento do operador. Os autores de schema sabem, portanto, que qualquer propriedade que declarem em spec.schema.values.<path> ou spec.schema.infra.<path> é alcançável como destino de binding; inversamente, qualquer propriedade pela qual um binding do Manifest roteie deve existir no schema da Feature de destino.
Quando uma anotação do lado do Aggregate ou do lado da Release corresponde a um binding, o compilador sintetiza uma anexação de Feature cujos payloads de pilar roteiam o valor da anotação para os caminhos nomeados. A anexação sintetizada é estruturalmente indistinguível de uma anexação de Feature explícita declarada pelo autor no mesmo local; a renderização subsequente, a validação e o contexto de template da FeatureRecipe consomem ambas as formas de maneira uniforme. Para a forma do binding, a partição entre lado e pilar e a disciplina em que a anexação explícita prevalece, consulte entities/manifest.md §“Bindings de Feature orientados por anotação”. Para a regra de cascata do lado do Aggregate e um exemplo de autoria, consulte providers/well-known-annotations.md §“Cascata de anotações do lado do Aggregate”.
O bloco assertions:
Feature.spec.assertions: é um mapa opcional de regras nomeadas que expressam invariantes arquiteturais do contrato da Feature — regras entre campos sobre os values: da Feature e o estado resolvido do Component anexado. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. O compilador as avalia após a validação de schema e antes que a FeatureRecipe associada renderize, na ordem em que estão escritas, e a primeira regra que falhar interrompe o build com a mensagem de erro própria dessa regra.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Assim como as asserções de Component, as asserções de Feature expressam invariantes no nível do contrato — propriedades que a anexação da Feature deve satisfazer independentemente de qual FeatureRecipe implementa a renderização. Para regras entre campos que dependem da implementação específica (um requisito de plugin Wasm, uma peculiaridade de um chart), use em vez disso o campo assertions: da FeatureRecipe. Para a gramática de autoria completa, o contexto de template e a divisão de responsabilidades entre as asserções de Feature e de FeatureRecipe, consulte templates/assertions-block.md.