Versão 1.0.0-alpha.1mais recente
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

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.
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.keyA 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.keyEsse 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.
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.
