Versão 1.0.0-alpha.1mais recente
Capítulo 2.6
Instalar a edição Community no Kubernetes
Uma instalação passo a passo da edição Community com o Helm, desde o cert-manager até todas as cargas de trabalho estarem prontas, com o ficheiro de valores explicado chave a chave, a razão pela qual não existe --wait, a ordem de execução dos hooks do chart e a via de instalação com o nexusctl como alternativa.
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

A instalação em si resume-se a um único helm install. Tudo o que a rodeia existe para que esse comando funcione à primeira: o cert-manager antes dele, um ficheiro de valores lido linha a linha e uma espera posterior que sabe pelo que aguardar. Na Harrow Port Authority, instalámos primeiro a edição Community, para um piloto de seis semanas, no cluster k3s de três nós da nossa folha de planeamento. A versão ficou em execução em cerca de vinte minutos e ninguém pôde iniciar sessão até a reivindicarmos, tal como deve ser.
Este capítulo pressupõe que já concluiu três tarefas: preencheu a folha de planeamento (capítulo 2.3, Planear uma instalação), obteve e verificou a versão (capítulo 2.4, Obter e verificar uma versão) e executou a verificação prévia (capítulo 2.5, Verificação prévia com o nexusctl). Se alguma destas tarefas ainda estiver pendente, volte atrás. A instalação recusa a maioria dos erros pelo nome, mas há alguns, como um custodiante cuja chave já tenha perdido, que não consegue detetar.
Passo 1: confirmar as ferramentas e o contexto
Verifique se o Helm é a versão 4.
helm versionA instalação depende de o Helm 4 aguardar, por predefinição, pelos Jobs de hook do chart. Utilizámos a v4.3.1.
Aponte o
kubectlpara o cluster indicado na sua folha de planeamento e confirme.kubectl config use-context harrow-prod kubectl get nodesCada nó deve apresentar
Ready. A verificação prévia já confirmou isto, mas um nó pode falhar entre a verificação prévia e a instalação, sendo mais rápido detetá-lo aqui.
Passo 2: instalar primeiro o cert-manager
O chart cria a sua própria autoridade de certificação (CA) local com o cert-manager, e todos os serviços comunicam entre si através de certificados por ela emitidos: um Issuer autoassinado, um certificado de CA local de dez anos e certificados de curta duração para os serviços. Por conseguinte, o cert-manager tem de estar em execução antes do Nexus. A versão requer a v1.21.3 e não necessita do trust-manager.
Instale o cert-manager a partir do respetivo chart, com os seus recursos personalizados:
helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \ --set crds.enabled=true --wait --timeout 10m<cert-manager-chart>é o chart do cert-manager v1.21.3 da própria versão do projeto cert-manager. Aguardar neste ponto é o procedimento correto; trata-se da instalação do próprio cert-manager, sem hooks que dependam de outros componentes.Aguarde pelo respetivo webhook, pelo qual passam todos os pedidos de certificado:
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
Passo 3: criar o namespace e o Secret de TLS
Com tls.mode: existing, o chart espera que o seu certificado exista como um Secret do Kubernetes no namespace antes da instalação. O Transport Layer Security (TLS) para os três endereços provém deste único Secret, pelo que o respetivo certificado tem de incluir o nome dos três anfitriões.
kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
--cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt é o certificado, com a respetiva cadeia, e harrow-public.key a sua chave privada. Se escolheu tls.mode: cert-manager ou none no capítulo 2.3, Planear uma instalação, ignore o Secret; pode ainda assim criar o namespace agora ou deixar que o Helm o faça com --create-namespace no passo 6.
Passo 4: escrever o ficheiro de valores
Este é o ficheiro de valores da Harrow para o piloto. Cada chave nele contida é uma chave aceite pelo esquema do chart; o esquema recusa qualquer outra, pelo que uma chave com erros ortográficos faz falhar a instalação em vez de ser ignorada silenciosamente.
# harrow-values.yaml (Helm values, Community)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
enterprise:
enabled: false
tls:
mode: existing
existingSecret: harrow-public-tls
ingress:
className: traefik
storage:
className: local-path
networkPolicy:
ingressNamespace: kube-system
externalEgressCIDRs: ["10.20.9.25/32"]
keys:
installationName: harrow-port-authority
custody:
recipients:
- "<recipient-aoife>"
- "<recipient-tomas>"
- "<recipient-safe-laptop>"Cada <recipient-...> é o destinatário age público de um custodiante, a linha age1... ou age1se1... que lhe enviaram. Eis todas as chaves que definimos e o respetivo motivo.
global.imageRegistry é o registo a partir do qual os seus nós extraem as imagens. O chart não tem predefinição; constrói cada imagem como <this>/nexus/<service>@<digest>. Para uma instalação ligada à Internet, é registry.adverant.ai. Se copiou as imagens para o seu próprio registo, é esse o anfitrião.
global.domain é o domínio sob o qual se encontram os três endereços.
hosts.console, hosts.api e hosts.auth constituem a identidade da instalação: os três nomes que as pessoas e os programas utilizam. Cada um tem de ser já resolvido no Domain Name System (DNS), o que foi confirmado pela verificação prévia.
edition e enterprise.enabled têm de coincidir: community com false, ou enterprise com true. O chart recusa qualquer outra combinação e recusa uma edição para a qual o seu bloqueio de imagens não tenha sido criado.
tls.mode e tls.existingSecret definem como a extremidade pública obtém o seu certificado. Com cert-manager definiria antes tls.clusterIssuer, e com none nenhum deles.
ingress.className indica a classe de ingress. Deixe por definir para utilizar a classe predefinida do cluster.
storage.className indica a classe de armazenamento para cada volume de dados. Deixe por definir para utilizar a predefinição.
networkPolicy.ingressNamespace é o namespace no qual o seu controlador de ingress é executado. A predefinição, kube-system, é a correta para o Traefik do k3s; definimo-la ainda assim para que fique explícita no ficheiro.
networkPolicy.externalEgressCIDRs lista os intervalos de endereços, na notação Classless Inter-Domain Routing (CIDR), fora do namespace que os serviços podem alcançar, para além do DNS e do servidor da interface de programação de aplicações (API) do Kubernetes. O nosso contém o endereço único do retransmissor de correio; com a lista vazia, nada fora do namespace está acessível.
keys.installationName é o nome permanente sob o qual o armazenamento de chaves emite a identidade da instalação.
keys.custody.recipients lista os destinatários age públicos dos custodiantes. O Job de custódia encripta cada parte de desselagem e chave de recuperação para cada um deles.
Chaves de que pode necessitar e chaves a não alterar
| Chave | Quando a definir |
|---|---|
networkPolicy.apiServerCIDRs |
Quando o chart não consegue ler os endereços do servidor da API a partir dos Endpoints kubernetes. Indique-os como intervalos /32 |
proxy.trustedCIDRs |
Quando os pods do seu controlador de ingress não estão no 10.42.0.0/16 do k3s |
ai.localProvider.baseUrl |
Quando a organização executa o seu próprio servidor de modelos de inteligência artificial (IA) compatível com OpenAI (capítulo 2.14, Fornecedores e modelos de IA) |
ai.installationHosts |
Quando esse servidor de modelos reside em nomes privados dentro da instalação |
dataTier.<store>.size |
Quando um armazenamento necessita de mais do que o seu volume predefinido |
dataTier.<store>.mode |
external para um armazenamento gerido por si (capítulo 2.11, Variações: armazenamentos externos, TLS e ingress) |
components.<service>.replicas, components.<service>.resources |
Quando aumenta a capacidade de um serviço |
auth.rateLimitPerMinute |
Quando a automatização intensiva necessita de mais de 5.000 pedidos por minuto por pessoa |
schemaWait.timeoutSeconds |
Quando um disco lento faz com que as primeiras migrações demorem mais de 30 minutos |
Deixe istio.enabled em false; o Nexus não necessita de uma malha de serviços (service mesh). Deixe telemetry.enabled em false; o esquema não aceita outro valor. Deixe orchestrator.platformServiceUserId e probitas.flags tal como o chart os define.
Nenhuma credencial é alguma vez um valor do chart. Não existe qualquer chave para a chave de API de um fornecedor de modelos, uma palavra-passe de correio ou um token de extração. Os serviços geram os seus próprios segredos internos na instalação e mantêm-nos nas atualizações, e as chaves de modelos de cada organização entram no seu próprio conjunto de chaves a partir da consola após a primeira execução.
Passo 5: executar a verificação prévia contra o ficheiro final
nexusctl preflight --context harrow-prod --values harrow-values.yamlA execução tem de terminar com 0 failed. O Capítulo 2.5, Verificação prévia com o nexusctl, explica cada linha. Se alterou alguma coisa desde a última execução, mesmo que seja um tamanho, execute-a novamente.
Passo 6: instalar, sem --wait
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
--namespace nexus -f harrow-values.yaml --timeout 45mSe não criou o namespace no passo 3, adicione --create-namespace. Se estiver a instalar a partir de um ficheiro de chart que transferiu e verificou, coloque o respetivo caminho em vez da referência oci://.
Não adicione --wait. O arranque da base de dados do chart é executado como um hook pós-instalação, depois de existirem os próprios recursos da versão, e é esse hook que atribui a cada serviço a sua função e palavra-passe na base de dados. --wait reteria a instalação até que cada Deployment estivesse Available, e nenhum Deployment pode ficar Available antes de o hook pelo qual aguarda ter sido executado. Os serviços ficam a recusar os inícios de sessão na base de dados e o Helm aguarda por eles até ao limite de tempo. Sem --wait, o Helm 4 continua a aguardar por cada Job de hook, por ordem, e é essa a espera pretendida.
Quando o último hook termina, o Helm apresenta o seu resumo:
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
STATUS: deployed significa que todos os hooks foram bem-sucedidos. Ainda não significa que todos os serviços estão a responder; o passo 7 aguarda por isso.
O que é executado e por que ordem
O Helm executa os hooks por peso, do mais baixo para o mais alto, e aguarda por cada um antes de passar ao seguinte. Cada Job de migração tem backoffLimit: 0: uma migração falhada faz falhar a instalação e nunca é repetida sem o seu conhecimento. Um Job bem-sucedido é eliminado; um Job que falhe permanece, com o respetivo registo, para que o possa ler.
| Peso | Hook | O que faz |
|---|---|---|
| -30 | Pré-requisitos | A conta de hook nexus-migrations, o Secret exclusivo para hooks nexus-migrations-env com as credenciais de base de dados geradas, e a conta, função, configuração e certificado do Job de custódia |
| -20 | nexus-db-bootstrap |
Cria as bases de dados e as funções, nenhuma delas como superutilizador e nenhuma capaz de contornar a segurança ao nível da linha (RLS); adiciona as extensões, entre as quais PostGIS e pgvector; cria o registo de versões (release ledger) |
| -15 | nexus-openbao-custody-init |
Inicializa o armazenamento de chaves e o respetivo desselador, encripta as partes e as chaves de recuperação para os seus custodiantes, revoga ambos os tokens de raiz e emite a identidade da instalação sob keys.installationName |
| -12 | nexus-graphrag-migrations |
Implementa primeiro o esquema do serviço de grafos, porque o esquema do serviço de início de sessão faz referência a objetos que lhe pertencem |
| -10 | nexus-auth-migrations |
Implementa o esquema do serviço de início de sessão e as suas duas funções de tempo de execução |
| -5 | nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations |
O esquema próprio de cada serviço; o probitas é executado após o auth porque verifica primeiro as tabelas do auth |
| 0 | nexus-alpha-bff-migrations |
Aprovisiona a base de dados do backend for frontend (BFF) e as respetivas funções, aplicando em seguida as suas migrações |
Cada hook de migração termina escrevendo uma linha no registo de versões, nexus_release.schema_applied: o nome da sua cadeia e o resumo (digest) da imagem que o executou. Só escreve essa linha depois de o seu executor de migração ter terminado sem erros. O Job de arranque apresenta db-bootstrap: done; os hooks de migração SQL apresentam schema-ledger: recorded <chain> for this release's image como última linha. O hook de migração da própria consola, nexus-alpha-bff-migrations, regista a sua linha da mesma forma e apresenta em seguida bff-migrate: done.
Como os serviços aguardam pelo seu esquema
Os Deployments iniciam-se assim que o Helm os cria, enquanto os hooks ainda estão em execução. Um serviço que iniciasse perante uma base de dados sem função, sem palavra-passe ou sem esquema falharia e reiniciaria até os hooks terminarem. Por isso, cada Deployment que utiliza a base de dados inclui um contentor de inicialização (init container), wait-for-schema, que retém o pod.
Lê o registo de versões como nexus_ledger_reader, um início de sessão que pode ler apenas essa tabela e mais nada, e aguarda até que o registo apresente as suas cadeias para os resumos de imagem desta versão. Faz a verificação a cada schemaWait.intervalSeconds (3 por predefinição), apresenta o seu estado quando este muda e a cada vigésima verificação, e desiste após schemaWait.timeoutSeconds (1800 por predefinição) com uma falha que indica o nome do serviço.
| Implementação | Aguarda por |
|---|---|
nexus-auth |
nexus-auth-migrations |
nexus-orchestrator, nexus-workflows |
nexus-orchestrator-migrations |
nexus-gateway |
nexus-gateway-migrations |
nexus-graphrag |
nexus-graphrag-migrations |
nexus-probitas |
nexus-probitas-migrations |
nexus-skills-engine |
nexus-db-bootstrap |
nexus-alpha-bff |
nexus-alpha-bff-migrations |
Para acompanhar a espera de um serviço em tempo real, leia o registo do respetivo contentor de inicialização:
kubectl -n nexus logs deploy/nexus-auth -c wait-for-schemawait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations; gives up after 1800s
wait-for-schema: ready after 212s: the release ledger shows nexus-auth-migrations
Como a espera se baseia no resumo da imagem, e não numa contagem de ficheiros, os pods de uma atualização posterior aguardam pelas linhas da nova versão, e um pod que reinicie após uma alteração apenas de valores encontra a sua linha de imediato.
Passo 7: aguardar por todas as cargas de trabalho
Aguarde pelos Deployments, com um limite de tempo:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900sdeployment.apps/nexus-alpha condition met
deployment.apps/nexus-alpha-bff condition met
deployment.apps/nexus-auth condition met
deployment.apps/nexus-gateway condition met
deployment.apps/nexus-graphrag condition met
deployment.apps/nexus-keys condition met
deployment.apps/nexus-orchestrator condition met
deployment.apps/nexus-probitas condition met
deployment.apps/nexus-skills-engine condition met
deployment.apps/nexus-workflows condition met
Em seguida, pelos StatefulSets. Os dois servidores de armazenamento de chaves só atualizam quando elimina os respetivos pods, e kubectl rollout status recusa essa estratégia de atualização, pelo que deve aguardar antes pela contagem de prontos:
for s in $(kubectl -n nexus get statefulset -o name); do
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
doneCada um apresenta condition met. No nosso cluster, ambas as esperas juntas demoraram menos de cinco minutos após o retorno do Helm.
Como se apresenta o estado pronto
kubectl -n nexus get deploy,statefulsetNAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/nexus-alpha 1/1 1 1 14m
deployment.apps/nexus-alpha-bff 1/1 1 1 14m
deployment.apps/nexus-auth 1/1 1 1 14m
deployment.apps/nexus-gateway 1/1 1 1 14m
deployment.apps/nexus-graphrag 1/1 1 1 14m
deployment.apps/nexus-keys 1/1 1 1 14m
deployment.apps/nexus-orchestrator 1/1 1 1 14m
deployment.apps/nexus-probitas 1/1 1 1 14m
deployment.apps/nexus-skills-engine 1/1 1 1 14m
deployment.apps/nexus-workflows 1/1 1 1 14m
NAME READY AGE
statefulset.apps/nexus-neo4j 1/1 14m
statefulset.apps/nexus-postgres 1/1 14m
statefulset.apps/nexus-qdrant 1/1 14m
statefulset.apps/nexus-seaweedfs 1/1 14m
statefulset.apps/nexus-valkey 1/1 14m
statefulset.apps/openbao 1/1 14m
statefulset.apps/openbao-unsealer 1/1 14m
Dez Deployments e sete StatefulSets, todos prontos. Juntamente com eles encontrará três CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule e nexus-keys-export-receipts, a manutenção noturna do serviço de chaves. kubectl -n nexus get jobs não deve listar quaisquer Jobs de hook: os que foram bem-sucedidos foram eliminados.
Vale a pena fazer duas coisas antes de sair do terminal. Registe (commit) o ficheiro de valores onde a sua equipa guarda a configuração; todas as atualizações partem dele. E não altere o Secret nexus-generated. O chart gera as palavras-passe e chaves internas uma única vez, na instalação, guarda-as aí e volta a lê-las em cada atualização, pelo que a sua eliminação deixaria os serviços incapazes de aceder aos seus próprios dados.
Pronto significa que a plataforma está em execução e por reivindicar. Abra https://console.harrow.example e acederá ao instalador, não a uma página de início de sessão: ninguém pode iniciar sessão até que alguém reivindique a instalação. Essa é a primeira execução, no capítulo 2.12, A primeira execução.
Se isto falhar
A maioria das falhas identifica-se a si própria. Leia a mensagem antes de alterar seja o que for.
| O que vê | Causa | O que fazer |
|---|---|---|
INSTALLATION_NAME_MISSING ou INSTALLATION_NAME_EXAMPLE |
keys.installationName está vazio ou tem o valor de exemplo |
Defina o seu próprio nome permanente |
KEYS_CUSTODIAN_MISSING ou KEYS_CUSTODIAN_EXAMPLE |
Sem custodiantes, ou com o de exemplo | Defina os destinatários próprios dos seus custodiantes |
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ |
Maiúsculas, pontos ou um dígito inicial | Utilize letras minúsculas, dígitos e hífenes, começando por uma letra |
keys.custody.recipients: ... e um motivo |
Um destinatário tem erros de digitação, é uma chave privada ou tem um formato para o qual o Job de custódia não consegue encriptar | Peça novamente o destinatário ao custodiante |
hosts.console is required (the installation identity) |
Um anfitrião não está definido | Defina todos os três anfitriões |
tls.existingSecret is required when tls.mode is existing |
Nenhum Secret indicado | Defina-o, ou altere tls.mode |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
A sua conta não consegue ler os endereços do servidor da API | Indique-os como intervalos /32 |
global.imageRegistry is required |
O registo não está definido | Defina-o |
O Helm aguarda até ao limite de tempo; nexus-auth regista password authentication failed |
Foi indicado --wait |
Desinstale e instale novamente sem --wait |
Error: ... job failed indicando o nome de um hook |
Uma migração falhou | kubectl -n nexus logs job/<hook-name> e leia as suas últimas linhas |
Um pod bloqueado em Init |
O respetivo wait-for-schema ainda está a aguardar |
Leia o respetivo registo: indica a cadeia em falta |
wait-for-schema: FAILED |
O hook da cadeia nunca escreveu a sua linha | Procure primeiro a falha desse hook |
ImagePullBackOff |
O nó não consegue extrair a partir de global.imageRegistry |
Verifique se o nó consegue alcançar o registo e, para a edição Enterprise, se tem o token de extração |
Cada hook que aguarda pelo PostgreSQL aguarda durante um tempo limitado e indica-o, waiting for postgres (12/60), pelo que uma base de dados bloqueada aparece no registo do hook no espaço de um minuto.
A via de instalação com o nexusctl
nexusctl install faz a mesma instalação, executando por si as verificações associadas. Utiliza o mesmo ficheiro de valores:
nexusctl install --context harrow-prod --values harrow-values.yamlExecuta novamente a verificação prévia e para se algum controlo tiver começado a falhar. Verifica a assinatura do pacote do chart face à chave da versão. Em seguida, instala, aguarda pelos hooks e pelas cargas de trabalho e apresenta cada passo com o tempo que demorou. --edition community declara a edição na linha de comandos, bem como no ficheiro. --ca-bundle <file> adiciona os seus próprios certificados de CA, tal como na verificação prévia. Para ver as operações helm e kubectl que seriam executadas, sem as executar, adicione --explain:
nexusctl install --context harrow-prod --values harrow-values.yaml --explainQuando termina, apresenta o endereço de reivindicação, um código de reivindicação de utilização única e a impressão digital da instalação:
Installed in <time>. Nobody can sign in yet.
Open https://console.harrow.example/claim
Code <code> works once, for 30 minutes
Fingerprint of this installation, to compare in the browser:
<eight groups of four>
O código tem três grupos e permite cinco tentativas; a impressão digital tem oito grupos de quatro caracteres, e o navegador apresenta os mesmos oito grupos para que os possa comparar antes de reivindicar.
Passagem para a primeira execução
Se instalou com o Helm, crie o código de reivindicação por si próprio, indicando o nome da pessoa que será o primeiro administrador:
nexusctl claim-code --administrator aoife.brennan@harrow.exampleExecuta o comando de código de reivindicação do próprio serviço de chaves no pod nexus-keys com o seu acesso ao cluster, e apresenta o endereço, o código e a impressão digital como acima. O código é válido durante 30 minutos; execute-o novamente para obter um novo.
A partir daqui, o processo continua no navegador: reivindique a instalação, crie o primeiro administrador com uma passkey e conclua os seis passos antes que alguém inicie sessão. Isso encontra-se no capítulo 2.12, A primeira execução. Se pretender licenciar a edição Enterprise de imediato, leia primeiro o capítulo 2.7, Instalar a edição Enterprise e aplicar uma licença, porque a licença é um desses seis passos.

