Iniciar sessãoAgendar apresentação

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

18 minutos de leitura

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

  1. Verifique se o Helm é a versão 4.

    helm version

    A instalação depende de o Helm 4 aguardar, por predefinição, pelos Jobs de hook do chart. Utilizámos a v4.3.1.

  2. Aponte o kubectl para o cluster indicado na sua folha de planeamento e confirme.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Cada 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.

  1. 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.

  2. Aguarde pelo respetivo webhook, pelo qual passam todos os pedidos de certificado:

    kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300s
    deployment "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.key

harrow-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.yaml

A 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 45m

Se 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.

Uma cronologia horizontal da esquerda para a direita, com a legenda "helm install". Na faixa superior, sete caixas de hooks por ordem: "-30 prerequisites", "-20 db-bootstrap", "-15 custody init", "-12 graphrag migrations", "-10 auth migrations", "-5 orchestrator, gateway, probitas migrations", "0 BFF migrations". Cada caixa de migração tem uma pequena seta a apontar para baixo, para um cilindro numa faixa intermédia com a legenda "release ledger: nexus_release.schema_applied". Na faixa inferior, uma barra longa que começa à esquerda com a legenda "Deployments start, wait-for-schema holds each pod"; pequenas setas verticais sobem dela até ao registo de versões, e a barra de cada Deployment fica sólida quando a sua própria linha aparece no registo.
A ordem de uma instalação de raiz, com os hooks e as cargas de trabalho lado a lado.

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-schema
wait-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=900s
deployment.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
done

Cada 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,statefulset
NAME                                  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.

Esta instalação (Community)
Esta instalação (Community)
A página própria de uma instalação Community depois de reivindicada: a versão em execução, o estado do motor, a utilização do disco, as cópias de segurança e o compromisso de correções de segurança, com as funcionalidades Enterprise apresentadas como demonstrações que indicam quem as pode ativar.

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.yaml

Executa 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 --explain

Quando 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.

A instalar
A instalar
A instalação a decorrer no terminal do operador. Cada passo é apresentado com a respetiva duração, e a execução termina com um código de utilização única e a impressão digital da instalação; ninguém pode iniciar sessão até que a instalação seja reivindicada num navegador.

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.example

Executa 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.