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

O bloco `assertions:`

Component, Feature, Recipe e FeatureRecipe transportam um campo opcional spec.assertions: — um mapa de regras com nome que o compilador avalia após a validação do esquema mas antes da renderização. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. Um único corpo de template escrito diretamente sob assertions: não tem a forma do campo e é rejeitado quando a entidade é lida, pelo que cada regra é escrita sob um nome próprio. O bloco exprime regras entre campos que o JSON Schema não consegue captar de forma compacta: invariantes que envolvem vários campos em que nenhum campo isolado é «o que está a ser validado». Esta página abrange a gramática de autoria, a fase de avaliação, o contexto do template e a divisão de responsabilidades entre as asserções de Component / Feature (invariantes arquiteturais do contrato) e as asserções de Recipe / FeatureRecipe (invariantes de implementação do fornecedor específico).

Para restrições por campo (intervalo, padrão, enum, formato), utilize as palavras-chave nativas do JSON Schema dentro de schema:. Para predicados personalizados por campo, utilize o campo validate: da forma compacta. Para uma forma condicional, utilize when:. O campo assertions: complementa-os — é o lugar das verdadeiras regras entre campos.

Onde o campo aparece

As quatro entidades que podem transportar assertions::

  • Component — invariantes arquiteturais do contrato do Component.
  • Feature — invariantes arquiteturais do contrato da Feature.
  • Recipe — invariantes de implementação do chart ou módulo subjacente da Recipe.
  • FeatureRecipe — invariantes de implementação do mecanismo subjacente da FeatureRecipe.

O campo é opcional em cada uma. As entidades sem regras entre campos omitem o campo por completo.

Quando as asserções são executadas

As fases de avaliação de asserções situam-se entre a validação do esquema e a renderização no pipeline de compilação:

  1. Resolução: validação e interpolação de parâmetros, depois validação do esquema em relação a schema: / usesSchema: / featuresSchema:.
  2. Construção da topologia e finalização do grafo: o grafo é montado.
  3. Análise estática: o seletor de cada socket uses: é verificado em relação às etiquetas dos componentes que as suas conexões alcançam.
  4. Asserções de Component / Feature avaliadas em relação a cada instância.
  5. Associação da Recipe.
  6. Asserções de Recipe / FeatureRecipe avaliadas em relação à instância associada.
  7. Renderização: templates de mapeamento avaliados, saída produzida.

As duas fases de asserção são executadas antes de qualquer renderização — nenhum chart renderizado, nenhum ficheiro Compose gerado. A única coisa que se pergunta a um fornecedor antes de as asserções da Recipe serem executadas é o nome que ele dá aos recursos de cada nó associado, que o provides de uma Recipe pode ler. Uma asserção falhada faz parar o build imediatamente com a mensagem de erro específica da asserção; os passos seguintes não são executados.

A separação entre as duas fases reflete a divisão de responsabilidades: as regras ao nível do Component aplicam-se independentemente da Recipe que seja associada, pelo que são acionadas antes da associação; as regras ao nível da Recipe aplicam-se dada uma escolha específica de Recipe, pelo que são acionadas depois da associação.

O contexto de template

Para as assertions: de Component e Feature, o contexto de template expõe o estado resolvido da instância:

  • .values — o conteúdo values do programador.
  • .infra — o conteúdo infra de Ops (do Aggregate ou da Release).
  • .uses — as conexões uses: resolvidas, cada uma já verificada em relação ao seletor do seu socket, na forma em que o autor as escreve: indexadas pelo nome do socket e, sob cada socket, pelo alias de cada conexão nele — o nome que o autor deu à conexão sob o socket ou, para uma conexão escrita como entrada de lista, o seu destino. A entrada de cada conexão descreve a conexão e não transporta nada que o seu destino tenha publicado. target é o id de instância do destino resolvido, alias repete o nome pelo qual a entrada é indexada, e origin_feature está presente quando foi uma anexação de Feature a traçar a conexão. Ao lado deles encontram-se três factos, sob os nomes pelos quais um template de Recipe os lê na entrada .context.uses.<alias> da mesma conexão, onde template-context-contract.md descreve o que cada um contém: labels — as etiquetas do destino, nunca as etiquetas do componente em que a asserção é executada — values, os valores escritos na conexão, e features, as anexações escritas na conexão, indexadas pelo slot que cada uma preenche. Cada um dos três está presente em todas as conexões, vazio onde a conexão não transporta nenhum, e uma anexação sob features tem a forma que .features dá a uma anexação mais abaixo. Assim, .uses.<socket>.<alias>.target lê o destino resolvido de uma conexão, .uses.<socket>.<alias>.labels as etiquetas desse destino, um socket que contém várias conexões contém uma entrada para cada uma, e uma referência que atravessa este mapa à procura de um valor publicado pelo destino faz parar o build, porque a entrada não transporta tal campo.
  • .features — as anexações resolvidas, indexadas pelo nome de instância que o autor deu a cada uma. Cada entrada transporta type (o URI de catálogo da Feature anexada), resolved_version (a versão associada para este build) e values (o conteúdo de intenção do programador próprio da anexação). Uma anexação escrita numa das conexões do componente não está entre elas, exatamente como não está entre as .features de um template de Recipe: é lida sob a sua conexão, em .uses.<socket>.<alias>.features.<slot>, nesta mesma forma.
  • .metadata — a instância a ser avaliada: o seu instance_id, o seu tipo component e a sua resolved_version, o seu boundary_path, e aggregate_name, aggregate_version e release_version do build.

Para as assertions: de Recipe e FeatureRecipe, o contexto acrescenta campos específicos da Recipe:

  • .provides — os valores provides: resolvidos do componente a ser avaliado, já calculados no momento em que a asserção é executada. Os valores publicados de um destino não estão nesta superfície; chegam antes a um chamador no contexto de renderização.
  • .locals — os locals da Recipe.
  • .recipe.metadata — o name e a version da Recipe, e a sua capability.
  • .recipe.source — o ponteiro de origem da Recipe.

O acesso a campos utiliza a sintaxe padrão dos templates Go (.values.architecture, .uses.databases.primary.target); a construção que faz parar o build é {{ fail "message" }}, de acordo com o contrato Loud Guardrails — uma asserção falhada produz um erro claro e específico em tempo de build que nomeia o invariante violado.

Esta superfície avalia com missingkey=error. Uma referência a uma chave que o contexto não transporta faz parar o build — nomeando a entidade, a instância, a asserção e a chave ausente — em vez de ser renderizada como nada. Esse rigor é o que torna uma asserção fiável: um predicado cuja referência fosse renderizada vazia compararia com nada e passaria, pelo que uma única gralha desativaria silenciosamente a regra que a asserção foi escrita para impor. Significa também que a referência simples é resolvida antes de qualquer fallback poder ser executado, pelo que um campo opcional precisa de uma forma que tenha em conta a presença; errors/fatal-halts.md apresenta a política de chaves em falta de cada superfície e as formas que funcionam sob ela.

Ler as conexões de um socket. A entrada de um socket tem uma única forma, seja o que for que contenha: uma entrada por conexão, sob o seu alias. Uma asserção lê uma conexão pelo seu alias, conta ou percorre o socket para ver cada conexão nele, e testa a própria chave do socket para perguntar se está ligado de todo. Dado um componente cuja entrada no Aggregate escreve

uses:
models:
local: { target: llama }
fast: { target: turbo }

estas asserções leem-na de cada uma das formas:

assertions:
# The socket's presence: the socket key alone, however many connections it holds.
models-wired: |
{{- if not (hasKey .uses "models") -}}
{{- fail "wire at least one model to the models socket" -}}
{{- end -}}
# Every connection on the socket: a range visits each one.
every-model-distinct: |
{{- $seen := list -}}
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- if has $connection.target $seen -}}
{{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}}
{{- end -}}
{{- $seen = append $seen $connection.target -}}
{{- end -}}
# One connection, by the alias it was written under; guarded, because the
# connection is optional.
fast-is-not-local: |
{{- with (optional .uses "models" dict) -}}
{{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}}
{{- fail (printf "the fast and local connections both point at %s" .local.target) -}}
{{- end -}}
{{- end -}}

Um ciclo range percorre as conexões de um socket por ordem alfabética dos seus aliases — aqui fast antes de local —, não pela ordem em que o Aggregate as escreveu. Um socket que contém uma única conexão é lido da mesma forma: .uses.models.local.target lê llama quer fast esteja ou não ligado ao lado, e .uses.models.target não endereça nenhuma conexão e faz parar o build.

Cada conexão que um componente detém tem aqui uma entrada própria, porque não há duas conexões de um mesmo componente que partilhem um alias — num socket ou em dois, qualquer que seja o documento ou a anexação que traçou cada uma. O build recusa um par assim, nomeando as duas conexões e onde cada uma foi escrita, antes de qualquer asserção ser executada. Uma lista que nomeia o mesmo destino duas vezes é um par assim, uma vez que o alias de uma entrada de lista é o seu destino; também o é a conexão local própria de um componente ao lado da conexão local de uma anexação no mesmo componente.

Ler o que uma conexão transporta. Uma regra sobre uma conexão pode ler o que é o seu destino, o que o programador escreveu na conexão e o que lhe está anexado, de modo que se mantém válida qualquer que seja a Recipe associada. Um Component cujo socket models declara um valor unauthenticated e um slot credential pode recusar uma conexão a um destino que o seu catálogo etiqueta como serviço alojado quando essa conexão não transporta nem uma credencial nem o opt-out:

assertions:
hosted-model-needs-a-credential: |
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}}
{{- $optedOut := optional $connection.values "unauthenticated" false -}}
{{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}}
{{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}}
{{- end -}}
{{- end -}}

A etiqueta é lida de labels, que são as do destino — o modelo — e nunca as do próprio componente; o opt-out é lido dos values da conexão; e a credencial é um slot sob as features da conexão. Cada um é lido com optional ou hasKey, porque um destino pode não transportar tal etiqueta e uma conexão tal valor. O que a etiqueta significa é a convenção do catálogo: o build transporta a string e a asserção decide o que ela significa.

O .uses de uma asserção não é o .context.uses de um template de Recipe, e uma referência escrita para um não se transfere para o outro. O contexto de renderização transporta uma projeção mais rica das mesmas arestas: indexada apenas pelo alias, com o nome do socket como campo da entrada, e com os valores publicados de cada destino aninhados sob provides — de modo que um template de Recipe lê .context.uses.<alias>.provides.<name> onde uma asserção lê .uses.<socket>.<alias>.target. Os factos que ambas as vistas transportam partilham os nomes, mas não os caminhos: .context.uses.<alias>.labels e .uses.<socket>.<alias>.labels são as etiquetas do mesmo destino, e values e features leem igualmente a mesma conexão em qualquer uma delas. As duas fases de asserção avaliam antes da renderização, razão pela qual a vista que uma asserção tem de uma aresta não transporta nada que o seu destino tenha publicado, e pela qual uma anexação nela não transporta nenhum provides.

Para a forma mais ampla do contexto de template e a semântica de disponibilidade por campo, consulte template-context-contract.md.

Números nesta superfície

Uma asserção lê um número escrito pelo autor exatamente como o faz um template de valor — consulte Números num template de valor:

  • Comparações. As seis comparações leem dois números pelo valor, qualquer que seja o tipo que transporta cada um: lt .values.replicas 1.5 e eq .values.replicas 3.0 respondem aqui como num template de valor, um 0.1 escrito pelo autor é eq a um 0.1 escrito na asserção, e comparar um número com texto entre aspas faz parar o build com as mesmas palavras.
  • Vazio. Um 0 escrito pelo autor é vazio: falso para if e with, verdadeiro para empty e substituído por default. Uma regra que pergunta se o autor escreveu um valor — incluindo um 0 — pergunta-o com os helpers de presença: para um 0 escrito pelo autor, hasKey .values "replicas" é verdadeiro e optional .values "replicas" 1 devolve 0. Uma regra que pergunta se o valor é zero compara: eq .values.replicas 0. Presença e vazio coloca as duas perguntas lado a lado.
  • Impressão. Um número que uma mensagem fail imprime lê-se como se leria na saída de um template de valor: um número inteiro como inteiro, de modo que printf "%d" imprime os seus dígitos, e qualquer outro número na sua forma decimal exata mais curta, de modo que um 0.0000001 escrito pelo autor se lê 0.0000001.

Asserções de Component / Feature — invariantes arquiteturais

Estas exprimem regras que se mantêm independentemente da Recipe que se associe ao Component. A regra é uma propriedade do contrato, não da implementação.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
schema:
values:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
secondary:
replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions:
# Replication mode requires at least 2 secondary replicas.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node count limit for safe replication coordination.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count must not exceed 9; got %d" $total) -}}
{{- end -}}

Ambas as regras exprimem propriedades do contrato do MariaDB. Qualquer que seja a Recipe associada — um chart da Bitnami, uma alternativa feita à mão — as regras aplicam-se.

O controlo de espaços em branco {{- ... -}} é importante: os templates de asserções não produzem saída, apenas efeitos secundários através de {{ fail }}. O corte dos espaços mantém vazio o corpo do template renderizado em caso de sucesso.

Asserções de Recipe / FeatureRecipe — invariantes de implementação

Estas exprimem regras que se mantêm para o chart ou módulo específico de onde a Recipe obtém a sua origem. A regra é uma propriedade da implementação, não do contrato.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: bitnami/datastore/mariadb/k8s
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:^1.0.0
source:
# Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead.
chart: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
valuesMapping:
$import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions:
# Bitnami chart 20.x requires an explicit ServiceMonitor namespace when
# replication and metrics scraping are both enabled.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# ARM-node incompatibility.
arm-rejects-hard-anti-affinity: |
{{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}}
{{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}}
{{- end -}}

Cada regra é específica da implementação do chart da Bitnami 20.x. Se for associada uma Recipe de MariaDB diferente — um chart feito à mão, uma implementação alternativa — estas regras não se aplicam. As regras ao nível do Component (replication-needs-two-secondaries, total-node-count-within-cap) continuam a aplicar-se porque são propriedades do contrato.

Porque é que as asserções de Component e de Recipe são separadas

Os dois papéis parecem semelhantes (ambos executam paragens {{ fail }} sobre regras entre campos), mas a divisão de responsabilidades é estrutural:

  • As asserções de Component fazem parte do contrato. Quando o programador escreve architecture: replication com secondary.replicaCount: 1, o build recusa independentemente da Recipe que seja associada. Uma futura Recipe alternativa não muda isso.
  • As asserções de Recipe fazem parte da implementação. Quando o arquiteto escolhe o chart da Bitnami 20.x como Recipe, o chart tem particularidades específicas (o requisito de serviceMonitor.namespace, o bug dos nós ARM). Estas não se aplicam a um chart diferente.

Colocar os dois tipos de regra no Component entrelaçaria o contrato com as suas implementações: o Component precisaria de referenciar a Recipe que lhe está associada para saber que regras de implementação impor, quebrando a separação Component-Recipe. Dividir as regras pelo seu local natural mantém limpo o modelo de responsabilidades. O custo de execução da divisão é desprezável; as duas fases são executadas antes da renderização e param com o mesmo diagnóstico Loud Guardrails, E0033, que nomeia a entidade, a instância e a regra.

A convenção das mensagens fail

O argumento de {{ fail "..." }} é o erro em tempo de build apresentado ao utilizador. Convenções:

  • Nomear a restrição — «architecture=replication requires secondary.replicaCount >= 2» (architecture=replication exige secondary.replicaCount >= 2).
  • Nomear o valor quando for relevante — «total node count must not exceed 9; got 12» (o número total de nós não deve exceder 9; obtido 12).
  • Sugerir a correção quando possível — «use ‘soft’ or omit the field» (utilize ‘soft’ ou omita o campo).
  • Evitar jargão — quem lê é o programador que escreveu o Aggregate, não o arquiteto que escreveu a asserção.

Para mensagens longas ou que contêm valores, utilize printf:

{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}

O compilador apresenta a mensagem no formato de erro Loud Guardrails com o nome da entidade, a localização da asserção no código-fonte e a mensagem de falha. O diagnóstico é suficientemente específico para que o programador identifique e corrija a causa principal.

Um valor que um autor declarou sensitive: true lê-se <redacted> nessa mensagem sempre que a mensagem o cita, pelo que nomear na mensagem o valor de um campo declarado é seguro: o diagnóstico continua a nomear a regra e o campo, e apenas o valor é retido. Uma asserção cujo resultado depende do que tal valor contém — uma comparação com um literal, um teste de prefixo — indica que o seu texto de falha é retido em vez da sua mensagem. vocabulary/compact-form-authoring.md «O que uma recusa diz sobre um valor declarado» contém a regra completa.

O que assertions: não substitui

assertions: é o lugar das regras entre campos. Não substitui:

  • Restrições de JSON Schema dentro de schema: — as regras por campo (intervalo, padrão, enum, formato, tipo) pertencem às palavras-chave nativas do JSON Schema.
  • O campo validate: da forma compacta — predicados personalizados por campo com âmbito de um único campo. Utilize validate: quando a regra se aplica a um campo específico; utilize assertions: quando a regra envolve vários campos e nenhum campo isolado é «o que está a ser validado».
  • O campo when: da forma compacta — forma condicional (se as restrições de uma subárvore se aplicam). Utilize when: para variações de forma; utilize assertions: quando a combinação de valores é inválida de um modo que se exprime melhor como um predicado de forma livre.
  • Verificações em tempo de execução — assertions: é executado apenas em tempo de compilação. Tudo o que depende do estado do cluster em tempo de execução (IPs ativos, conteúdo do vault, estado dos pods em tempo de execução) tem de ser expresso como strings de ponteiro determinísticas (consulte o contrato de pureza AOT).

Exemplos práticos

Mínimo — regra arquitetural única

spec:
assertions:
replication-needs-two-secondaries: |
{{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}}
{{- fail "replication requires secondary.replicaCount >= 2" -}}
{{- end -}}

Dimensão média — contrato de Component com várias regras

spec:
assertions:
# Replication minimum.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node limit.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)"
$total .values.primary.replicaCount .values.secondary.replicaCount) -}}
{{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one.
service-monitor-needs-metrics: |
{{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}}
{{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}}
{{- end -}}

Produção — Recipe com regras de implementação

spec:
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# TLS certificate consistency.
tls-needs-both-certificate-files: |
{{- if .values.tls.enabled -}}
{{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}}
{{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}}
{{- end -}}
{{- end -}}
# Replication-mode storage class consistency.
replication-needs-one-storage-class: |
{{- if eq .values.architecture "replication" -}}
{{- $primaryClass := .values.primary.persistence.storageClass -}}
{{- $secondaryClass := .values.secondary.persistence.storageClass -}}
{{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}}
{{- fail "replication mode requires primary and secondary to use the same storageClass" -}}
{{- end -}}
{{- end -}}

Integração com ferramentas

  • aggrega build avalia as asserções entre a validação do esquema e a renderização; uma asserção falhada faz parar o build com a mensagem {{ fail }} da asserção.
  • aggrega validate aplica a mesma correção antes da renderização sem escrever artefactos — para uma Recipe cuja origem não é obtida, conduz o pipeline de compilação real em torno de um Aggregate, um Manifest e uma Release mínimos sintetizados, de modo que um template de asserção malformado ou uma asserção que referencia um campo desconhecido surge como um erro de correção; as asserções de uma Recipe cuja origem é obtida são avaliadas por um build. Uma asserção que aí chame fail é reportada como um aviso que transporta a sua mensagem, e a verificação passa: a Release sintetizada contém marcadores de posição e valores predefinidos em vez dos valores que uma Release real define, pelo que o veredicto sobre a asserção fica para um build — consulte uma asserção falhada é um aviso. (aggrega lint abrange as convenções de publicação, não a correção das asserções.)
  • Os IDE com suporte para templates Sprig destacam as referências .values.X; a documentação apresentada ao passar o rato remete para a definição do esquema quando a integração com o IDE está configurada.