Iniciar sessãoAgendar apresentação

Capítulo 2.3

Planear uma instalação

O que uma instalação Kubernetes do Nexus necessita antes de introduzir um comando, qual a sua dimensão e as duas decisões irreversíveis: o nome da instalação e os guardiões das chaves. Termina com a folha de planeamento preenchida da Harrow Port Authority.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

16 minutos de leitura

Quando instalámos o Nexus na Harrow Port Authority, os comandos demoraram uma tarde. O planeamento demorou uma semana, e a maior parte dessa semana foi dedicada a duas questões que nada têm que ver com o Kubernetes: que nome daríamos à instalação e que pessoas guardariam as suas chaves de recuperação. Ambas as respostas são permanentes. Tudo o resto neste capítulo pode ser alterado mais tarde com um ficheiro de valores e um helm upgrade.

Sou o Tomás Reilly, o engenheiro de plataforma na Harrow. A Harrow executa duas instalações. Este capítulo planeia a instalação ligada na nossa rede corporativa, onde testámos primeiro a edição Community. A rede de operações do porto, que não tem rota para a internet, recebeu a sua própria instalação mais tarde; o capítulo 2.10, Instalação isolada da rede (air-gapped), aborda esse tema. Este capítulo é o que eu gostaria de ter tido na primeira manhã: o cluster que o Nexus espera, os nomes a que responde, o que exige dos seus nós e as decisões a tomar com o seu diretor de TI antes da instalação. Termina com a folha de trabalho que a Aoife Brennan, a nossa diretora de TI, aprovou antes de começarmos. O capítulo 2.4, Obter e verificar um lançamento, aborda a obtenção e verificação do lançamento, e o capítulo 2.5, Pré-verificação com o nexusctl, verifica o seu cluster em relação a tudo o que é aqui apresentado.

O que o cluster deve ter

O Nexus instala-se como um único chart do Helm, nexus, versão 1.0.0-alpha.1. O chart inclui os serviços da plataforma e a respetiva camada de dados, e recusa-se a instalar num cluster ao qual faltem os elementos abaixo.

Requisito O que o Nexus espera Porquê
Kubernetes 1.33 ou posterior. Testado em k3s v1.33.6+k3s1 O kubeVersion do chart é >=1.33.0-0, e o helm install impõe-no
cert-manager v1.21.3, instalado antes do Nexus O chart cria a sua própria autoridade de certificação (CA) local e os certificados que os seus serviços utilizam para comunicar entre si
Helm v4 (utilizámos a v4.3.1) O Helm 4 aguarda pelos Jobs de hook do chart por predefinição, dos quais a instalação depende
Uma classe de armazenamento Uma marcada como predefinida, ou uma que indique em storage.className Cada armazenamento de dados reclama um volume persistente
Uma classe de ingress Uma marcada como predefinida, ou uma que indique em ingress.className Os três endereços públicos são Ingresses networking.k8s.io/v1 simples
Portas 80 e 443 Abertas no controlador de ingress, como um Service do tipo LoadBalancer ou NodePort As pessoas acedem ao Nexus através do controlador de ingress
Arquitetura Nós linux/amd64 ou linux/arm64 Cada imagem é compilada para ambos

Duas coisas estão ausentes dessa tabela de propósito. O Nexus não precisa de service mesh: o TLS mútuo (mTLS, Transport Layer Security em ambas as direções) entre serviços provém da CA local do chart através do cert-manager. O chart tem uma chave istio.enabled cuja predefinição é false, e deve deixá-la assim. O Nexus também não precisa de um motor de políticas de admissão próprio.

Na sua estação de trabalho precisará de kubectl, do Helm v4, do cosign v3 para verificar assinaturas, do age para criar chaves de custodiante, e do nexusctl, a interface de linha de comandos (CLI) do operador do Nexus. O capítulo 2.4, Obter e verificar um lançamento, indica onde se encontra cada transferência do Nexus.

Três endereços

Cada instalação responde em três nomes de anfitrião. O chart chama-lhes a identidade da instalação, e todos os serviços se recusam a iniciar sem eles.

Chave de valores Nome na Harrow O que responde aí
hosts.console console.harrow.example A consola, a aplicação web onde as pessoas iniciam sessão
hosts.api api.harrow.example O gateway, que serve a interface de programação de aplicações (API) e encaminha todos os pedidos de inteligência artificial (IA)
hosts.auth auth.harrow.example O serviço de início de sessão, nexus-auth

global.domain contém o domínio sob o qual os três se encontram, harrow.example no nosso caso. Cada anfitrião é um nome completo por direito próprio e pode estar sob qualquer domínio que controle. Mantivemos os três sob um único domínio porque um só certificado podia então abrangê-los.

Crie um registo de Sistema de Nomes de Domínio (DNS) para cada um dos três, a apontar para o endereço do seu controlador de ingress. Faça-o antes da pré-verificação. O nexusctl preflight procura cada nome a partir da sua estação de trabalho e faz falhar a instalação se algum deles não tiver registo, porque uma pessoa não consegue aceder a um nome que não resolve.

À esquerda, três nomes de DNS: console.harrow.example, api.harrow.example e auth.harrow.example, cada um com uma seta para uma caixa com a legenda "ingress controller, ports 80 and 443". A partir dessa caixa, três setas conduzem a uma caixa maior com a legenda "namespace nexus": a seta de console para "nexus-alpha :3000", a seta de api para "nexus-gateway :9092" e a seta de auth para "nexus-auth :9101". Um limite tracejado à volta do namespace tem a legenda "default deny; only the ingress namespace may reach these three".
Como os três nomes públicos chegam aos serviços por detrás deles.

Escolher onde termina o TLS

A chave tls.mode do chart decide quem detém os certificados para os três endereços públicos. Existem três opções, e pode alternar entre elas mais tarde através de uma atualização.

tls.mode O que fornece O que o chart faz
existing (a predefinição) Um Secret TLS do Kubernetes no namespace nexus, indicado em tls.existingSecret Todos os três Ingresses utilizam esse único Secret
cert-manager Um ClusterIssuer que execute, indicado em tls.clusterIssuer Anota cada Ingress para que o cert-manager emita nexus-console-tls, nexus-api-tls e nexus-auth-tls
none Algo à frente do cluster que termine o TLS, como o seu próprio balanceador de carga Gera os Ingresses sem secção de TLS

Com existing, um certificado serve todos os três anfitriões, pelo que tem de indicar os três, seja como três nomes alternativos do sujeito (SAN) ou como um wildcard para o seu domínio. Utilizámos um certificado da CA interna da Harrow. A pré-verificação lê o Secret antes de instalar e avisa quando o certificado expira no prazo de 30 dias.

Com cert-manager e um emissor Automatic Certificate Management Environment (ACME), o chart não adiciona nenhum redirecionamento próprio, pelo que um pedido /.well-known/acme-challenge/ na porta 80 chega ao resolvedor intacto. Não adicione um redirecionamento de HTTP para HTTPS no seu controlador de ingress que seja executado antes do caminho do desafio; um certificado que não consegue renovar falha silenciosamente, semanas mais tarde.

Qualquer que seja a sua escolha para a extremidade pública, os serviços dentro do namespace comunicam sempre por TLS a partir da CA local do chart. Essa parte não é opcional, e é por isso que o cert-manager é um pré-requisito mesmo quando tls.mode é existing ou none.

O que sai do cluster e o que não sai

O chart gera uma política de rede de negação por predefinição (default-deny) para o namespace nexus. Depois disso, apenas estes fluxos são permitidos:

  • tráfego entre pods do Nexus dentro do namespace;
  • consultas de DNS para o serviço de DNS do cluster;
  • o servidor da API do Kubernetes, para os poucos serviços que reveem tokens de cargas de trabalho;
  • o namespace do controlador de ingress, para os três Services públicos;
  • quaisquer intervalos de Classless Inter-Domain Routing (CIDR) que liste em networkPolicy.externalEgressCIDRs.

Essa última lista está vazia por predefinição. Se for utilizar um retransmissor de correio (mail relay) ou um servidor de modelos fora do cluster, o respetivo intervalo entra aí. A telemetria está desativada e permanece desativada: o esquema apenas aceita telemetry.enabled: false, e o relatório de utilização dos próprios armazenamentos de dados também está desativado.

O chart lê os endereços do servidor da API a partir do cluster quando instala. Se a sua conta não puder ler os Endpoints kubernetes no namespace default, indique-os você mesmo em networkPolicy.apiServerCIDRs, como intervalos /32. proxy.trustedCIDRs indica a rede de pods onde se encontra o seu controlador de ingress, para que o nexus-auth saiba no cabeçalho X-Forwarded-For de quem deve confiar. A predefinição, 10.42.0.0/16, é a rede de pods do k3s.

Dimensionamento

Os pedidos predefinidos do chart somam cerca de 2,05 núcleos de unidade central de processamento (CPU) e 6,7 GiB de memória. É isso que o escalonador reserva; os limites são superiores, e os armazenamentos de dados crescem até eles à medida que adiciona pessoas e ficheiros.

Componente CPU pedida Memória pedida
Nove serviços da plataforma (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1,1 núcleos 2,6 GiB
O serviço de chaves, nexus-keys 0,05 núcleos 64 MiB
PostgreSQL 0,25 núcleos 1 GiB
Neo4j 0,25 núcleos 2 GiB
Valkey, Qdrant e o armazenamento de objetos em conjunto 0,25 núcleos 640 MiB
Os dois servidores OpenBao do armazenamento de chaves 0,15 núcleos 384 MiB

Os volumes predefinidos somam 142 GiB:

Armazenamento Chave de valores Tamanho predefinido
PostgreSQL 16 com PostGIS 3 e pgvector 0.8 dataTier.postgres.size 50Gi
Armazenamento de objetos (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
O armazenamento de chaves e o seu desselador (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi e 1Gi
Recibos do serviço de chaves keys.receiptsStorage 1Gi

Para um único nó, planeie 8 vCPU, 32 GiB de memória de acesso aleatório (RAM) e uma unidade de estado sólido (SSD) de 250 GB. Para uma avaliação, 4 vCPU, 16 GiB e 200 GB são suficientes. A imagem de disco do instalador recusa uma máquina com menos de 16 GiB de memória (consulte o capítulo 2.9, A imagem de disco do instalador), e eu trataria isso como o mínimo em qualquer cenário.

Os nós gráficos são opcionais. Sem um nó que ofereça uma unidade de processamento gráfico (GPU), o assistente responde através de um modelo alojado, utilizando a própria chave da organização. A pré-verificação reporta isso como um aviso, nunca como uma falha. O capítulo 2.14, Fornecedores e modelos de IA, aborda ambas as vias.

Cada armazenamento também pode ser executado fora do cluster: defina dataTier.<store>.mode como external e indique o seu anfitrião e um Secret. Um PostgreSQL externo precisa de uma conta de superutilizador para o arranque (bootstrap) da instalação e de um certificado que o Nexus possa verificar. O capítulo 2.11, Variações: armazenamentos externos, TLS e ingress, aborda esse tema. Se os mantiver no cluster, coloque-os numa classe de armazenamento suportada por discos reais. A base de dados é a parte de que sentirá mais falta se o disco local de um nó avariar.

O nome da instalação é permanente

keys.installationName é como os operadores chamam a esta instalação. Tem de corresponder a ^[a-z][a-z0-9-]{0,62}$: uma letra minúscula, seguida de até 62 letras minúsculas, dígitos ou hífenes.

Na primeira vez que o armazenamento de chaves inicia, gera a identidade da instalação sob este nome, e essa identidade fica fixa para sempre. Uma licença da Adverant é emitida para essa identidade, pelo que uma licença feita para uma instalação é recusada noutra com LICENCE_OTHER_INSTALLATION. Mudar o nome significaria uma nova instalação, uma nova identidade e novas licenças.

O chart não tem predefinição para o nome. Recusa uma instalação sem nome (INSTALLATION_NAME_MISSING) e recusa o nome de exemplo dos seus próprios ficheiros de valores de exemplo (INSTALLATION_NAME_EXAMPLE). A pré-verificação reporta ambos antes de chegar a esse ponto.

Na Harrow demorámos mais tempo nisto do que eu gostaria de admitir. Decidimo-nos por harrow-port-authority: indica o nome da organização, não diz nada sobre o cluster em que é executado e continuará a ser válido quando o hardware for substituído. Evite nomes como prod-k3s-2 que descrevem as máquinas de hoje.

Custódia de chaves

O Nexus guarda as chaves de cada organização no seu próprio armazenamento de chaves, dentro do cluster. Não o opera no dia a dia, mas decide, antes da instalação, quem o pode recuperar após um reinício. Esta é a decisão que sai mais cara se errar.

O armazenamento de chaves é composto por dois servidores OpenBao. O principal, openbao, guarda as chaves e dessela-se a si mesmo através de um segundo, mais pequeno, openbao-unsealer. O desselador (unsealer) é selado com o esquema de Shamir: cinco partes (shares), em que três quaisquer o abrem. Quando instala, um Job de custódia inicializa ambos os servidores dentro do cluster. Na memória desse Job, este encripta as partes do desselador e as chaves de recuperação do armazenamento de chaves para cada custodiante que indicar, armazena apenas o texto cifrado (nos Secrets openbao-unseal-shares-encrypted e openbao-recovery-keys-encrypted) e revoga ambos os tokens de raiz antes de terminar. Nenhuma parte em texto simples chega alguma vez a um disco ou a um registo (log).

Após qualquer reinício do nó do desselador, este inicia selado. O armazenamento de chaves aguarda por ele, e nada que precise de uma chave funciona até que um custodiante o dessele. Isso requer uma desencriptação com a chave privada do próprio custodiante. O procedimento encontra-se no capítulo 2.15, Dia dois: operar o Nexus.

Criar uma chave de custodiante

Um custodiante é identificado pela metade pública de uma chave age, chamada o seu destinatário (recipient). Cada custodiante cria a sua própria chave na sua própria máquina e entrega-lhe apenas o destinatário:

age-keygen -o custodian.key

A linha # public key: do ficheiro é o destinatário, começando por age1. Um custodiante com um Mac pode, em vez disso, guardar a chave no Secure Enclave do Mac, para que a metade privada nunca saia do chip e cada utilização peça uma impressão digital:

age-plugin-se keygen --access-control=any-biometry -o custodian.key

Esse destinatário começa por age1se1. O Job de custódia encripta para cinco formas de destinatário: age1 (X25519), age1tag1 e age1tagpq1 (tag), age1pq1 (híbrido pós-quântico) e age1se1 (Secure Enclave). Recusa qualquer outra forma de plugin, como age1yubikey1; indique antes essa chave numa das formas aceites.

O chart verifica cada destinatário quando o gera. Um destinatário com erros de digitação falha a sua soma de verificação (checksum) bech32 e é recusado, pelo que nada é alguma vez selado para uma chave que ninguém detém. Se alguém colar uma chave privada na lista por engano, o chart recusa-a sem a repetir no ecrã. O destinatário de exemplo nos próprios ficheiros de valores do chart também é recusado (KEYS_CUSTODIAN_EXAMPLE); ninguém detém a sua metade privada.

Quantos custodiantes

Cada parte é encriptada para cada custodiante, pelo que qualquer custodiante pode desselar sozinho. Mais custodiantes significa mais formas de recuperar e mais pessoas que podem, cada uma, agir sozinhas. Escolhemos três na Harrow: a Aoife, eu e uma chave Secure Enclave num portátil sobresselente que fica no cofre do porto. Dois é o mínimo que eu aceitaria. Um é um ponto único de falha que, mais cedo ou mais tarde, estará de férias quando um nó reiniciar.

Escolher a edição

edition é community ou enterprise, e enterprise.enabled tem de concordar com ele. O chart recusa uma divergência e recusa qualquer edição que não seja uma das duas.

A edição também decide que imagens instala. Cada pacote do chart inclui um bloqueio de imagens (images lock), a lista de todas as imagens por digest, para uma edição. Uma instalação Community utiliza apenas imagens Community. Uma instalação Enterprise utiliza o bloqueio Enterprise, que corresponde às imagens Community mais as compilações Enterprise, e transfere-as com um token de transferência (pull token) da sua conta Adverant. O capítulo 2.4, Obter e verificar um lançamento, explica o bloqueio, e o capítulo 2.2, As edições ao detalhe, explica o que cada edição contém.

Não tem de decidir de forma definitiva. Uma instalação Community passa para Enterprise no mesmo local, mantendo as suas pessoas, ficheiros e histórico; o capítulo 2.7, Instalar a edição Enterprise e aplicar uma licença, mostra como. Executámos a Community para o piloto na Harrow e mudámos seis semanas depois.

A licença nunca faz parte deste plano. Não é um valor do chart nem um ficheiro montado: importa-a após a instalação, através da consola, do nexusctl ou da API.

Escolher a forma de entrega

Formato Quando se adequa Capítulo
Chart do Helm a partir de registry.adverant.ai O seu próprio cluster Kubernetes, com uma rota para o registo 2.6 e 2.7
nexusctl install O mesmo cluster, com a pré-verificação e a verificação de assinatura executadas automaticamente 2.6
nexusctl install --single-node Uma máquina, onde o nexusctl também configura o cluster 2.8
A imagem de disco do instalador Um servidor físico (bare metal) ou máquina virtual (VM) que prefira não preparar manualmente 2.9
O pacote offline Sem qualquer rota para o exterior; as imagens e o chart vêm num disco 2.10

O chart é o mesmo em todos os formatos. O que muda é quem cria o cluster e de onde vêm as imagens.

Obter o lançamento
Obter o lançamento
Esta é a página de lançamentos na conta Adverant. Repare na declaração clara do que um lançamento alfa promete, no tamanho e na assinatura ao lado de cada ficheiro e nos comandos offline para verificar uma transferência.

A folha de planeamento

Esta é a da Harrow, tal como a Aoife a aprovou. Copie as duas colunas da esquerda e preencha a da direita para a sua própria instalação.

Decisão Chave de valores ou comando Harrow Port Authority
Kubernetes e versão (a pré-verificação lê-o) k3s v1.33.6+k3s1, três nós
Contexto Kube para a instalação --context harrow-prod
Namespace --namespace nexus
Edição edition, enterprise.enabled community para o piloto, depois enterprise
Registo de imagens global.imageRegistry registry.adverant.ai
Domínio global.domain harrow.example
Endereço da consola hosts.console console.harrow.example
Endereço da API hosts.api api.harrow.example
Endereço de início de sessão hosts.auth auth.harrow.example
TLS na extremidade (edge) tls.mode, tls.existingSecret existing, Secret harrow-public-tls da CA interna da Harrow
Classe de ingress ingress.className traefik
Namespace do ingress networkPolicy.ingressNamespace kube-system
Classe de armazenamento storage.className local-path
Armazenamentos de dados dataTier.<store>.mode Todos in-cluster, tamanhos predefinidos
Intervalos de saída networkPolicy.externalEgressCIDRs Apenas o intervalo do retransmissor de correio
Nome da instalação (permanente) keys.installationName harrow-port-authority
Custodiantes (permanentes na prática) keys.custody.recipients Três: Aoife Brennan, Tomás Reilly, o portátil do cofre (age1se1)
Nós gráficos (a pré-verificação lê-o) Nenhum para o piloto ligado; modelo alojado com a chave própria da Harrow
Primeiro administrador nexusctl claim-code --administrator aoife.brennan@harrow.example

Duas linhas nessa folha não podem ser revertidas: o nome da instalação e os custodiantes, no sentido em que perdê-los a todos implica perder o armazenamento de chaves. Obtenha a aprovação dessas duas por parte de alguém com autoridade para dizer que sim. Tudo o resto é uma alteração de valores.

Com a folha de trabalho concluída, avance para o capítulo 2.4, Obter e verificar um lançamento, e obtenha o lançamento.