ArtifactLibrary
Uma ArtifactLibrary é uma entidade de catálogo que contém bundles de artefatos reutilizáveis — conjuntos nomeados de arquivos de saída auxiliares que andam juntos. Recipes e FeatureRecipes que emitem os mesmos recursos de apoio — uma CRD com seu RBAC e um ConfigMap, uma NetworkPolicy junto com um HPA — declaram esse conjunto uma vez em uma biblioteca e o referenciam no momento do consumo por meio de uma entrada artifacts: cujo valor é uma diretiva $import:. A entidade biblioteca é de Tier 3: opcional para catálogos que precisam reutilizar artefatos entre Recipes. Catálogos cujas Recipes carregam cada uma seus próprios arquivos auxiliares são distribuídos sem nenhuma ArtifactLibrary.
O papel da ArtifactLibrary
Arquitetos de plataforma escrevem ArtifactLibraries para centralizar os manifestos auxiliares que se repetem nas Recipes e FeatureRecipes do catálogo. Uma biblioteca não é uma instrução de build implantável; é um namespace de definições. Autores de Recipe e FeatureRecipe referenciam um bundle por uma diretiva $import:, escrita uma vez e consumida onde quer que a importação seja resolvida.
O que distingue este tipo de biblioteca dos outros três é a granularidade de uma entrada. Uma entrada de SchemaLibrary é um esquema, uma entrada de MappingLibrary é um fragmento de template e uma entrada de WorkloadLibrary é um documento Workload — cada uma um único corpo consumido em um único ponto. Uma entrada de ArtifactLibrary é um conjunto de arquivos, porque os recursos que ela agrupa só são úteis juntos: importar uma CRD sem o seu RBAC produz um conjunto de manifestos que não funciona. É por isso que um bundle é a unidade de reutilização e um único ponto de consumo se expande em várias saídas.
Envelope da entidade
Uma entidade ArtifactLibrary carrega o envelope padrão do catálogo. apiVersion: aggrega.ai/v1beta1 e kind: ArtifactLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue versionamento semântico estrito. Ambos são obrigatórios. metadata.description, metadata.labels e metadata.annotations são opcionais — labels e anotações são metadados opacos declarados pelo autor, carregados para que aquilo que lê a biblioteca possa usá-los na correspondência, e o compilador não interpreta seus valores. O conteúdo da biblioteca fica em spec.artifacts, um mapa obrigatório que deve declarar pelo menos um bundle.
O envelope é fechado nos três níveis — a raiz do documento, metadata e spec rejeitam, cada um, chaves que o esquema não declara.
apiVersion: aggrega.ai/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Escrevendo bundles de artefatos
spec.artifacts tem dois níveis de profundidade, e cada nível tem uma função distinta. A chave externa é o nome do bundle — o identificador que um consumidor referencia. As chaves internas são nomes de arquivo, e cada valor interno é o corpo em Go template emitido para aquele arquivo. Um bundle deve declarar pelo menos um arquivo.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"O corpo de um arquivo é um fragmento de Go template escrito como string YAML. Como um manifesto ocupa várias linhas, os corpos de arquivo usam o escalar de estilo literal do YAML (|) para que quebras de linha e indentação sobrevivam ao round-trip. O valor de uma entrada de bundle deve ser um mapeamento de nome de arquivo para corpo em string; escrever uma string simples onde vai o bundle, ou uma sequência, é rejeitado — o nível que um consumidor importa é o bundle, não um arquivo individual.
O corpo é opaco para o envelope da entidade. O compilador armazena cada string literalmente ao carregar a ArtifactLibrary e não faz o parsing do template ali; o parser de templates é executado no momento do consumo, quando uma Recipe ou FeatureRecipe importa o bundle. Armazenar os corpos literalmente preserva a fidelidade ao que foi escrito para a reemissão, e faz com que um erro de template apareça onde o bundle é consumido e seu contexto de pilares é conhecido, em vez de na biblioteca.
A ordem dos arquivos dentro de um bundle é a ordem em que o autor os escreveu, preservada no carregamento e no consumo, de modo que o conjunto emitido é estável entre builds.
Todo o vocabulário de composição de Go template está disponível dentro do corpo de um arquivo: {{ define "name" }}...{{ end }} declara blocos reutilizáveis, {{ template "name" . }} os invoca, e pipelines e funções seguem o pacote padrão do Go text/template. O contexto de pilares que o corpo de um arquivo pode ler — .values, .infra, .locals, .context, .features, e .workload e .source onde a Recipe consumidora os declara — é o contexto que as próprias entradas artifacts: da Recipe consumidora leem, documentado na página Recipe no campo artifacts:. Um corpo que lê .workload onde a Recipe consumidora não declara nenhum workload:, ou .source onde ela não declara nenhum source:, é interrompido com um diagnóstico que nomeia a referência que não pôde satisfazer — cada pilar é verificado separadamente, de modo que declarar um não autoriza ler o outro.
Modo de autoria único
A ArtifactLibrary oferece um único modo de autoria: Go templates. spec não aceita nenhuma superfície de autoria paralela nem nenhuma via de escape de expressividade no nível da biblioteca.
O motivo é a uniformidade da superfície de consumo. Recipes e FeatureRecipes são Go template do início ao fim, e seu próprio conteúdo é avaliado pelo mesmo mecanismo de Go template que resolve um bundle importado. Uma superfície de autoria paralela obrigaria os autores a trocar de modelo de avaliação dentro da renderização de uma única Recipe — um modelo para o conteúdo próprio da Recipe, outro para cada bundle importado. Manter a superfície uniforme significa que os autores aprendem um único modelo de avaliação e o aplicam em toda parte.
Autores que precisam de expressividade além do vocabulário de composição de Go template compõem em um nível mais alto — Components ou Features que envolvem os bundles da biblioteca com sua própria variação substancial — em vez de recorrer a uma segunda linguagem de autoria dentro da biblioteca.
Convenções de nomenclatura
Nomes de biblioteca e nomes de bundle seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em duas posições por meio de restrições de padrão:
metadata.namecorresponde a^[A-Z][A-Za-z0-9]*$.- As chaves do mapa
spec.artifactscorrespondem ao mesmo padrão por meio depropertyNames.
Uma ArtifactLibrary com um nome de bundle que não está em PascalCase falha na validação do envelope ao carregar o workspace. A imposição é estrutural: nomes de bundle aparecem no fragmento de referência #/artifacts/<name>, de modo que um nome fora do PascalCase se propagaria por todo consumidor que importa o bundle.
A uniformidade dos nomes mantém legível o fragmento #/artifacts/<name>: #/artifacts/OperatorSupport se lê num relance.
Nomes de arquivo dentro de um bundle são livres, desde que cada um nomeie um arquivo. Eles não estão em PascalCase e nenhum padrão de esquema os restringe, porque nomeiam os arquivos que a saída de um build acaba contendo — crd.yaml, deny-all.yaml, values-override.json são todos válidos. O que um nome de arquivo precisa ser é um nome de arquivo relativo comum, escrito de forma simples; o build recusa um nome que não nomeia um arquivo próprio, como descrito em Referenciando entradas de biblioteca. Os dois níveis são restringidos de forma diferente porque servem a leitores diferentes: o nome do bundle é um identificador que outras entidades citam, e os nomes de arquivo são os nomes que um consumidor vê dentro do diretório em que o bundle é importado.
Referenciando entradas de biblioteca
Autores de Recipe e FeatureRecipe referenciam um bundle dentro de uma entrada artifacts: cujo valor é um mapa $import:, pela identidade do bundle como nome simples:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"O fragmento #/artifacts/<name> seleciona o bundle e distingue uma referência de artefatos de #/mappings/<name> da MappingLibrary, de #/schemas/<name> da SchemaLibrary e de #/workloads/<name> da WorkloadLibrary. A referência não carrega nenhum host de registry; uma forma com host oci://… é rejeitada tanto pelo esquema do envelope quanto no ponto de consumo, de modo que uma localização física de registry nunca entra no código-fonte escrito. Um autor pode declarar um piso de versão mínima opcional como <Library>:<version>#/artifacts/<name> — o separador de versão é :, igual aos outros tipos de biblioteca e ao pin do lockfile, e escrever @ no lugar é recusado com um diagnóstico que nomeia a referência corrigida. A versão resolvida é fornecida pelo lockfile de cada Release, que fixa cada biblioteca consumida por nome, versão e digest do conteúdo; a localização física é vinculada no momento da resolução.
O bundle é dono dos seus nomes de arquivo, e a chave consumidora é dona do diretório em que eles ficam. Uma entrada artifacts: que importa um bundle se expande em uma saída por arquivo daquele bundle, cada uma aninhada sob a chave de consumo como <key>/<filename>. A chave no ponto de consumo — operator-support acima — nomeia o consumo inteiro em vez de um único arquivo; o exemplo emite operator-support/crd.yaml e operator-support/rbac.yaml. Assim, o nome de um bundle é escolhido pela legibilidade na referência, os nomes de arquivo são escolhidos para quem lê o diretório de saída, e nenhum precisa concordar com o outro. A própria chave de consumo é limitada a um único nome de arquivo — uma letra ou dígito inicial, depois letras, dígitos, pontos, hifens e sublinhados, e uma chave fora desse alfabeto falha na validação do envelope — de modo que ela nomeia exatamente um segmento de diretório, e tudo abaixo desse segmento vem do bundle. É isso que permite que os nomes de arquivo de um bundle continuem livres enquanto a chave continua estrita: um nome de arquivo é único dentro do seu bundle, uma chave é única dentro do seu documento, e a chave é o primeiro segmento de todo caminho que a entrada emite, de modo que duas entradas artifacts: nunca nomeiam a mesma saída. Livre significa livre dentro desse segmento: um nome de arquivo pode ter uma estrutura aninhada própria — crds/widget.yaml vai para <key>/crds/widget.yaml — mas deve ser um nome de arquivo relativo comum abaixo da chave, escrito de forma simples, e um nome de arquivo que não seja assim interrompe o build em vez de colocar o arquivo em algum lugar que a Recipe consumidora nunca nomeou. Isso recusa um nome que sobe acima da chave ou que nomeia uma localização absoluta; . ou ./, e um nome que volta a coincidir com a chave, como x/.., que nomeiam o próprio diretório da chave em vez de um arquivo dentro dele; e um nome com uma / final ou dobrada, ou uma parte . ou .. — x/, a//b, ./a, a/../b — que é uma segunda grafia de um arquivo que outro nome pode carregar, de modo que a//b ao lado de a/b colocaria dois arquivos em um mesmo caminho. O diagnóstico nomeia o arquivo do bundle e a chave em que ele foi importado. Duas saídas que de fato carregam o mesmo nome de arquivo interrompem o build quando o nó é renderizado, o que acontece quando dois tipos de entrada diferentes contribuem com um mesmo nome de arquivo. Consulte Recipe para ver como artifacts: se compõe com os outros tipos de entrada da Recipe e os dois modos de autoria que não usam bibliotecas, e vocabulary/cross-document-ref para a distinção mais ampla entre $ref: / $import:.
Composição entre bibliotecas
O corpo de um arquivo de bundle é conteúdo terminal. Diferentemente de uma entrada de MappingLibrary ou de WorkloadLibrary, um arquivo de bundle não pode ser um redirecionamento $import: na raiz do campo: um único slot de arquivo não tem espaço para os vários arquivos que outro bundle traria, então o compilador rejeita essa forma em vez de resolvê-la em algo que o autor não escreveu. Um corpo cujo primeiro token é $import: é interrompido com um diagnóstico que nomeia o bundle e o arquivo.
Em vez disso, a composição acontece no ponto de consumo, onde há espaço para ela. Uma Recipe que precisa de dois bundles declara duas entradas artifacts:, e cada uma se expande de forma independente:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Um nome de biblioteca desconhecido e um nome de bundle ausente de uma biblioteca que é resolvida são relatados como diagnósticos distintos, de modo que um autor consegue distinguir uma dependência ausente de um nome de bundle digitado errado.
Posicionamento nos tiers
A ArtifactLibrary é de Tier 3 no modelo de documentação por tiers das entidades — opcional para catálogos que precisam reutilizar artefatos entre Recipes. Catálogos cujas Recipes carregam seus próprios arquivos auxiliares são distribuídos sem nenhuma entidade ArtifactLibrary; a marcação de tier sinaliza “avançado; pule se não precisar” para a navegação na documentação, não uma capacidade. O compilador trata a ArtifactLibrary de forma uniforme com os outros tipos de entidade de catálogo: a mesma validação do envelope ao carregar o workspace, o mesmo pipeline de publicação OCI no momento da publicação, o mesmo pin no lockfile por nome, versão e digest do conteúdo.
Este tipo de biblioteca completa um conjunto no nível do catálogo — a SchemaLibrary contém definições de esquema reutilizáveis, a MappingLibrary fragmentos de mapeamento reutilizáveis, a WorkloadLibrary conteúdo de workload reutilizável e a ArtifactLibrary bundles de artefatos reutilizáveis. Cada uma é opcional de forma independente; os catálogos distribuem as que precisam e nenhuma das outras.
O que a ArtifactLibrary não é
Alguns equívocos comuns que vale a pena evitar:
-
Não é um substituto para
artifacts:inline. A maioria das Recipes carrega arquivos auxiliares específicos o bastante para ficarem inline, onde o autor os lê junto com o restante da Recipe. Uma ArtifactLibrary ajuda quando o MESMO conjunto de arquivos acompanha muitas Recipes; para conteúdo pontual, escrever inline é a escolha certa. -
Não é uma forma de renomear os arquivos dentro de um bundle. Os nomes de arquivo pertencem ao bundle. Um consumidor escolhe o diretório em que eles ficam — é isso que a chave de consumo faz —, mas não como cada um deles se chama: um consumidor que precisa de um nome de arquivo diferente usa um bundle que o declare ou escreve o arquivo inline.
-
Não é um lugar para conteúdo de workload, de mapeamento ou de esquema. Um documento Workload pertence a uma WorkloadLibrary, o documento de valores de uma Recipe pertence a uma MappingLibrary e as definições de esquema pertencem a uma SchemaLibrary. Os tipos de biblioteca se dividem por tipo de conteúdo, não por padrão de reutilização.
-
Não é o mecanismo para recursos transversais. Recursos auxiliares que se aplicam a muitos componentes independentemente de qual Recipe os realiza — um sidecar de backup vinculado a cada datastore — pertencem à geração de recursos da FeatureRecipe, que se vincula por Feature em vez de por Recipe. Consulte entities/featurerecipe.md. Uma ArtifactLibrary reúne arquivos que várias Recipes emitem, cada uma por conta própria.
-
Não é uma entidade implantável de forma independente. Um bundle é conteúdo de artefatos, e conteúdo de artefatos nunca é endereçável sozinho — ele existe como a entrada que uma Recipe ou FeatureRecipe consome. Publicar uma ArtifactLibrary torna seus bundles importáveis; não os torna implantáveis.