Stack Harbor — um registro de contêineres implantado como uma única release
Este exemplo compila um registro de contêineres real para manifestos do Kubernetes a partir de um único Aggregate escrito pelo desenvolvedor.
Um registro de contêineres é composto por muitos serviços que cooperam — um plano de controle de API e serviço de tokens, um blob store OCI e o seu controlador, um console web, uma camada de workers assíncronos, um scanner de vulnerabilidades, um backend relacional, um cache chave-valor e um proxy reverso na frente deles. O catálogo descreve tudo isso como um único Component, porque os próprios mantenedores do registro publicam um chart do Helm que o implanta por inteiro como uma única release, na ordem de que os seus serviços precisam. O Component declara o registro; a Recipe encapsula esse chart.
O registro é 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 mais alto importa o módulo pelo nome e lhe passa três das chaves do registro; o operador dimensiona o componente do módulo na Release.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: importa o módulo de registro de contêineres (core/harbor) e lhe passa três das chaves do registro a partir de parâmetros próprios. |
manifest-helm-synth.yaml | Mapeia o tipo de componente do registro 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 senha do administrador, que ele vincula pelo nome à realização que emite um Secret a partir do parâmetro do módulo. |
release-helm-synth.yaml | Documento do operador para o destino Kubernetes. Nomeia os Secrets que contêm as três chaves que o Aggregate repassa para baixo, dimensiona o componente do módulo pelo seu ID com escopo de módulo, e vincula a ele a chave de assinatura de tokens, o segredo compartilhado dos serviços e a chave com a qual as credenciais armazenadas são criptografadas, nomeando os Secrets que as contêm; todo o resto fica com os valores padrão do esquema. |
O que ele demonstra
- Um produto com vários serviços como um único Component. O que faz do registro um único Component em vez de vários não é o seu tamanho, mas onde o seu cabeamento é mantido: o roteamento do proxy reverso, a chave do serviço de tokens com a qual o plano de controle verifica cada pull e cada push, as configurações de conexão que cada serviço lê para o backend e o cache, a divisão em bancos de dados lógicos que mantém separados os espaços de chaves do cache dos serviços, e a ordem de inicialização — tudo isso é mantido em sintonia com o produto pelas pessoas que o publicam, dentro do chart. Um consumidor declara um registro e recebe tudo isso em concordância.
- Um chart encapsulado. A Recipe nomeia o chart em
source:e sobrepõe a ele umvaluesMapping:— o template de valores é toda a implementação, e o provedor 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 o build baixa, então é fixado como qualquer dependência: o arquivo de bloqueio registra a versão do chart, a sua URL resolvida e o digest do tarball, em
source_artifacts. Um build com um arquivo de bloqueio preenchido serve o chart a partir do repositório de conteúdo e o verifica em relação a esse digest. - Um único endereço publicado para uma plataforma inteira. O proxy reverso do chart roteia o caminho de navegador
/para o console e os caminhos do registro e da API (/v2/,/api/,/service/,/c/) para o plano de controle, então um cliente de contêineres faz login, push e pull no mesmo host pelo qual um navegador acessa o console. Esse Service é o queprovides.hostpublica, 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 se comunicam, e comoui, o endpoint web. Ambos resolvem para o endereço que serve os dois conjuntos de caminhos, então um consumidor se conecta 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 escopo de módulo (
harbor.registry) para definir os recursos de computação, sem que o Aggregate do desenvolvedor repita o dimensionamento físico. - Regras de completude em um valor agrupado.
infra.computetraz uma chave de CPU e uma de memória, e a Recipe é interrompida diante de um grupo que deixe qualquer uma delas vazia. Um plano de controle renderizado com um limite de CPU e sem limite de memória é substancialmente diferente daquele que os valores padrão declarados do Component descrevem, e nada na saída renderizada indicaria isso — então o build para e nomeia a chave ausente. Uma chave que o grupo omite assume o valor padrão do Component. - Seis chaves sem valor padrão. A chave com a qual o serviço de tokens assina os tokens do registro, junto com o seu certificado; os três segredos com os quais os próprios serviços do registro se autenticam entre si e assinam o estado dos uploads; a chave contra falsificação de requisições; e a chave com a qual o plano de controle criptografa as credenciais armazenadas não têm valor padrão: uma chave que todo leitor do catálogo tivesse permitiria a qualquer pessoa emitir tokens em que o registro confia ou ler o que ele armazena. O Component declara esses slots como obrigatórios, então um build que deixe um deles vazio é interrompido e nomeia o slot. O build não lê nenhum dos seis valores nem renderiza nenhum deles: cada carga de trabalho lê cada um de um Secret que ela nomeia.
- Três chaves que a Release vincula. O módulo não vincula nem a chave de assinatura de tokens, nem o segredo compartilhado do plano de controle, nem a chave com a qual as credenciais armazenadas são criptografadas, então a Release vincula as três ao componente do módulo,
token_key,core_secretesecret_key, cada uma por meio decore/referenced-secretcominfra.originnomeando um Secret, e o Manifest associa a Feature ak8s-existing-secret. O plano de controle monta a chave de assinatura de tokens e a chave de criptografia a partir dos Secrets que elas nomeiam, e os serviços leem o segredo compartilhado do seu. - Credenciais que o módulo preenche. A senha da conta de administrador, a chave contra falsificação de requisições entre sites, o segredo compartilhado da camada de workers e o segredo do estado de upload do blob store também são 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) por meio da Feature de credencialcore/referenced-secret, então cada carga de trabalho os lê de um Secret pelo nome. Como o módulo vincula essa Feature, o Manifest a mapeia. As três chaves também não têm valor padrão no módulo, então o Aggregate declara parâmetros próprios e os repassa para baixo por meio deaggregates.harbor.parameters, a Release os preenche, ek8s-existing-secretlê cada um como o nome de um Secret que já existe no namespace; uma Release que não fornece nenhum valor interrompe o build, nomeando o parâmetro. Este exemplo deixa a senha do administrador no valor padrão de desenvolvimento do módulo, e o Manifest associa pelo nome essa única vinculação ak8s-secret-from-parameter, que emite um Secret que a contém. As senhas restantes são escritas na configuração que a Release renderiza, então são substituídas definindoinfra; sem definição, cada uma assume um valor de desenvolvimento que a Recipe declara. - Saída determinística sobre um chart que de outra forma geraria material. Deixado por conta própria, este chart gera os seus próprios segredos quando nenhum é fornecido — os segredos compartilhado e de assinatura de tokens do plano de controle, os segredos da camada de workers e do blob store, a chave contra falsificação de requisições e a senha com hash do blob store, cujo hash ele recalcula com um novo salt a cada renderização. Em vez disso, cada um é fornecido: as seis chaves sempre a partir dos Secrets que a Release nomeia, e as senhas a partir da credencial vinculada 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. Toda imagem que o registro executa é fixada em uma tag explícita. O produto publica todas elas com uma única tag, então
infra.engine_versionseleciona todas de uma vez;infra.overrides.imagesubstitui a fixação de um único serviço, einfra.overrides.image_prefixmove todas juntas para uma Release que faz pull de um espelho.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example harbor-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd harbor-stackBuild
Este espaço de trabalho não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária. A Recipe baixa um chart, então resolva primeiro as dependências no arquivo de bloqueio:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlOs artefatos renderizados ficam em dist/.
Antes de aplicá-los, crie os seis Secrets que a Release nomeia no namespace em que o registro é implantado: harbor-token-key, contendo uma chave privada RSA sob a chave de dados tls.key e um certificado sobre essa chave sob tls.crt; harbor-core-secret, contendo um segredo de 16 caracteres sob a chave de dados secret; harbor-secret-key, contendo uma chave de 16 caracteres sob secretKey; harbor-csrf-key, contendo uma chave de 32 caracteres sob CSRF_KEY; e harbor-jobservice-secret e harbor-registry-http-secret, contendo um segredo de 16 caracteres sob JOBSERVICE_SECRET e REGISTRY_HTTP_SECRET. Por exemplo:
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl 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 registro cujos serviços não encontram esses Secrets não inicia.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `harbor-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `harbor-stack` e sem `dir`: ela grava o exemplo em uma 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. Diga-me quais arquivos o build gravou; eles ficam em `harbor-stack/dist/`.Como fica o registro composto
O build emite os recursos que o chart define para esta configuração: Deployments para o proxy reverso, o console, o plano de controle, a camada de workers e o blob store; StatefulSets para o backend, o cache e o scanner; solicitações 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 ficam na frente deles. Ao lado deles, a Feature de credencial emite um Secret, harbor-zdregistry-admin-password, que traz o valor padrão de desenvolvimento do módulo para a senha do administrador, que o plano de controle lê dele em vez do Secret próprio do chart. Nenhum Secret é emitido para nenhuma das seis chaves: o plano de controle monta a chave de assinatura de tokens de harbor-token-key e a chave de criptografia de harbor-secret-key, e os serviços leem as demais 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 conectam — dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:
apiVersion: v1kind: Servicemetadata: 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: nginxO seu seletor nomeia o proxy reverso, que é o que dá ao registro 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, então 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 mais alto e depois acrescenta a eles um sufixo — o Service do plano de controle é <instance>-core, o do console <instance>-portal, o do blob store <instance>-registry, e assim por diante para a camada de workers, o scanner, o backend e o cache. Nada recebe apenas o nome puro.
O Service publicado é nomeado por um ajuste separado, com escopo de exposição, cujo próprio valor padrão é um literal fixo independente do nome de nível mais alto. Uma Recipe que fixasse apenas o ajuste de nível mais alto publicaria um endereço ao qual nenhum Service responde, e duas instâncias em um 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 isso com atenção ao encapsular qualquer chart de plataforma: provides.host precisa nomear o Service que o chart realmente cria, e qual ajuste decide isso é uma propriedade do chart, e não uma convenção entre charts.
O que esta configuração não inclui
O Ingress do chart fica desativado e o proxy reverso é 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 roteamento 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 certificadora 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 registro também estão desativadas. O values.metrics_enabled do Component as ativa para o plano de controle, a camada de workers, o blob store e um exporter adicional, e publica os quatro Services para que um scraper os descubra; a mesma configuração do chart também abre o listener de depuração do blob store — profiling, traces de execução e variáveis de runtime, sem nenhuma verificação do chamador — a todo chamador interno ao cluster. O módulo deixa esse valor no seu padrão false, então este exemplo não renderiza nenhuma métrica; um Aggregate que declare o próprio Component pode defini-lo. A imagem do exporter é fixada mesmo assim junto com as demais.