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

Stack Harbor — um registo de contentores implementado como uma única release

Este exemplo compila um registo de contentores real em manifestos do Kubernetes a partir de um único Aggregate escrito pelo programador.

Um registo de contentores é composto por muitos serviços que cooperam — um plano de controlo de API e serviço de tokens, um blob store OCI e o seu controlador, uma consola web, uma camada de workers assíncronos, um scanner de vulnerabilidades, um backend relacional, uma cache chave-valor e um proxy inverso à frente deles. O catálogo descreve tudo isso como um único Component, porque os próprios responsáveis pela manutenção do registo publicam um chart do Helm que o implementa por inteiro como uma única release, na ordem de que os seus serviços precisam. O Component declara o registo; a Recipe encapsula esse chart.

O registo é importado como um módulo: um subagregado reutilizável que compõe o Component e exporta o seu endereço publicado. O Aggregate de nível superior importa o módulo pelo nome e passa-lhe três das chaves do registo; o operador dimensiona o componente do módulo na Release.

Ficheiros

FicheiroPapel
aggregate.yamlIntenção do programador: importa o módulo de registo de contentores (core/harbor) e passa-lhe três das chaves do registo a partir de parâmetros próprios.
manifest-helm-synth.yamlMapeia o tipo de componente do registo para a Recipe que encapsula o seu chart do Helm, e a Feature de credencial para a realização que lê um Secret já presente no namespace — exceto a palavra-passe do administrador, que liga pelo nome à realização que emite um Secret a partir do parâmetro do módulo.
release-helm-synth.yamlDocumento do operador para o destino Kubernetes. Nomeia os Secrets que contêm as três chaves que o Aggregate passa para baixo, dimensiona o componente do módulo pelo seu ID com âmbito de módulo, e anexa-lhe a chave de assinatura de tokens, o segredo partilhado dos serviços e a chave com que as credenciais armazenadas são cifradas, nomeando os Secrets que as contêm; tudo o resto fica com as predefinições do esquema.

O que demonstra

  • Um produto com vários serviços como um único Component. O que faz do registo um único Component em vez de vários não é o seu tamanho, mas o sítio onde as suas ligações são mantidas: o encaminhamento do proxy inverso, a chave do serviço de tokens com a qual o plano de controlo verifica cada pull e cada push, as definições de ligação que cada serviço lê para o backend e a cache, a divisão em bases de dados lógicas que mantém separados os espaços de chaves da cache dos serviços, e a ordem de arranque — tudo isso é mantido em sintonia com o produto pelas pessoas que o publicam, dentro do chart. Um consumidor declara um registo e obtém tudo isso em concordância.
  • Um chart encapsulado. A Recipe nomeia o chart em source: e sobrepõe-lhe um valuesMapping: — o template de valores é toda a implementação, e o fornecedor Helm renderiza os templates próprios do chart com base nele. Nenhuma carga de trabalho é sintetizada aqui.
  • Uma entrada externa fixada. O chart é uma entrada que a compilação transfere, pelo que é fixado como qualquer dependência: o ficheiro de bloqueio regista a versão do chart, o seu URL resolvido e o digest do tarball, em source_artifacts. Uma compilação com um ficheiro de bloqueio preenchido serve o chart a partir do repositório de conteúdo e verifica-o em relação a esse digest.
  • Um único endereço publicado para uma plataforma inteira. O proxy inverso do chart encaminha o caminho de navegador / para a consola e os caminhos do registo e da API (/v2/, /api/, /service/, /c/) para o plano de controlo, pelo que um cliente de contentores inicia sessão, faz push e faz pull no mesmo host pelo qual um navegador acede à consola. Esse Service é o que provides.host publica, e um consumidor não precisa de um segundo endereço para alcançar nenhum dos dois conjuntos de caminhos.
  • Dois nomes públicos para ele. O módulo exporta esse único endereço como registry, o endpoint com o qual os clientes de imagens e a API comunicam, e como ui, o endpoint web. Ambos resolvem para o endereço que serve os dois conjuntos de caminhos, pelo que um consumidor se liga ao nome que descreve a sua intenção.
  • Dimensionamento do componente de um módulo pelo operador. A Release endereça o componente do módulo pelo seu ID com âmbito de módulo (harbor.registry) para definir os recursos de computação, sem que o Aggregate do programador repita o dimensionamento físico.
  • Regras de completude num valor agrupado. infra.compute contém uma chave de CPU e uma de memória, e a Recipe é interrompida perante um grupo que deixe qualquer uma delas vazia. Um plano de controlo renderizado com um limite de CPU e sem limite de memória é substancialmente diferente daquele que os valores predefinidos declarados do Component descrevem, e nada no resultado renderizado o indicaria — pelo que a compilação para e nomeia, em vez disso, a chave em falta. Uma chave que o grupo omite assume o valor predefinido do Component.
  • Seis chaves sem valor predefinido. A chave com a qual o serviço de tokens assina os tokens do registo, juntamente com o seu certificado; os três segredos com os quais os próprios serviços do registo se autenticam entre si e assinam o estado dos carregamentos; a chave contra a falsificação de pedidos; e a chave com a qual o plano de controlo cifra as credenciais armazenadas não têm valor predefinido: uma chave que todos os leitores do catálogo possuíssem permitiria a qualquer pessoa emitir tokens em que o registo confia ou ler o que ele armazena. O Component declara esses slots como obrigatórios, pelo que uma compilação que deixe um deles vazio é interrompida e nomeia o slot. A compilação não lê nenhum dos seis valores nem renderiza nenhum deles: cada carga de trabalho lê cada um a partir de um Secret que nomeia.
  • Três chaves que a Release anexa. O módulo não anexa nem a chave de assinatura de tokens, nem o segredo partilhado do plano de controlo, nem a chave com a qual as credenciais armazenadas são cifradas, pelo que a Release anexa as três ao componente do módulo, token_key, core_secret e secret_key, cada uma através de core/referenced-secret com infra.origin a nomear um Secret, e o Manifest associa a Feature a k8s-existing-secret. O plano de controlo monta a chave de assinatura de tokens e a chave de cifragem a partir dos Secrets que elas nomeiam, e os serviços leem o segredo partilhado a partir do seu.
  • Credenciais que o módulo preenche. A palavra-passe da conta de administrador, a chave contra a falsificação de pedidos entre sites, o segredo partilhado da camada de workers e o segredo do estado de carregamento do blob store são também slots de credencial do Component, e o módulo preenche cada um a partir de um parâmetro próprio (admin_password, csrf_key, jobservice_secret, registry_http_secret) através da Feature de credencial core/referenced-secret, pelo que cada carga de trabalho os lê a partir de um Secret pelo nome. Como o módulo anexa essa Feature, o Manifest mapeia-a. As três chaves também não têm valor predefinido no módulo, pelo que o Aggregate declara parâmetros próprios e passa-os para baixo através de aggregates.harbor.parameters, a Release satisfá-los, e k8s-existing-secret lê cada um como o nome de um Secret que já existe no namespace; uma Release que não forneça nenhum valor interrompe a compilação, nomeando o parâmetro. Este exemplo deixa a palavra-passe do administrador no valor predefinido de desenvolvimento do módulo, e o Manifest associa pelo nome esse único anexo a k8s-secret-from-parameter, que emite um Secret que a contém. As restantes palavras-passe são escritas na configuração que a Release renderiza, pelo que são substituídas definindo infra; quando não definidas, cada uma assume um valor de desenvolvimento que a Recipe indica.
  • Resultado determinístico sobre um chart que de outro modo geraria material. Deixado por conta própria, este chart gera os seus próprios segredos quando nenhum é fornecido — os segredos partilhado e de assinatura de tokens do plano de controlo, os segredos da camada de workers e do blob store, a chave contra a falsificação de pedidos e a palavra-passe com hash do blob store, cujo hash recalcula com um novo salt em cada renderização. Em vez disso, cada um é fornecido: as seis chaves sempre a partir dos Secrets que a Release nomeia, e as palavras-passe a partir da credencial anexada pelo nome onde um slot está preenchido e a partir de um valor de desenvolvimento fixo onde não está, de modo que duas renderizações de uma entrada idêntica emitem bytes idênticos.
  • Imagens reproduzíveis. Cada imagem que o registo executa está fixada numa tag explícita. O produto publica-as todas com uma única tag, pelo que infra.engine_version seleciona todas de uma vez; infra.overrides.image substitui a fixação de um único serviço, e infra.overrides.image_prefix move-as todas em conjunto para uma Release que faz pull a partir de um espelho.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

Terminal window
aggrega scaffold --example harbor-stack

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd harbor-stack

Compilação

Este espaço de trabalho não contém nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo. A Recipe transfere um chart, pelo que é necessário resolver primeiro as dependências no ficheiro de bloqueio:

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Os artefactos renderizados ficam em dist/.

Antes de os aplicar, é necessário criar os seis Secrets que a Release nomeia no namespace em que o registo é implementado: harbor-token-key, com uma chave privada RSA sob a chave de dados tls.key e um certificado sobre essa chave sob tls.crt; harbor-core-secret, com um segredo de 16 caracteres sob a chave de dados secret; harbor-secret-key, com uma chave de 16 caracteres sob secretKey; harbor-csrf-key, com uma chave de 32 caracteres sob CSRF_KEY; e harbor-jobservice-secret e harbor-registry-http-secret, com um segredo de 16 caracteres sob JOBSERVICE_SECRET e REGISTRY_HTTP_SECRET. Por exemplo:

Terminal window
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \
-keyout tls.key -out tls.crt
kubectl create secret tls harbor-token-key --key tls.key --cert tls.crt
kubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"
kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"
kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"
kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"
kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"

Um registo cujos serviços não encontrem estes Secrets não arranca.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `harbor-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `harbor-stack` e sem `dir`: esta escreve o exemplo numa nova pasta `harbor-stack`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `harbor-stack`, `release` definido como `release-helm-synth.yaml`, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros o build escreveu; encontram-se em `harbor-stack/dist/`.

Como é o registo composto

A compilação emite os recursos que o chart define para esta configuração: Deployments para o proxy inverso, a consola, o plano de controlo, a camada de workers e o blob store; StatefulSets para o backend, a cache e o scanner; pedidos de volume persistente para o blob store e para os logs da camada de workers; os ConfigMaps e Secrets que cada serviço lê; e os Services que estão à frente deles. Ao lado deles, a Feature de credencial emite um Secret, harbor-zdregistry-admin-password, que contém o valor predefinido de desenvolvimento do módulo para a palavra-passe do administrador, que o plano de controlo lê a partir dele em vez do Secret próprio do chart. Não é emitido nenhum Secret para nenhuma das seis chaves: o plano de controlo monta a chave de assinatura de tokens a partir de harbor-token-key e a chave de cifragem a partir de harbor-secret-key, e os serviços leem as restantes a partir de harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret e harbor-registry-http-secret, os Secrets que a Release nomeia.

Exatamente um desses Services é o endereço ao qual os consumidores se ligam — dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:

apiVersion: v1
kind: Service
metadata:
name: harbor-zdregistry
[… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]
spec:
type: ClusterIP
ports:
- name: http
port: 80
targetPort: 8080
selector:
release: harbor-zdregistry
app: "harbor"
component: nginx

O seu seletor nomeia o proxy inverso, que é o que dá ao registo um único endereço. port segue infra.port; o proxy por trás dele escuta na porta que o chart define e o Service encaminha o tráfego para ela, pelo que alterar infra.port move o endereço publicado e não o listener.

Nomenclatura: o ajuste que publica um endereço não é o ajuste que nomeia os recursos

Este chart deriva a maioria dos nomes dos seus recursos de um ajuste de nome de nível superior e depois acrescenta-lhes um sufixo — o Service do plano de controlo é <instance>-core, o da consola <instance>-portal, o do blob store <instance>-registry, e assim por diante para a camada de workers, o scanner, o backend e a cache. Nada recebe apenas o nome simples.

O Service publicado é nomeado por um ajuste separado, com âmbito de exposição, cujo próprio valor predefinido é um literal fixo independente do nome de nível superior. Uma Recipe que fixasse apenas o ajuste de nível superior publicaria um endereço ao qual nenhum Service responde, e duas instâncias num mesmo namespace emitiriam ambas um Service com esse literal fixo e colidiriam. Por isso a Recipe define os dois ajustes a partir do ID da instância, e é por isso que o Service emitido acima recebe o nome da instância e que provides.host nomeia um endereço que existe.

Vale a pena ler isto com atenção ao encapsular qualquer chart de plataforma: provides.host tem de nomear o Service que o chart realmente cria, e qual o ajuste que o decide é uma propriedade do chart, e não uma convenção comum aos charts.

O que esta configuração não inclui

O Ingress do chart fica desativado e o proxy inverso é exposto, em vez disso, como um Service interno ao cluster, porque o Component publica um endereço interno ao cluster em vez de um hostname externo. Um único endpoint externo é montado na camada de ingress, com encaminhamento para o endereço que este módulo exporta. A segurança de transporte está desativada, porque a fonte de certificados própria do chart gera uma autoridade de certificação e um certificado assinado no momento da renderização, o que duas renderizações de uma entrada idêntica não reproduziriam. O monitor do Prometheus operator está desativado.

As métricas do registo também estão desativadas. O values.metrics_enabled do Component ativa-as para o plano de controlo, a camada de workers, o blob store e um exporter adicional, e publica os quatro Services para que um scraper os descubra; a mesma definição do chart abre também o listener de depuração do blob store — profiling, traces de execução e variáveis de runtime, sem qualquer verificação do chamador — a qualquer chamador interno ao cluster. O módulo deixa esse valor no seu predefinido false, pelo que este exemplo não renderiza nenhuma métrica; um Aggregate que declare ele próprio o Component pode defini-lo. A imagem do exporter está, ainda assim, fixada juntamente com as restantes.