Quando recorrer a um passo de pipeline
Uma FeatureRecipe oferece duas formas de moldar a saída com que uma Feature contribui: uma FeatureRecipe baseada em modelos que gera os seus próprios documentos, e um passo de pipeline (pipeline:) que executa um plugin Wasm sobre a saída renderizada. Resolvem problemas diferentes. Esta página é o guia de decisão: recorra-se a um passo de pipeline perante exatamente dois gatilhos, e use-se uma FeatureRecipe baseada em modelos para tudo o resto.
As duas ferramentas
Uma FeatureRecipe baseada em modelos é local e generativa. Produz os seus próprios documentos a partir dos seus próprios valores através de um modelo Go — o ConfigMap de um sidecar, um CRD de política, um objeto de escalonamento automático. Tudo o que emite é função dos values: e infra: da Feature e do contexto de renderização entregue aos seus modelos. Nunca entra na saída de outra entidade; acrescenta documentos próprios. Se aquilo que é preciso produzir puder ser escrito a partir do que a Feature já sabe, uma FeatureRecipe baseada em modelos é a ferramenta certa e mais simples — sem plugin, sem pipeline.
Um passo de pipeline é global e transformador. É executado depois da renderização, sobre o conjunto real de documentos que a compilação já emitiu. O anfitrião entrega ao passo esse conjunto de documentos indexado por chave, inteiro; o passo lê o conteúdo real, seleciona os documentos a que se destina e devolve patches RFC 6902 precisos à estrutura deles — ou emite documentos novos como efeitos secundários. Um passo raciocina sobre o que foi renderizado, não apenas sobre o que a Feature declarou. Esse alcance é toda a sua razão de existir, e é também por isso que deve ser usado com moderação.
Os dois gatilhos para um passo de pipeline
Recorra-se a um passo de pipeline apenas quando um destes casos se verificar. Se nenhum se verificar, gere-se antes o documento com uma FeatureRecipe baseada em modelos.
-
Patch no âmbito do anfitrião — é preciso entrar na estrutura de outra entidade já renderizada. O caso clássico é injetar uma variável de ambiente, uma montagem de volume ou um contentor sidecar na carga de trabalho do componente consumidor — um documento que a própria Feature não escreveu. Uma FeatureRecipe baseada em modelos não o consegue fazer: produz os seus próprios documentos, não edita os de outrem. Um passo de pipeline consegue, porque opera sobre o conjunto renderizado e pode endereçar por chave os documentos do componente anfitrião.
-
Emissão ou patch dependente do conteúdo — a saída depende do que o conjunto renderizado contém. Quando o recurso emitido, ou o patch aplicado, é função do conteúdo que a compilação produziu — as portas reais que um Deployment declarou, os nomes de contentores que acabaram no manifesto, os recursos em que um chart se expandiu — a decisão precisa do conteúdo renderizado em mão. Uma FeatureRecipe baseada em modelos renderiza a partir dos valores próprios da Feature e nunca vê o conjunto final, pelo que não pode fazer uma escolha dependente do conteúdo; um passo de pipeline lê primeiro o conteúdo e depois age.
Ambos os gatilhos partilham uma forma: precisam de informação que só existe depois da renderização — a estrutura de outra entidade, ou o próprio conteúdo emitido. A geração local nunca precisa disso, pelo que a geração local nunca precisa de um passo de pipeline.
Um passo transforma; uma política valida
Um passo de pipeline é um transformador: altera o conjunto renderizado. Não é o local para verificar se um resultado é aceitável. Para validar uma compilação — para afirmar que uma carga de trabalho com patch tem o sidecar, que nenhum segredo em texto simples chegou à saída, que uma etiqueta obrigatória está presente — anexe-se uma política da fase de renderização: um plugin de governação no papel render-verdict, que é executado depois da renderização sobre os artefactos emitidos e devolve um veredicto. Um veredicto halt interrompe a compilação; um veredicto warn ou info avisa sem bloquear.
Mantenham-se os dois separados. Não se deve colocar lógica de validação num passo de pipeline, nem recorrer a uma política para modificar a saída — um plugin de governação anexado a um papel de veredicto devolve veredictos e nunca aplica patches, e o anfitrião lê a saída de um papel de veredicto apenas como uma decisão. Um passo molda a saída; uma política render-verdict julga-a. A página do socket de governação cobre os quatro papéis de governação e as severidades dos veredictos.
Os passos compõem-se
Um passo de pipeline pode declarar um contrato tipado de entrada e de saída, de modo que a sua entrada with: e as saídas que devolve sejam formas validadas em vez de blobs livres. Um passo devolve também outputs com nome, e um passo declarado mais adiante no mesmo pipeline lê as saídas de um passo anterior a partir do seu próprio modelo with: como .steps.<id>.outputs.<key>. É assim que um padrão em duas partes se compõe sem acoplamento: um passo Fetcher emite um recurso de credenciais e publica o nome do Secret resultante como saída; um passo Injector lê esse nome e aplica um patch à carga de trabalho consumidora para o montar. Cada passo trata de uma só preocupação, e o pipeline encadeia as saídas deles pela ordem declarada.
Referências cruzadas
entities/featurerecipe.md— a superfície de criação da FeatureRecipe, incluindopipeline:.plugins/plugin-contract.md— a forma de transmissão do passo de pipeline: à entrada, o conjunto de documentos indexado por chave; à saída, patches RFC 6902, efeitos secundários, diagnósticos e saídas do passo.plugins/policy-socket.md— o socket de governação, incluindo o papel de veredicto da fase de renderização que valida a saída de uma compilação.templates/template-context-contract.md— o campo.steps.<id>.outputsque um passo posterior lê.examples/04-secrets.md— o formato de pipeline Fetcher + Injector.