Iniciar sessãoAgendar apresentação

Capítulo 2.15

Dia dois: operar o Nexus

O trabalho de rotina de manter uma instalação em funcionamento após a primeira semana. Começa com a abertura do cofre de chaves após um reinício e termina com a desinstalação.

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

Na primeira vez que faltou a energia na sala de servidores da Harrow Port Authority, tudo voltou a funcionar, exceto as partes que precisavam de chaves. Os pods estavam em execução (Running) e a consola carregou. Ninguém conseguia abrir um ficheiro. Tomás Reilly tinha lido sobre isto e, ainda assim, demorou vinte minutos a lembrar-se do motivo. O desselador do repositório de chaves inicia selado após cada reinício do seu nó, e apenas um custódio o pode abrir.

Este capítulo acompanha a rotina do operador após a primeira semana, desde o repositório de chaves e os seus custódios até à desinstalação. Cada verbo nexusctl aqui aceita --explain, que imprime as operações kubectl e helm que executaria sem as executar. Utilize-o na primeira vez que executar algo num cluster de produção.

Custódia do cofre de chaves

Uma instalação tem dois servidores OpenBao no seu namespace. O repositório de chaves, openbao, guarda todas as chaves que o Nexus utiliza. O desselador, openbao-unsealer, é um segundo OpenBao, mais pequeno, cuja única função é desselar o repositório de chaves. O repositório de chaves dessela-se a si próprio através da chave de trânsito do desselador; o desselador é selado com o esquema de Shamir, sob a forma de 5 partes das quais quaisquer 3 o desselam.

Na primeira instalação, um Job de custódia inicializa ambos os servidores dentro do cluster. Este encripta as partes do desselador e as chaves de recuperação do repositório de chaves na sua própria memória para cada custódio nomeado em keys.custody.recipients, e armazena apenas o texto cifrado (os Secrets openbao-unseal-shares-encrypted e openbao-recovery-keys-encrypted). Revoga ambos os tokens de raiz no mesmo Job. O pacote de cada custódio contém partes suficientes para desselar por si só, pelo que basta um custódio após um reinício.

Após o reinício de um nó

Após qualquer reinício do nó onde o desselador é executado (um corte de energia, um reinício da máquina, um reinício do tempo de execução do contentor), o desselador inicia selado. Até que um custódio o dessele, o repositório de chaves também permanece selado e nada que precise de uma chave funciona. A consola continua a responder e as pessoas ainda podem iniciar sessão, mas qualquer ação que necessite de uma chave do repositório de chaves fica a aguardar: abrir conteúdo encriptado, uma reivindicação, uma verificação de uma parte compilada.

Pergunte ao próprio OpenBao, dentro de cada pod. Este é o desselador:

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Execute o mesmo comando contra openbao-0 com -tls-server-name=openbao para o repositório de chaves. bao status termina com o código 0 quando o servidor está desselado, 2 quando está selado e 1 quando não conseguiu responder. Uma saída com 1 não permite concluir nada, porque o pod pode ainda não estar ativo. Aguarde um minuto e pergunte novamente. Se o desselador estiver desselado e o repositório de chaves ainda estiver selado, o repositório de chaves está a desselar-se a si próprio e não tem de fazer nada.

À esquerda: um ícone de uma pessoa com a legenda "Custódio, com a sua própria identidade age". Uma seta vai para a direita para uma caixa "unseal.sh na máquina do custódio (uma desencriptação)". A partir daí, uma seta com a legenda "kubectl port-forward, Transport Layer Security (TLS) verificado contra a autoridade de certificação (CA) do desselador" entra numa caixa "openbao-unsealer (Shamir 5 partes, quaisquer 3)". Do desselador, uma segunda seta com a legenda "chave de trânsito, automática" entra numa caixa "openbao, o repositório de chaves". A partir do repositório de chaves, um leque de setas aponta para pequenas caixas "nexus-keys", "nexus-auth", "os outros serviços". Uma nota sob o custódio: "a identidade nunca sai desta máquina".
O que um custódio faz após o reinício de um nó.

Desselagem

O chart disponibiliza unseal.sh, na sua pasta files/custody/, exatamente igual byte por byte em cada lançamento. Um custódio executa-o na sua própria máquina. Este lê o Secret encriptado, desencripta-o uma vez com a identidade do custódio (uma identidade Secure Enclave pede o Touch ID uma vez), submete as partes ao desselador e confirma que está desselado. Nenhuma parte é alguma vez escrita num ficheiro ou colocada numa linha de comandos.

A Harrow executa-o em modo direto, através de um port-forward:

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> é o ficheiro de identidade age do custódio, a metade privada de um dos destinatários em keys.custody.recipients. UNSEAL_RESOLVE é o nome que o certificado do desselador contém (<namespace> é o namespace onde o Nexus está instalado, nexus por predefinição), pelo que o TLS é verificado contra a própria CA do desselador, mesmo que a ligação vá para 127.0.0.1. O script nunca desativa a verificação de certificados.

Saída Última linha Significado
0 UNSEALED nexus/openbao-unsealer-0 Desselado. Se já estava, nada foi enviado
1 STILL-SEALED … Ainda selado, ou uma chamada de desselagem falhou
2 UNSEAL-REFUSED … Falta um pré-requisito, indicado na mensagem
3 UNSEAL-REFUSED … Esta identidade não consegue desencriptar as partes, pelo que não é um custódio desta instalação. Nada foi enviado

Dentro de um minuto, o repositório de chaves segue-se por si só. Verifique com kubectl -n nexus get deploy,statefulset se tudo está pronto novamente.

Os custódios são escolhidos antes da instalação e cada um cria a sua própria chave na sua própria máquina. O chart apenas vê a metade pública:

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

O primeiro comando cria uma identidade age comum; o seu destinatário é a linha # public key: age1... no ficheiro. O segundo cria uma guardada no Secure Enclave de um Mac, com um destinatário que começa por age1se1. Qualquer um dos destinatários entra em keys.custody.recipients. O ficheiro de identidade fica com o respetivo custódio, offline.

Cópia de segurança e restauro

Cópia de segurança e restauro mostra cada repositório com a sua última cópia de segurança e a última vez que um restauro do mesmo foi efetivamente testado. Uma cópia de segurança só é comprovada depois de ter sido restaurada, pelo que a página regista ambos. São feitas cópias de segurança de seis repositórios. A base de dados principal guarda pessoas e definições; tarefas e o registo de auditoria. Ao lado desta encontram-se o grafo de conhecimento e o índice de pesquisa, seguidos do repositório de ficheiros e do repositório de memória. As chaves são o sexto, seladas e mantidas separadas dos dados. As cópias de segurança vão para o seu próprio armazenamento, encriptadas com as suas próprias chaves, e a Adverant não as consegue ler. Quando um repositório não teve um restauro testado dentro da sua regra, a página mostra a placa RESTORE_TEST_OVERDUE com um botão Testar agora. Um restauro de teste é executado num espaço separado e ninguém dá por isso.

As mesmas duas ações estão disponíveis a partir da linha de comandos:

nexusctl backup now
nexusctl backup verify

backup now faz uma cópia de segurança de todos os repositórios de uma só vez. backup verify verifica a cópia de segurança mais recente. Execute ambos antes de qualquer alteração que o deixe apreensivo.

Cópia de segurança e restauro
Cópia de segurança e restauro
Cada repositório com a sua última cópia de segurança e o seu último restauro testado. O índice de pesquisa tem um teste em atraso e a placa propõe executar um agora.

Para restaurar, deve indicar o nome da cópia de segurança:

nexusctl restore --from <backup-id>

<backup-id> provém da lista em Cópia de segurança e restauro. Um restauro necessita da aprovação de uma segunda pessoa e, enquanto é executado, a barra de progresso mostra-o com a hora a que começou e quem o aprovou. Todos ficam em modo só de leitura durante o restauro, o que é diferente de estar bloqueado: as pessoas podem iniciar sessão e ler. As tarefas não iniciam (os agendamentos aguardam e recuperam o atraso) e a pesquisa regressa quando o índice de pesquisa estiver de volta. Tudo o que foi escrito após a realização da cópia de segurança é perdido, pelo que o relatório de restauro lista esses dados por proprietário para que os possam refazer.

A restaurar
A restaurar
Um restauro em curso. Os repositórios regressam por ordem, as pessoas ficam em modo só de leitura até que o último esteja concluído e um aviso em cada página indica quando se prevê que esteja de volta.

Guarde mais uma coisa com as suas cópias de segurança: o Secret nexus-generated no namespace nexus. O chart cria as palavras-passe geradas e as chaves de encriptação da instalação na primeira instalação e volta a lê-las a partir desse Secret em cada atualização. Os dados selados sob EXTERNAL_KEY_ENCRYPTION_KEY abrem apenas com essa chave. Armazene uma cópia do Secret onde quer que guarde o material mais sensível que possui, porque qualquer pessoa que o detenha detém essas chaves.

Atualizações

Tomás atualiza em dois passos. Primeiro, pergunta o que irá mudar:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

O plano lista o que muda no lançamento, qualquer alteração à estrutura da base de dados e se pode ser revertida. Em seguida, aplica-a:

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

A aplicação faz primeiro uma cópia de segurança e executa as verificações prévias (preflight). Depois, move os motores por vagas, e cada vaga aguarda até que a anterior esteja saudável durante 10 minutos. A página Atualização mostra cada vaga à medida que avança e o estado de saúde da instalação entretanto. Também indica até quando o caminho de regresso permanece aberto; após essa data, voltar atrás requer um restauro. Se um passo falhar, o Nexus reverte todos os motores para o lançamento anterior e verifica-os. O aviso UPGRADE_ROLLED_BACK indica então o nome do passo que falhou e informa que os dados não foram alterados. A correção aparece antes de Tentar novamente, e o pacote de suporte está à distância de um botão.

Para uma instalação sem ligação ao exterior, o pacote chega em suporte físico. A opção Importar de suporte físico verifica a assinatura do lançamento contra a chave de lançamento da Adverant instalada na instalação e garante que as versões apenas avançam. Os ficheiros assinados por qualquer outra entidade são recusados com MEDIA_SIGNATURE_INVALID: nada é carregado e o lançamento em execução continua a funcionar.

Atualização
Atualização
Uma atualização em curso. Foi feita primeiro uma cópia de segurança, a segunda de três vagas está em movimento e o caminho de regresso permanece aberto até uma data indicada.
A atualização falhou e foi revertida
A atualização falhou e foi revertida
Uma vaga falhou porque um volume ficou sem espaço. Todos os motores voltaram ao lançamento anterior com os dados intactos, e a correção está listada antes de Tentar novamente.

O que acontece nos bastidores

nexusctl upgrade apply executa helm upgrade contra o chart. Se atualizar com o Helm por conta própria, aplicam-se as mesmas regras:

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

O esquema avança antes de os novos pods serem implementados. As migrações do chart são hooks de pré-atualização que são executados por ordem: primeiro o bootstrap da base de dados, depois as migrações de cada serviço e, por fim, as do backend for frontend (BFF) da consola. O Job de custódia também é executado e, numa instalação que já esteja inicializada, confirma esse facto e não altera nada. Cada Job de hook tem um limite de tentativas (backoff limit) de 0, pelo que uma migração que falhe interrompe a atualização e nunca é repetida silenciosamente: leia o respetivo registo com kubectl -n nexus logs job/<hook-job> antes de tentar novamente.

O pod de cada serviço aguarda num contentor de inicialização (init container), wait-for-schema, até que o registo de lançamentos mostre as suas migrações aplicadas para a imagem do novo lançamento. Após uma reversão, ou uma atualização que tenha alterado apenas valores, um pod reiniciado encontra a sua linha e inicia de imediato.

Antes de atualizar

Vale a pena planear tendo em conta três pontos das notas de lançamento:

  1. Atualize num período calmo. Na primeira atualização de uma instalação feita a partir de um chart anterior, a tarefa de bootstrap retira os antigos direitos de tabela predefinidos, e cada serviço recupera os seus através da sua própria migração. Até que essa migração seja executada, um serviço não pode utilizar as suas tabelas. O intervalo dura segundos. Se os segundos importarem, escale primeiro os serviços para zero e volte a escalar assim que as tarefas de migração tiverem terminado.
  2. Atribua uma organização a cada chave da interface de programação de aplicações (API). Uma chave sem organização é recusada com 403 TOKEN_ORG_MISSING por todos os serviços que verificam chaves através do nexus-auth, incluindo o nexus-graphrag. Antes de atualizar, atribua uma organização a cada uma dessas chaves ou emita uma nova chave. As chaves bcrypt antigas continuam a funcionar até à sua data de revogação definitiva.
  3. Limpe as chaves de API em cache posteriormente. Até uma hora de entradas de chaves em cache contém o nome da aplicação incorreto até que o faça. Execute isto contra a cache do nexus-auth, o Valkey da instalação (nexus-valkey, palavra-passe no Secret nexus-generated sob VALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

Isto aplica-se ao repositório predefinido dentro do cluster. Com dataTier.valkey.mode: external não existe tal pod: execute a mesma análise e eliminação contra o seu próprio anfitrião Valkey, com a palavra-passe do Secret indicado em dataTier.valkey.external.existingSecret.

Reversão (Rollback)

Dentro do período que a página Atualização mostra, a opção Voltar atrás devolve todos os motores ao lançamento anterior. Após esse período, voltar atrás significa restaurar a cópia de segurança que a atualização fez primeiro.

Dois valores nunca devem mudar ao longo de uma atualização ou reversão.

keys.installationName é permanente. O primeiro bootstrap do repositório de chaves cria a identidade da instalação sob este valor, e é essa identidade que a sua licença refere. Utilize exatamente o mesmo valor em todos os ficheiros de valores que alguma vez aplicar a esta instalação.

O Secret nexus-generated deve permanecer como está. Em cada atualização, o chart lê EXTERNAL_KEY_ENCRYPTION_KEY a partir dele e verifica a sua estrutura. Um valor que não seja base64 de 32 bytes nem a chave bruta de 32 bytes de uma instalação mais antiga interrompe a renderização com EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, e o chart nunca imprime o valor. Isto significa que alguém editou ou substituiu o Secret. Reponha a chave sob a qual os dados desta instalação estão selados, como base64 dos seus 32 bytes (printf %s "$OLD" | base64), e atualize novamente. Uma nova chave aleatória deixaria ilegível tudo o que estivesse selado sob a antiga.

Escalonamento

Cada componente tem um interruptor e um tamanho no ficheiro de valores. Os componentes obrigatórios não podem ser desligados: o chart executa-os independentemente do que diga o seu interruptor. Aos outros podem ser atribuídas mais réplicas e mais recursos.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Aplique-o com helm upgrade conforme indicado acima. Os volumes são dimensionados sob dataTier.<store>.size; verifique se a sua classe de armazenamento permite aumentar um volume antes de o elevar. A página Como está a instalação apresenta gráficos sobre o quão ocupados têm estado os processadores e a memória do cluster, com o espaço livre restante em cada um. Aumente o que se esgotar primeiro.

Pacotes de suporte

Quando a Harrow precisa da ajuda da Adverant, Tomás cria um pacote de suporte:

nexusctl support-bundle --out harrow-support-4471.tar.gz

A página Pacote de suporte da consola cria o mesmo ficheiro. Esta recolhe os registos dos motores das últimas 24 horas com detalhes de saúde e de versão. As definições entram sem os seus segredos, juntamente com os relatórios de verificações prévias (preflight) e de instalação. Antes de algo ser escrito, a ocultação substitui nomes e segredos por marcadores de posição, e pode ler uma pré-visualização daquilo que irá exatamente sair. O conteúdo próprio das pessoas nunca é recolhido. O pacote segue para a Adverant através de carregamento para a página Suporte e pacotes de suporte da sua conta ou como um ficheiro transportado em suporte físico. Apenas os engenheiros de suporte nomeados no pedido o podem abrir, e é apagado após 30 dias.

Pacote de suporte
Pacote de suporte
A criar um pacote de suporte. A pré-visualização de ocultação mostra o que é escondido antes de algo sair, e apenas os engenheiros nomeados o podem abrir.

Exportação de evidências

Os auditores e a sua própria equipa de conformidade querem frequentemente provas de que a plataforma se comporta conforme descrito. nexusctl evidence export escreve essas provas:

nexusctl evidence export --out harrow-evidence-2027-01

Juntamente com os registos que exporta, o comando executa as sondas de aceitação da plataforma: o encaminhador de inteligência artificial (IA) está acessível e responde, uma tarefa UNO é enviada e concluída, e uma leitura entre organizações é recusada. Os respetivos resultados encontram-se em probes.json na pasta de saída.

Estado num relance

nexusctl status --json responde se a instalação está saudável e em que estado se encontra cada componente. Também comunica o estado da licença com a respetiva data de expiração, a edição e o lançamento em execução. Cada parte compilada é listada com o seu resumo criptográfico (digest) e assinatura. É o comando ideal para colocar por trás da sua própria monitorização.

Desinstalação

nexusctl uninstall --profile <profile-file>

<profile-file> é o perfil de implementação para o cluster, o mesmo ficheiro que passou para nexusctl handoff --profile <profile-file> --out <dir> se a sua equipa de plataforma gerir o cluster. A transferência (handoff) escreve, para essa equipa, uma lista em linguagem simples do que o Nexus precisa do cluster e os manifestos para o satisfazer. A desinstalação remove os namespaces do Nexus e nada mais, mantendo as suas cópias de segurança. A identidade da instalação desaparece com ela. Uma instalação posterior no mesmo cluster é uma nova instalação com uma nova identidade, pelo que a sua reivindicação é uma nova reivindicação e a sua licença é uma nova licença.

As páginas Esta instalação (This installation)

Os operadores da instalação têm o seu próprio grupo no menu, Esta instalação, e é nas suas páginas que ocorre a maior parte deste capítulo na consola. Um membro que abra uma delas vê a página Não é um administrador, que indica quem pode agir.

Página Para que serve
Licença e o que desbloqueia A licença e os seus grupos de funcionalidades (capítulo 2.13, Licenças)
Se a licença expirar A escada de expiração por palavras, com as datas desta licença
Partes compiladas Cada módulo licenciado com a sua verificação de assinatura noturna
Declaração de utilização para a Adverant Os contadores anuais, legíveis antes de saírem
Versões e atualizações Cada versão instalada, com quem a instalou e quando
Atualização A atualização faseada e o caminho de regresso
Cópia de segurança e restauro Cada repositório, a sua última cópia de segurança e o seu último restauro testado
Estado da instalação Nós, capacidade e custo de operação, com avisos
Chaves e apagamento A chave de cada organização, e Apagar com um motivo e uma segunda pessoa
Incidentes Problemas abertos e fechados, com o que foi feito
A descontinuar em breve Funcionalidades a serem desligadas, com datas, exportação e substituição
Estado Cada parte do Nexus agora e ao longo de 30 dias, em palavras que qualquer pessoa pode ler
Pacote de suporte O que sai para a Adverant, e como

Duas destas páginas merecem uma menção. Partes compiladas verifica todas as noites cada módulo licenciado contra a assinatura da Adverant. Uma cópia alterada de um módulo é recusada e nunca é carregada, enquanto a cópia assinada continua em execução, e a página conta as recusas por mês para que uma cópia adulterada não passe despercebida. Estado está escrito de forma a que qualquer pessoa na organização o possa ler. Mostra cada parte do Nexus agora e ao longo dos últimos 30 dias como uma faixa de dias, com manutenção agendada e incidentes recentes, e um operador adiciona um incidente ou uma janela de manutenção a partir da mesma página.

Uma instalação Community tem uma página, Esta instalação (Community), com a sua versão, saúde e atualizações. As páginas Enterprise aparecem nela como amostras que indicam quem as pode ativar.