O bloco `assertions:`
Component, Feature, Recipe e FeatureRecipe carregam um campo opcional spec.assertions: — um mapa de regras nomeadas 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, de modo que cada regra é escrita sob um nome próprio. O bloco expressa regras entre campos que o JSON Schema não consegue capturar de forma compacta: invariantes que envolvem vários campos em que nenhum campo isolado é “o que está sendo validado”. Esta página cobre 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 provedor específico).
Para restrições por campo (intervalo, padrão, enum, formato), use as palavras-chave nativas do JSON Schema dentro de schema:. Para predicados personalizados por campo, use o campo validate: da forma compacta. Para uma forma condicional, use when:. O campo assertions: os complementa — é o lugar das verdadeiras regras entre campos.
Onde o campo aparece
As quatro entidades que podem carregar 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. 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 ficam entre a validação do esquema e a renderização no pipeline de compilação:
- Resolução: validação e interpolação de parâmetros, depois validação do esquema em relação a
schema:/usesSchema:/featuresSchema:. - Construção da topologia e finalização do grafo: o grafo é montado.
- Análise estática: o seletor de cada socket
uses:é verificado em relação aos rótulos dos componentes que as suas conexões alcançam. - Asserções de Component / Feature avaliadas em relação a cada instância.
- Associação da Recipe.
- Asserções de Recipe / FeatureRecipe avaliadas em relação à instância associada.
- 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 arquivo Compose gerado. A única coisa que é perguntada a um provedor antes que as asserções da Recipe sejam executadas é o nome que ele dá aos recursos de cada nó associado, que o provides de uma Recipe pode ler. Uma asserção com falha interrompe o build imediatamente com a mensagem de erro específica da asserção; as etapas seguintes não são executadas.
A separação entre as duas fases reflete a divisão de responsabilidades: as regras no nível do Component se aplicam independentemente de qual Recipe seja associada, por isso disparam antes da associação; as regras no nível da Recipe se aplicam dada uma escolha específica de Recipe, por isso disparam 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údovaluesdo desenvolvedor..infra— o conteúdoinfrade Ops (do Aggregate ou da Release)..uses— as conexõesuses: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 carrega nada que o seu destino tenha publicado.targeté o id de instância do destino resolvido,aliasrepete o nome pelo qual a entrada é indexada, eorigin_featureestá presente quando uma vinculação de Feature traçou a conexão. Ao lado deles ficam três fatos, 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— os rótulos do destino, nunca os rótulos do componente em que a asserção é executada —values, os valores escritos na conexão, efeatures, as vinculações escritas na conexão, indexadas pelo slot que cada uma preenche. Cada um dos três está presente em toda conexão, vazio onde a conexão não carrega nenhum, e uma vinculação sobfeaturestem a forma que.featuresdá a uma vinculação mais abaixo. Assim,.uses.<socket>.<alias>.targetlê o destino resolvido de uma conexão,.uses.<socket>.<alias>.labelsos rótulos 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 em busca de um valor publicado pelo destino interrompe o build, porque a entrada não carrega tal campo..features— as vinculações resolvidas, indexadas pelo nome de instância que o autor deu a cada uma. Cada entrada carregatype(o URI de catálogo da Feature vinculada),resolved_version(a versão associada para este build) evalues(o conteúdo de intenção do desenvolvedor próprio da vinculação). Uma vinculação escrita em uma das conexões do componente não está entre elas, exatamente como não está entre as.featuresde um template de Recipe: ela é lida sob a sua conexão, em.uses.<socket>.<alias>.features.<slot>, nesta mesma forma..metadata— a instância sendo avaliada: o seuinstance_id, o seu tipocomponente a suaresolved_version, o seuboundary_path, eaggregate_name,aggregate_versionerelease_versiondo build.
Para as assertions: de Recipe e FeatureRecipe, o contexto adiciona campos específicos da Recipe:
.provides— os valoresprovides:resolvidos do componente sendo avaliado, já calculados no momento em que a asserção é executada. Os valores publicados de um destino não estão nesta superfície; em vez disso, eles chegam a um chamador no contexto de renderização..locals— os locals da Recipe..recipe.metadata— onamee aversionda Recipe, e a suacapability..recipe.source— o ponteiro de origem da Recipe.
O acesso a campos usa a sintaxe padrão de templates Go (.values.architecture, .uses.databases.primary.target); a construção que interrompe o build é {{ fail "message" }}, conforme o contrato Loud Guardrails — uma asserção com falha 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 carrega interrompe 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 confiável: um predicado cuja referência fosse renderizada vazia compararia com nada e passaria, de modo que um único erro de digitação desativaria silenciosamente a regra que a asserção foi escrita para impor. Também significa que a referência pura é resolvida antes que qualquer fallback possa ser executado, de modo que um campo opcional precisa de uma forma que leve em conta a presença; errors/fatal-halts.md traz a política de chaves ausentes 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 ele está conectado. Dado um componente cuja entrada no Aggregate escreve
uses: models: local: { target: llama } fast: { target: turbo }estas asserções a leem de cada forma:
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 laço range percorre as conexões de um socket em ordem alfabética dos seus aliases — aqui fast antes de local —, não na 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 esteja ou não fast conectado ao lado, e .uses.models.target não endereça nenhuma conexão e interrompe o build.
Cada conexão que um componente mantém tem aqui uma entrada própria, porque não há duas conexões de um mesmo componente que compartilhem um alias — em um socket ou em dois, qualquer que seja o documento ou a vinculação que traçou cada uma. O build recusa um par assim, nomeando as duas conexões e onde cada uma foi escrita, antes que qualquer asserção seja executada. Uma lista que nomeia o mesmo destino duas vezes é um par assim, já 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 vinculação no mesmo componente.
Ler o que uma conexão carrega. Uma regra sobre uma conexão pode ler o que é o seu destino, o que o desenvolvedor escreveu na conexão e o que está vinculado a ela, de modo que vale 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 rotula como serviço hospedado quando essa conexão não carrega 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 -}}O rótulo é lido de labels, que são os do destino — o modelo — e nunca os 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 carregar tal rótulo e uma conexão tal valor. O que o rótulo significa é a convenção do catálogo: o build carrega 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 carrega 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 fatos que ambas as visões carregam compartilham os nomes, mas não os caminhos: .context.uses.<alias>.labels e .uses.<socket>.<alias>.labels são os rótulos do mesmo destino, e values e features igualmente leem a mesma conexão em qualquer uma delas. As duas fases de asserção avaliam antes da renderização, e é por isso que a visão que uma asserção tem de uma aresta não carrega nada que o seu destino tenha publicado, e por isso uma vinculação nela não carrega nenhum provides.
Para a forma mais ampla do contexto de template e a semântica de disponibilidade por campo, veja template-context-contract.md.
Números nesta superfície
Uma asserção lê um número escrito pelo autor exatamente como um template de valor o faz — veja Números em um template de valor:
- Comparações. As seis comparações leem dois números pelo valor, qualquer que seja o tipo que carrega cada um:
lt .values.replicas 1.5eeq .values.replicas 3.0respondem aqui como em um template de valor, um0.1escrito pelo autor éeqa um0.1escrito na asserção, e comparar um número com texto entre aspas interrompe o build com as mesmas palavras. - Vazio. Um
0escrito pelo autor é vazio: falso paraifewith, verdadeiro paraemptye substituído pordefault. Uma regra que pergunta se o autor escreveu um valor — um0incluído — pergunta com os helpers de presença: para um0escrito pelo autor,hasKey .values "replicas"é verdadeiro eoptional .values "replicas" 1retorna0. 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
failimprime é lido como seria na saída de um template de valor: um número inteiro como inteiro, de modo queprintf "%d"imprime os seus dígitos, e qualquer outro número na sua forma decimal exata mais curta, de modo que um0.0000001escrito pelo autor é lido como0.0000001.
Asserções de Component / Feature — invariantes arquiteturais
Estas expressam regras que valem independentemente de qual Recipe se associe ao Component. A regra é uma propriedade do contrato, não da implementação.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: 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 expressam propriedades do contrato do MariaDB. Qualquer que seja a Recipe associada — um chart da Bitnami, uma alternativa feita à mão — as regras se aplicam.
O controle de espaços em branco {{- ... -}} é importante: templates de asserções não produzem saída, apenas efeitos colaterais via {{ fail }}. O corte dos espaços mantém vazio o corpo do template renderizado no caso de sucesso.
Asserções de Recipe / FeatureRecipe — invariantes de implementação
Estas expressam regras que valem para o chart ou módulo específico de que a Recipe obtém a sua origem. A regra é uma propriedade da implementação, não do contrato.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: bitnami/datastore/mariadb/k8s version: 1.0.0spec: 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 uma Recipe de MariaDB diferente for associada — um chart feito à mão, uma implementação alternativa — essas regras não se aplicam. As regras no nível do Component (replication-needs-two-secondaries, total-node-count-within-cap) continuam valendo porque são propriedades do contrato.
Por que as asserções de Component e de Recipe são separadas
Os dois papéis parecem semelhantes (ambos executam interrupções {{ fail }} sobre regras entre campos), mas a divisão de responsabilidades é estrutural:
- Asserções de Component fazem parte do contrato. Quando o desenvolvedor escreve
architecture: replicationcomsecondary.replicaCount: 1, o build recusa independentemente de qual Recipe seja associada. Uma futura Recipe alternativa não muda isso. - Asserções de Recipe fazem parte da implementação. Quando o arquiteto escolhe o chart da Bitnami 20.x como Recipe, o chart tem peculiaridades específicas (a exigência de
serviceMonitor.namespace, o bug dos nós ARM). Elas 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 referenciar a Recipe associada a ele para saber quais regras de implementação impor, quebrando a separação Component-Recipe. Dividir as regras em 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 interrompem 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 exibido ao usuário. Convenções:
- Nomeie a restrição — “architecture=replication requires secondary.replicaCount >= 2” (architecture=replication exige secondary.replicaCount >= 2).
- Nomeie o valor quando relevante — “total node count must not exceed 9; got 12” (a contagem total de nós não deve exceder 9; obtido 12).
- Sugira a correção quando possível — “use ‘soft’ or omit the field” (use ‘soft’ ou omita o campo).
- Evite jargão — quem lê é o desenvolvedor que escreveu o Aggregate, não o arquiteto que escreveu a asserção.
Para mensagens longas ou que contêm valores, use 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 é específico o suficiente para que o desenvolvedor identifique e corrija a causa raiz.
Um valor que um autor declarou sensitive: true é lido como <redacted> nessa mensagem sempre que a mensagem o cita, de modo que nomear na mensagem o valor de um campo declarado é seguro: o diagnóstico continua nomeando 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 — informa 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” traz a regra completa.
O que assertions: não substitui
assertions: é o lugar das regras entre campos. Ele não substitui:
- Restrições de JSON Schema dentro de
schema:— 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 escopo de um único campo. Usevalidate:quando a regra se aplica a um campo específico; useassertions:quando a regra envolve vários campos e nenhum campo isolado é “o que está sendo validado”. - O campo
when:da forma compacta — forma condicional (se as restrições de uma subárvore se aplicam). Usewhen:para variações de forma; useassertions:quando a combinação de valores é inválida de um modo mais bem expresso 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, status dos pods em tempo de execução) deve ser expresso como strings de ponteiro determinísticas (veja 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 -}}Porte médio — 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 buildavalia as asserções entre a validação do esquema e a renderização; uma asserção com falha interrompe o build com a mensagem{{ fail }}da asserção.aggrega validateaplica a mesma correção antes da renderização sem escrever artefatos — para uma Recipe cuja origem não é buscada, ele executa 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 aparece como um erro de correção; as asserções de uma Recipe cuja origem é buscada são avaliadas por um build. Uma asserção ali que chamafailé relatada como um aviso que carrega a sua mensagem, e a verificação passa: a Release sintetizada contém placeholders e valores padrão em vez dos valores que uma Release real define, de modo que o veredito sobre a asserção fica para um build — veja uma asserção com falha é um aviso. (aggrega lintcobre as convenções de publicação, não a correção das asserções.)- IDEs com suporte a templates Sprig destacam referências
.values.X; a documentação exibida ao passar o mouse remete à definição do esquema quando a integração com o IDE está configurada.