Feature
O papel conceptual da entidade Feature (o traço operacional modular no Domínio 2) está descrito em architecture/04-entity-taxonomy.md. A distinção entre Features operacionais e Features de credenciais (as etiquetadas com feature.aggrega.ai/kind: secret) está descrita em architecture/08-credential-model.md. O vocabulário de etiquetas semânticas usado pelos seletores de Feature está em entities/component. Esta página abrange a superfície de criação da Feature no catálogo.
Localização no catálogo
Ao contrário dos Components (que usam URIs de três segmentos com subdiretórios de categoria), as Features estão organizadas de forma plana: um diretório por Feature sob o 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} (p. ex., hub.aggrega.ai/feature/core/data-masking:1.0.0).
Contrato de criação
As Features declaram:
metadata.labels: usefeature.aggrega.ai/kind: secretpara marcar uma Feature como Feature de credencial. A etiqueta é metadados descritivos para o autor, para o site do catálogo e para os seletores de etiquetas; nenhum ramo do compilador a lê, e o que uma anexação produz é decidido pela FeatureRecipe para a qual o Manifest mapeia o seu tipo, não pela etiqueta. Uma Feature de credencial e uma Feature comum são anexadas da mesma forma, na mesma superfície de anexação, em qualquer âmbito. A família de credenciais da biblioteca padrão divide-se pelo resultado:core/secret-valueentrega um valor no canal de inject;core/referenced-secretindica um recurso secreto referenciável (um Secret do Kubernetes, um segredo do AWS Secrets Manager, uma entrada do Vault), um que a saída da sua FeatureRecipe cria ou um que já existe, e declara um contrato de saídaschema.provides—name(o localizador do recurso, independente do fornecedor) ekey(o campo de dados dentro dele) — que um consumidor lê como.features.<slot>.provides.<key>para referenciar o recurso sem voltar a derivar o seu nome;core/referenced-secret-setmaterializa um recurso que contém 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 motor de destino gera e gere ele próprio a credencial, pelo que não declara nemvaluesnemprovidese as suas FeatureRecipes são pura ligação que não renderiza nenhum byte. Dois eixos separam os membros: quem fornece o material — um autor escreve-o ou indica onde obtê-lo, ou o motor de destino é inteiramente dono dele, como comcore/generated-secret— e o que a anexação produz: um valor injetado, um recurso referenciável ou nada renderizado. Cada membro é par dos outros na mesma superfície de anexação, pelo que um slot de credencial está sempre associado e o que varia entre Releases é aquilo que o associa. Uma Feature de credencial que declara um contratoschema.providesobriga cada FeatureRecipe que a implementa a publicar essas chaves — caso contrário, o build é interrompido — e oselectorde um slot defeaturesSchemavisa 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 visa um cofre). Consulte architecture/13-catalog-and-registry.md §2 para o mecanismo Split Schema.schema: valida os blocosvalueseinfrada anexação da Feature — a intenção cognitiva que o Programador configura em cada anexação no Aggregate (osvaluessão o domínio do Programador, e o esquema da Release proíbevalues:nas anexações de Feature) e a capacidade que o Operador decide por ambiente na Release (infra). Um campo que declara umdefault:é validado com base nele e também é preenchido com ele no pilar renderizado quando nada o cria; consulte Âmbito da Feature e forma de criação. Aceita JSON Schema 2020-12 expresso na abreviatura YAML de forma compacta (a predefinição; consultevocabulary/compact-form-authoring.md) ou em JSON Schema YAML completo, com$ref:entre documentos para entradas de SchemaLibrary para formas partilhadas (consultevocabulary/cross-document-ref.md). Uma folha que contém material secreto declarasensitive: true— as Features de credenciais da biblioteca padrão marcam a folha que contém o material e deixam deliberadamente sem marca os seus localizadores publicados, uma vez que o nome de um recurso e uma chave de dados são ambos públicos. A palavra-chave, e o limite do que declará-la consegue, estão emvocabulary/compact-form-authoring.md«Declarar uma folha como sensível».featuresSchema(opcional): declara os slots de anexação de que a Feature precisa para o seu próprio funcionamento — uma Feature declara slots exatamente como um Component, pelo que uma Feature que ela própria precisa de uma credencial (a chave de API de uma Feature de sidecar do Datadog, por exemplo) indica o ponto de ligação em vez de recorrer aos slots do Component anfitrião. Consulte A credencial própria de uma Feature para ver uma Feature que declara o seu próprio slot e uma FeatureRecipe que lê o que o preenche. Cada slot aceita os mesmos campos que um slot defeaturesSchemade um Component, com a mesma semântica — incluindo umselectoropcional (um seletor de etiquetas ao estilo do Kubernetes que restringe que Feature pode preencher o slot, o análogo, para slots, de um seletor de socket deusesSchema; um preenchimento cujas etiquetas não o satisfaçam interrompe o build, e o seletor é avaliado contra as etiquetas da Feature anexada e nada mais), umsensitiveopcional (que declara que aquilo que associa o slot trata material secreto — uma afirmação sobre o ponto de ligação e não sobre um preenchimento em particular) 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 ao nível do slot e a forma como difere da de uma folha de esquema, e as duas formas em que uma entidade que declara slots é implementada estão todas em entities/component.md «Slots de anexação».appliesTo/appliesToAnyOf: seletores de etiquetas que controlam a que Components a Feature se pode anexar. Avaliados pelo motor nativo de correspondência de etiquetas do compilador durante a fase de análise estática. Consulte Anexação baseada em etiquetas abaixo e architecture/13-catalog-and-registry.md §2 «Seletores ao estilo do Kubernetes» para a referência da sintaxe dos seletores.interoperability(opcional): um bloco aninhado que contémconflictsWith— as Features com as quais esta Feature não pode alcançar um componente em conjunto. O build é interrompido antes da renderização quando um componente acaba por transportar ambas, qualquer que seja o âmbito em que cada uma foi anexada. Consulte O blocointeroperabilityabaixo para a explicação completa.
A renderização estrutural de uma Feature está associada à sua FeatureRecipe correspondente, que mapeia a interface da Feature para uma implementação de infraestrutura concreta.
Anexação baseada em etiquetas
Os dois seletores applies no esquema da Feature controlam a que Components a Feature se anexa, avaliados pelo motor nativo de correspondência de etiquetas do compilador durante a fase de análise estática:
appliesTo— uma string de seletor de etiquetas ao estilo do Kubernetes; a superfície de composição AND. Os requisitos separados por vírgulas têm todos de se verificar, com o vocabulário completo de operadores:key=value,key!=value,key in (v1, v2),key notin (v1, v2),keysimples (etiqueta presente),!key(etiqueta ausente). Uma Feature que declaraappliesTo: "datastore.aggrega.ai/engine=vector"anexa-se apenas a Components etiquetados com esse par chave-valor exato;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"exprime «qualquer servidor ou worker que não contenha dados restritos» numa ú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 (a mesma gramática queappliesTo; os requisitos dentro da string combinam-se com AND) ou um mapa plano chave-valor para correspondência apenas por igualdade. Usado quando uma Feature se adequa a 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 ambas numa única string de seletor.
Sem a forma any-of, os Arquitetos teriam de duplicar o mesmo YAML de Feature para cada forma de componente não relacionada a que a Feature se adequa. As duas formas compõem-se: uma Feature pode declarar ambas, e os resultados combinam-se com AND entre as formas — a string appliesTo tem de se verificar e pelo menos um item de appliesToAnyOf tem de corresponder. Um seletor omitido ou vazio não declara nenhuma restrição e corresponde a qualquer conjunto de etiquetas.
Uma string de seletor é lida face à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 outro seletor: um requisito vazio (uma vírgula no início, no fim ou duplicada, ou uma string apenas com separadores), uma chave que contenha espaços em branco ou qualquer um de =, !, (, ) e a vírgula, e um conjunto in ( ou notin ( que não esteja fechado. É isso que apanha os erros que, de outro modo, selecionariam silenciosamente o oposto do pretendido: appliesTo: "!tier=frontend", escrito para manter uma Feature fora dos frontends, é recusado porque ! indica uma chave de etiqueta e nada mais — tier!=frontend é a forma de excluir um valor — e tier in frontend é recusado em favor de tier in (frontend). Um valor é o texto após o seu operador, sejam quais forem os caracteres que contenha, pelo que tier==frontend pede uma etiqueta cujo valor é =frontend. A interrupção indica a Feature, o seu seletor e o requisito que não pôde ser lido. Uma Feature que nada anexa nunca é avaliada, pelo que um seletor malformado nela só é comunicado quando uma anexação a indicar.
Consulte architecture/13-catalog-and-registry.md §2 «Seletores ao estilo do Kubernetes» para a referência da sintaxe dos seletores — a gramática que um seletor de Feature aceita é a mesma que os seletores de socket de usesSchema aceitam, a forma de string que os utilizadores do Kubernetes conhecem de kubectl get -l.
O bloco interoperability
O esquema da Feature declara um bloco spec.interoperability opcional que contém um único controlo: com que outras Features esta Feature pode coexistir num componente.
interoperability.conflictsWith — uma lista das Features mutuamente exclusivas com a Feature que está a ser definida, cada uma escrita da forma como o type de uma anexação indica uma Feature. Impede a geração de configurações incompatíveis — anexar uma mesh apenas TCP e um proxy com reconhecimento de HTTP ao mesmo componente, por exemplo.
O build é interrompido antes de renderizar o que quer que seja quando um componente acaba por transportar esta Feature e uma Feature que a sua lista indica. O que conta é o alcance: uma anexação alcança o componente em que está escrita e todos os componentes dentro do subsistema ou da fronteira em que está escrita, incluindo fronteiras aninhadas; uma anexação escrita numa entrada de componente da Release, ou produzida pela expansão orientada por anotações, alcança o 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á numa fronteira e a outra num componente dentro dela, quando uma está numa fronteira exterior e a outra numa fronteira aninhada dentro dela que contém um componente, e quando uma está num subsistema e a outra num componente desse subsistema. Duas Features anexadas a fronteiras irmãs que não partilham nenhum componente nunca se encontram, e uma fronteira sem nenhum componente não alcança nada — nenhum dos casos interrompe o build.
- Uma declaração é suficiente. O build é interrompido quando a lista de qualquer uma das Features indica a outra; a segunda Feature não tem de listar a primeira em reciprocidade.
- Nomes, sejam quais forem as versões. Cada entrada e o tipo de cada anexação são comparados sem qualquer versão, pelo que uma entrada
core/fixed-replica-controllercorresponde a uma anexação decore/fixed-replica-controller:2.0.0, e uma entrada com uma versão corresponde a todas as versões da Feature que indica. - Os nomes são tudo o que lê. O compilador compara os nomes que o autor da Feature declarou com as Features que um componente transporta — o mesmo tipo de avaliação que
appliesTo, sobre dados que o autor escreveu. Se duas Features são incompatíveis é um juízo do autor, e a lista é onde fica registado.
A interrupção indica a Feature cuja lista indica a outra, cada local onde cada uma das duas foi anexada — no componente no Aggregate, num subsistema, numa fronteira da Release com o seu caminho, numa entrada de componente da Release ou por expansão orientada por anotações de uma anotação com nome — e o componente onde se encontram. Um par que se encontra em vários componentes é comunicado 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 anexa-se apenas a Components do tipo server e declara incompatibilidade com outra Feature de controlo de réplicas: um build em que qualquer componente acabe por transportar ambas é interrompido antes da renderização. Uma FeatureRecipe que precise do nome do componente a que está anexada — para apontar um autoscaler para o seu destino, por exemplo — lê-o a partir do seu contexto de template e escreve-o onde a sua saída precisar: .context.instance_id é a identidade do componente, e .context.rendered_name é o nome que o próprio fornecedor do componente dá aos recursos que renderiza para ele, que é o que deve ser usado para visar 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 os seus próprios nomes.
Herança através de extends
Uma Feature pode declarar spec.extends: <feature-name> apontando para uma Feature base cuja superfície de criação herda. A referência indica a base pelo seu metadata.name, não pela coordenada de registo sob a qual a Feature é publicada, e aceita as mesmas três formas de versão que todas as referências de catálogo aceitam: simples (core/queue) para a versão mais alta disponível, exata (core/queue:1.0.0) ou um intervalo com acento circunflexo (core/queue:^1.0.0). O compilador percorre a cadeia de pais no carregamento do catálogo, valida que a cadeia é acíclica e depois funde as especificações dos pais no filho para produzir uma única Feature resolvida. Os campos criados do 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 fundidos automaticamente para baixo. Todos os outros campos de metadata são literalmente os do filho, pelo que a identidade e a proveniência nunca são herdadas.
O que o metadata: de uma Feature herda. labels e annotations fundem-se por chave ao longo da cadeia, primeiro a base, prevalecendo o valor da Feature que estende numa chave partilhada — a mesma regra que os Components seguem. O resto de metadata: não passa: name, version, description, maintainers, license, repository, home e keywords são da própria Feature que estende, exatamente como foram criados.
# 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 fundido herda appliesTo do pai, herda as propriedades values.qos e infra.partition_count e acrescenta values.compression_codec. Um filho que declare explicitamente appliesTo substitui por inteiro o seletor do pai (a fusão de seletores de etiquetas 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 herda cada parte da superfície de anexação. As duas formas de seletor herdam-se independentemente uma da outra, porque se compõem em vez de se substituírem: cada forma presente tem de se verificar — a string appliesTo tem de corresponder, e pelo menos um item de appliesToAnyOf tem de corresponder — enquanto uma forma ausente não restringe nada. Assim, uma Feature pode receber o seletor AND da sua base e declarar um conjunto OR próprio. O bloco interoperability herda-se campo a campo — um filho que declara o bloco sem uma lista conflictsWith continua a transportar a lista que a sua base declarou, enquanto um filho que declara a sua própria conflictsWith substitui a lista da base em vez de lhe acrescentar. Uma Feature que não declara nenhum dos três anexa-se exatamente onde a sua base se anexa.
A herança é fusão de esquemas, não associação de interfaces. Uma cadeia extends: de Feature produz uma única Feature resolvida, não uma família polimórfica. O URI da Feature base da cadeia não é o que o campo feature: de uma associação de Manifest referencia — os Manifests associam pelo URI da Feature folha, e o esquema resolvido inclui as propriedades herdadas. O contrato de Feature que uma FeatureRecipe implements: é igualmente o URI da folha; as FeatureRecipes não navegam pela cadeia de herança.
aggrega pull obtém a base. Uma Feature base é uma dependência de cada Release que anexa uma Feature que a estende, quer algo mais a indique quer não. aggrega pull segue cada extends: até ao fim da cadeia, obtém do registry uma base que nenhum diretório de catálogo contém e regista cada base no lockfile da Release, referenciada a partir do spec.extends da Feature que a indica; um build lê a base a partir daí.
Modos de erro. Uma cadeia extends: cíclica, e um pai que nenhuma entidade do catálogo fornece, interrompem a compilação, indicando a Feature a partir da qual a resolução começou, a Feature cuja linha extends: deve ser aberta e a referência que esta declara. As mensagens encontram-se 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 credenciais, consulte vocabulary/inheritance-and-interface.md.
Componibilidade: o contrato social da 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; não se combinam num ú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 esta convenção. As definições de Feature com preocupações mistas são sintaticamente legais e compilam sem erros. A imposição é opcional:
- As empresas que criam catálogos internos podem criar um plugin de linter personalizado que inspeciona as definições de Feature em CI/CD e emite um aviso quando as etiquetas
appliesTode uma única Feature abrangem domínios de capacidade não relacionados. - O autor de uma Feature que regista, em
interoperability.conflictsWith, que duas Features se sobreporiam adere a uma verificação no momento do build: o compilador interrompe o build onde quer que as duas alcancem um componente. Compara os nomes declarados e nada mais, pelo que 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 criação; os catálogos empresariais são livres de se desviar quando um composto fortemente acoplado se adequa genuinamente ao modelo de implementação.
O que justifica uma Feature, e onde pertence um parâmetro próprio de um produto
Uma Feature é uma anexação: traz algo que o programador ou o operador anexa deliberadamente — recursos, um passo de pipeline, ligações — e a convenção da biblioteca padrão é que 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 honra-a nos seus próprios termos.
Uma capacidade que apenas um produto no mercado tem é um parâmetro próprio desse produto e não uma Feature. Pertence como valor criado na superfície própria desse produto, que o autor que a decide define no seu pilar e lê a par de tudo o resto que configura o mesmo produto. Publicá-la como Feature oferece, em vez disso, uma portabilidade que nenhum outro produto consegue entregar: a anexação indica um único produto por construção, pelo que um autor que a anexe ao próximo produto que usar encontra um build que é interrompido indicando o tipo, e a Feature ensinou uma capacidade que nunca teve.
O teste conta produtos no mercado, não componentes deste catálogo, cada um lido a partir da sua própria referência de configuração atual. Dois produtos independentes que implementam uma capacidade tornam-na portável, por muitos deles que sejam disponibilizados aqui, pelo que uma Feature pode ser declarada antes de algo no catálogo a realizar — anexá-la então interrompe o build indicando o tipo — e cada realização disponibilizada é uma FeatureRecipe para um produto, que honra a anexação da forma como esse produto a configura.
A fixação de certificados upstream é o caso trabalhado. Uma fixação é um controlo sobre a chave que 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 encadeie até uma âncora de confiança que a Release fornece, e diferente ainda de afirmar o que o sujeito de um certificado diz — ambas indicam o que um certificado tem de dizer, enquanto uma fixação indica que chave tem de ser. Vários gateways aqui conseguem verificar contra uma âncora, e é por isso que dataplane.aggrega.ai/upstream-tls: trust-anchor é um valor com que um seletor pode corresponder. A fixação é uma capacidade separada, e pelo menos dois produtos independentes implementam-na para as ligações que abrem a um upstream: o Tyk recebe a chave pública do upstream em formato PEM e o Envoy recebe um hash dela. Por isso é uma Feature, core/upstream-key-pinning, cujo seletor indica dataplane.aggrega.ai/upstream-pinning: public-key, e o que este catálogo realiza é respondido produto a produto: core/gateway/tyk transporta o valor e uma FeatureRecipe para cada um dos seus destinos, enquanto os gateways aqui que incorporam o Envoy expõem a sua definição de fixação apenas para os certificados que os clientes apresentam, ou não a expõem de todo, pelo que não transportam nenhum valor e uma anexação a eles é interrompida no seletor. Uma fixação restringe o que um upstream pode apresentar; é um controlo, não uma garantia de que a ligação é, quanto ao resto, sólida.
Dois limites ao teste, e o segundo é a metade mais facilmente esquecida:
- É disciplina de criação, não uma verificação do compilador. Uma Feature que declara opções que nenhum produto implementa passa igualmente na validação do esquema, no linter de publicação e numa renderização — o compilador não interpreta o que uma Feature promete. O juízo cabe ao autor do catálogo.
- A incapacidade de um produto de honrar uma opção não é motivo para eliminar essa opção. Quando dois ou mais produtos disponibilizam uma capacidade sob nomes que se agrupam, a capacidade é portável e a Feature mantém-na; o produto que não a consegue honrar recusa-a. Uma Feature reduzida ao que todos os produtos suportam quase não tem nada a dizer.
Âmbito da Feature e forma de criação
O spec.schema de uma Feature define as formas values: e infra: da própria Feature — a intenção cognitiva que o Programador configura por anexação de Feature no Aggregate (values), distinta dos números de capacidade que o Operador decide por ambiente (infra). Os pilares da Feature residem nos seus próprios espaços de nomes e são validados independentemente dos pilares do Component anfitrião. Quando o Programador anexa uma Feature autoscaler a um Component web-server no Aggregate, o Aggregate contém os values: do Component (forma do anfitrião) mais os values: da Feature (a forma da intenção de escalamento — que métrica conduz o escalamento); os números de capacidade orientados para o operador (min_replicas / max_replicas) fluem através do 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 próprios blocos values: e infra: da anexação da Feature. O schema: do Component valida os do próprio Component. Os dois são avaliados de forma independente na fase de análise estática; um pilar de anexação que não corresponda ao schema: da Feature interrompe o build com um erro com âmbito no local da anexação da Feature, não no Component anfitrião. O que é validado é a configuração efetiva da anexação — o resultado de compor todos os âmbitos que a configuraram — pelo que um valor tornado conforme num âmbito e depois substituído por algo ilegal num âmbito mais estreito é detetado.
Os valores predefinidos declarados materializam-se nos pilares renderizados da anexação. Além da validação, um default: declarado num campo values ou infra de uma Feature é preenchido no pilar renderizado dessa anexação no momento do build para cada chave que nada criou — pelo que um template de FeatureRecipe que lê {{ .infra.tier }} recebe o valor declarado no esquema em vez de um vazio. Os valores fornecidos pelo autor prevalecem sempre, e um valor predefinido preenche apenas as chaves que estes omitem: uma anexação que cria uma chave do esquema da Feature continua a receber os valores predefinidos declarados para as outras chaves desse esquema, e um objeto aninhado parcialmente criado 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 criar:
- Um valor predefinido nunca substitui um valor que algum âmbito forneceu. Quando uma Feature é anexada em mais do que um âmbito — uma fronteira da Release e um dos seus componentes, por exemplo — o valor do âmbito mais estreito mantém-se e o valor predefinido preenche apenas o que nenhum âmbito escreveu.
- Um valor predefinido preenche uma anexação; nunca cria uma. Declarar valores predefinidos numa Feature que nada anexa não contribui com nada para a saída, pelo que o esquema de uma Feature não pode acrescentar configuração que nenhum autor pediu.
- Uma anexação declarada numa fronteira da Release, e não num único componente, preenche apenas
infra, porque essa superfície não transporta nenhum blocovalues:para preencher.
Como a materialização usa a mesma resolução de esquemas que a validação, um valor predefinido declarado numa Feature pai chega às anexações de um filho extends:, e os valores predefinidos alcançados através de um $ref: entre documentos para uma SchemaLibrary também se materializam. Os valores predefinidos declarados apenas dentro de uma referência local no documento #/$defs/, ou sob um ramo allOf / oneOf / anyOf, não são materializados.
Vale a pena indicar claramente uma consequência, porque a validação por si só não a revela: um campo required: que também tenha um default: é satisfeito por esse valor predefinido, pelo que omiti-lo é legal — e o valor com que a verificação foi aceite é o valor que a saída renderizada transporta.
O contexto de template do compilador expõe o estado da instância da Feature à FeatureRecipe associada através 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 através de .values.<field> no âmbito de template da própria FeatureRecipe; os values: do Component anfitrião 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 anfitrião.
Esta separação de âmbitos torna as Features componíveis: uma Feature autoscaler não depende do Component a que se anexa; o seu schema: descreve a intenção de escalamento automático independentemente do anfitrião. Os values: do Component anfitrião dizem respeito ao anfitrião; os values: da Feature dizem respeito à Feature; os dois pilares compõem-se sem que nomes de campos passem a fronteira.
Destinos de associação de anotações
Uma Feature não declara ela própria associações de anotações; é o mapa mappings.features.annotations do Manifest que as contém. Uma Feature participa indiretamente na relação de associação como destino de encaminhamento: cada associação indica um tipo de Feature através do seu campo feature:, e as listas maps.infra e maps.values da associação declaram caminhos com pontos para as propriedades spec.schema.infra.<path> e spec.schema.values.<path> da Feature indicada.
No carregamento do catálogo, o compilador verifica que cada caminho com pontos nas listas maps de uma associação corresponde a uma propriedade que o spec.schema da Feature de destino declara efetivamente no pilar indicado. Uma associação que encaminha para um caminho que o esquema da Feature não declara interrompe o carregamento do catálogo com um OPS_ERROR claro, que indica a associação, a Feature de destino e o pilar e o caminho por onde encaminhou — a associação está escrita no Manifest, que é o documento do operador. Os autores de esquemas sabem, portanto, que qualquer propriedade que declarem em spec.schema.values.<path> ou spec.schema.infra.<path> pode ser alcançada como destino de associação; inversamente, qualquer propriedade por onde uma associação de Manifest encaminhe tem de existir no esquema da Feature de destino.
Quando uma anotação do lado do Aggregate ou do lado da Release corresponde a uma associação, o compilador sintetiza uma anexação de Feature cujas cargas dos pilares encaminham o valor da anotação para os caminhos indicados. A anexação sintetizada é estruturalmente indistinguível de uma anexação de Feature explícita declarada pelo autor no mesmo local; a renderização a jusante, a validação e o contexto de template da FeatureRecipe consomem ambas as formas uniformemente. Para a forma da associação, a partição lado-versus-pilar e a disciplina de prevalência da anexação explícita, consulte entities/manifest.md §«Associações de Features orientadas por anotações». Para a regra de cascata do lado do Aggregate e um exemplo de criação, 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 com nome que exprimem 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 avalia-as depois da validação do esquema e antes de a FeatureRecipe associada renderizar, pela ordem em que estão escritas, e a primeira regra que falha interrompe o build com a mensagem de erro 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 -}}Tal como as asserções de Component, as asserções de Feature exprimem invariantes ao nível do contrato — propriedades que a anexação da Feature tem de satisfazer independentemente da FeatureRecipe que implementa a renderização. Para regras entre campos que dependam da implementação específica (um requisito de plugin Wasm, uma particularidade de um chart), use antes o campo assertions: da FeatureRecipe. Para a gramática de criação 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.