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

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/v1beta1
kind: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
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.name corresponde a ^[A-Z][A-Za-z0-9]*$.
  • As chaves do mapa spec.artifacts correspondem ao mesmo padrão por meio de propertyNames.

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.