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

ArtifactLibrary

Uma ArtifactLibrary é uma entidade de catálogo que contém pacotes de artefactos reutilizáveis — conjuntos com nome de ficheiros de saída auxiliares que vão juntos. As Recipes e FeatureRecipes que emitem os mesmos recursos de suporte — uma CRD com o seu RBAC e um ConfigMap, uma NetworkPolicy emparelhada com um HPA — declaram esse conjunto uma vez numa biblioteca e referenciam-no no momento do consumo através de uma entrada artifacts: cujo valor é uma diretiva $import:. A entidade de biblioteca é de Nível 3: opcional, para catálogos que precisam de reutilizar artefactos entre Recipes. Os catálogos cujas Recipes transportam cada uma os seus próprios ficheiros auxiliares são distribuídos sem qualquer ArtifactLibrary.

O papel da ArtifactLibrary

Os 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 compilação implantável; é um espaço de nomes de definições. Os autores de Recipes e FeatureRecipes referenciam um pacote através de uma diretiva $import:, escrita uma vez e consumida onde quer que a importação resolva.

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 um um único corpo consumido num único local. Uma entrada de ArtifactLibrary é um conjunto de ficheiros, porque os recursos que agrupa só são úteis em conjunto: importar uma CRD sem o seu RBAC produz um conjunto de manifestos que não funciona. É por isso que um pacote é a unidade de reutilização e que um único local de consumo se expande em várias saídas.

Envelope da entidade

Uma entidade ArtifactLibrary transporta 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 um versionamento semântico estrito. Ambos são obrigatórios. metadata.description, metadata.labels e metadata.annotations são opcionais — as etiquetas e as anotações são metadados opacos declarados pelo autor, transportados para que aquilo que lê a biblioteca os possa usar na correspondência, e o compilador não interpreta os seus valores. O conteúdo da biblioteca fica em spec.artifacts, um mapa obrigatório que tem de declarar pelo menos um pacote.

O envelope é fechado nos três níveis — a raiz do documento, metadata e spec rejeitam cada um as 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"]

Escrever pacotes de artefactos

spec.artifacts tem dois níveis de profundidade, e cada nível tem uma função distinta. A chave exterior é o nome do pacote — o identificador que um consumidor referencia. As chaves interiores são nomes de ficheiros, e cada valor interior é o corpo de template Go emitido para esse ficheiro. Um pacote tem de declarar pelo menos um ficheiro.

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 ficheiro é um fragmento de template Go escrito como uma cadeia YAML. Como um manifesto tem várias linhas, os corpos dos ficheiros usam o escalar de estilo literal do YAML (|), para que as quebras de linha e a indentação sobrevivam à ida e volta. O valor de uma entrada de pacote tem de ser um mapeamento de nome de ficheiro para um corpo de cadeia; escrever uma cadeia simples onde deveria estar o pacote, ou uma sequência, é rejeitado — o nível que um consumidor importa é o pacote, não um único ficheiro.

O corpo é opaco para o envelope da entidade. O compilador guarda cada cadeia literalmente no carregamento da ArtifactLibrary e não analisa aí o template; o analisador de templates corre no momento do consumo, quando uma Recipe ou FeatureRecipe importa o pacote. Guardar os corpos literalmente preserva a fidelidade da autoria para a reemissão, e significa que um erro de template aparece onde o pacote é consumido e o seu contexto de pilares é conhecido, e não na biblioteca.

A ordem dos ficheiros dentro de um pacote é a ordem em que o autor os escreveu, preservada ao longo do carregamento e do consumo, pelo que o conjunto emitido é estável entre compilações.

Todo o vocabulário de composição dos templates Go está disponível dentro do corpo de um ficheiro: {{ define "name" }}...{{ end }} declara blocos reutilizáveis, {{ template "name" . }} invoca-os, e os pipelines e as funções seguem o pacote padrão text/template do Go. O contexto de pilares que o corpo de um ficheiro pode ler — .values, .infra, .locals, .context, .features, e .workload e .source quando 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 quando a Recipe consumidora não declara nenhum workload:, ou .source quando não declara nenhuma source:, para com um diagnóstico que nomeia a referência que não conseguiu satisfazer — cada pilar é verificado por si, pelo que declarar um não autoriza a leitura do outro.

Modo de autoria único

A ArtifactLibrary é distribuída com um único modo de autoria: templates Go. spec não aceita nenhuma superfície de autoria paralela nem nenhuma via de escape de expressividade ao nível da biblioteca.

A razão é a uniformidade da superfície de consumo. As Recipes e FeatureRecipes são inteiramente em template Go, e o seu próprio conteúdo é avaliado através do mesmo motor de templates Go que resolve um pacote importado. Uma superfície de autoria paralela obrigaria os autores a mudar 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 qualquer pacote importado. Manter a superfície uniforme significa que os autores aprendem um único modelo de avaliação e o aplicam em todo o lado.

Os autores que precisem de expressividade para além do vocabulário de composição dos templates Go compõem a um nível superior — Components ou Features que envolvem os pacotes da biblioteca com a sua própria variação substantiva — em vez de escalarem para uma segunda linguagem de autoria dentro da biblioteca.

Convenções de nomenclatura

Os nomes de bibliotecas e os nomes de pacotes seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em duas posições através 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 através de propertyNames.

Uma ArtifactLibrary com um nome de pacote que não está em PascalCase falha a validação do envelope no carregamento do espaço de trabalho. A imposição é estrutural: os nomes de pacotes aparecem no fragmento de referência #/artifacts/<name>, pelo que um nome que não estivesse em PascalCase propagar-se-ia por todos os consumidores que importam o pacote.

A uniformidade de nomenclatura mantém o fragmento #/artifacts/<name> legível: #/artifacts/OperatorSupport lê-se num relance.

Os nomes de ficheiros dentro de um pacote são de forma livre, desde que cada um nomeie um ficheiro. Não estão em PascalCase e nenhum padrão de esquema os restringe, porque nomeiam os ficheiros que a saída de uma compilação acaba por transportar — crd.yaml, deny-all.yaml e values-override.json são todos válidos. O que um nome de ficheiro tem de ser é um nome de ficheiro relativo comum, escrito de forma simples; a compilação recusa um que não nomeie nenhum ficheiro próprio, como descreve Referenciar entradas da biblioteca. Os dois níveis são restringidos de forma diferente porque servem leitores diferentes: o nome do pacote é um identificador que outras entidades citam, e os nomes de ficheiros são os nomes que um consumidor vê dentro do diretório em que o pacote é importado.

Referenciar entradas da biblioteca

Os autores de Recipes e FeatureRecipes referenciam um pacote dentro de uma entrada artifacts: cujo valor é um mapa $import:, pela identidade de nome simples do pacote:

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

O fragmento #/artifacts/<name> seleciona o pacote e distingue uma referência de artefactos do #/mappings/<name> da MappingLibrary, do #/schemas/<name> da SchemaLibrary e do #/workloads/<name> da WorkloadLibrary. A referência não transporta nenhum anfitrião de registo; uma forma oci://… com anfitrião é rejeitada tanto pelo esquema do envelope como no local de consumo, pelo que uma localização física de registo nunca entra na origem escrita. Um autor pode afirmar um mínimo de versão opcional como <Library>:<version>#/artifacts/<name> — o separador de versão é :, em conformidade com os outros tipos de biblioteca e com a fixação do lockfile, e escrever @ em vez dele é recusado com um diagnóstico que nomeia a referência corrigida. A versão resolvida é fornecida pelo lockfile por Release, que fixa cada biblioteca consumida por nome, versão e digest de conteúdo; a localização física é associada no momento da resolução.

O pacote é dono dos seus nomes de ficheiros, e a chave de consumo é dona do diretório onde ficam. Uma entrada artifacts: que importa um pacote expande-se numa saída por ficheiro desse pacote, cada uma aninhada sob a chave de consumo como <key>/<filename>. A chave no local de consumo — operator-support acima — nomeia todo o consumo e não um único ficheiro; o exemplo emite operator-support/crd.yaml e operator-support/rbac.yaml. Assim, um nome de pacote é escolhido pela legibilidade na referência, os nomes de ficheiros são escolhidos para o leitor do diretório de saída, e nenhum tem de concordar com o outro. A própria chave de consumo está limitada a um único nome de ficheiro — uma letra ou um dígito iniciais, seguidos de letras, dígitos, pontos, hífenes e underscores, falhando a validação do envelope uma chave fora desse alfabeto —, pelo que nomeia exatamente um segmento de diretório, e tudo o que está abaixo desse segmento vem do pacote. É isso que permite que os nomes de ficheiros de um pacote se mantenham de forma livre enquanto a chave se mantém estrita: um nome de ficheiro é único dentro do seu pacote, uma chave é única dentro do seu documento, e a chave é o primeiro segmento de todos os caminhos que a entrada emite, pelo que não há duas entradas artifacts: que nomeiem a mesma saída. De forma livre significa livre dentro desse segmento: um nome de ficheiro pode ter uma estrutura aninhada própria — crds/widget.yaml fica em <key>/crds/widget.yaml —, mas tem de ser um nome de ficheiro relativo comum por baixo da chave, escrito de forma simples, e um nome de ficheiro que não o seja para a compilação em vez de colocar o ficheiro num 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 colapsa de volta na chave, como x/.., que nomeiam o próprio diretório da chave e não um ficheiro dentro dele; e um nome com uma / final ou duplicada ou com uma parte . ou .. — x/, a//b, ./a, a/../b —, que é uma segunda grafia de um ficheiro que outro nome pode transportar, pelo que a//b ao lado de a/b colocaria dois ficheiros num só caminho. O diagnóstico nomeia o ficheiro do pacote e a chave em que foi importado. Duas saídas que transportam de facto o mesmo nome de ficheiro param a compilação quando o nó é renderizado, o que acontece quando dois tipos de entrada diferentes contribuem com um mesmo nome de ficheiro. Consulte Recipe para saber como artifacts: se compõe com os outros tipos de entrada da Recipe e para os dois modos de autoria que não usam bibliotecas, e vocabulary/cross-document-ref para a distinção mais ampla entre $ref: e $import:.

Composição entre bibliotecas

O corpo de um ficheiro de pacote é conteúdo terminal. Ao contrário de uma entrada de MappingLibrary ou de WorkloadLibrary, um ficheiro de pacote não pode ser um redirecionamento $import: na raiz do campo: um único slot de ficheiro não tem espaço para os vários ficheiros que outro pacote traria, pelo que o compilador rejeita essa forma em vez de a resolver em algo que o autor não escreveu. Um corpo cujo primeiro token é $import: para com um diagnóstico que nomeia o pacote e o ficheiro.

Em vez disso, a composição acontece no local de consumo, onde há espaço para ela. Uma Recipe que precisa de dois pacotes declara duas entradas artifacts:, e cada uma expande-se 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 pacote ausente de uma biblioteca que resolve são reportados como diagnósticos distintos, para que um autor consiga distinguir uma dependência em falta de um nome de pacote mal escrito.

Posicionamento por nível

A ArtifactLibrary é de Nível 3 no modelo de documentação por níveis de entidades — opcional, para catálogos que precisam de reutilizar artefactos entre Recipes. Os catálogos cujas Recipes transportam os seus próprios ficheiros auxiliares são distribuídos sem qualquer entidade ArtifactLibrary; a marcação de nível sinaliza «avançado; ignore se não precisar» para a navegação na documentação, não a capacidade. O compilador trata a ArtifactLibrary de forma uniforme com os outros tipos de entidade de catálogo: a mesma validação de envelope no carregamento do espaço de trabalho, o mesmo pipeline de publicação OCI no momento do lançamento, a mesma fixação no lockfile por nome, versão e digest de conteúdo.

O tipo de biblioteca completa um conjunto ao nível do catálogo — a SchemaLibrary contém definições de esquema reutilizáveis, a MappingLibrary contém fragmentos de mapeamento reutilizáveis, a WorkloadLibrary contém conteúdo de carga de trabalho reutilizável e a ArtifactLibrary contém pacotes de artefactos reutilizáveis. Cada um é opcional de forma independente; os catálogos incluem os que precisam e nenhum dos outros.

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 transporta ficheiros auxiliares suficientemente específicos para pertencerem inline, onde o autor os lê juntamente com o resto da Recipe. Uma ArtifactLibrary ajuda quando o MESMO conjunto de ficheiros acompanha muitas Recipes; para conteúdo pontual, a autoria inline é a escolha certa.

  • Não é uma forma de mudar o nome dos ficheiros dentro de um pacote. Os nomes de ficheiros pertencem ao pacote. Um consumidor escolhe o diretório onde ficam — é isso que a chave de consumo faz —, mas não o nome de nenhum deles: um consumidor que precise de um nome de ficheiro diferente usa um pacote que o declare ou escreve o ficheiro inline.

  • Não é um lugar para conteúdo de carga de trabalho, 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 dividem-se por tipo de conteúdo, não por padrão de reutilização.

  • Não é o mecanismo para recursos transversais. Os recursos auxiliares que se aplicam a muitos componentes, independentemente da Recipe que os realiza — um sidecar de cópia de segurança anexado a todos os armazenamentos de dados —, pertencem à geração de recursos da FeatureRecipe, que se anexa por Feature e não por Recipe. Consulte entities/featurerecipe.md. Uma ArtifactLibrary isola ficheiros que várias Recipes emitem cada uma por conta própria.

  • Não é uma entidade implantável de forma independente. Um pacote é conteúdo de artefactos, e o conteúdo de artefactos nunca é endereçável por si só — existe como a entrada que uma Recipe ou FeatureRecipe consome. Publicar uma ArtifactLibrary torna os seus pacotes importáveis; não os torna implantáveis.